@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/ios-accessibility/SKILL.md

@@ -1,90 +1,96 @@
 ---
 name: ios-accessibility
-description: "Implements, reviews, or improves accessibility in iOS/macOS apps with SwiftUI, UIKit, and AppKit. Use when adding VoiceOver, Voice Control, Switch Control, or Full Keyboard Access support; when working with accessibility labels, hints, values, traits, accessibilityInputLabels, NSAccessibility, grouping, reading order, accessibility focus restoration with @AccessibilityFocusState, Dynamic Type, @ScaledMetric, custom rotors, accessibility actions, XCTest accessibility checks, App Store Accessibility Nutrition Labels, App Store Connect accessibility answers, a11y compliance audits, or system accessibility preferences."
+description: "VoiceOver, Voice Control, Switch Control and Full Keyboard Access in SwiftUI, UIKit and AppKit on iOS, iPadOS and macOS: labels, hints, values, traits, accessibilityInputLabels, NSAccessibility, grouping and reading order, @AccessibilityFocusState focus restore, Dynamic Type and @ScaledMetric, rotors, custom actions, XCTest accessibility checks, system accessibility preferences, Accessibility Nutrition Labels and App Store Connect answers. Use when implementing, reviewing or auditing accessibility (a11y). Not for keyboard or directional focus mechanics (Tab order, FocusState, UIFocusGuide): use hig-inputs."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# iOS/macOS Accessibility - SwiftUI, UIKit, and AppKit
-
-Every user-facing view must be usable with VoiceOver, Switch Control, Voice Control, Full Keyboard Access, and other assistive technologies. This skill covers SwiftUI, UIKit, and AppKit patterns required to build accessible iOS, iPadOS, and macOS apps.
-
-## Contents
-
-- [Core Principles](#core-principles)
-- [How VoiceOver Reads Elements](#how-voiceover-reads-elements)
-- [SwiftUI Accessibility Modifiers](#swiftui-accessibility-modifiers)
-- [Focus Management](#focus-management)
-- [Dynamic Type](#dynamic-type)
-- [Custom Rotors](#custom-rotors)
-- [System Accessibility Preferences](#system-accessibility-preferences)
-- [Decorative Content](#decorative-content)
-- [Voice Control](#voice-control)
-- [Switch Control](#switch-control)
-- [Full Keyboard Access](#full-keyboard-access)
-- [Assistive Access (iOS 18+)](#assistive-access-ios-18)
-- [UIKit Accessibility Patterns](#uikit-accessibility-patterns)
-- [AppKit Accessibility Patterns](#appkit-accessibility-patterns)
-- [Accessibility Custom Content](#accessibility-custom-content)
-- [App Store Accessibility Nutrition Labels](#app-store-accessibility-nutrition-labels)
-- [Testing Accessibility](#testing-accessibility)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
----
-
-## Core Principles
-
-1. Every interactive element MUST have an accessible label. If no visible text exists, add `.accessibilityLabel`.
-2. Every custom control MUST have correct traits via `.accessibilityAddTraits` (never direct assignment). For binary custom controls such as favorite/star buttons, prefer a real `Toggle`; otherwise expose toggle behavior with `.accessibilityAddTraits(.isToggle)` and a current state value without putting the control type in the label.
-3. Custom adjustable controls such as quantity steppers MUST expose adjustable behavior with `.accessibilityAdjustableAction`; UIKit custom adjustable controls also need the `.adjustable` trait.
-4. Decorative images MUST be hidden from assistive technologies.
-5. Sheet and dialog dismissals MUST return VoiceOver focus to the trigger element.
-6. All tap targets MUST be at least 44x44 points.
-7. Dynamic Type MUST be supported everywhere (system fonts, `@ScaledMetric`, adaptive layouts).
-8. No information conveyed by color alone -- always provide text or icon alternatives.
-9. System accessibility preferences MUST be respected: Reduce Motion, Reduce Transparency, Bold Text, Increase Contrast.
-
-## How VoiceOver Reads Elements
-
-VoiceOver reads element properties in a fixed, non-configurable order:
-
-**Label -> Value -> Trait -> Hint**
-
-Design your labels, values, and hints with this reading order in mind.
-
-## SwiftUI Accessibility Modifiers
-
-See [references/a11y-patterns.md](references/a11y-patterns.md) for detailed SwiftUI modifier examples (labels, hints, traits, grouping, custom controls, adjustable actions, and custom actions).
-
-## Focus Management
-
-Focus management is where most apps fail. When a sheet, alert, or popover is dismissed, VoiceOver focus MUST return to the element that triggered it.
-
-This section is about accessibility focus for assistive technologies. For keyboard focus, directional focus, `focusSection()`, scene-focused values, and `UIFocusGuide`, use the `focus-engine` skill.
-
-When triaging broad focus bugs, still call out accessibility traversal separately: accessibility element order and grouping in the view hierarchy directly affect VoiceOver swipe order, Switch Control scan order, Voice Control overlay targeting, and Full Keyboard Access reachability review. Route keyboard-focus implementation to `focus-engine`, but keep this traversal impact in `ios-accessibility`.
+# iOS Accessibility
+
+Whatever appears on screen must also work for people who navigate with
+VoiceOver, speak commands through Voice Control, scan with Switch Control, drive
+a hardware keyboard through Full Keyboard Access, or rely on any other
+assistive technology. Platforms: iOS, iPadOS and macOS. Frameworks: SwiftUI,
+UIKit and AppKit.
+
+References:
+
+- [Code patterns](references/a11y-patterns.md): worked examples of the
+  modifiers in both UI frameworks, grouping, custom and adjustable controls, custom actions, rotors,
+  Dynamic Type, AppKit, Voice Control, Switch Control, Full Keyboard Access,
+  XCTest checks.
+- [Nutrition labels](references/nutrition-labels.md): the current App Store
+  label categories and what passes or fails each one.
+- [Media](references/media-accessibility.md): captions, SDH, audio
+  descriptions and `AVMediaCharacteristic`.
+
+## Ground rules
+
+1. Anything interactive has an accessible label. No visible text means you add
+   `.accessibilityLabel`.
+2. Custom controls gain traits with `.accessibilityAddTraits`. Never replace
+   the trait set wholesale.
+3. A two-state custom control (star, pin, favourite) should be a real
+   `Toggle`. If it cannot be, add `.accessibilityAddTraits(.isToggle)`
+   (iOS 17+) and report on/off as the value; the label never says what kind of
+   control it is.
+4. Custom adjustable controls, such as a quantity stepper, implement
+   `.accessibilityAdjustableAction`. In UIKit they also carry the `.adjustable`
+   trait.
+5. Purely decorative images are hidden from assistive technologies.
+6. When a sheet or dialog closes, VoiceOver focus goes back to whatever
+   opened it.
+7. Nothing tappable is smaller than 44x44 points.
+8. Dynamic Type works everywhere: system text styles, `@ScaledMetric`, layouts
+   that adapt.
+9. Color is never the only signal; pair it with text or an icon.
+10. Honour Increase Contrast, Bold Text, Reduce Transparency and Reduce Motion.
+
+## What VoiceOver says, and in which order
+
+VoiceOver speaks an element's parts in a fixed order you cannot change:
+**label, value, trait, hint**. Write each piece knowing what comes before and
+after it, so the sentence as a whole makes sense ("Volume, 60 percent,
+adjustable, swipe up or down to adjust").
+
+Modifier examples for labels, hints, traits, grouping, custom and adjustable
+controls and custom actions: [code patterns](references/a11y-patterns.md).
+
+## Accessibility focus
+
+Focus is where apps most often break for assistive technology users. After a
+sheet, alert or popover goes away, VoiceOver focus must land back on the
+control that opened it.
+
+Scope: this section is about the assistive-technology cursor. `UIFocusGuide`,
+`focusSection()`, scene-focused values, and keyboard or directional focus in
+general are implementation topics for the `hig-inputs` skill. Even when
+triaging a broad focus bug, report accessibility traversal as its own finding:
+the order and grouping of elements decide the path a VoiceOver swipe follows,
+the sequence a switch scan visits, where Voice Control places its overlays and
+whether Full Keyboard Access can get somewhere. The keyboard wiring goes to `hig-inputs`; the traversal impact
+finding stays here.
 
 ### `@AccessibilityFocusState` (iOS 15+)
 
-`@AccessibilityFocusState` is a property wrapper that reads and writes the current accessibility focus. It works with `Bool` for single-target focus or an optional `Hashable` enum for multi-target focus.
+A property wrapper you can read to learn where accessibility focus is and
+write to move it. One target: bind a `Bool`. Several: bind an optional enum
+that conforms to `Hashable`.
 
 ```swift
-struct ContentView: View {
-    @State private var showSheet = false
-    @AccessibilityFocusState private var focusOnTrigger: Bool
+struct ReceiptRow: View {
+    @AccessibilityFocusState private var detailButtonFocused: Bool
+    @State private var showsDetail = false
 
     var body: some View {
-        Button("Open Settings") { showSheet = true }
-            .accessibilityFocused($focusOnTrigger)
-            .sheet(isPresented: $showSheet) {
-                SettingsSheet()
+        Button("Receipt details") { showsDetail = true }
+            .accessibilityFocused($detailButtonFocused)
+            .sheet(isPresented: $showsDetail) {
+                ReceiptDetail()
                     .onDisappear {
-                        // Slight delay allows the transition to complete before moving focus
                         Task { @MainActor in
-                            try? await Task.sleep(for: .milliseconds(100))
-                            focusOnTrigger = true
+                            try? await Task.sleep(for: .seconds(0.1))   // about 100 ms
+                            detailButtonFocused = true
                         }
                     }
             }
@@ -92,368 +98,390 @@ struct ContentView: View {
 }
 ```
 
-### Multi-Target Focus with Enum
+The short pause lets the dismissal animation finish before focus moves;
+moving it mid-transition tends to be ignored. `Task.sleep(for:)` needs iOS 16;
+on iOS 15 use `Task.sleep(nanoseconds: 100_000_000)`.
+
+### Several targets
 
 ```swift
-enum A11yFocus: Hashable {
-    case nameField
-    case emailField
-    case submitButton
-}
+enum SignUpField: Hashable { case handle, password, create }
 
-struct FormView: View {
-    @AccessibilityFocusState private var focus: A11yFocus?
+struct SignUpForm: View {
+    @State private var handle = ""
+    @AccessibilityFocusState private var a11yFocus: SignUpField?
 
     var body: some View {
         Form {
-            TextField("Name", text: $name)
-                .accessibilityFocused($focus, equals: .nameField)
-            TextField("Email", text: $email)
-                .accessibilityFocused($focus, equals: .emailField)
-            Button("Submit") { validate() }
-                .accessibilityFocused($focus, equals: .submitButton)
+            TextField("Handle", text: $handle)
+                .accessibilityFocused($a11yFocus, equals: .handle)
+            // ...same for the password field and the Create account button
         }
     }
 
-    func validate() {
-        if name.isEmpty {
-            focus = .nameField // Move VoiceOver to the invalid field
-        }
-    }
+    private func submit() { if handle.isEmpty { a11yFocus = .handle } }
 }
 ```
 
-### Custom Modals
+When validation fails, assign the case of the offending field and VoiceOver
+jumps straight to it.
+
+### Custom modals
 
-Custom overlay views need the `.isModal` trait to trap VoiceOver focus and an escape action for dismissal:
+A hand-built overlay needs two things: the `.isModal` trait so VoiceOver
+cannot wander outside it, and an escape action so the standard dismiss gesture
+works.
 
 ```swift
-CustomDialog()
+CouponPopover(onClose: close)
     .accessibilityAddTraits(.isModal)
-    .accessibilityAction(.escape) { dismiss() }
+    .accessibilityAction(.escape) { close() }
 ```
 
-Test dismissal as part of the modal contract: users must be able to dismiss the overlay with the relevant assistive-technology escape gesture or keyboard escape path, and focus should return to the trigger or next logical target.
+Closing is part of the modal's contract: test that the VoiceOver escape
+gesture (two-finger scrub) or the keyboard Escape key dismisses it. Afterwards
+focus belongs on the trigger or on the next sensible element.
 
-### Accessibility Notifications (UIKit)
-
-When you need to announce changes or move focus imperatively in UIKit contexts:
+### UIKit notifications
 
 ```swift
-// Announce a status change (e.g., "Item deleted", "Upload complete")
-UIAccessibility.post(notification: .announcement, argument: "Upload complete")
-
-// Partial screen update -- move focus to a specific element
-UIAccessibility.post(notification: .layoutChanged, argument: targetView)
-
-// Full screen transition -- move focus to the new screen
-UIAccessibility.post(notification: .screenChanged, argument: newScreenView)
+UIAccessibility.post(notification: .announcement, argument: "Draft saved")
+UIAccessibility.post(notification: .layoutChanged, argument: errorBanner)
+UIAccessibility.post(notification: .screenChanged, argument: summaryHeader)
 ```
 
-## Dynamic Type
-
-Scale text with system text styles. Scale non-text dimensions too: icon sizes, spacing, control heights, and custom hit-region dimensions should use `@ScaledMetric(relativeTo:)` where they need to track text size.
+- `.announcement`: speak a status change (an export finished, a row was
+  removed).
+- `.layoutChanged`: part of the screen changed; focus moves to the argument.
+- `.screenChanged`: a whole new screen; focus moves to the argument.
 
-See [references/a11y-patterns.md](references/a11y-patterns.md) for Dynamic Type and adaptive layout examples, including `@ScaledMetric` and minimum tap target patterns.
+## Dynamic Type
 
-## Custom Rotors
+Text scales when you use system text styles. Sizes that should grow with the
+text (icons, spacing, control heights, custom hit regions) use
+`@ScaledMetric(relativeTo:)`. Examples, including minimum tap targets:
+[code patterns](references/a11y-patterns.md).
 
-Rotors let VoiceOver users quickly navigate to specific content types. Add custom rotors for content-heavy screens. See [references/a11y-patterns.md](references/a11y-patterns.md) for complete rotor examples.
+## Custom rotors
 
-## System Accessibility Preferences
+A rotor lets a VoiceOver user hop straight between items of one kind, such as
+unread threads or headings. Add them to screens dense with content; see
+[code patterns](references/a11y-patterns.md).
 
-Always respect these environment values:
+## System preferences
 
-```swift
-@Environment(\.accessibilityReduceMotion) var reduceMotion
-@Environment(\.accessibilityReduceTransparency) var reduceTransparency
-@Environment(\.colorSchemeContrast) var contrast         // .standard or .increased
-@Environment(\.legibilityWeight) var legibilityWeight    // .regular or .bold
-```
+| Environment value | Type | Setting |
+|---|---|---|
+| `\.accessibilityReduceMotion` | `Bool` | Reduce Motion |
+| `\.accessibilityReduceTransparency` | `Bool` | Reduce Transparency |
+| `\.colorSchemeContrast` | `.standard` / `.increased` | Increase Contrast |
+| `\.legibilityWeight` | `.regular` / `.bold` | Bold Text |
 
 ### Reduce Motion
 
-Replace movement-based animations with crossfades or no animation:
+With Reduce Motion on, replace movement with a crossfade or with no animation.
 
 ```swift
-withAnimation(reduceMotion ? nil : .spring()) {
-    showContent.toggle()
+struct FilterDrawer: View {
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @State private var isExpanded = false
+
+    var body: some View {
+        VStack {
+            Button("Filters") {
+                withAnimation(reduceMotion ? nil : .spring()) { isExpanded.toggle() }
+            }
+            if isExpanded {
+                PanelView()
+                    .transition(reduceMotion ? .opacity : .move(edge: .bottom))
+            }
+        }
+    }
 }
-content.transition(reduceMotion ? .opacity : .slide)
 ```
 
-Review every moving transition, including row deletion, quantity changes, sheet or checkout presentation, and modal dismissal. Under Reduce Motion, replace slide, bounce, parallax, spring, and large spatial transitions with opacity changes, instant state changes, or no animation.
+Go through every moving transition, not just the obvious one: row removal,
+quantity changes, presenting a sheet or checkout, dismissing a modal. Slides,
+bounces, parallax, springs and big spatial moves become fades, an immediate
+jump to the end state, or no animation at all.
 
-### Reduce Transparency, Increase Contrast, Bold Text
+### Transparency, contrast, bold text
 
 ```swift
-// Solid backgrounds when transparency is reduced
-.background(reduceTransparency ? Color(.systemBackground) : Color(.systemBackground).opacity(0.85))
+@Environment(\.accessibilityReduceTransparency) private var reduceTransparency
+@Environment(\.colorSchemeContrast) private var contrast
+@Environment(\.legibilityWeight) private var legibilityWeight
 
-// Stronger colors when contrast is increased
-.foregroundStyle(contrast == .increased ? .primary : .secondary)
+private let base = Color(uiColor: .systemBackground)
 
-// Bold weight when system bold text is enabled
-.fontWeight(legibilityWeight == .bold ? .bold : .regular)
+var body: some View {
+    Text(caption)
+        .foregroundStyle(contrast == .increased ? .primary : .secondary)
+        .fontWeight(legibilityWeight == .bold ? .bold : .regular)
+        .background(reduceTransparency ? base : base.opacity(0.8))
+}
 ```
 
-## Decorative Content
+## Decorative versus meaningful images
 
 ```swift
-// Decorative images: hidden from VoiceOver
-Image(decorative: "background-pattern")
-Image("visual-divider").accessibilityHidden(true)
-
-// Icon next to text: Label handles this automatically
-Label("Settings", systemImage: "gear")
-
-// Icon-only buttons: MUST have an accessibility label
-Button(action: { }) {
-    Image(systemName: "gear")
+Image(decorative: "confetti")                     // never announced
+Image("wave-divider").accessibilityHidden(true)   // hide an existing image
+Label("Downloads", systemImage: "arrow.down")     // icon folded into the text
+Button { openFilters() } label: {
+    Image(systemName: "slider.horizontal.3")
 }
-.accessibilityLabel("Settings")
+.accessibilityLabel("Filters")                    // icon-only button needs a name
 ```
 
-Treat an image as decorative only when it adds no information beyond adjacent accessible text. If it communicates a product variant, state, chart point, user-generated content, or another distinguishing detail, provide a meaningful description instead of hiding it.
+An image counts as decorative only when nearby accessible text already says
+everything it says. If it shows a product variant, a state, a chart point,
+something a user posted, or any other distinguishing detail, describe it
+instead of hiding it.
 
 ## Voice Control
 
-Voice Control relies on accessibility labels to generate spoken tap targets. If a label is missing or unspeakable, Voice Control cannot target the element.
-
-- Every interactive element MUST have a speakable accessibility label (no emoji-only, no symbol-only).
-- Labels must be unique within the visible screen  -  duplicate labels force users to disambiguate with overlay numbers.
-- Treat `accessibilityInputLabels` as pre-freeze accessibility work for long, awkward, localized, acronym-heavy, or commonly shortened spoken labels; do not defer it as polish. Voice Control and Full Keyboard Access use these. List alternatives in descending order of importance.
-- Apply `accessibilityInputLabels` broadly to any visible target whose primary label is hard to say, including repeated row actions, quantity controls, account/settings links, media controls, and localized labels with acronyms or product names.
-- Test with Voice Control enabled: say "Show Names" and "Show Numbers" to verify all interactive elements are targetable.
-- For Voice Control reviews, verify both overlays: "Show Names" confirms speakable labels, and "Show Numbers" confirms every visible interactive target can still be reached when names are missing, duplicated, or awkward.
-
-See [references/a11y-patterns.md](references/a11y-patterns.md) for `accessibilityInputLabels` examples and speakable label guidelines.
+Spoken commands find their target through its accessibility label: the label
+is the name a person says to tap the element. An element with no label, or a label nobody can say, cannot be
+targeted by voice.
+
+- Every interactive element needs a label a person can say aloud. No labels
+  made only of emoji or symbols.
+- Labels must differ among the elements on screen at the same time;
+  duplicates push users onto overlay numbers.
+- Add `accessibilityInputLabels` before feature freeze, not as late polish,
+  wherever a label is long, clumsy, localized, full of acronyms, or usually
+  shortened when spoken. Both Full Keyboard Access and Voice Control consume
+  them. List the entries most important first.
+- Good candidates: media controls, settings and account links, per-row
+  actions that repeat down a list, quantity steppers, localized labels that
+  contain product names or acronyms.
+- Turn Voice Control on and say "Show Names", then "Show Numbers". The names
+  overlay proves labels can be spoken; the numbers overlay proves every
+  visible target stays reachable even if its name is missing, duplicated or
+  awkward. A review
+  checks both overlays.
+
+Examples and speakable-label guidance: [code patterns](references/a11y-patterns.md).
 
 ## Switch Control
 
-Switch Control scans accessibility elements sequentially in reading order. Proper grouping and custom actions are critical for usability.
-
-- Group related content with `.accessibilityElement(children: .combine)` to reduce scan stops.
-- Every scan target should be meaningful and actionable. Decorative elements hidden from VoiceOver are also hidden from Switch Control.
-- Switch Control users cannot perform swipe-to-delete, long-press, or multi-finger gestures. Expose these interactions as `.accessibilityAction(named:)` custom actions instead  -  Switch Control presents them as a menu.
-- Custom controls with non-standard hit areas should ensure `accessibilityFrame` accurately reflects the tappable region (for point scanning mode).
+Switch Control steps through accessibility elements one at a time in reading
+order, so grouping and custom actions matter more here than anywhere else.
 
-See [references/a11y-patterns.md](references/a11y-patterns.md) for custom action and grouping examples.
+- `.accessibilityElement(children: .combine)` merges related pieces and
+  removes scan stops. Each remaining stop should mean something and do
+  something.
+- Anything hidden from VoiceOver as decorative is skipped by Switch Control
+  too.
+- Multi-finger gestures, long presses and swipe-to-delete are out of reach
+  for switch users. Offer those operations as `.accessibilityAction(named:)`; Switch
+  Control lists them in a menu.
+- In point scanning mode, a custom control whose tappable area is unusual
+  must report an `accessibilityFrame` that matches that area.
 
 ## Full Keyboard Access
 
-Full Keyboard Access (iOS/iPadOS 13.4+) lets users navigate and operate an app with a hardware keyboard.
-
-This skill covers the accessibility review surface: whether all controls are reachable, clearly labeled, visibly focused, and operable without touch. If the bug is Tab traversal, skipped custom cards, `.focusable()`, `@FocusState`, `focusSection()`, directional movement, scene-focused values, tvOS focus behavior, or `UIFocusGuide`, route implementation to the `focus-engine` skill first. Keep only the accessibility finding here.
-
-- Every interactive element can be reached and activated with the keyboard.
-- Traversal order is logical and does not trap focus.
-- Focus indicators remain visible at all contrast and text-size settings.
-- Gesture-only behavior has a keyboard-operable alternative.
-- App shortcuts do not override system-defined shortcuts such as Cmd+C, Cmd+V, or Cmd+Tab.
-
-See [references/a11y-patterns.md](references/a11y-patterns.md) for Full Keyboard Access audit checks.
-
-## Traversal Order
-
-Explicitly assess how accessibility element order and grouping affect traversal outcomes: VoiceOver swipe order, Switch Control scan order, Voice Control overlay targeting, and Full Keyboard Access reachability review can all break when grouping/order differs from visual or task order. Missing labels, duplicate labels, excessive row children, hidden custom controls, or grouping that does not match the visual/task order can make traversal confusing across all of them. Keep implementation mechanics for keyboard or directional routing in `focus-engine`; keep the accessibility impact and ordering audit here.
+Available since iOS and iPadOS 13.4, Full Keyboard Access lets people run the
+app from a hardware keyboard. This skill owns the review: can everything be
+reached, is it clearly labelled, is focus visible, does it work without touch.
+`UIFocusGuide`, tvOS focus, scene-focused values, directional movement,
+`focusSection()`, `@FocusState`, `.focusable()`, custom cards that Tab jumps
+over, and Tab traversal bugs in general go to `hig-inputs` first; only the accessibility finding
+stays here.
+
+Audit:
+
+- the keyboard alone can reach and trigger every interactive element;
+- the traversal order makes sense and never traps focus;
+- focus indicators stay visible at every contrast and text-size setting;
+- anything that only works through a gesture has a keyboard route;
+- the app's own shortcuts leave system ones (Cmd+C, Cmd+V, Cmd+Tab) alone.
+
+## Traversal order
+
+Always judge the effect of ordering and grouping on four things at once: the
+path of VoiceOver swipes, the steps of a switch scan, where Voice Control
+overlays land, and what the keyboard can reach. All four go wrong together
+when grouping or order disagrees with the visual layout or the task order. Usual causes:
+missing labels, duplicate labels, rows exposing too many children, custom
+controls hidden from accessibility, grouping that does not match what the eye
+sees. The keyboard and directional routing mechanics are `hig-inputs` work;
+the ordering audit and its accessibility impact are reported here.
 
 ## Assistive Access (iOS 18+)
 
-Assistive Access provides a simplified interface for users with cognitive disabilities. Apps should support this mode:
+This pared-down system mode serves people with cognitive disabilities, and
+apps should behave well inside it.
 
 ```swift
-// Check if Assistive Access is active (iOS 18+)
-@Environment(\.accessibilityAssistiveAccessEnabled) var isAssistiveAccessEnabled
+struct LibraryScreen: View {
+    @Environment(\.accessibilityAssistiveAccessEnabled) private var assistiveAccess
 
-var body: some View {
-    if isAssistiveAccessEnabled {
-        SimplifiedContentView()
-    } else {
-        FullContentView()
+    var body: some View {
+        if assistiveAccess { SimpleLibraryView() } else { FullLibraryView() }
     }
 }
 ```
 
-Key guidelines:
-- Reduce visual complexity: fewer controls, larger tap targets, simpler navigation
-- Use clear, literal language for labels and instructions
-- Minimize the number of choices presented at once
-- Test with Assistive Access enabled in Settings > Accessibility > Assistive Access
+- Less on screen: fewer controls, bigger targets, flatter navigation.
+- Literal, plain wording in labels and instructions.
+- Only a few choices at a time.
+- Try it under Settings > Accessibility > Assistive Access.
 
-## UIKit Accessibility Patterns
+From iOS 26 an app can also declare `UISupportsAssistiveAccess` in its
+Info.plist and provide a dedicated `AssistiveAccess` scene.
 
-When working with UIKit views:
+## UIKit
 
-- Set `isAccessibilityElement = true` on meaningful custom views.
-- Set `accessibilityLabel` on all interactive elements without visible text.
-- Use `.insert()` and `.remove()` for trait modification (not direct assignment).
-- Set `accessibilityViewIsModal = true` on custom overlay views to trap focus.
-- Post `.announcement` for transient status messages.
-- Post `.layoutChanged` with a target view for partial screen updates.
-- Post `.screenChanged` for full screen transitions.
+- `isAccessibilityElement = true` on custom views that carry meaning.
+- `accessibilityLabel` on every interactive element without visible text.
+- Change traits with `.insert()` and `.remove()` instead of assigning:
+  `badgeView.accessibilityTraits.insert(.button)`,
+  `badgeView.accessibilityTraits.remove(.staticText)`.
+- `accessibilityViewIsModal = true` on custom overlays to keep focus inside.
+- Post `.announcement` for passing status, `.layoutChanged` with a target for
+  partial updates, `.screenChanged` for full transitions.
 
-```swift
-// UIKit trait modification
-customButton.accessibilityTraits.insert(.button)
-customButton.accessibilityTraits.remove(.staticText)
+## AppKit
 
-// Modal overlay
-overlayView.accessibilityViewIsModal = true
-```
+AppKit accessibility rests on `NSAccessibilityProtocol` plus role-specific
+protocols. Standard controls already publish most of what assistive apps need,
+including notifications, so prefer them and customise only where the defaults
+fall short.
 
-## AppKit Accessibility Patterns
+- A custom `NSView` adopts the right role behaviour and reports its role,
+  label, value and supported actions accurately.
+- Items with no view behind them use `NSAccessibilityElement`.
+- Post `NSAccessibility` notifications when a change must reach assistive
+  apps.
 
-AppKit accessibility uses `NSAccessibilityProtocol` and related role-specific protocols to describe accessible elements. Standard AppKit controls already provide much of this behavior; customize labels, values, roles, and actions only when the defaults are insufficient.
+The full custom-view example (a toggle-like `NSView` returning role, label,
+"On"/"Off" value and a press action, posting `.valueChanged` when its state
+changes) and `NSAccessibilityElement` usage are in
+[code patterns](references/a11y-patterns.md#appkit).
 
-- Prefer standard AppKit controls first  -  they already expose accessibility metadata and notifications.
-- For custom `NSView` subclasses, adopt the appropriate role-specific accessibility behavior and return the correct role, label, value, and actions.
-- Use `NSAccessibilityElement` for accessible items that are not backed by their own `NSView`.
-- Post `NSAccessibility` notifications when state changes need to be announced to assistive apps.
+## Custom content
 
-```swift
-final class FavoriteToggleView: NSView {
-    var isFavorite = false {
-        didSet {
-            NSAccessibility.post(element: self, notification: .valueChanged)
-        }
-    }
-
-    override func isAccessibilityElement() -> Bool { true }
-    override func accessibilityRole() -> NSAccessibility.Role? { .button }
-    override func accessibilityLabel() -> String? { "Favorite" }
-    override func accessibilityValue() -> Any? { isFavorite ? "On" : "Off" }
-
-    override func accessibilityPerformPress() -> Bool {
-        isFavorite.toggle()
-        return true
-    }
-}
-```
-
-See [references/a11y-patterns.md](references/a11y-patterns.md) for AppKit examples including `NSAccessibilityElement` and announcement notifications.
-
-## Accessibility Custom Content
-
-See [references/a11y-patterns.md](references/a11y-patterns.md) for UIKit and AppKit accessibility patterns and custom content examples.
+`.accessibilityCustomContent` attaches extra labelled facts to an element.
+By default VoiceOver offers them only on request (More Content rotor); with
+`importance: .high` they are read along with the element.
 
 ```swift
-ProductRow(product: product)
-    .accessibilityCustomContent("Price", product.formattedPrice)
-    .accessibilityCustomContent("Rating", "\(product.rating) out of 5")
-    .accessibilityCustomContent(
-        "Availability",
-        product.inStock ? "In stock" : "Out of stock",
-        importance: .high  // .high reads automatically with the element
-    )
+HotelCard(hotel: hotel)
+    .accessibilityCustomContent("Nightly rate", Text(hotel.rateText), importance: .high)
+    .accessibilityCustomContent("Guest score", Text(hotel.scoreText))
 ```
 
-## App Store Accessibility Nutrition Labels
-
-For App Store accessibility nutrition labels, product-page claims, or App Store Connect accessibility answers, read [references/nutrition-labels.md](references/nutrition-labels.md).
-
-Before recommending a claim, require evidence that users can complete all common tasks with that feature on the relevant device type. Use a structured common-task by accessibility-feature matrix, include media transcripts when captions for audio-only content are relevant, and explicitly warn that App Store accessibility answers must stay accurate and must not be treated as marketing claims.
-
-## Testing Accessibility
-
-### Manual Testing
+More UIKit, AppKit and custom-content examples:
+[code patterns](references/a11y-patterns.md).
 
-- **Accessibility Inspector** (Xcode > Open Developer Tool): Audit views for missing labels, traits, and contrast issues. Run audits against the Simulator or connected device.
-- **VoiceOver testing**: Enable in Settings > Accessibility > VoiceOver. Navigate every screen with swipe gestures.
-- **Voice Control testing**: Enable in Settings > Accessibility > Voice Control. Say both "Show Names" and "Show Numbers"; names verify speakable labels, while numbers verify every visible interactive target is reachable even when names are duplicated, missing, or awkward.
-- **Full Keyboard Access testing**: Enable in Settings > Accessibility > Keyboards > Full Keyboard Access. Tab through every screen and verify all interactive elements receive focus.
-- **Switch Control testing**: Enable in Settings > Accessibility > Switch Control. Verify scan order is logical and custom actions appear for gesture-based interactions.
-- **Dynamic Type**: Test with all text sizes in Settings > Accessibility > Display & Text Size > Larger Text.
+## App Store Accessibility Nutrition Labels
 
-### Automated Testing with XCTest
+Questions about the labels, accessibility claims on the product page, or the
+accessibility answers in App Store Connect: open the
+[nutrition label reference](references/nutrition-labels.md) first. A claim is
+only recommended after you:
 
-Use `XCUIElement` accessibility attributes to write UI tests that verify accessibility properties:
+- ask for evidence that users can finish every common task with that feature
+  on the device type in question;
+- lay the evidence out as a matrix of common tasks against features;
+- include transcripts where audio-only content needs a text equivalent;
+- say plainly that these answers must stay accurate and are not marketing.
 
-```swift
-func testProductRowAccessibility() throws {
-    let app = XCUIApplication()
-    app.launch()
+## Testing
 
-    let productCell = app.cells["product-organic-apples"]
-    XCTAssertTrue(productCell.exists)
-    XCTAssertTrue(productCell.isEnabled)
+### By hand
 
-    // Verify the label is set and meaningful
-    XCTAssertFalse(productCell.label.isEmpty)
+| Tool | What to do | Where |
+|---|---|---|
+| Accessibility Inspector | Run an audit against the Simulator or a device; it reports contrast issues, absent labels and wrong traits | Xcode > Open Developer Tool |
+| VoiceOver | Swipe from the first element to the last on each screen | Settings > Accessibility > VoiceOver |
+| Voice Control | Say "Show Names", then "Show Numbers" | Settings > Accessibility > Voice Control |
+| Full Keyboard Access | Press Tab across each screen and confirm each control receives focus | Settings > Accessibility > Keyboards > Full Keyboard Access |
+| Switch Control | Watch the scan order; gesture features need custom actions | Settings > Accessibility > Switch Control |
+| Dynamic Type | Step through the whole size range | Settings > Accessibility > Display & Text Size > Larger Text |
 
-    // Verify a specific element has the expected label
-    let favoriteButton = productCell.buttons["Favorite"]
-    XCTAssertTrue(favoriteButton.exists)
-    XCTAssertTrue(favoriteButton.isEnabled)
-}
-```
-
-Key `XCUIElementAttributes` properties for accessibility verification: `label`, `identifier`, `value`, `isEnabled`, `hasFocus`, `isSelected`, `placeholderValue`, `title`.
+### With XCTest
 
-Test dismissal focus restoration:
+UI tests can assert accessibility through `XCUIElement` attributes. The useful
+ones in `XCUIElementAttributes` are `identifier`, `label`, `title`, `value`,
+`placeholderValue`, `isSelected`, `isEnabled` and `hasFocus`.
 
 ```swift
-func testSheetDismissReturnsFocus() throws {
+@MainActor
+func testFocusReturnsAfterSheet() {
     let app = XCUIApplication()
     app.launch()
 
-    let triggerButton = app.buttons["Open Settings"]
-    triggerButton.tap()
-
-    // Dismiss the sheet
-    let doneButton = app.buttons["Done"]
-    doneButton.tap()
-
-    // Verify focus returns to trigger (in accessibility-focused testing)
-    XCTAssertTrue(triggerButton.hasFocus)
+    let opener = app.buttons["Seat map"]
+    opener.tap()
+    app.buttons["Done"].tap()
+    XCTAssertTrue(opener.hasFocus)
 }
 ```
 
-## Common Mistakes
-
-1. **Direct trait assignment**: UIKit trait mutation or incorrect SwiftUI trait APIs can overwrite existing behavior. In SwiftUI, use `.accessibilityAddTraits(.isButton)`.
-2. **Missing focus restoration**: Dismissing sheets without returning VoiceOver focus to the trigger element.
-3. **Ungrouped list rows**: Multiple text elements per row create excessive swipe stops. Use `.accessibilityElement(children: .combine)`.
-4. **Redundant trait in labels**: `.accessibilityLabel("Settings button")` reads as "Settings button, button." Omit the type.
-5. **Missing labels on icon-only buttons**: Every `Image`-only button MUST have `.accessibilityLabel`.
-6. **Ignoring Reduce Motion**: Always check `accessibilityReduceMotion` before movement animations.
-7. **Fixed font sizes**: `.font(.system(size: 16))` ignores Dynamic Type. Use `.font(.body)` or similar text styles.
-8. **Small tap targets**: Icons without `frame(minWidth: 44, minHeight: 44)` and `.contentShape()`.
-9. **Color as sole indicator**: Red/green for error/success without text or icon alternatives.
-10. **Missing `.isModal` on overlays**: Custom modals without `.accessibilityAddTraits(.isModal)` let VoiceOver escape.
-
-## Review Checklist
-
-For every user-facing view, verify:
-
-- [ ] Every interactive element has an accessible label
-- [ ] Custom controls use correct traits via `.accessibilityAddTraits`
-- [ ] Adjustable custom controls expose adjustable behavior with `.accessibilityAdjustableAction` or UIKit `.adjustable`
-- [ ] Decorative images are hidden (`Image(decorative:)` or `.accessibilityHidden(true)`)
-- [ ] List rows group content with `.accessibilityElement(children: .combine)`
-- [ ] Sheets and dialogs return focus to the trigger on dismiss
-- [ ] Custom overlays have `.isModal` trait and escape action
-- [ ] All tap targets are at least 44x44 points
-- [ ] Dynamic Type supported (`@ScaledMetric`, system fonts, adaptive layouts)
-- [ ] Reduce Motion respected (no movement animations when enabled)
-- [ ] Row, checkout, sheet, and modal animations have Reduce Motion alternatives
-- [ ] Reduce Transparency respected (solid backgrounds when enabled)
-- [ ] Increase Contrast respected (stronger foreground colors)
-- [ ] No information conveyed by color alone
-- [ ] Custom actions provided for swipe-to-reveal and context menu features
-- [ ] Icon-only buttons have labels
-- [ ] Heading traits set on section headers
-- [ ] Custom accessibility types and notification payloads are `Sendable` when passed across concurrency boundaries
-- [ ] Labels are speakable and unique for Voice Control (no emoji-only or duplicate labels on screen)
-- [ ] Voice Control testing covers both "Show Names" and "Show Numbers"
-- [ ] `accessibilityInputLabels` provided for elements with long or awkward primary labels
-- [ ] Gesture-based interactions (swipe-to-delete, long-press) have accessibility custom action equivalents for Switch Control
-- [ ] Full Keyboard Access reaches and activates every control without focus traps
-- [ ] Element order and grouping are checked for traversal impact across VoiceOver, Switch Control, Voice Control overlays, and Full Keyboard Access review
-- [ ] System keyboard shortcuts are not overridden
-
-## References
-
-- [references/a11y-patterns.md](references/a11y-patterns.md)  -  SwiftUI and UIKit modifier examples, grouping, custom actions, rotors, Dynamic Type
-- [references/nutrition-labels.md](references/nutrition-labels.md)  -  App Store Accessibility Nutrition Labels: current categories with pass/fail criteria
-- [references/media-accessibility.md](references/media-accessibility.md)  -  Captions, audio descriptions, AVMediaCharacteristic, SDH
+A row test (querying `app.cells["id"]`, asserting `exists`, `isEnabled`, a
+non-empty `label` and a nested `buttons[...]` query) is in
+[code patterns](references/a11y-patterns.md#automated-checks-with-xctest).
+
+`hasFocus` reports keyboard focus (Full Keyboard Access, hardware keyboard),
+not the VoiceOver cursor, which XCTest cannot observe. Confirm VoiceOver focus
+restoration by hand as well.
+
+## Mistakes seen most often
+
+- Assigning traits (or using the wrong trait API) wipes existing behaviour;
+  use `.accessibilityAddTraits(.isButton)`.
+- A sheet closes and VoiceOver focus is not put back on its trigger.
+- Ungrouped list rows, one swipe stop per subview; combine them.
+- The control type inside the label: `.accessibilityLabel("Filter button")`
+  is heard as "Filter button, button".
+- `Image`-only buttons without `.accessibilityLabel`.
+- Movement animations that never check `accessibilityReduceMotion`.
+- Fixed sizes like `.font(.system(size: 15))` instead of `.font(.body)`.
+- Small targets; fix with `.frame(minWidth: 44, minHeight: 44)` and
+  `.contentShape(Rectangle())`.
+- Red versus green as the only error or success signal.
+- A custom modal without `.accessibilityAddTraits(.isModal)`, so VoiceOver
+  wanders out of it.
+
+## Review checklist
+
+- [ ] Every interactive element has a label.
+- [ ] Custom controls get traits through `.accessibilityAddTraits`.
+- [ ] Adjustable custom controls use `.accessibilityAdjustableAction`, or the
+      UIKit `.adjustable` trait.
+- [ ] Decorative images are hidden (`Image(decorative:)` or
+      `.accessibilityHidden(true)`).
+- [ ] Sheets and dialogs give focus back to their trigger.
+- [ ] Each list row is a single combined element
+      (`.accessibilityElement(children: .combine)`).
+- [ ] Custom overlays carry `.isModal` and an escape action.
+- [ ] Every tap target is at least 44x44 pt.
+- [ ] Dynamic Type works (`@ScaledMetric`, system fonts, adaptive layout).
+- [ ] Reduce Motion removes movement animations.
+- [ ] Each animated flow (sheet, modal, checkout, row changes) has a
+      reduced-motion version.
+- [ ] Reduce Transparency gets solid backgrounds.
+- [ ] Increase Contrast gets stronger foreground colors.
+- [ ] Nothing is communicated by color alone.
+- [ ] Context menus and swipe-revealed actions are also offered as custom
+      actions.
+- [ ] Icon-only buttons are labelled.
+- [ ] Section headers have the header trait.
+- [ ] Any custom accessibility type or notification payload that crosses an
+      isolation boundary conforms to `Sendable`.
+- [ ] Voice Control labels are speakable and unique (no emoji-only labels, no
+      duplicates on screen).
+- [ ] Voice Control was exercised with the "Show Numbers" overlay as well as
+      "Show Names".
+- [ ] Long or awkward labels have `accessibilityInputLabels`.
+- [ ] Long-press and swipe-to-delete can also be done through custom actions,
+      for switch users.
+- [ ] With Full Keyboard Access every control can be reached and triggered,
+      and focus never gets stuck.
+- [ ] Ordering and grouping were reviewed for their effect on all four
+      traversal paths (VoiceOver, switch scanning, Voice Control overlays,
+      keyboard).
+- [ ] The app leaves system keyboard shortcuts alone.