Mobile Accessibility skill for Codex

Done well means: a screen reader user can complete every core task without sighted help, text scales to the largest setting without truncating meaning, every control is at least 44x44 pt on iOS and 48x48 dp on Android, contrast meets WCAG AA, and automated checks run in CI so regressions fail the build.

Before changing anything

1. Read AGENTS.md, then identify the UI stack per screen: SwiftUI, UIKit, Jetpack Compose, Android Views, React Native or Flutter. APIs differ by stack; fixes must use the stack’s own semantics, not overlays.
2. List the core tasks (sign in, search, purchase, settings) and audit those first.
3. Check whether the design system defines text styles and color tokens; most fixes belong there, not in individual screens.

Audit workflow

• Run automated checks (below) to clear the mechanical issues
• Walk each core task with VoiceOver (iOS) and TalkBack (Android), eyes off the screen
• Repeat at the largest text size (iOS Accessibility sizes, Android font scale 2.0)
• Check contrast of text and icons against their actual backgrounds, both themes
• Turn on Reduce Motion and confirm animations calm down
• Use Switch Control or a hardware keyboard to confirm focus reaches every control
• Record each finding with screen, element, WCAG criterion, severity and fix

Thresholds

Check	Target	Source
Touch target	44x44 pt iOS, 48x48 dp Android (visual can be smaller if the hit area is not)	Apple HIG, Material
Minimum target, WCAG	24x24 CSS px or adequate spacing	WCAG 2.2 SC 2.5.8 (AA)
Text contrast	4.5:1 normal, 3:1 large (18 pt, or 14 pt bold)	SC 1.4.3
Icons, borders, focus indicators	3:1 against adjacent colors	SC 1.4.11
Text resize	Usable at 200 percent	SC 1.4.4
Motion	Respect the OS reduce-motion setting	SC 2.3.3 (AAA), platform guidance

Screen reader semantics

Every interactive element needs a name, a role and a state, announced in that order.

Need	SwiftUI	UIKit	Compose	Views	React Native	Flutter
Name	.accessibilityLabel("Delete")	accessibilityLabel	contentDescription in semantics	contentDescription	accessibilityLabel	Semantics(label:)
Role	.accessibilityAddTraits(.isButton)	accessibilityTraits	role = Role.Button	AccessibilityDelegateCompat / widget type	accessibilityRole	Semantics(button: true)
State	.accessibilityValue, .isSelected trait	accessibilityValue	stateDescription, selected	stateDescription	accessibilityState	Semantics(checked:, selected:)
Group	.accessibilityElement(children: .combine)	container with one element	Modifier.semantics(mergeDescendants = true) {}	focusable parent + screenReaderFocusable	accessible={true} on parent	MergeSemantics
Hide decoration	.accessibilityHidden(true)	isAccessibilityElement = false	Modifier.clearAndSetSemantics {}	importantForAccessibility="no"	accessibilityElementsHidden / importantForAccessibility	ExcludeSemantics
Heading	.accessibilityAddTraits(.isHeader)	.header trait	heading()	accessibilityHeading	accessibilityRole="header"	Semantics(header: true)

Rules:

• Labels describe purpose, not appearance: “Delete message”, not “trash icon”. Do not include the role (“button”) in the label; the screen reader adds it.
• Group a card into one element with a combined label and expose secondary actions as custom actions (.accessibilityAction(named:), Compose customActions) instead of several tiny focus stops.
• Announce async changes: iOS AccessibilityNotification.Announcement("Saved").post(), Compose liveRegion = LiveRegionMode.Polite, RN AccessibilityInfo.announceForAccessibility.
• Move focus to new content after navigation or when a modal opens, and return it on close.
• Images that convey information get a label; decorative images are hidden.
• Custom gestures (swipe to delete, long press) need an equivalent accessible action.

HStack {
    AsyncImage(url: item.thumbnail).accessibilityHidden(true)
    VStack(alignment: .leading) {
        Text(item.title).font(.headline)
        Text(item.price, format: .currency(code: "EUR")).font(.subheadline)
    }
}
.accessibilityElement(children: .combine)
.accessibilityAction(named: "Add to cart") { cart.add(item) }

Row(
    Modifier
        .semantics(mergeDescendants = true) {
            customActions = listOf(CustomAccessibilityAction("Add to cart") { cart.add(item); true })
        }
        .clickable(onClickLabel = "Open product") { open(item) }
) { /* image with contentDescription = null, title, price */ }

Text scaling

• iOS: use text styles (.font(.body), UIFont.preferredFont(forTextStyle:) with adjustsFontForContentSizeCategory = true). Scale custom sizes and spacing with @ScaledMetric. Switch horizontal layouts to vertical when dynamicTypeSize.isAccessibilitySize.
• Android: text in sp, never dp; Android 14 scales nonlinearly up to 200 percent. Avoid fixed-height containers around text; let rows grow.
• React Native: keep allowFontScaling on; cap extremes with maxFontSizeMultiplier only where layout truly cannot adapt. Flutter: respect MediaQuery.textScalerOf(context).
• Never truncate essential text to one line at large sizes; wrap or reflow.

Touch targets and contrast

• Expand hit areas without growing visuals: SwiftUI .contentShape(Rectangle()) with a .frame(minWidth: 44, minHeight: 44); Compose Modifier.minimumInteractiveComponentSize() (Material components apply it already); Views TouchDelegate or padding; RN hitSlop.
• Compute contrast on the rendered colors, including text over images and gradients (add a scrim). Placeholder text and disabled-looking active controls are common failures.
• Never use color alone to convey state; add an icon, text or shape.

Automated checks

// XCUITest (Xcode 15+ / iOS 17+)
func testCheckoutAccessibility() throws {
    let app = XCUIApplication(); app.launch()
    app.buttons["Checkout"].tap()
    try app.performAccessibilityAudit()
}

// Espresso with Android Views: enable once in the test class
@Before fun setUp() { AccessibilityChecks.enable().setRunChecksFromRootView(true) }

• Android: Accessibility Scanner app for manual sweeps; Compose UI tests can run the same accessibility checks in recent ui-test versions (check the release notes for the enabling API in your version). Android Lint flags missing contentDescription.
• React Native: eslint-plugin-react-native-a11y; Flutter: meetsGuideline(androidTapTargetGuideline), textContrastGuideline and labeledTapTargetGuideline in widget tests.
• Automated checks catch perhaps a third of issues. Manual screen reader passes are required.

Useful device commands:

adb shell settings put system font_scale 2.0            # restore with 1.0
xcrun simctl ui booted content_size accessibility-extra-extra-extra-large

Gotchas

• accessibilityIdentifier / testTag is for tests and is never read aloud.
• A SwiftUI Button with only an Image(systemName:) reads the symbol name; always give it a label.
• Custom tab bars and bottom sheets often trap or lose focus; test them explicitly.
• Web content in a WebView follows web rules (ARIA); audit it separately with wcag-accessibility-audit.
• Compliance (EAA since June 2025, ADA, Section 508) is a legal judgment; report WCAG conformance findings and let counsel decide on claims.

Output

## Accessibility audit: <app> <version>, <platforms>
| # | Screen | Element | Issue | WCAG | Severity | Fix |
|---|---|---|---|---|---|---|
**Automated:** <tools run, issue counts before/after>
**Manual:** <VoiceOver/TalkBack task walk results, largest text size result>
**Not tested:** <screens, devices, assistive tech>

Severity: blocker (task impossible), major (task possible with significant effort), minor.