iOS Accessibility for Engineers (2026): Real Code, Rotors, WCAG Mapping

VoiceOver labels, values, and traits — the three you must set

Every interactive or informative element in your UI needs three pieces of information for VoiceOver: what it is (label), what state it's in (value), and what kind of thing it is (traits). The default SwiftUI inference is right ~70% of the time; the senior+ work is the 30% it gets wrong.

// 1. CUSTOM LABEL — when the visible text isn't the right thing to read
Button(action: deletePost) {
    Image(systemName: "trash")
}
.accessibilityLabel("Delete post")

// 2. LABEL + VALUE — for stateful controls
struct VolumeSlider: View {
    @Binding var volume: Double  // 0.0 ... 1.0
    var body: some View {
        Slider(value: $volume)
            .accessibilityLabel("Volume")
            .accessibilityValue("\(Int(volume * 100)) percent")
    }
}

// 3. CUSTOM TRAITS — for non-button views that should behave like buttons
VStack { /* whole-card touch target */ }
    .onTapGesture { open(post) }
    .accessibilityElement(children: .combine)
    .accessibilityAddTraits(.isButton)
    .accessibilityLabel("\(post.title), \(post.author)")

// 4. HIDE DECORATIVE IMAGES
Image("banner-decorative")
    .accessibilityHidden(true)

// 5. COMBINE OVER-VERBOSE NARRATION — the single most common fix
// BEFORE: VoiceOver reads each VStack child as a separate node
VStack {
    Text(post.title)
    Text(post.author)
    Text(post.timestamp.formatted())
}
// AFTER: one node, all three pieces narrated together
VStack {
    Text(post.title)
    Text(post.author)
    Text(post.timestamp.formatted())
}
.accessibilityElement(children: .combine)
.accessibilityLabel("\(post.title), by \(post.author), \(post.timestamp.formatted())")

WWDC22 'Writing great accessibility labels' (developer.apple.com/videos/play/wwdc2022/10100) covers label craft — including the specifics that label text should not include the trait ('Delete', not 'Delete button'; the trait is added by the system).

accessibilityCustomAction: rotor-discoverable shortcuts

Custom actions add operations VoiceOver users can invoke from the rotor without leaving the current element. Common pattern: a list row with several actions (delete, archive, share) — VoiceOver users get all three via custom actions, sighted users get them via swipe.

struct InboxRow: View {
    let message: Message
    let onArchive: () -> Void
    let onDelete: () -> Void
    let onMarkUnread: () -> Void

    var body: some View {
        HStack {
            Avatar(url: message.senderAvatar)
            VStack(alignment: .leading) {
                Text(message.subject).font(.headline)
                Text(message.preview).font(.caption).lineLimit(1)
            }
        }
        .swipeActions(edge: .trailing) {
            Button("Archive", action: onArchive)
            Button("Delete", role: .destructive, action: onDelete)
        }
        .accessibilityElement(children: .combine)
        .accessibilityLabel("\(message.subject), from \(message.sender)")
        .accessibilityValue(message.isRead ? "Read" : "Unread")
        .accessibilityAction(named: "Archive", onArchive)
        .accessibilityAction(named: "Delete", onDelete)
        .accessibilityAction(named: "Mark unread", onMarkUnread)
    }
}

The non-obvious win: custom actions reduce VoiceOver gesture cost. Without them, a VoiceOver user has to swipe to focus the row, swipe again to reach a 'More' button, swipe through a menu to find Archive — five gestures. With custom actions, the rotor surfaces all three at the row level — two gestures total.

Dynamic Type: support every size including AccessibilityXL

Dynamic Type ranges from xSmall through AccessibilityXXXL — twelve sizes. Hardcoding pixel sizes breaks the contract. The right pattern uses semantic font styles and @ScaledMetric for custom dimensions:

struct ScaledCard: View {
    // Custom dimensions that scale with Dynamic Type
    @ScaledMetric private var iconSize: CGFloat = 24
    @ScaledMetric private var spacing: CGFloat = 12
    @ScaledMetric private var cornerRadius: CGFloat = 16

    let title: String
    let body: String

