duo-accessibility

Makes iPhone Duo apps work with VoiceOver, Dynamic Type, Reduce Motion, Increase Contrast, hardware keyboards, Switch Control and Voice Control on both displays. Use it when VoiceOver reads two panes

SKILL.md

GitHub

duo-accessibility

iPhone Duo changes shape while people use it. One pane becomes two, a row of text gets about twice the width, the window jumps to another display. Accessibility settings don't change with it: the same VoiceOver user, text size and Reduce Motion setting meet every layout. This skill makes each layout work for them.

Load neighbours for depth: duo-design-system (type scale, colour tokens, contrast checks), duo-transitions (animating the resize), duo-postures (hinge effects), duo-ergonomics (44 pt targets), duo-testing (UI test setup), duo-shared-screen (two people, one screen).

Labels: measured means we ran it in a probe app with UI tests on the shared iPhone Duo simulator (Xcode 27.1, iOS 27.1, 18 October 2026). Unverified means we could not confirm it. Everything else links to Apple. Details: references/evidence.md.

Rules

  1. Make each pane a VoiceOver container. Two panes side by side are read row by row otherwise.
  2. Keep the pane order stable in every pose. Change it only with accessibilitySortPriority, never by pose.
  3. After a fold or unfold, put VoiceOver back where the person was. Wait for the new layout first.
  4. Reflow at large text sizes. Never truncate or clip. Design the closed outer display at the largest size first.
  5. Under Reduce Motion: no hinge effects, no moving or zooming resize animations. Fades only.
  6. Check every custom colour with Increase Contrast on, in light and dark. Never show state with colour alone.
  7. Give every main command a keyboard shortcut and a label. Every drag, swipe and hinge input needs a button or a named action.
  8. Use system controls. Give icon-only buttons a title (Label), because vertical bars hide it on screen and VoiceOver, Voice Control and the overflow menu still need it. Give your own icon-only buttons a 44 pt frame inside the label.
  9. Put accessibility modifiers, contentShape and gestures before .position.
  10. Test closed, open and partly folded: Accessibility Inspector by hand, performAccessibilityAudit and a VoiceOver walk in UI tests.

1. VoiceOver order across two panes

VoiceOver reads top to bottom, then leading to trailing, the way people read the language (HIG, VoiceOver). Two panes side by side break that. Measured, closed and open, with two plain panes in an HStack:

Inbox, Heading | Message, Heading | Left 1 | Right 1 | Left 2 | Right 2 | Left 3 | Right 3
  • Moving the right pane 20 pt lower did not help. ArrangementView with .split read row by row too, open; closed, it showed only the primary (measured).
  • NavigationSplitView already reads the sidebar, then the detail (measured open). Leave it alone.

Make each pane a container with accessibilityElement(children: .contain). VoiceOver then visits all of one container's children before the next container (doc).

import SwiftUI

extension View {
    /// One VoiceOver container per pane: the whole pane is read before the next one.
    /// A higher priority is read first; the default is 0, leading pane first.
    func accessibilityPane(_ label: LocalizedStringKey, priority: Double = 0) -> some View {
        accessibilityElement(children: .contain)
            .accessibilityLabel(label)
            .accessibilitySortPriority(priority)
    }
}

@available(iOS 27.1, *)
struct ArticleWithComments: View {
    var body: some View {
        ArrangementView {
            ScrollView { Text("Article text") }
                .accessibilityPane("Article")
        } secondary: {
            List(1...20, id: \.self) { Text("Comment \($0)") }
                .accessibilityPane("Comments")
        }
    }
}

Measured with containers labelled "Inbox pane" and "Message pane": Inbox, Heading | Left 1 | Left 2 | Left 3 | Message pane, Message, Heading | Right 1 | .... VoiceOver spoke the second pane's label (the probe's own text; VoiceOver adds no "pane") as it entered it, but not the first pane's label at the start. With accessibilitySortPriority(1) on the right pane, VoiceOver read it first. Higher numbers go first; the default is 0 (doc).

  • Add a heading trait (.accessibilityAddTraits(.isHeader)) to each pane's title so the rotor can jump between panes.
  • The fold is not an element. Content that crosses it needs nothing. In a two-page layout, make each page a container ("Page 12").
  • Don't hide a visible pane with accessibilityHidden. Closed, a pane that is not on screen is already gone.
  • UIKit, recipes for each pattern, and the rotor: references/voiceover-order.md.

