adamayoung/swiftui-accessibility-expert

SwiftUI Accessibility

Overview

This skill provides comprehensive guidance for building SwiftUI apps accessible to everyone — including users of VoiceOver, Voice Control, Switch Control, and other assistive technologies across iOS, macOS, and visionOS.

Scope: SwiftUI accessibility modifiers, accessibility tree management, assistive technology support, Dynamic Type, motion/color/contrast preferences, accessibility testing.

Relationship to swiftui-expert-skill: The swiftui-expert-skill covers general SwiftUI best practices. This skill owns all accessibility concerns in depth — labels, traits, actions, grouping, focus management, motion, color, testing. Where topics overlap (e.g., Dynamic Type), this skill provides the authoritative accessibility perspective.

Agent Behavior Contract

1. Every interactive element must have a meaningful accessibilityLabel — "Delete" not "Button", "Close" not "X icon". Labels describe purpose, not appearance. Labels must not include the element type (VoiceOver adds it).
2. Decorative images must use Image(decorative:) or .accessibilityHidden(true) — prevent VoiceOver from reading filenames or placeholder text for purely visual elements.
3. Use semantic controls — Button, Toggle, Picker, Slider instead of onTapGesture on Text/Image. Semantic controls provide correct traits, actions, and values automatically.
4. Never use color alone to convey meaning — pair with text, icons, or shapes. Check accessibilityDifferentiateWithoutColor for additional non-color indicators.
5. Respect Dynamic Type — no hardcoded font sizes; use text styles (.body, .headline) and @ScaledMetric for custom dimensions. Test at accessibility sizes.
6. Animations must check accessibilityReduceMotion — provide a static or fade alternative. Reduce means reduce, not remove — use subtle transitions instead of no animation.
7. Group related elements with .accessibilityElement(children: .combine) — reduce VoiceOver stops. A card with title, subtitle, and image should be one stop, not three.
8. Test with Accessibility Inspector and VoiceOver — use performAccessibilityAudit() in UI tests. Test at multiple Dynamic Type sizes, in dark mode, and with reduce motion enabled.

Quick Decision Tree

When a developer needs accessibility guidance:

• Adding labels or descriptions? └─ references/accessible-descriptions.md — labels, values, hints, headings, custom content, speech
• Making a control work with VoiceOver? └─ references/accessible-controls.md — traits, actions, adjustable, gestures, representation
• Handling Dynamic Type, color, or motion? └─ references/accessible-appearance.md — text styles, @ScaledMetric, contrast, reduce motion
• Fixing navigation or focus issues? └─ references/accessible-navigation.md — sort priority, rotors, focus state, notifications
• Reducing VoiceOver stops or structuring elements? └─ references/accessible-grouping.md — combine, contain, ignore, conditional grouping, modal
• Testing or auditing accessibility? └─ references/accessible-testing.md — Inspector, VoiceOver checklist, performAccessibilityAudit

Triage-First Playbook

Common VoiceOver/accessibility errors and the next best move:

• VoiceOver reads "Button" with no label → references/accessible-descriptions.md — add accessibilityLabel describing the action
• Decorative image announced by VoiceOver → references/accessible-descriptions.md — use Image(decorative:) or .accessibilityHidden(true)
• Too many VoiceOver stops on a card/row → references/accessible-grouping.md — use .accessibilityElement(children: .combine)
• Color-only indicator not conveyed → references/accessible-appearance.md — pair with icon/text, check accessibilityDifferentiateWithoutColor
• Custom control not interactive for VoiceOver → references/accessible-controls.md — add correct traits and actions
• VoiceOver reads elements in wrong order → references/accessible-navigation.md — use accessibilitySortPriority
• Button says item name but no action context → references/accessible-descriptions.md — add accessibilityHint describing the navigation destination or result
• Animations don't respect reduce motion → references/accessible-appearance.md — check accessibilityReduceMotion, provide fade alternative
• Focus not moving after content change → references/accessible-navigation.md — use @AccessibilityFocusState or post AccessibilityNotification

Core Patterns Reference

Labeling an Icon Button