    var body: some View {
        VStack(alignment: .leading, spacing: spacing) {
            Image(systemName: "sparkles")
                .font(.system(size: iconSize))  // scales with @ScaledMetric
            Text(title)
                .font(.headline)  // semantic style — scales automatically
            Text(body)
                .font(.body)
                .lineLimit(nil)  // do NOT cap lines — text must wrap freely
        }
        .padding()
        .background(Color.accentColor.opacity(0.1))
        .clipShape(RoundedRectangle(cornerRadius: cornerRadius))
        // Optional: cap how large the user-set scaling can grow this view
        .dynamicTypeSize(...DynamicTypeSize.accessibility3)
    }
}

// In tests — simulate accessibility sizes
#Preview("Accessibility XL") {
    ScaledCard(title: "Hello", body: "World")
        .environment(\.dynamicTypeSize, .accessibility5)
}

Three rules that catch most failures:

1. Never .font(.system(size:)) for body text. Use semantic styles (.body, .headline, .caption). They scale automatically.
2. Never .lineLimit(N) on user-facing text without a Dynamic Type fallback. AccessibilityXXXL roughly doubles the font size — your two-line title is now four lines.
3. Use ViewThatFits (iOS 16+) to swap layouts when the type size doesn't fit the original arrangement: ViewThatFits { HStack { ... } VStack { ... } } — system picks whichever lays out without clipping.

VoiceOver rotor: custom navigation categories

The rotor (rotated two fingers on screen) lets VoiceOver users jump between categories of content — Headings, Links, Form Controls. Adding custom rotor entries is the senior+ accessibility surface most engineers never touch.

struct ArticleView: View {
    let article: Article
    let comments: [Comment]

    var body: some View {
        ScrollView {
            VStack(alignment: .leading, spacing: 16) {
                Text(article.title).font(.largeTitle)
                ForEach(article.sections) { section in
                    Text(section.heading)
                        .font(.title2)
                        .accessibilityAddTraits(.isHeader)  // makes it discoverable in the Headings rotor
                    Text(section.body)
                }
                Divider()
                Text("Comments (\(comments.count))")
                    .font(.title2)
                    .accessibilityAddTraits(.isHeader)
                ForEach(comments) { comment in
                    CommentView(comment: comment)
                        .accessibilityIdentifier("comment-\(comment.id)")
                }
            }
            .padding()
        }
        .navigationTitle("Article")
        // CUSTOM ROTOR — let VoiceOver users jump between comments by author
        .accessibilityRotor("Comments by author") {
            ForEach(comments) { comment in
                AccessibilityRotorEntry(comment.author, id: comment.id)
            }
        }
    }
}

WWDC20 'VoiceOver efficiency with custom rotors' (developer.apple.com/videos/play/wwdc2020/10116) is the canonical reference. The rotor pattern is what makes a long article navigable — without it, a VoiceOver user has to swipe through every paragraph linearly.

WCAG 2.2 mapped to iOS APIs

WCAG 2.2 (W3C, October 2023) is the international accessibility standard. Most large tech apps target Level AA. The mapping to iOS APIs is direct:

WCAG 2.2 quickref: w3.org/WAI/WCAG22/quickref. Apple's accessibility guidelines: developer.apple.com/design/human-interface-guidelines/accessibility.

Audit tooling: Accessibility Inspector and CI integration

Two tools matter for production audits:

1. Accessibility Inspector (Xcode → Open Developer Tool → Accessibility Inspector). Connects to a running app, runs an automated audit, surfaces issues with severity ratings and suggested fixes. The audit covers element labelling, contrast ratios, hit-target sizing, and traits. Run it before every release.
2. XCUITest accessibility audits (iOS 17+). Inside a UI test, call app.performAccessibilityAudit(). The method returns issues; you can fail the test or warn. Production CI pattern:

import XCTest

final class AccessibilityAuditTests: XCTestCase {
    func testFeedScreenAccessibility() throws {
        let app = XCUIApplication()
        app.launch()

        // Navigate to the feed
        app.tabBars.buttons["Feed"].tap()
        XCTAssertTrue(app.staticTexts["feed-title"].waitForExistence(timeout: 5))

        // Run the audit. iOS 17+ — fails the test if any issue is found.
        try app.performAccessibilityAudit { issue in
            // Allow specific known issues to slip through; assert against
            // unknown ones.
            return false  // do NOT skip any
        }
    }
}

WWDC23 'Perform accessibility audits for your app' (developer.apple.com/videos/play/wwdc2023/10035) walks the audit API end-to-end. Audit failures look like: Element [Label: "", Trait: button] is missing a label. (Element at xPath ...) — actionable enough to fix without re-running the inspector.