Axiom Accessibility

Cursor UI Tool Availability

xcui is an external tool and is not bundled with the Cursor plugin; it has no Axiom MCP wrapper. Before UI automation, check command -v xcui. If it is absent, AXe fallback is limited to compatible input verbs: tap, slider, type, swipe, drag, touch, gesture, button, key, key-sequence, key-combo, and screenshot. Then check command -v axe before that fallback and handle DEVELOPER_DIR explicitly if AXe reports a SimulatorKit loading error. AXe cannot replace wait, assert, a11y, dialog, voiceover, resize, or doctor. If neither tool is available, stop UI automation, explain the external setup requirement, and continue only with non-UI simulator and log checks. If AXe exists but the requested workflow requires an xcui-only capability, stop that UI workflow and report the limitation.

Accessibility

You MUST use this skill for ANY accessibility work including VoiceOver, Dynamic Type, color contrast, WCAG compliance, and UX flow auditing.

Cursor Subagent Routing

Delegate to the appropriate Cursor subagent when this router calls for a specialized auditor.

Quick Reference

Cross-Suite Routes

• Full watchOS development context → See axiom-watchos
• Live accessibility validation on the simulator (set toggles, assert announcements) → simulator-tester agent + xcui — see axiom-tools (skills/xcui-ref.md)
• Asserting VoiceOver speech in an XCUITest (XCUIDevice.shared.voiceOverService, OS27) → axiom-testing (skills/ui-testing.md Pattern 7)

Decision Tree

digraph accessibility {
    start [label="Accessibility issue" shape=ellipse];
    what [label="What type?" shape=diamond];

    start -> what;
    what -> "skills/accessibility-diag.md" [label="VoiceOver/labels/hints"];
    what -> "skills/accessibility-diag.md" [label="Dynamic Type"];
    what -> "skills/accessibility-diag.md" [label="color contrast"];
    what -> "skills/accessibility-diag.md" [label="touch targets"];
    what -> "skills/accessibility-diag.md" [label="keyboard nav"];
    what -> "skills/accessibility-diag.md" [label="resizable window / desktop-class"];
    what -> "skills/accessibility-diag.md" [label="Reduce Motion"];
    what -> "skills/accessibility-diag.md" [label="Assistive Access"];
    what -> "skills/accessibility-diag.md" [label="custom control techniques"];
    what -> "skills/accessibility-diag.md" [label="continuous reading / text navigation"];
    what -> "skills/accessibility-diag.md" [label="captions / subtitle styling"];
    what -> "skills/accessibility-diag.md" [label="App Store prep / Nutrition Labels"];
    what -> "skills/ux-flow-audit.md" [label="UX dead end/dismiss trap"];
    what -> "skills/ux-flow-audit.md" [label="missing states"];
    what -> "skills/watchos-a11y.md" [label="watchOS VoiceOver / AssistiveTouch / Double Tap"];
    what -> "accessibility-auditor" [label="automated scan" shape=box];
}

1. ANY VoiceOver, Dynamic Type (including tvOS Large Text), contrast, touch target, or WCAG issue → skills/accessibility-diag.md
2. Assistive Access (cognitive disabilities, iOS 17+) → skills/accessibility-diag.md
3. App Store accessibility rejection or Nutrition Labels → skills/accessibility-diag.md
4. Reading app: VoiceOver stops at paragraphs/pages, Speak Screen halts → skills/accessibility-diag.md
5. UX dead ends, dismiss traps, buried CTAs, missing states → skills/ux-flow-audit.md
6. watchOS-specific accessibility (rotor on Digital Crown, AssistiveTouch, Double Tap) → skills/watchos-a11y.md
7. Want automated accessibility scan? → accessibility-auditor agent or /axiom-audit accessibility

Automated Scanning

Accessibility audit → Delegate to the accessibility-auditor subagent or /axiom-audit accessibility

• VoiceOver labels and hints
• Dynamic Type violations
• Color contrast failures
• WCAG compliance scanning

UX flow audit → Delegate to the ux-flow-auditor subagent

• Dead-end views, dismiss traps
• Buried CTAs, missing empty/loading/error states
• Deep link dead ends, accessibility dead ends

Critical Patterns

Image Accessibility

• Use Image(decorative: "photo") for purely decorative images — automatically hidden from VoiceOver (equivalent to accessibilityHidden(true) but semantically clearer)
• Use accessibilityInputLabels() for buttons with complex or changing labels — improves Voice Control accuracy by providing alternative labels
• Respect accessibilityDifferentiateWithoutColor environment value — when active, provide non-color cues (icons, patterns, labels) alongside color indicators

Anti-Rationalization

Example Invocations

User: "My button isn't being read by VoiceOver" → See skills/accessibility-diag.md

User: "How do I support Dynamic Type?" → See skills/accessibility-diag.md

User: "Check my app for accessibility issues" → See skills/accessibility-diag.md

User: "Prepare for App Store accessibility review" → See skills/accessibility-diag.md

User: "Scan my app for accessibility issues automatically" → Delegate to the accessibility-auditor subagent

User: "How do I support Assistive Access?" → See skills/accessibility-diag.md

User: "How do I prepare my tvOS app for Large Text?" → See skills/accessibility-diag.md

User: "VoiceOver reads my screen in the wrong order after the window resizes" → See skills/accessibility-diag.md

User: "How do I support Button Shapes / the Large Content Viewer in my custom controls?" → See skills/accessibility-diag.md

User: "VoiceOver stops reading at the end of each page in my book app" → See skills/accessibility-diag.md

User: "How do I let users restyle subtitles or get generated captions in my video player?" → See skills/accessibility-diag.md

User: "Check for UX dead ends and dismiss traps" → See skills/ux-flow-audit.md

User: "My fullScreenCover has no way to dismiss" → See skills/ux-flow-audit.md

User: "Are there missing empty states in my app?" → See skills/ux-flow-audit.md