// Audit accessibility of the running React Native app. Captures the accessibility tree from the iOS Simulator and checks it against React Native best practices. Triggers on "audit accessibility", "check a11y", "VoiceOver check", "accessibility issues", "screen reader test", "are labels correct".
| name | a11y-audit |
| description | Audit accessibility of the running React Native app. Captures the accessibility tree from the iOS Simulator and checks it against React Native best practices. Triggers on "audit accessibility", "check a11y", "VoiceOver check", "accessibility issues", "screen reader test", "are labels correct". |
| allowed-tools | Bash, Read, Grep, Agent |
On load: Read ../../.claude-plugin/plugin.json from this skill's base directory. Display a11y-audit v{version} before proceeding.
Audit the accessibility tree of a running React Native app in the iOS Simulator against official React Native accessibility documentation.
| Skill / Resource | Why |
|---|---|
ios-sim | ui.sh describe-all captures the accessibility tree; capture.sh view used for optional screenshot context |
_shared (metro.sh, cdp-bridge.js) | Optional Step 1.5 — extracts React-declared a11y props via CDP when Metro is running |
| Level | Meaning | Examples |
|---|---|---|
| Critical | Blocks screen reader users | Interactive element without accessibilityLabel; image without label |
| Warning | Degrades experience | Touch target < 44x44pt; missing accessibilityRole on button |
| Info | Improvement opportunity | Missing accessibilityHint; elements that could be grouped |
Before dispatching the subagent, verify AXe is installed:
Run: command -v "${IOS_SIMULATOR_MCP_AXE_PATH:-axe}" >/dev/null 2>&1
If this fails, stop and tell the user:
"a11y-audit requires AXe to read the accessibility tree.
Install with: brew install cameroncooke/axe/axe
Then re-run this skill."
Do not dispatch the subagent if AXe is missing — it will fail immediately.
Never load the accessibility tree in main context. Dispatch a subagent.
Dispatch Agent:
subagent_type: general-purpose
model: haiku
description: "a11y-audit: capture and analyze accessibility tree"
prompt: |
You are auditing the accessibility of a React Native app running in the iOS Simulator.
1. Run: ${CLAUDE_SKILL_DIR}/../ios-sim/scripts/ui.sh describe-all
This outputs the full accessibility tree as JSON.
2. Read the checklist: ${CLAUDE_SKILL_DIR}/references/a11y-checklist.md
3. Walk every element in the tree. Check for these issues:
CRITICAL:
- Interactive elements (buttons, links, switches, text fields) without accessibilityLabel
- Images without an accessibility label
- Elements with an accessibilityLabel that is just a filename or empty string
WARNING:
- Interactive elements without accessibilityRole or role
- Touch targets smaller than 44x44 points (check frame width/height)
- Nested accessible elements (accessible parent containing accessible children)
- Toggle/checkbox elements missing accessibilityState
INFO:
- Interactive elements missing accessibilityHint
- Potential grouping opportunities (adjacent related elements)
- Static text elements that could use a header role
4. Return a structured text report in this exact format:
ACCESSIBILITY AUDIT REPORT
==========================
Total elements scanned: <N>
Issues found: <N> critical, <N> warning, <N> info
CRITICAL ISSUES
---------------
1. [element description] at (x, y) — Missing accessibilityLabel
Fix: Add accessibilityLabel="<suggested label>"
...
WARNINGS
--------
1. [element description] at (x, y) — Touch target too small (WxH)
Fix: Add hitSlop or increase padding to at least 44x44pt
...
INFO
----
1. [element description] — Missing accessibilityHint
Suggestion: Add accessibilityHint="<suggested hint>"
...
If no issues in a category, write "None found."
Return text only. Be thorough but concise.
If Metro/Hermes debugger is available, extract React-declared accessibility props from the fiber tree and compare against the native accessibility tree from Step 1.
Guard: Run ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh status. If exit code is 1 (Metro not running), skip silently to Step 2.
If Metro is running:
Dispatch a subagent that:
${CLAUDE_SKILL_DIR}/../_shared/scripts/cdp-bridge.js tree (full fiber tree output)accessible, accessibilityLabel, accessibilityRole, accessibilityHint, accessibilityState, accessibilityValue, importantForAccessibility, role, aria-label, aria-hiddenWhy subagent: Full fiber tree is 10-100 KB, too large for main context. The subagent processes it and returns only the discrepancy report (~1-3 KB).
After the subagent returns its report, grep the React Native docs for relevant best practices. If CDP data is available from Step 1.5, add a DISCREPANCIES section comparing React-declared props against native a11y tree values.
Grep "${CLAUDE_SKILL_DIR}/../../refs/react-native-docs/accessibility.md" for key terms
from the audit (e.g., accessibilityLabel, accessibilityRole, accessibilityHint).
Read specific sections only if needed to provide accurate fix guidance.
Combine the subagent audit report with doc references:
accessibility.md| Item | Size | In Main Context? |
|---|---|---|
| Accessibility tree JSON | ~10-100 KB | NEVER — subagent only |
| Audit checklist | ~4 KB | Subagent only |
| Subagent text report | ~1-3 KB | YES |
| CDP a11y discrepancy report | ~1-3 KB | YES (from subagent) |
| Doc grep results | ~200-500 chars | YES |
ios-sim skill to launch if needed.frame dimensions from the tree.adb is needed (not covered by this skill).React Native coding guidance — consults official docs before writing code and suggests verification after. Use when writing components, implementing features, building screens, fixing queries, or adding views. Triggers on "write a component", "implement this feature", "build this screen", "add a view", "React Native code", "fix this query", "use best practices".
Intelligent environment reset for React Native projects — diagnoses stale caches before cleaning instead of blindly nuking everything. Triggers on "clean build", "reset caches", "fresh start", "metro won't start", "build is broken", "nuclear clean", "clear derived data".
Debug React Native apps — view console logs, JS errors, Metro status, evaluate expressions, inspect React component tree, monitor network requests. Use for runtime debugging of JavaScript and React layers. Triggers on "console logs", "JS errors", "Metro status", "evaluate expression", "React component tree", "network requests", "debug".
Test deep links and URL schemes in the iOS Simulator. Reads navigation/linking config, constructs test URLs, fires them via xcrun simctl, and verifies the resulting screen. Triggers on "test deep link", "test this URL scheme", "verify navigation to", "does deeplink work", "open URL in simulator", "test universal link".
Diagnose React Native errors by cross-referencing error text against docs, error pattern database, and project config. Use for build failures, red screens, runtime crashes, and dependency issues. Triggers on "diagnose this error", "why is my build failing", "what does this red screen mean", "Unable to resolve module", "null is not an object", "Invariant Violation", "pod install failed", "gradlew failed", "EACCES", "metro error".
Search React Native official documentation. Use when answering questions about React Native APIs, components, hooks, layout, navigation, native modules, or platform-specific behavior. Triggers on "React Native", "RN docs", "how does View work", "FlatList props", "native module", "new architecture".