Mobile Accessibility

Overview

VoiceOver and TalkBack are not an edge case — they're how a meaningful share of your users, and every store review, go through the screen. Every control that is interactive needs a label a screen reader can speak; every screen needs a sane reading and focus order; text needs to scale.

Core principle: build it accessible the first time — retrofitting labels after the fact means re-testing the whole screen.

Per-stack API table

Concern	Flutter	Compose	SwiftUI
Label	Semantics(label:) / tooltip / semanticLabel on Image/Icon	contentDescription (null = decorative)	accessibilityLabel / Button("…", systemImage:)
Grouping	MergeSemantics	Modifier.semantics(mergeDescendants = true)	.accessibilityElement(children: .combine)
Heading	Semantics(header: true)	semantics { heading() }	.accessibilityAddTraits(.isHeader)
Hidden/decorative	ExcludeSemantics	Modifier.clearAndSetSemantics {}	Image(decorative:)
Custom action	CustomSemanticsAction	Modifier.semantics { customActions = … }	.accessibilityAction(named:)
Live region	Semantics(liveRegion: true)	Modifier.semantics { liveRegion = … }	.accessibilityAddTraits(.updatesFrequently)

Rules that apply everywhere:

• Every interactive control (button, icon button, tappable row) has a non-empty, human-readable label — never a bare icon with no text or label.
• Don't rely on a swipe-only gesture for something achievable another way; add a custom action or a visible control alongside it.
• Group a composite control (e.g. an icon + label that act as one tap target) with the merge/combine API so a screen reader announces it once, not as separate stops.
• Headings get the heading trait so screen-reader users can jump by section.
• @ScaledMetric (SwiftUI) / theme text styles (Flutter, Compose) everywhere text appears — never a hardcoded point/sp size that ignores the system font-scale setting.
• Respect reduce-motion: MediaQuery.disableAnimationsOf(context) (Flutter), LocalAccessibilityManager/animation duration checks (Compose), @Environment(\.accessibilityReduceMotion) (SwiftUI) — skip or shorten a decorative animation, never a functional state change.
• Contrast: body text ≥4.5:1, large text ≥3:1 against its background in both light and dark — check this when picking theme token values, not per-screen.

Automated checks

• Flutter (verified): meetsGuideline — androidTapTargetGuideline (48×48), iOSTapTargetGuideline (44×44), labeledTapTargetGuideline, textContrastGuideline. Run all four against any new interactive widget's test (see mobile-visual-self-review's worked example).
• Compose: rule.enableAccessibilityChecks() (ui-test-junit4-accessibility) runs the Accessibility Test Framework before every UI-mutating test action. It requires an API 34+ device/emulator — on Robolectric it only warns, so a Robolectric-only pass is inconclusive and must be said so in the closing message. tryPerformAccessibilityChecks() for a manual, one-off gate inside a test.
• XCUITest: try app.performAccessibilityAudit() (Xcode 15+) inside a UI test — fails the test on a real finding (e.g. insufficient contrast, missing label).

The device proxy

When you have a device but not a screen reader to drive, mobile_read_ui {filter: "clickable=\"true\""} is your proxy for "what would TalkBack/VoiceOver say here": every line needs a non-empty text or content-desc, and the bounds must meet the tap-target floor. This is not a substitute for the automated checks above — it catches missing labels, not contrast or reading order.

Worked Example

❌ IconButton(icon: Icon(Icons.delete), onPressed: delete)                 // no label at all
✅ IconButton(
     icon: const Icon(Icons.delete),
     tooltip: 'Delete task',                                               // spoken by TalkBack/VoiceOver
     onPressed: delete,
   )

// ❌ Button(action: delete) { Image(systemName: "trash") }                 // icon-only, silent
// ✅
Button("Delete task", systemImage: "trash", action: delete)
    .labelStyle(.iconOnly)                                                 // visually icon-only, still spoken

Common Mistakes

• An icon-only button with no tooltip/contentDescription/accessibilityLabel.
• Hardcoding a font size instead of a scalable text style, so Dynamic Type/font-scale does nothing.
• Treating a Robolectric-only enableAccessibilityChecks() pass as a verified result.
• A decorative animation that ignores the reduce-motion setting.
• A composite row (icon + title + chevron) left as three separate screen-reader stops instead of merged into one.

Red Flags

• Icon/Image used as the entire content of a tappable control with no label anywhere in the diff.
• A contrast value picked without checking it against both light and dark theme backgrounds.
• A swipe-to-reveal action with no equivalent reachable another way.