2. Focus after fold and unfold

When the window resizes, views come and go, and VoiceOver can lose its place. Measured, real fold in Device Hub, with VoiceOver on a list row that only exists open:

Code Where VoiceOver landed after Closed
Nothing Back, Button, the first element on screen
Focus set at once in onChange(of: horizontalSizeClass) Back, Button: the request was lost
Focus set 0.3 s later Lunch on Friday, Heading, the target

So wait for the new layout, then move focus once, to the element that holds the person's place.

import SwiftUI

/// Moves VoiceOver to `target` after a fold, unfold or Split View change
/// switches the width class. Measured: a move made at once was ignored.
struct RefocusAfterResize<Value: Hashable>: ViewModifier {
    let focus: AccessibilityFocusState<Value?>.Binding
    let target: () -> Value?
    var delay: Duration = .milliseconds(500)
    @Environment(\.horizontalSizeClass) private var widthClass

    func body(content: Content) -> some View {
        content.task(id: widthClass) {
            // .task restarts on every change and cancels a pending move.
            guard (try? await Task.sleep(for: delay)) != nil, let value = target() else { return }
            focus.wrappedValue = value
        }
    }
}

struct MessageScreen: View {
    enum Spot: Hashable { case row(Int), title }
    @AccessibilityFocusState private var spot: Spot?
    @State private var lastSpot: Spot?
    @Environment(\.horizontalSizeClass) private var widthClass

    var body: some View {    // accessibilityPane: section 1
        HStack(alignment: .top) {
            if widthClass == .regular {
                List(1...4, id: \.self) { row in
                    Text("Row \(row)").accessibilityFocused($spot, equals: .row(row))
                }
                .accessibilityPane("Messages")
            }
            VStack(alignment: .leading) {
                Text("Lunch on Friday").font(.title)
                    .accessibilityAddTraits(.isHeader)
                    .accessibilityFocused($spot, equals: .title)
                Text("See you at noon.")
            }
            .accessibilityPane("Message")
        }
        .onChange(of: spot) { _, new in if let new { lastSpot = new } }
        .modifier(RefocusAfterResize(focus: $spot) {
            // Closed, the list is gone: fall back to the title.
            if case .row = lastSpot, widthClass != .regular { return .title }
            return lastSpot
        })
    }
}
  • The task runs on first appear too. With nothing focused yet, lastSpot is nil and it does nothing.
  • Move focus only to keep the person's place. Apple allows a move to a nearby item when the focused one disappears (HIG, Focus). Don't announce it.
  • Our run used onChange and a 0.3 s sleep. This modifier does the same with .task(id:) and 0.5 s; it was not run on a real fold or on hardware, and unfold (closed to open) was not measured (unverified). Test both the same way.
  • UIKit (UIAccessibility.post(notification: .layoutChanged, argument:)), @FocusState for text fields, and the full measurements: references/focus-after-fold.md.

3. Dynamic Type at both display sizes

One text size meets two very different widths. The narrow cases: the closed outer display, 382 pt of safe-area width (measured by duo-design-system), and, open, the pane beside the vertical bar, about 371 pt (derived, references/dynamic-type.md). Apple asks you to show as much text at the largest accessibility size as at the largest standard size, and to stack items when they crowd (HIG, Typography).

import SwiftUI

struct MessageRow: View {
    let subject: String
    let date: String
    @Environment(\.dynamicTypeSize) private var typeSize
    @ScaledMetric(relativeTo: .body) private var avatar = 32.0

    var body: some View {
        let stacked = typeSize.isAccessibilitySize
        let layout = stacked
            ? AnyLayout(VStackLayout(alignment: .leading, spacing: 4))
            : AnyLayout(HStackLayout(alignment: .center, spacing: 8))
        layout {
            Circle().fill(.tint).frame(width: avatar, height: avatar)
                .accessibilityHidden(true)
            Text(subject)                       // no lineLimit, no fixed height
            if !stacked { Spacer(minLength: 8) }
            Text(date).foregroundStyle(.secondary)
        }
        .accessibilityElement(children: .combine)
    }
}