Button(action: toggleFavorite) {
    Image(systemName: isFavorite ? "heart.fill" : "heart")
}
.accessibilityLabel(isFavorite ? "Remove from favorites" : "Add to favorites")

Grouping a Card

HStack {
    AsyncImage(url: movie.posterURL)
    VStack(alignment: .leading) {
        Text(movie.title)
        Text(movie.year)
    }
}
.accessibilityElement(children: .combine)

Conditional Grouping

HStack {
    if isEditing {
        Button("Delete") { delete() }
    }
    Text(movie.title)
}
.accessibilityElement(children: isEditing ? .contain : .combine)

Carousel with Per-Item Buttons and Hints

Use when each carousel item navigates to its own destination. Each item is an independent VoiceOver stop.

Carousel {
    ForEach(Array(movies.enumerated()), id: \.offset) { offset, movie in
        Button {
            didSelectMovie(movie.id)
        } label: {
            MovieCard(movie: movie)
        }
        .accessibilityIdentifier("carousel.movie.\(offset)")
        .accessibilityLabel(movie.title)
        .accessibilityHint("View movie details")
        .buttonStyle(.plain)
    }
}
.accessibilityIdentifier("movies.carousel")

Warning: Do NOT use .accessibilityElement() on the carousel container when items should be individually tappable — it collapses all children into one opaque element.

Checking Reduce Motion

@Environment(\.accessibilityReduceMotion) private var reduceMotion

var body: some View {
    ContentView()
        .transition(reduceMotion ? .opacity : .move(edge: .trailing))
}

Dynamic Type with @ScaledMetric

@ScaledMetric(relativeTo: .body) private var posterHeight: CGFloat = 120

AsyncImage(url: posterURL)
    .frame(height: posterHeight)

Review Checklist

Labels & Descriptions

• [ ] Every interactive element has a meaningful accessibilityLabel
• [ ] Navigation buttons with item-name labels have an accessibilityHint describing the destination
• [ ] Decorative images use Image(decorative:) or .accessibilityHidden(true)
• [ ] Labels describe purpose, not appearance
• [ ] Labels and hints are localized

Traits & Roles

• [ ] Semantic controls used (Button, Toggle, not onTapGesture on Text)
• [ ] Headers marked with .isHeader or .h1–.h6
• [ ] Selected states use .isSelected trait
• [ ] Modal overlays use .isModal trait

Controls & Actions

• [ ] Custom actions provided for multi-action elements
• [ ] Adjustable action for carousels/steppers
• [ ] Escape action for custom dismissals
• [ ] Magic tap for media play/pause

Grouping & Hierarchy

• [ ] Related content grouped with .combine to reduce VoiceOver stops
• [ ] Interactive elements within groups still reachable (.contain when editing)
• [ ] Redundant traits cleaned up after combining
• [ ] Canvas views provide accessibilityChildren

Appearance & Adaptability

• [ ] No hardcoded font sizes — text styles or @ScaledMetric
• [ ] Color is not the sole indicator of meaning
• [ ] Animations respect accessibilityReduceMotion
• [ ] Images exempt from Smart Invert with accessibilityIgnoresInvertColors()
• [ ] Minimum tap targets: 44x44pt (iOS), 60x60pt (visionOS)

Testing

• [ ] Tested with VoiceOver enabled
• [ ] Tested at accessibility Dynamic Type sizes
• [ ] performAccessibilityAudit() in UI tests
• [ ] Tested in both light and dark mode for contrast

Reference Files

| File | Description | |------|-------------| | references/_index.md | Navigation index with quick links by problem | | references/accessible-descriptions.md | Labels, values, hints, headings, custom content, speech customization | | references/accessible-controls.md | Traits (all 17), actions, adjustable, gestures, representation | | references/accessible-appearance.md | Dynamic Type, color/contrast, motion, transparency, AT checks | | references/accessible-navigation.md | Sort priority, rotors, linked groups, focus, notifications, charts | | references/accessible-grouping.md | Children behavior, conditional grouping, hidden, modal, Canvas | | references/accessible-testing.md | Inspector, VoiceOver checklist, audits, environment overrides, visionOS |