buildanything 1.7.1 → 2.0.0

package/skills/ios/swift-accessibility/references/voiceover-uikit.md

@@ -0,0 +1,519 @@
+# VoiceOver — UIKit
+
+## Contents
+- [Core UIAccessibility Properties](#core-uiaccessibility-properties)
+- [UIAccessibilityTraits Reference](#uiaccessibilitytraits-reference)
+- [UIAccessibilityElement - Custom Elements](#uiaccessibilityelement---custom-elements)
+- [UIAccessibilityContainer - Element Ordering](#uiaccessibilitycontainer---element-ordering)
+- [UIAccessibilityCustomAction - Custom Actions](#uiaccessibilitycustomaction---custom-actions)
+- [UIAccessibilityCustomRotor - Custom Navigation](#uiaccessibilitycustomrotor---custom-navigation)
+- [Notifications - Announcements and Focus](#notifications---announcements-and-focus)
+- [UIAccessibilityReadingContent](#uiaccessibilityreadingcontent)
+- [Modal Views](#modal-views)
+- [Custom Control Patterns](#custom-control-patterns)
+- [NSAttributedString Accessibility Attributes](#nsattributedstring-accessibility-attributes)
+- [Common Mistakes](#common-mistakes)
+
+---
+
+## Core UIAccessibility Properties
+
+Every `UIView` subclass exposes these properties. Override them to provide accessibility information.
+
+```swift
+class RatingView: UIView {
+    var rating: Int = 0 {
+        didSet {
+            // Notify VoiceOver that value changed
+            UIAccessibility.post(notification: .layoutChanged, argument: self)
+        }
+    }
+
+    // REQUIRED: opt this view into the accessibility tree
+    override var isAccessibilityElement: Bool {
+        get { true }
+        set { }
+    }
+
+    override var accessibilityLabel: String? {
+        get { "Rating" }
+        set { }
+    }
+
+    override var accessibilityValue: String? {
+        get { "\(rating) out of 5 stars" }
+        set { }
+    }
+
+    override var accessibilityHint: String? {
+        get { "Double-tap and hold, then swipe up or down to change" }
+        set { }
+    }
+
+    override var accessibilityTraits: UIAccessibilityTraits {
+        get { .adjustable }
+        set { }
+    }
+
+    // Support increment/decrement gestures (VoiceOver swipe up/down)
+    override func accessibilityIncrement() {
+        rating = min(5, rating + 1)
+    }
+
+    override func accessibilityDecrement() {
+        rating = max(0, rating - 1)
+    }
+}
+```
+
+### Key Properties
+
+| Property | Type | Purpose |
+|---|---|---|
+| `isAccessibilityElement` | `Bool` | Opt view into accessibility tree |
+| `accessibilityLabel` | `String?` | Announced name (required for non-text elements) |
+| `accessibilityHint` | `String?` | Describes the result of activating |
+| `accessibilityValue` | `String?` | Current value (sliders, progress) |
+| `accessibilityTraits` | `UIAccessibilityTraits` | Semantic role and state |
+| `accessibilityFrame` | `CGRect` | Accessibility hit area (in screen coordinates) |
+| `accessibilityPath` | `UIBezierPath?` | Custom non-rectangular hit area |
+| `accessibilityActivationPoint` | `CGPoint` | Precise tap point |
+| `accessibilityViewIsModal` | `Bool` | Constrain VoiceOver focus to this view |
+| `shouldGroupAccessibilityChildren` | `Bool` | Group children for scanning |
+| `accessibilityNavigationStyle` | `UIAccessibilityNavigationStyle` | `.automatic` / `.combined` / `.separate` |
+| `accessibilityCustomActions` | `[UIAccessibilityCustomAction]?` | Custom action list |
+| `accessibilityCustomRotors` | `[UIAccessibilityCustomRotor]?` | Custom rotor navigation |
+| `accessibilityContainerType` | `UIAccessibilityContainerType` | `.none` / `.list` / `.landmark` / `.semanticGroup` / `.table` / `.dataTable` |
+
+### `accessibilityFrame` — Custom Hit Area
+
+By default, `accessibilityFrame` matches the view's frame in screen coordinates. Override when the visual and accessible areas differ.
+
+```swift
+override var accessibilityFrame: CGRect {
+    // Convert to screen coordinates
+    return UIAccessibility.convertToScreenCoordinates(bounds, in: self)
+}
+
+// Extend hit area to 44pt minimum
+override var accessibilityFrame: CGRect {
+    let frame = convert(bounds, to: nil)
+    let minSize: CGFloat = 44
+    let expandX = max(0, (minSize - frame.width) / 2)
+    let expandY = max(0, (minSize - frame.height) / 2)
+    return frame.insetBy(dx: -expandX, dy: -expandY)
+}
+```
+
+---
+
+## UIAccessibilityTraits Reference
+
+Traits can be combined with `|` (union).
+
+```swift
+accessibilityTraits = [.button, .selected]
+```
+
+| Trait | When to Use |
+|---|---|
+| `.button` | Any tappable element that isn't a `UIButton` |
+| `.link` | Opens a URL or navigates outside the app |
+| `.header` | Section or page header |
+| `.selected` | Currently selected item |
+| `.image` | Image view (decorative or informational) |
+| `.searchField` | Search text field |
+| `.playsSound` | Activation plays audio |
+| `.keyboardKey` | Custom keyboard key |
+| `.staticText` | Non-interactive display text |
+| `.summaryElement` | Spoken when app first launches |
+| `.notEnabled` | Disabled/unavailable control |
+| `.updatesFrequently` | Live region — re-read on value change |
+| `.startsMediaSession` | Starts audio/video playback |
+| `.adjustable` | Supports increment/decrement |
+| `.allowsDirectInteraction` | Passes raw touches (piano keys, drawing) |
+| `.causesPageTurn` | Triggers a page turn in reading apps |
+| `.tabBar` | Tab bar (system-handled) |
+
+### State via Traits
+
+```swift
+// ✅ Selected state as trait
+cell.accessibilityTraits = isSelected ? [.button, .selected] : .button
+
+// ❌ State embedded in label (breaks automation and is verbose)
+cell.accessibilityLabel = isSelected ? "Photos, selected" : "Photos"
+```
+
+---
+
+## UIAccessibilityElement - Custom Elements
+
+Use when content is drawn in a custom view (`drawRect`, Core Graphics, Metal) with no native subviews. `UIAccessibilityElement` creates virtual elements over the custom-drawn content.
+
+```swift
+class GraphView: UIView {
+    var bars: [BarData] = []
+
+    // Cache elements — recreate when data changes
+    private var _accessibilityElements: [UIAccessibilityElement]?
+
+    override var isAccessibilityElement: Bool {
+        get { false }   // Container itself is NOT an element
+        set { }
+    }
+
+    override var accessibilityElements: [Any]? {
+        get {
+            if _accessibilityElements == nil {
+                _accessibilityElements = bars.enumerated().map { index, bar in
+                    let element = UIAccessibilityElement(accessibilityContainer: self)
+                    element.accessibilityLabel = bar.label
+                    element.accessibilityValue = "\(bar.value) units"
+                    element.accessibilityTraits = .staticText
+                    // Convert bar's CGRect to screen coordinates
+                    let barFrame = frameForBar(at: index)
+                    element.accessibilityFrame = UIAccessibility.convertToScreenCoordinates(barFrame, in: self)
+                    return element
+                }
+            }
+            return _accessibilityElements
+        }
+        set { _accessibilityElements = newValue as? [UIAccessibilityElement] }
+    }
+
+    func dataDidChange() {
+        _accessibilityElements = nil
+        // Tell VoiceOver the layout changed
+        UIAccessibility.post(notification: .layoutChanged, argument: nil)
+    }
+}
+```
+
+---
+
+## UIAccessibilityContainer - Element Ordering
+
+When a view contains multiple subviews that should be navigated in a specific order, implement `UIAccessibilityContainer` by providing `accessibilityElements`.
+
+```swift
+class DashboardView: UIView {
+    @IBOutlet var headerView: UIView!
+    @IBOutlet var chartView: UIView!
+    @IBOutlet var summaryLabel: UILabel!
+    @IBOutlet var actionButton: UIButton!
+
+    // Return elements in the desired reading order
+    override var accessibilityElements: [Any]? {
+        get { [headerView!, summaryLabel!, chartView!, actionButton!] }
+        set { }
+    }
+}
+```
+
+### `accessibilityContainerType`
+
+Provides semantic meaning to containers. VoiceOver announces container type changes.
+
+```swift
+tableContainerView.accessibilityContainerType = .dataTable
+listView.accessibilityContainerType = .list
+navContainerView.accessibilityContainerType = .landmark
+```
+
+### `shouldGroupAccessibilityChildren`
+
+Groups all children into a single node for Switch Control scanning. Does NOT merge for VoiceOver navigation.
+
+```swift
+groupView.shouldGroupAccessibilityChildren = true
+```
+
+---
+
+## UIAccessibilityCustomAction - Custom Actions
+
+Adds entries to VoiceOver's Actions rotor (double-tap and hold → swipe up/down). Essential for swipe-to-reveal and long-press menus.
+
+```swift
+class MessageCell: UITableViewCell {
+    override var accessibilityCustomActions: [UIAccessibilityCustomAction]? {
+        get {
+            [
+                UIAccessibilityCustomAction(name: "Reply", target: self, selector: #selector(reply)),
+                UIAccessibilityCustomAction(name: "Forward", target: self, selector: #selector(forward)),
+                UIAccessibilityCustomAction(name: "Delete", image: UIImage(systemName: "trash")) { [weak self] _ in
+                    self?.deleteMessage()
+                    return true
+                }
+            ]
+        }
+        set { }
+    }
+
+    @objc private func reply() -> Bool {
+        replyToMessage()
+        return true  // return true = action succeeded
+    }
+
+    @objc private func forward() -> Bool {
+        forwardMessage()
+        return true
+    }
+}
+```
+
+**Return value:** Return `true` if the action was performed, `false` if not applicable.
+
+---
+
+## UIAccessibilityCustomRotor - Custom Navigation
+
+Creates new items in VoiceOver's rotor for app-specific navigation (e.g., jump between headings, unread items, errors).
+
+```swift
+class ArticleViewController: UIViewController {
+    var headings: [Heading] = []
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        accessibilityCustomRotors = [makeHeadingRotor(), makeBookmarkRotor()]
+    }
+
+    private func makeHeadingRotor() -> UIAccessibilityCustomRotor {
+        UIAccessibilityCustomRotor(name: "Headings") { [weak self] predicate in
+            guard let self = self else { return nil }
+
+            let currentIndex = self.headings.firstIndex { $0.view == predicate.currentItem.targetElement as? UIView }
+            let nextIndex: Int
+
+            switch predicate.searchDirection {
+            case .next:
+                nextIndex = (currentIndex.map { $0 + 1 }) ?? 0
+            case .previous:
+                nextIndex = currentIndex.map { $0 - 1 } ?? self.headings.count - 1
+            @unknown default:
+                return nil
+            }
+
+            guard nextIndex >= 0, nextIndex < self.headings.count else { return nil }
+            let heading = self.headings[nextIndex]
+            return UIAccessibilityCustomRotorItemResult(targetElement: heading.view, targetRange: nil)
+        }
+    }
+}
+```
+
+---
+
+## Notifications - Announcements and Focus
+
+### Post an Announcement
+
+```swift
+// Simple string announcement
+UIAccessibility.post(notification: .announcement, argument: "Message sent")
+
+// Attributed string for priority control (iOS 17+)
+let announcement = NSAttributedString(
+    string: "Emergency alert",
+    attributes: [.accessibilitySpeechQueueAnnouncement: true]
+)
+UIAccessibility.post(notification: .announcement, argument: announcement)
+```
+
+### Screen Changed — Full Focus Reset
+
+Post when the entire screen content changes (e.g., modal presented, tab switched).
+
+```swift
+// Focus moves to the first element
+UIAccessibility.post(notification: .screenChanged, argument: nil)
+
+// Focus moves to a specific view
+UIAccessibility.post(notification: .screenChanged, argument: confirmButton)
+```
+
+### Layout Changed — Partial Update
+
+Post when part of the layout changes (section expands, items load, error appears).
+
+```swift
+UIAccessibility.post(notification: .layoutChanged, argument: errorLabel)
+```
+
+### Page Scrolled
+
+```swift
+UIAccessibility.post(notification: .pageScrolled, argument: "Page 3 of 10")
+```
+
+### Observing Status Changes
+
+```swift
+NotificationCenter.default.addObserver(
+    self,
+    selector: #selector(voiceOverStatusChanged),
+    name: UIAccessibility.voiceOverStatusDidChangeNotification,
+    object: nil
+)
+
+@objc func voiceOverStatusChanged() {
+    // Update UI if needed — but avoid branching core logic on VoiceOver status
+}
+```
+
+---
+
+## UIAccessibilityReadingContent
+
+For views that display long-form text (e-book readers, document viewers). Enables VoiceOver's "Read All" and line-by-line navigation.
+
+```swift
+class BookPageView: UIView, UIAccessibilityReadingContent {
+    var lines: [String] = []
+
+    func accessibilityLineNumber(for point: CGPoint) -> Int {
+        return lineIndex(for: point)
+    }
+
+    func accessibilityContent(forLineNumber lineNumber: Int) -> String? {
+        guard lineNumber < lines.count else { return nil }
+        return lines[lineNumber]
+    }
+
+    func accessibilityFrame(forLineNumber lineNumber: Int) -> CGRect {
+        return UIAccessibility.convertToScreenCoordinates(
+            frameForLine(lineNumber), in: self
+        )
+    }
+
+    func accessibilityPageContent() -> String? {
+        return lines.joined(separator: " ")
+    }
+}
+```
+
+---
+
+## Modal Views
+
+When a modal or alert is presented, VoiceOver must be prevented from reaching background content.
+
+```swift
+class ModalView: UIView {
+    override var accessibilityViewIsModal: Bool {
+        get { true }
+        set { }
+    }
+}
+
+// When presenting:
+func presentModal() {
+    let modal = ModalView()
+    view.addSubview(modal)
+    // VoiceOver now ignores everything behind modal
+    UIAccessibility.post(notification: .screenChanged, argument: modal.firstInteractiveElement)
+}
+
+// Support Escape to dismiss (VO two-finger Z)
+override func accessibilityPerformEscape() -> Bool {
+    dismiss()
+    return true
+}
+```
+
+---
+
+## Custom Control Patterns
+
+### Toggle / Checkbox
+
+```swift
+class AccessibleCheckbox: UIControl {
+    var isChecked: Bool = false {
+        didSet { accessibilityValue = isChecked ? "On" : "Off" }
+    }
+
+    override var isAccessibilityElement: Bool { get { true } set {} }
+    override var accessibilityLabel: String? { get { title } set {} }
+    override var accessibilityTraits: UIAccessibilityTraits {
+        get { isChecked ? [.button, .selected] : .button }
+        set {}
+    }
+
+    // Or use .toggleButton trait (iOS 17+)
+}
+```
+
+### Custom Slider
+
+```swift
+class CustomSlider: UIView {
+    var value: Float = 0.5
+    var minValue: Float = 0
+    var maxValue: Float = 1
+
+    override var accessibilityTraits: UIAccessibilityTraits { get { .adjustable } set {} }
+    override var accessibilityValue: String? {
+        get { "\(Int(value * 100)) percent" }
+        set {}
+    }
+
+    override func accessibilityIncrement() {
+        value = min(maxValue, value + 0.05)
+        UIAccessibility.post(notification: .layoutChanged, argument: self)
+    }
+
+    override func accessibilityDecrement() {
+        value = max(minValue, value - 0.05)
+        UIAccessibility.post(notification: .layoutChanged, argument: self)
+    }
+}
+```
+
+### `accessibilityActivate()` — Custom Activation
+
+Called when VoiceOver user double-taps. Useful when the normal tap behavior differs from the accessibility action.
+
+```swift
+override func accessibilityActivate() -> Bool {
+    // Show expanded detail view instead of just toggling
+    showDetailPanel()
+    return true  // true = handled, false = pass to normal tap handler
+}
+```
+
+---
+
+## NSAttributedString Accessibility Attributes
+
+Apply per-character accessibility attributes for rich text.
+
+```swift
+let string = NSMutableAttributedString(string: "Error: Invalid password")
+string.addAttributes([
+    .accessibilitySpeechPitch: 0.5,               // lower pitch
+    .accessibilitySpeechQueueAnnouncement: true,   // queue, don't interrupt
+    .accessibilitySpeechSpellOut: false,
+    .accessibilitySpeechLanguage: "en-US"
+], range: NSRange(location: 0, length: string.length))
+
+label.attributedText = string
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Container `isAccessibilityElement = true` alongside `accessibilityElements` | Set `isAccessibilityElement = false` on containers that expose children |
+| `accessibilityFrame` in local coordinates | Always convert: `UIAccessibility.convertToScreenCoordinates(rect, in: view)` |
+| Forgetting to invalidate cached `accessibilityElements` | Nil out cache and post `.layoutChanged` when data changes |
+| Missing `accessibilityIncrement`/`Decrement` on `.adjustable` trait | `.adjustable` trait requires both methods |
+| No `accessibilityPerformEscape()` on custom modals | Implement to support two-finger Z gesture and Escape key |
+| Using `notification: .screenChanged` for partial updates | Use `.layoutChanged` for partial; `.screenChanged` for full screen replacement |
+| `accessibilityViewIsModal` on wrong view | Set on the outermost modal view, not a child |
+| No announcement after async state change | Post `.layoutChanged` or `.announcement` after network/async operations complete |
+| Labels in `UIAccessibilityElement` not updated after layout change | Rebuild elements array and nil cache when bounds change |

package/skills/ios/swift-accessibility/references/wcag-mapping.md

@@ -0,0 +1,167 @@
+# WCAG 2.2 → iOS/SwiftUI/UIKit Mapping
+
+Maps WCAG 2.2 Level A and AA success criteria to native platform APIs. Covers iOS, macOS, watchOS, tvOS, and visionOS. Based on WCAG 2.2 and WCAG2ICT (mobile application guidance).
+
+**Scope:** Level A and AA only — these are the standard compliance targets. Level AAA criteria are noted where native frameworks provide support.
+
+---
+
+## 1. Perceivable
+
+### 1.1 Text Alternatives
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 1.1.1 Non-text Content | A | Text alternative for non-text content | SwiftUI: `.accessibilityLabel(_:)`, `.accessibilityHidden(true)` for decorative; UIKit: `accessibilityLabel`, `isAccessibilityElement = false` |
+
+### 1.2 Time-based Media
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 1.2.1 Audio-only / Video-only | A | Alternative for prerecorded media | Provide transcript; use `AVPlayerViewController` |
+| 1.2.2 Captions (Prerecorded) | A | Captions for prerecorded audio in video | `AVPlayerViewController` (auto-enables captions); `AVMediaCharacteristic.legible` |
+| 1.2.3 Audio Description or Alternative | A | Audio description for prerecorded video | `AVMediaCharacteristic.describesVideoForAccessibility` |
+| 1.2.4 Captions (Live) | AA | Captions for live audio in video | App-provided live captions/transcriptions integrated into the streaming experience|
+| 1.2.5 Audio Description (Prerecorded) | AA | Audio description for prerecorded video | `AVPlayerViewController` + audio description track |
+
+### 1.3 Adaptable
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 1.3.1 Info and Relationships | A | Programmatic structure matches visual | SwiftUI: `.accessibilityElement(children:)`, `.accessibilityAddTraits(.isHeader)`, `Section`, `NavigationStack`; UIKit: `UIAccessibilityTraits`, `accessibilityContainerType` |
+| 1.3.2 Meaningful Sequence | A | Correct reading order | SwiftUI: `.accessibilitySortPriority(_:)`, layout order; UIKit: `accessibilityElements` array order |
+| 1.3.3 Sensory Characteristics | A | Don't rely solely on shape, size, position, or sound | Combine visual cues with text labels and accessibility labels |
+| 1.3.4 Orientation | AA | Content works in portrait and landscape | Support both orientations via Auto Layout / SwiftUI adaptive layout; lock only when essential (e.g., camera) |
+| 1.3.5 Identify Input Purpose | AA | Programmatic purpose for input fields | UIKit: `textContentType` (`.emailAddress`, `.password`, etc.); SwiftUI: `.textContentType(_:)`, `.keyboardType(_:)` |
+
+### 1.4 Distinguishable
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 1.4.1 Use of Color | A | Color is not the only visual indicator | Add shape, icon, or text alongside color; check with `@Environment(\.accessibilityDifferentiateWithoutColor)` |
+| 1.4.2 Audio Control | A | Mechanism to pause/stop/control audio | Standard playback controls; respect silent mode |
+| 1.4.3 Contrast (Minimum) | AA | 4.5:1 text, 3:1 large text | Semantic colors: `Color(.label)`, `Color(.secondaryLabel)`; check with Accessibility Inspector contrast checker; respond to `@Environment(\.colorSchemeContrast)` |
+| 1.4.4 Resize Text | AA | Text resizable to 200% without loss | SwiftUI: `.font(.body)` text styles, `@ScaledMetric`; UIKit: `UIFontMetrics`, `adjustsFontForContentSizeCategory = true`; test with Dynamic Type Variants in Canvas |
+| 1.4.5 Images of Text | AA | Use real text, not images of text | Use `Text` views with styling instead of rendered text images |
+| 1.4.10 Reflow | AA | Content reflows at narrow widths | SwiftUI: `ViewThatFits` (iOS 16+), adaptive stacks; UIKit: Auto Layout with proper constraints |
+| 1.4.11 Non-text Contrast | AA | 3:1 for UI components and graphics | Borders, icons, focus indicators against their backgrounds; use Accessibility Inspector |
+| 1.4.12 Text Spacing | AA | Support adjusted spacing | Use system text styles — they respect user settings automatically |
+| 1.4.13 Content on Hover/Focus | AA | Dismissible, hoverable, persistent | Ensure `.popover()` / `.help()` content stays visible when pointer moves into it, is dismissible via Escape, and persists until dismissed; avoid custom hover-triggered UI that vanishes on pointer move |
+
+---
+
+## 2. Operable
+
+### 2.1 Keyboard Accessible
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 2.1.1 Keyboard | A | All functionality via keyboard | Full Keyboard Access: every element reachable via Tab; SwiftUI: `.focusable()`, `FocusState`; UIKit: `canBecomeFocused`, `UIKeyCommand` |
+| 2.1.2 No Keyboard Trap | A | Keyboard focus can always move away | Ensure Escape dismisses modals; SwiftUI: `.sheet()` handles this; UIKit: implement `accessibilityPerformEscape()` |
+| 2.1.4 Character Key Shortcuts | A | Single-key shortcuts can be remapped/disabled | Avoid single-character key shortcuts; use modifier keys (Cmd+, Ctrl+) |
+
+### 2.2 Enough Time
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 2.2.1 Timing Adjustable | A | Users can extend time limits | Provide timeout warnings and extensions; no auto-advancing without user control |
+| 2.2.2 Pause, Stop, Hide | A | Auto-updating content can be paused | Provide pause controls; respect `@Environment(\.accessibilityReduceMotion)` |
+
+### 2.3 Seizures and Physical Reactions
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 2.3.1 Three Flashes | A | No content flashes > 3 times/second | Avoid flashing content; gate with `accessibilityReduceMotion` |
+
+### 2.4 Navigable
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 2.4.1 Bypass Blocks | A | Skip repeated content | SwiftUI: use `NavigationStack`, `TabView` for structure; UIKit: `accessibilityContainerType = .semanticGroup` |
+| 2.4.2 Page Titled | A | Screens have descriptive titles | SwiftUI: `.navigationTitle(_:)`; UIKit: `title` property on `UIViewController` |
+| 2.4.3 Focus Order | A | Logical focus/navigation order | SwiftUI: `.accessibilitySortPriority(_:)`, layout order; UIKit: `accessibilityElements` array |
+| 2.4.4 Link Purpose | A | Purpose of links clear from context | Use descriptive button/link labels; avoid "Click here" |
+| 2.4.5 Multiple Ways | AA | Multiple ways to reach content | Tab bar + search + navigation hierarchy |
+| 2.4.6 Headings and Labels | AA | Descriptive headings and labels | SwiftUI: `.accessibilityAddTraits(.isHeader)`; UIKit: `UIAccessibilityTraits.header` |
+| 2.4.7 Focus Visible | AA | Keyboard focus indicator visible | System provides default focus rings; do not suppress them with `.focusEffectDisabled(true)`; AppKit: only set `NSView.focusRingType = .none` when drawing a custom focus ring or when space is insufficient for the default ring |
+| 2.4.11 Focus Not Obscured (Minimum) | AA | Focused element not fully hidden | Ensure modals/overlays don't cover the focused element; use `.accessibilityViewIsModal` |
+
+### 2.5 Input Modalities
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 2.5.1 Pointer Gestures | A | Single-pointer alternative to multi-touch | Provide button alternatives for pinch/rotate gestures; `.accessibilityAction` for custom gestures |
+| 2.5.2 Pointer Cancellation | A | Down-event doesn't trigger action | Use `touchUpInside` (UIKit default), not `touchDown`; SwiftUI `Button` handles this automatically |
+| 2.5.3 Label in Name | A | Accessible name contains visible text | Voice Control: `.accessibilityInputLabels` must match or contain visible text |
+| 2.5.4 Motion Actuation | A | Alternative to device motion | Don't require shake/tilt; provide on-screen button alternative |
+| 2.5.7 Dragging Movements | AA | Single-pointer alternative to drag | Provide button-based reorder; `.accessibilityAction(named: "Move Up") { … }`; `.accessibilityDragPoint` / `.accessibilityDropPoint` |
+| 2.5.8 Target Size (Minimum) | AA | Touch targets ≥ 24×24 CSS px (44×44pt recommended) | SwiftUI: `.frame(minWidth: 44, minHeight: 44)`; UIKit: ensure `accessibilityFrame` ≥ 44×44pt; the Human Interface Guidelines recommend 44×44pt |
+
+---
+
+## 3. Understandable
+
+### 3.1 Readable
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 3.1.1 Language of Page | A | Language of content is programmatic | Set app language in Info.plist `CFBundleDevelopmentRegion`; per-view: SwiftUI `.environment(\.locale, …)` |
+| 3.1.2 Language of Parts | AA | Language of parts identified | `NSAttributedString` with `.accessibilitySpeechLanguage`; SwiftUI: `.accessibilitySpeechLanguage(_:)` |
+
+### 3.2 Predictable
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 3.2.1 On Focus | A | No unexpected changes on focus | Don't trigger navigation or state changes on focus alone |
+| 3.2.2 On Input | A | No unexpected changes on input | Confirm before submitting; don't auto-navigate on picker selection |
+| 3.2.3 Consistent Navigation | AA | Consistent navigation across screens | Use standard `TabView`, `NavigationStack` patterns |
+| 3.2.4 Consistent Identification | AA | Same function = same label | Use consistent `.accessibilityLabel` across screens for same action |
+| 3.2.6 Consistent Help | A | Help mechanism in consistent location | Place help in Settings or consistent toolbar position |
+
+### 3.3 Input Assistance
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 3.3.1 Error Identification | A | Errors identified and described | Post `AccessibilityNotification.Announcement` for errors; use `.accessibilityLabel` on error text |
+| 3.3.2 Labels or Instructions | A | Input fields have labels | SwiftUI: `TextField("Email", …)`; UIKit: `accessibilityLabel` on `UITextField` |
+| 3.3.3 Error Suggestion | AA | Suggest corrections for errors | Provide actionable error messages; use `.textContentType` for autofill suggestions |
+| 3.3.4 Error Prevention (Legal/Financial) | AA | Reversible, verified, or confirmed | Confirm destructive actions; provide undo; review before submit |
+| 3.3.7 Redundant Entry | A | Don't re-ask for previously entered info | Use Keychain, AutoFill, and state management to avoid re-entry |
+| 3.3.8 Accessible Authentication (Minimum) | AA | No cognitive function test for auth | Support passkeys, biometrics (`LAContext`), password managers; avoid CAPTCHAs |
+
+---
+
+## 4. Robust
+
+### 4.1 Compatible
+
+| SC | Level | Requirement | Platform API |
+|---|---|---|---|
+| 4.1.2 Name, Role, Value | A | All UI components have accessible name, role, value | SwiftUI: `.accessibilityLabel`, `.accessibilityValue`, `.accessibilityAddTraits`; UIKit: `accessibilityLabel`, `accessibilityTraits`, `accessibilityValue` |
+| 4.1.3 Status Messages | AA | Status changes announced without focus | SwiftUI: `AccessibilityNotification.Announcement(_:).post()`; UIKit: `UIAccessibility.post(notification: .announcement, argument:)` |
+
+---
+
+## Quick Lookup: WCAG SC → Nutrition Label
+
+| Nutrition Label | Primary WCAG SC |
+|---|---|
+| VoiceOver | 1.1.1, 1.3.1, 1.3.2, 2.4.3, 2.4.6, 4.1.2 |
+| Voice Control | 2.5.3, 2.5.8, 2.1.1 |
+| Larger Text | 1.4.4, 1.4.10, 1.4.12 |
+| Dark Interface | 1.4.3, 1.4.11 |
+| Differentiate Without Color | 1.4.1, 1.4.11 |
+| Sufficient Contrast | 1.4.3, 1.4.11 |
+| Reduced Motion | 2.2.2, 2.3.1 |
+| Captions | 1.2.2, 1.2.4 |
+| Audio Descriptions | 1.2.3, 1.2.5 |
+
+---
+
+## Mobile-Specific Notes (from WCAG2ICT)
+
+- **Touch targets**: WCAG 2.5.8 specifies 24×24 CSS pixels minimum. Human Interface Guidelines recommend 44×44pt — use that stricter standard.
+- **Orientation**: Support all orientations unless essential to the experience (1.3.4). Don't lock to portrait unless the feature requires it (e.g., camera viewfinder).
+- **Text resize**: iOS Dynamic Type satisfies 1.4.4. Test at all sizes including Accessibility sizes — use Xcode Canvas Dynamic Type Variants.
+- **Drag alternatives**: 2.5.7 requires single-pointer alternatives to drag. Provide button-based reordering, `.accessibilityAction(named:)`, or `.accessibilityDragPoint` / `.accessibilityDropPoint`.
+- **Authentication**: 3.3.8 is new in WCAG 2.2. Support biometrics (`Face ID`, `Touch ID`), passkeys, and password autofill to avoid cognitive function tests.