Measured closed, with a row built the same way: 348 × 42 pt at Large, 297 × 370 pt at AX5, no audit issues. The same row with lineLimit(1) and frame(height: 30) got two "Text clipped" issues, at the default size and at AX5.

  • AnyLayout keeps view identity, so state survives the switch (doc).
  • ViewThatFits picks the first child that fits, for short strips of controls (doc).
  • Size icons, avatars and spacing with @ScaledMetric, never fixed numbers (doc).
  • Open, cap line length and use fewer, wider columns at accessibility sizes (readableWidth and span in duo-design-system).
  • Custom views in a vertical bar can't grow; the bar has a fixed width (talk 111462). Give them accessibilityShowsLargeContentViewer() (doc).
  • More recipes, UIKit and what to test: references/dynamic-type.md.

4. Reduce Motion, Increase Contrast, Reduce Transparency

Reduce Motion asks you to cut zooming, scaling and peripheral motion, and to swap slides for fades (HIG, Accessibility). On Duo that means the hinge and the resize.

import SwiftUI

@available(iOS 27.1, *)
struct HingeParallax: ViewModifier {
    @Environment(\.accessibilityReduceMotion) private var reduceMotion
    @State private var lift = 0.0

    func body(content: Content) -> some View {
        content
            .offset(y: reduceMotion ? 0 : lift)          // resets at once if the setting turns on
            .onHingeChange(isEnabled: !reduceMotion) { _, new in
                guard let hinge = new.hinge, hinge.status == .partiallyOpen else { lift = 0; return }
                lift = (180 - hinge.angle.degrees) / 10  // decoration only, never layout
            }
    }
}
  • Resize, as in duo-transitions: .animation(reduceMotion ? nil : .smooth(duration: 0.3), value: widthClass) on the stack, so nothing moves or resizes under Reduce Motion. A pane that appears gets .transition(reduceMotion ? .opacity.animation(.easeInOut(duration: 0.2)) : .opacity.combined(with: .move(edge: .trailing))): the fade carries its own animation, so it still fades (measured by duo-transitions). iOS 26.4 adds accessibilityPrefersCrossFadeTransitions for the finer setting (doc).
  • No VoiceOver announcement and no haptic per hinge angle. Hinge input needs an on-screen control that does the same job (duo-postures).
  • Increase Contrast: read colorSchemeContrast == .increased and give custom colours high-contrast variants. Text needs 4.5:1, or 3:1 at 18 pt or bold (HIG). Measured: the audit failed Color(white: 0.85) text on white and said "nearly passed" for .secondary text.
  • Reduce Transparency gives the vertical bar a background. Custom bar content must read on both (talk 111462).
  • Differentiate Without Color: add a shape, symbol or .isSelected trait to the selected pane or row.
  • UIKit and full recipes: references/motion-and-contrast.md.

5. Keyboard, Switch Control and Voice Control

People can drive any iPhone from a hardware keyboard, and Full Keyboard Access lets them reach every control from it (Testing system accessibility features).

import SwiftUI

struct ReplyControls: View {
    let reply: () -> Void
    let archive: () -> Void

    var body: some View {
        HStack {
            iconButton("Reply", "arrowshape.turn.up.left", reply)
                .keyboardShortcut("r", modifiers: .command)
                .accessibilityInputLabels(["Reply", "Answer"])
            iconButton("Archive", "archivebox", archive)
                .keyboardShortcut("e", modifiers: .command)
        }
    }

    /// Icon only; the title stays for VoiceOver and Voice Control. 44 pt hit area, as in duo-ergonomics.
    private func iconButton(_ title: LocalizedStringKey, _ symbol: String, _ action: @escaping () -> Void) -> some View {
        Button(action: action) {
            Label(title, systemImage: symbol).labelStyle(.iconOnly)
                .frame(minWidth: 44, minHeight: 44).contentShape(.rect)  // inside: outside, the audit flagged it
        }
    }
}
  • Use Command shortcuts and don't take over standard ones (HIG, Keyboards).
  • Measured closed, in UI tests: UIFocusSystem.focusSystem(for:) was nil in every run and Tab never reached focusable() views. Tab moved between two text fields in one run, not in another. Command shortcuts worked. Inner display: unverified. focusSection() is unavailable on iOS (iOS 27.1 SDK): use @FocusState, focused(_:equals:) and defaultFocus(_:_:priority:).
  • accessibilityInputLabels gives Voice Control and Full Keyboard Access other names, most important first (doc).
  • Switch Control and Voice Control need a tap path for every drag: a button or accessibilityAction(named:_:).
  • Details, UIKit UIKeyCommand, and Full Keyboard Access checks: references/keyboard-and-switch.md.

