Mobile Accessibility Skill
This skill provides mobile accessibility reference data for React Native, Expo, iOS, and Android auditing. Used by the mobile-accessibility skill.
React Native Accessibility Props - Full Reference
Each prop, with its type, values or notes, WCAG SC and required. The aria-* props and role are aliases in current React Native (0.88); there is no aria-describedby or aria-role.
| Prop | Type | Values / Notes | WCAG SC | Required |
|---|---|---|---|---|
accessible |
boolean | true marks the view as an accessibility node |
4.1.2 | Conditional |
accessibilityLabel |
string | Human-readable name - overrides all child text | 1.1.1, 4.1.2 | Yes (all interactive + image elements) |
accessibilityLabelledBy |
string / string[] | Android only - references the nativeID of the labelling element |
1.3.1 | For form inputs |
accessibilityRole |
string (see roles table) | Communicates element type to AT | 4.1.2 | Yes (all interactive elements) |
accessibilityHint |
string | Additional context spoken after label + role | 3.3.2 | When action isn't obvious |
accessibilityState |
object | {checked, disabled, expanded, selected, busy} |
4.1.2 | State-bearing elements |
accessibilityValue |
object | {min, max, now, text} |
4.1.2 | Sliders, steppers, progress bars |
accessibilityActions |
array | [{name, label}] - defines custom actions |
2.5.1, 4.1.2 | Context menus, long-press alternatives |
onAccessibilityAction |
function | Handles custom action triggers | 2.5.1, 4.1.2 | Paired with accessibilityActions |
accessibilityLiveRegion |
string | Android only - 'none' / 'polite' / 'assertive' |
4.1.3 | Dynamic content updates |
accessibilityViewIsModal |
boolean | iOS only - VoiceOver ignores sibling views | 2.4.3 | Modals, drawers, sheets |
accessibilityElementsHidden |
boolean | iOS - hides element and children from VoiceOver | 1.1.1 | Decorative elements |
importantForAccessibility |
string | Android - 'auto' / 'yes' / 'no' / 'no-hide-descendants' |
1.1.1 | Decorative / grouped elements |
accessibilityIgnoresInvertColors |
boolean | iOS - preserves colors in Inverted Colors mode | - | Images, video |
aria-label |
string | Alias for accessibilityLabel |
1.1.1, 4.1.2 | Preferred in new code |
aria-labelledby |
string | Android only - alias for accessibilityLabelledBy |
1.3.1 | Form inputs |
role |
string | Alias for accessibilityRole that takes ARIA role names (button, heading, listitem...) |
4.1.2 | All interactive elements |
aria-checked |
boolean / 'mixed' | RN 0.73+ alias for accessibilityState.checked |
4.1.2 | Checkboxes |
aria-disabled |
boolean | RN 0.73+ alias for accessibilityState.disabled |
4.1.2 | Disabled elements |
aria-expanded |
boolean | RN 0.73+ alias for accessibilityState.expanded |
4.1.2 | Accordions, dropdowns |
aria-selected |
boolean | RN 0.73+ alias for accessibilityState.selected |
4.1.2 | Tabs, list items |
aria-busy |
boolean | RN 0.73+ alias for accessibilityState.busy |
4.1.3 | Loading elements |
aria-hidden |
boolean | RN 0.73+ - maps to importantForAccessibility / accessibilityElementsHidden |
1.1.1 | Decorative content |
aria-live |
string | Android only - 'polite' / 'assertive' / 'off' |
4.1.3 | Dynamic content |
aria-modal |
boolean | iOS only - alias for accessibilityViewIsModal |
2.4.3 | Modals |
Accessibility Role Values
Each accessibilityRole, with the UIAccessibilityTraits value React Native sets on iOS and the class name it reports on Android (from React Native 0.88 source, RCTViewManager.m and ReactAccessibilityDelegate.kt). "None" means React Native adds no trait; the state props still apply. accessibilityRole has no listitem; the web-style role prop accepts listitem and other ARIA role names.
| Role | iOS trait | Android class | Use For |
|---|---|---|---|
'button' |
Button | android.widget.Button | Buttons, submission triggers |
'link' |
Link | android.view.View | Navigation links, external URLs |
'search' |
SearchField | android.widget.EditText | Search bars |
'image' |
Image | android.widget.ImageView | Images (when accessible=true) |
'imagebutton' |
Image + Button | android.widget.ImageButton | Icon buttons |
'header' |
Header | android.view.View | Headings |
'text' |
StaticText | android.widget.TextView | Static text |
'adjustable' |
Adjustable | android.widget.SeekBar | Sliders |
'checkbox' |
None | android.widget.CheckBox | Checkboxes |
'combobox' |
None | android.view.View | Dropdowns |
'dropdownlist' |
None | android.widget.Spinner | Dropdown lists |
'menu' |
None | android.view.View | Menus |
'menuitem' |
None | android.view.View | Menu items |
'menubar' |
None | android.view.View | Menu bars |
'progressbar' |
UpdatesFrequently | android.view.View | Progress indicators |
'radio' |
None | android.widget.RadioButton | Radio buttons |
'radiogroup' |
None | android.view.View | Radio button groups |
'scrollbar' |
None | android.view.View | Scrollbars |
'spinbutton' |
None | android.widget.SpinButton | Steppers, number inputs |
'switch' |
switch trait (private) | android.widget.Switch | Toggle switches |
'togglebutton' |
Button | android.widget.ToggleButton | Toggle buttons |
'tab' |
None | android.view.View | Tab elements |
'tablist' |
None | android.view.View | Tab containers |
'timer' |
None | android.view.View | Countdown timers |
'toolbar' |
None | android.view.View | Toolbars |
'grid' |
None | android.widget.GridView | Data grids |
'list' |
None | android.widget.AbsListView | Lists |
'summary' |
SummaryElement | android.view.View | Summary/status views |
'alert' |
None | android.view.View | Alerts |
'none' |
None | android.view.View | Suppress role |
Touch Target Size Requirements
Each platform, with its minimum size, recommended and standard.
| Platform | Minimum Size | Recommended | Standard |
|---|---|---|---|
| iOS | 44 x 44 pt | 44 x 44 pt | HIG |
| Android | 48 x 48 dp | 48 x 48 dp | Material Design |
| Web mobile | 44 x 44 CSS px (AAA) | 44 x 44 CSS px | WCAG 2.5.5 |
| Web mobile (AA, 2.2) | 24 x 24 CSS px with spacing | 44 x 44 CSS px | WCAG 2.5.8 |
Detection Pattern (React Native)
// Violation: TouchableOpacity below minimum
const styles = StyleSheet.create({
closeBtn: { width: 24, height: 24 }, // FAIL HIG - below 44pt (meets the 24px floor of 2.5.8)
iconBtn: { width: 32, height: 32 }, // FAIL HIG - below 44pt
navBtn: { padding: 4 }, // CONDITIONAL - depends on content size
compliant: { width: 44, height: 44 }, // PASS
compliantWithPadding: { padding: 12 }, // PASS if content >= 20pt
});
iOS UIAccessibility - Quick Reference
SwiftUI Modifiers
Each modifier, with its purpose.
| Modifier | Purpose |
|---|---|
.accessibilityLabel("...") |
Overrides spoken name |
.accessibilityHint("...") |
Spoken usage hint (after pause) |
.accessibilityValue("...") |
Spoken current value |
.accessibilityHidden(true) |
Removes from VoiceOver tree |
.accessibilityElement(children: .combine) |
Merges child elements into one node |
.accessibilityElement(children: .contain) |
Groups children as sub-elements |
.accessibilityElement(children: .ignore) |
Container becomes accessible, children hidden |
.accessibilityAddTraits(.isButton) |
Adds role trait |
.accessibilityRemoveTraits(.isImage) |
Removes wrong role trait |
.accessibilityInputLabels(["..."]) |
Voice Control activation labels |
.accessibilitySortPriority(n) |
Overrides VoiceOver reading order (higher = earlier) |
.accessibilityAction(named: "...", {}) |
Custom action in the Actions rotor |
.accessibilityActivationPoint(CGPoint) |
Override activation tap point |
.accessibilityCustomContent("label", "value") |
Extra info in Accessibility Inspector |
SwiftUI Trait Values
isButton, isHeader, isLink, isImage, isStaticText, isSelected, isKeyboardKey, isSearchField, playsSound, isModal, updatesFrequently, startsMediaSession, allowsDirectInteraction, causesPageTurn, isTabBar, isSummaryElement
UIKit Properties
Each property, with its type and notes.
| Property | Type | Notes |
|---|---|---|
isAccessibilityElement |
Bool | Set true on custom views |
accessibilityLabel |
String? | Overrides spoken name |
accessibilityHint |
String? | Spoken after pause |
accessibilityValue |
String? | Current value (sliders, progress) |
accessibilityTraits |
UIAccessibilityTraits | Bitfield of traits (.button, .header, etc.) |
accessibilityFrame |
CGRect | Determines VoiceOver focus rect |
accessibilityActivate() |
func | Override activation behavior |
accessibilityElements |
[Any]? | Set container's VoiceOver child order |
shouldGroupAccessibilityChildren |
Bool | Groups all children into single node |
accessibilityViewIsModal |
Bool | true = VoiceOver trapped inside |
accessibilityElementsHidden |
Bool | Hides all children from VoiceOver |
Android Jetpack Compose Semantics - Quick Reference
Each modifier / property, with its purpose.
| Modifier / Property | Purpose |
|---|---|
semantics { contentDescription = "..." } |
Accessible name |
semantics { role = Role.Button } |
Element role |
semantics { stateDescription = "..." } |
Current state text |
semantics { heading() } |
Marks as heading |
semantics { selected = true/false } |
Selected state |
semantics { toggleableState = ToggleableState.On } |
Toggle state |
semantics { onClick(label = "...", action = {...}) } |
Click action with label |
semantics { disabled() } |
Disabled state |
semantics { focused = true } |
Force focus |
semantics { liveRegion = LiveRegionMode.Polite } |
Live region announcements |
semantics { hideFromAccessibility() } |
Hide from TalkBack (replaces the deprecated invisibleToUser()) |
clearAndSetSemantics { ... } |
Replace all descendant semantics |
Modifier.semantics(mergeDescendants = true) { } |
Short merge pattern |
Role Values
Role.Button, Role.Checkbox, Role.DropdownList, Role.Image, Role.RadioButton, Role.Switch, Role.Tab
Common Violation Patterns and Fixes
RN-001: Missing accessibilityLabel on icon button
// VIOLATION
<TouchableOpacity
<Icon name="x" size={20} />
</TouchableOpacity>
// FIX
<TouchableOpacity
accessibilityRole="button"
accessibilityLabel="Close"
>
<Icon name="x" size={20} aria-hidden />
</TouchableOpacity>
RN-002: Image missing label
// VIOLATION
<Image source={productImage} style={styles.product} />
// FIX - informational image
<Image
source={productImage}
style={styles.product}
accessibilityLabel="Blue suede shoes, size 10"
/>
// FIX - decorative image
<Image
source={decorativeBackground}
style={styles.bg}
accessible={false}
importantForAccessibility="no"
/>
RN-003: TextInput missing label
// VIOLATION - placeholder is not a label
<TextInput placeholder="Email" value={email} />
// FIX
<View>
<Text nativeID="emailLabel">Email address</Text>
<TextInput
value={email}
accessibilityLabelledBy="emailLabel"
accessibilityHint="Enter your email address"
keyboardType="email-address"
autoComplete="email"
/>
</View>
RN-004: Checkbox missing state
// VIOLATION
<TouchableOpacity
<Image source={checked ? checkedIcon : uncheckedIcon} />
<Text>Accept terms</Text>
</TouchableOpacity>
// FIX
<TouchableOpacity
accessibilityRole="checkbox"
accessibilityState={{ checked }}
accessibilityLabel="Accept terms and conditions"
>
<Image source={checked ? checkedIcon : uncheckedIcon} accessible={false} />
<Text>Accept terms</Text>
</TouchableOpacity>
RN-005: Modal not trapping focus
// VIOLATION - custom modal without VoiceOver trap
<View style={styles.modal}>
<Text>Are you sure?</Text>
<Button title="Confirm" />
</View>
// FIX - use the Modal component (it presents in its own window) or set
// accessibilityViewIsModal (iOS) on the container View
<Modal
visible={visible}
transparent
// Android back button
>
<View style={styles.overlay} accessibilityViewIsModal={true}>
<Text>Are you sure?</Text>
<Button title="Confirm" />
<Button title="Cancel" />
</View>
</Modal>
AND-001: Compose image missing content description
// VIOLATION
Image(
painter = painterResource(id = R.drawable.product),
contentDescription = null // null = decorative, but wrong for informational image
)
// FIX - informational
Image(
painter = painterResource(id = R.drawable.product),
contentDescription = stringResource(R.string.product_image_description)
)
// FIX - truly decorative
Image(
painter = painterResource(id = R.drawable.divider),
contentDescription = null // null is enough for a decorative Image
)
// FIX - decorative element that is not an Image (for example a separator Text)
Text(
text = "\u2022",
modifier = Modifier.semantics { hideFromAccessibility() }
)
Testing Tool Commands
iOS Accessibility Inspector (Xcode)
Xcode -> Xcode menu -> Open Developer Tool -> Accessibility Inspector
- Run audit: choose the target (Simulator or device), then use the Audit control
- Inspect: use the inspection pointer and hover over elements in Simulator
- VoiceOver is not available in Simulator; test VoiceOver on a device
Android Accessibility Scanner
# Install Accessibility Scanner from Google Play (package com.google.android.apps.accessibility.auditor).
# adb install needs an APK file path, not a package name.
# Enable TalkBack via ADB (for CI)
adb shell settings put secure enabled_accessibility_services \
com.google.android.marvin.talkback/.TalkBackService
# Check accessibility node tree
adb shell uiautomator dump /sdcard/ui_dump.xml
adb pull /sdcard/ui_dump.xml
React Native Testing Library
npm install --save-dev @testing-library/react-native
import { render, screen, fireEvent } from '@testing-library/react-native';
// @testing-library/react-native 14: render() and fireEvent return Promises
test('button has accessible name and role', async () => {
await render(<SubmitButton />);
const btn = screen.getByRole('button', { name: /submit/i });
expect(btn).toBeOnTheScreen();
});
test('checkbox updates state', async () => {
await render(<TermsCheckbox />);
const checkbox = screen.getByRole('checkbox', { name: /accept terms/i });
expect(checkbox).not.toBeChecked();
await fireEvent.press(checkbox);
expect(checkbox).toBeChecked();
});
Maestro (E2E)
# .maestro/accessibility-checks.yaml
appId: com.example.myapp
---
- launchApp
- assertVisible:
label: "Submit form"
- tapOn:
label: "Close"
- assertNotVisible:
label: "Are you sure?"