6. Accessibility modifiers before .position

.position returns a view as large as its parent. A contentShape or gesture after it covers that whole area, and the accessibility element grows with it. Measured: a 60 pt circle with contentShape(Rectangle()), a tap gesture and its accessibility element after .position got a 382 × 103 pt element, and a tap at the far left of the area counted. With those modifiers before .position: 60 × 60 pt. An accessibility element alone after .position stayed 60 × 60 pt; keep the order anyway. A contentShape and tap on a container also stretched its child's element to the container (measured, as in recipe-two-player-game). Prefer a Button when you can: placed with .position, it kept its own 51 × 20 pt frame (measured); give it a 44 pt label frame as in section 5.

import SwiftUI

struct Target: View {
    let hit: () -> Void

    var body: some View {
        GeometryReader { proxy in
            Circle()
                .frame(width: 56, height: 56)
                .contentShape(Circle())            // hit area: the circle
                .onTapGesture(perform: hit)
                .accessibilityElement()
                .accessibilityLabel("Target")
                .accessibilityAddTraits(.isButton)
                .accessibilityAction { hit() }     // VoiceOver and Switch Control activate
                .position(x: proxy.size.width / 2, y: proxy.size.height / 2) // last
        }
    }
}

7. Test on the iPhone Duo simulator

  1. Settings. xcrun simctl ui <UDID> content_size accessibility-extra-extra-extra-large and increase_contrast enabled. Reduce Motion, Reduce Transparency, Bold Text and Full Keyboard Access: Accessibility Inspector's Settings pane or the Settings app. Put every setting back on a shared simulator.
  2. Accessibility Inspector (Xcode > Open Developer Tool). Pick the simulator and your app. Use the navigation play button to hear the reading order, then run an audit. Repeat closed, open and partly folded (Inspecting screens).
  3. UI tests. performAccessibilityAudit(for:_:) in each pose and text size, and a VoiceOver walk with XCUIDevice.shared.voiceOverService (iOS 27). The query order of XCUI elements is not VoiceOver's order (measured on a split view), so test order with the VoiceOver service.
  4. Poses. No test API changes the pose. Use duo-pose set closed from duo-pose-matrix, or ask the person to press the pose in Device Hub. duo-pose refuses while any UI test runs, your own fold-focus test included: check that the only test processes are yours (pgrep -fl "xctrunner|xcodebuild.*test"), then pass --force with the user's OK. Otherwise ask the person to press Closed.

Test file, launch arguments, cleanup if VoiceOver stays on, and the audit results we got: references/testing.md.

Checklist

  • Each custom pane is an accessibilityElement(children: .contain) with a label; the order is the same closed, open and partly folded.
  • Pane titles have the header trait.
  • After fold and unfold, VoiceOver lands on the person's place, moved once, after the layout settles.
  • At AX5 on the closed display and in the open pane beside the vertical bar, nothing truncates, clips or overlaps; rows stack; no lineLimit(1) on content, no fixed text heights.
  • Icons and spacing use @ScaledMetric; custom bar items have a large content view.
  • Reduce Motion turns off hinge effects and moving resize animations; fades remain.
  • Custom colours pass 4.5:1 (3:1 at 18 pt or bold) in light, dark and Increase Contrast; state never relies on colour alone.
  • Main commands have Command shortcuts; icon-only buttons have titles and a 44 pt hit area; drags and hinge input have a button or named action.
  • Accessibility modifiers, contentShape and gestures come before .position.
  • Accessibility Inspector order and audit checked closed, open and partly folded; UI tests run the audit and a VoiceOver walk.
  • VoiceOver, text size and contrast are back to their defaults on the shared simulator.