Agentic A11Y

Accessibility Audit

Multi-agent accessibility audit of user-facing code across any platform. Dispatches specialist agents in parallel — each focused on a different disability category — verifies findings to filter false positives, maps every issue to specific accessibility criteria, and produces a persistent report with concrete fix recommendations.

Conformance target: WCAG 2.2 AA as baseline (applied via WCAG2ICT for non-web platforms). AAA criteria are flagged as bonus recommendations. Platform-specific guidelines (Apple HIG Accessibility, Android Accessibility, Xbox Accessibility Guidelines) are referenced where applicable.

This is a technique skill. Follow the phases in order. Do not skip verification.

Arguments

/paad:agentic-a11y accepts optional $ARGUMENTS:

• /paad:agentic-a11y — audit all user-facing code in the repository
• /paad:agentic-a11y src/components/ — scope the audit to a specific directory
• /paad:agentic-a11y src/components/Modal.tsx — audit a specific file

When a path is provided, only audit files within that scope. Still detect platform and run all specialists, but limit the file manifest accordingly.

Pre-flight Checks

digraph preflight {
  "Conversation has history?" [shape=diamond];
  "User-facing code exists?" [shape=diamond];
  "Proceed to Phase 1" [shape=box];
  "STOP: recommend new session" [shape=box, style=bold];
  "STOP: no user-facing code" [shape=box, style=bold];

  "Conversation has history?" -> "STOP: recommend new session" [label="yes"];
  "Conversation has history?" -> "User-facing code exists?" [label="no"];
  "User-facing code exists?" -> "STOP: no user-facing code" [label="no"];
  "User-facing code exists?" -> "Proceed to Phase 1" [label="yes"];
}

1. Context window: If conversation has substantive history beyond invoking this skill, tell the user: "This audit consumes significant context. Start a fresh session with /paad:agentic-a11y to avoid context rot." Stop and wait.
2. User-facing code: Scan for any of the following. If none found, tell the user: "No user-facing code detected in this repository." Stop.

Phase 1: Reconnaissance

Run these steps and collect results:

1. Platform detection

Classify the project into one or more platforms from the table above. A project may span multiple platforms (e.g., a web app with a CLI tool, or a React Native app with web support). Record all detected platforms — specialists will receive this classification.

2. Tech stack identification

Per detected platform:

• Web: Frameworks (React, Vue, Angular, Svelte, Next.js, etc.), CSS approach (Tailwind, CSS Modules, styled-components, etc.), component libraries (MUI, Radix, Headless UI, Bootstrap — note built-in a11y support)
• iOS: SwiftUI vs UIKit vs mixed, any a11y wrapper libraries
• Android: Jetpack Compose vs View system vs mixed, any a11y libraries
• React Native: version, any a11y libraries (e.g., react-native-a11y)
• Flutter: version, any a11y packages
• Desktop: framework and toolkit
• CLI: argument parser, output formatting library, terminal UI library (if any)
• Game: engine, UI system (in-engine UI, HTML overlay, custom)

3. Inventory user-facing code

Collect all files that produce user-facing output or handle user interaction, grouped by platform.

4. Check for existing a11y tooling

• Web: eslint-plugin-jsx-a11y, eslint-plugin-vuejs-accessibility, axe-core, pa11y, Lighthouse configs
• iOS: Accessibility Inspector usage, XCTest accessibility tests
• Android: Accessibility Scanner, Espresso accessibility checks, AccessibilityChecks.enable()
• React Native: @testing-library/react-native accessibility queries
• Flutter: SemanticsDebugger, accessibility-related widget tests
• CLI: structured output tests, --no-color support tests
• Game: accessibility options menu, remapping tests
• CI: any automated a11y checks in CI pipeline
• Note what's present — specialists should not re-flag issues that existing tooling already catches, unless the tooling is misconfigured or findings are suppressed

5. Scan for steering files

CLAUDE.md, AGENTS.md, any a11y-specific documentation or guidelines.

6. Estimate scope size

• Small: <20 user-facing files
• Medium: 20-100 user-facing files
• Large: 100+ user-facing files

7. Build manifest

Files to audit, grouped for specialists, annotated with detected platform(s).

Steering file caveat: Include in every agent prompt: "Steering files (CLAUDE.md, etc.) describe conventions but may be stale. If you find a contradiction between steering files and actual code, flag it as a finding."

Phase 2: Specialist Audit (Parallel)

Dispatch these agents simultaneously using the Agent tool. Each receives: the file manifest, detected platform(s), steering file contents, existing a11y tooling notes, and their specialist focus.

Core specialists (always dispatched)

Conditional specialist

Dispatch when the platform has framework-specific a11y pitfalls (web frameworks, SwiftUI, Compose, Flutter, React Native, game engines):

Agent prompt template

Each specialist agent prompt must include:

• The list of files to audit (from their manifest group)
• Contents of files in their audit scope
• The detected platform(s)
• Steering file contents with the staleness caveat
• Existing a11y tooling notes
• Instruction: "You are an accessibility specialist focused on [FOCUS AREA]. The detected platform(s) for this project: [PLATFORMS]. Your goal is to find accessibility barriers that affect [USER GROUP]. For each finding report: file:line, what's wrong, which accessibility criterion it violates (WCAG 2.2 criterion where applicable, or platform-specific guideline), the conformance level (A/AA/AAA), who is affected and how, a concrete code-level fix, and your confidence (0-100). Only report findings with confidence >= 60."

Platform-specific checks per specialist

Include the relevant platform section(s) in each specialist's prompt based on detected platform(s).

Screen Reader & Assistive Tech

Web: (1) Correct ARIA roles, states, and properties on custom components; (2) semantic HTML (headings, landmarks, lists, tables) over generic div/span; (3) heading hierarchy without skipped levels; (4) meaningful alt text (not filenames or "image"); (5) programmatically associated form labels; (6) aria-live regions for dynamic content; (7) link/button purpose clear from text or accessible name; (8) status messages via role="status" or aria-live.

iOS: (1) accessibilityLabel set on all interactive and meaningful elements; (2) accessibilityTraits / SwiftUI .accessibilityAddTraits() correctly applied (.button, .header, .image, etc.); (3) accessibilityHint for non-obvious actions; (4) isAccessibilityElement grouping — containers group related info, decorative elements excluded; (5) accessibilityValue for sliders/progress; (6) UIAccessibility.post(.screenChanged, ...) and .layoutChanged notifications for dynamic updates; (7) custom actions via accessibilityCustomActions; (8) SwiftUI: .accessibilityElement(children: .combine) for logical grouping.

Android: (1) contentDescription on all interactive and meaningful elements; (2) importantForAccessibility set correctly — decorative elements marked no; (3) labelFor connecting labels to inputs; (4) accessibilityLiveRegion for dynamic content; (5) accessibilityHeading on section headers; (6) Compose: semantics { } block with appropriate properties, contentDescription, heading(), stateDescription; (7) custom AccessibilityNodeInfo actions where needed; (8) ViewCompat.setAccessibilityDelegate for custom views.

React Native: (1) accessibilityLabel on all interactive elements; (2) accessibilityRole set correctly (button, header, link, image, etc.); (3) accessibilityState for toggles, disabled, expanded states; (4) accessibilityHint for non-obvious actions; (5) accessibilityLiveRegion for dynamic updates; (6) accessibilityElementsHidden for decorative content; (7) AccessibilityInfo.announceForAccessibility() for dynamic state changes.

Flutter: (1) Semantics widget wrapping meaningful UI with label, button, header, image properties; (2) excludeSemantics: true on decorative elements; (3) MergeSemantics for logically grouped content; (4) SemanticsService.announce() for dynamic updates; (5) tooltip properties on IconButton and similar; (6) semanticsLabel on Text where displayed text differs from meaning.

CLI: (1) Structured, parseable output (not just visual formatting with boxes/lines); (2) information not conveyed solely by position/layout — screen readers linearize output; (3) progress indication via text updates, not just spinners or progress bars that rely on cursor repositioning; (4) error messages written to stderr with clear text (not just color/emoji).

Game: (1) UI elements have text alternatives available for screen reader narration mode; (2) menu items narrated with name, type, and state; (3) game state changes announced; (4) narration option in settings if not always-on.

Visual & Color

Web: Contrast ratios — AA: 4.5:1 normal text, 3:1 large text (18pt+/14pt+ bold), 3:1 UI components and graphics. AAA: 7:1/4.5:1. Check CSS custom properties and theme values. Flag color-only meaning (error states, status indicators, required fields, links distinguished only by color). Reflow at 320px width. Text spacing override support. prefers-contrast media query support.

iOS: (1) Dynamic Type support (UIFontMetrics, SwiftUI .dynamicTypeSize), test with all type sizes including accessibility sizes; (2) Bold Text support (UIAccessibility.isBoldTextEnabled); (3) Increase Contrast (UIAccessibility.isDarkerSystemColorsEnabled); (4) Reduce Transparency support; (5) sufficient contrast ratios in custom themes (same ratios as web); (6) color-only information has shape/icon/text alternatives; (7) SF Symbols accessibility variants.

Android: (1) sp units for text (scales with user preference); (2) test at 200% font scale; (3) High Contrast Text setting support; (4) sufficient contrast in custom themes; (5) color-only meaning has alternatives; (6) Magnification gesture compatibility (no content hidden at 200%+ zoom); (7) custom views render correctly with font scaling.

React Native: (1) Font scaling support — not disabled via allowFontScaling={false} unless justified; (2) layout accommodates scaled text without overflow/truncation; (3) contrast ratios on all custom-themed elements; (4) color-only meaning has alternatives.

Flutter: (1) MediaQuery.textScaleFactorOf(context) respected — UI tested at 2.0 scale; (2) contrast ratios met in custom ThemeData; (3) color-only meaning has alternatives; (4) MediaQuery.boldTextOf(context) support; (5) MediaQuery.highContrastOf(context) support.

CLI: (1) --no-color flag or NO_COLOR env var support; (2) information not conveyed by color alone — use labels, prefixes, symbols alongside color (e.g., [ERROR] not just red text); (3) supports TERM detection for capability; (4) works in high-contrast terminal themes.

Game: (1) Colorblind mode(s) — at minimum deuteranopia (red-green), ideally also protanopia and tritanopia; (2) UI element outlines/patterns supplement color; (3) font size options or UI scaling; (4) high contrast UI option; (5) brightness/gamma controls; (6) important game elements distinguishable by shape, not just color.

Keyboard & Motor

Web: (1) Every interactive element reachable and activatable via keyboard; (2) no keyboard traps (focus can escape every modal, dropdown, overlay); (3) logical focus order matching visual layout; (4) visible focus indicators (not suppressed by outline: none without replacement); (5) skip navigation links; (6) custom widgets follow WAI-ARIA Authoring Practices keyboard patterns; (7) click targets at least 24x24 CSS px (AA), recommend 44x44 (AAA); (8) drag-and-drop has click/keyboard alternative; (9) single-character shortcuts remappable or only active on focus; (10) pointer-events, user-select not disabling expected interactions.

iOS: (1) Full Keyboard Access support — all actions reachable via external keyboard; (2) Switch Control compatibility — all interactive elements in accessibility tree with correct order; (3) AssistiveTouch custom gesture alternatives for complex gestures; (4) minimum 44x44pt tap targets (Apple HIG); (5) no gesture-only actions without alternatives (e.g., swipe-to-delete must have edit button); (6) custom gesture recognizers don't block Switch Control; (7) accessibilityActivationPoint set for non-standard hit areas.

Android: (1) Full keyboard navigation — android:focusable, logical nextFocusDown/Up/Left/Right; (2) Switch Access compatibility — all interactive elements focusable with adequate ordering; (3) minimum 48x48dp touch targets (Material Design); (4) no gesture-only actions without alternatives; (5) android:importantForAccessibility not hiding interactive elements; (6) custom views implement onKeyDown/onKeyUp for keyboard users; (7) TalkBack gesture alternatives for complex interactions.

React Native: (1) accessible={true} on all interactive elements; (2) accessibilityActions for custom actions; (3) onMagicTap, onEscape handlers where appropriate (iOS); (4) minimum touch target sizes (48x48dp Android / 44x44pt iOS); (5) gesture-based interactions have tap alternatives.

Flutter: (1) All interactive widgets have Semantics with tap/long press actions; (2) minimum touch targets via MaterialTapTargetSize.padded; (3) FocusNode and FocusTraversalGroup for logical keyboard order; (4) RawKeyboardListener/KeyboardListener for keyboard shortcuts; (5) no IgnorePointer/AbsorbPointer hiding accessible interactions; (6) custom GestureDetector actions have keyboard alternatives.

CLI: (1) Keyboard-only by nature, but check: interactive prompts (e.g., fuzzy finders, multi-select) navigable with arrow keys and enter; (2) Ctrl-C always exits; (3) no mouse-only interactions in TUI; (4) tab completion where appropriate; (5) long-running operations cancellable via keyboard.

Game: (1) Fully remappable controls; (2) multiple input device support (keyboard, mouse, controller, touch); (3) one-handed mode or alternative layouts; (4) no quick-time events without alternatives or adjustable timing; (5) auto-aim/aim assist option; (6) adjustable input sensitivity/dead zones; (7) hold-vs-toggle options for sustained inputs; (8) copilot/co-pilot mode if multiplayer.

Cognitive & Learning

All platforms: (1) Consistent navigation patterns across screens/pages; (2) consistent identification of common elements; (3) clear error messages identifying the problem and suggesting a fix; (4) labels and instructions on all form inputs; (5) predictable behavior — no unexpected context changes on focus or input; (6) adequate time — adjustable/extendable timeouts, warnings before expiry; (7) help in a consistent, findable location; (8) no unnecessary re-entry of previously provided information; (9) accessible authentication — no cognitive function tests (CAPTCHAs) without alternatives.

Web additionally: (1) lang attribute on <html> and lang attributes on content in other languages; (2) multiple ways to find pages (nav, search, sitemap); (3) breadcrumbs or location indicator.

iOS/Android additionally: (1) Back navigation always works predictably; (2) undo support for destructive actions; (3) confirmation dialogs for irreversible operations.

CLI additionally: (1) --help with clear, complete documentation; (2) confirmation prompts for destructive commands (with --yes/-y to skip); (3) meaningful exit codes; (4) consistent flag naming conventions (e.g., --verbose not -v in one command and --debug in another).

Game additionally: (1) Tutorial or onboarding; (2) difficulty options including easy/story mode; (3) objective tracking/quest log; (4) adjustable game speed; (5) pause in single-player; (6) clear visual/audio feedback for actions; (7) option to simplify UI.

Multimedia & Temporal

All platforms: (1) Pre-recorded video has captions; (2) pre-recorded audio has transcript; (3) no content flashes more than 3 times per second; (4) auto-playing media has pause/stop control; (5) moving/blinking/scrolling content can be paused; (6) no time limits, or limits are adjustable/extendable with warning.

Web additionally: prefers-reduced-motion media query respected — all CSS animations/transitions have reduced or disabled alternatives. Audio descriptions for pre-recorded video (AA). <video>/<audio> elements have controls. No autoplay without mute.

iOS additionally: UIAccessibility.isReduceMotionEnabled / SwiftUI .accessibilityReduceMotion checked and respected — simplify or remove animations. UIAccessibility.isVideoAutoplayEnabled respected.

Android additionally: Settings.Global.ANIMATOR_DURATION_SCALE respected (set to 0 disables animations). View.IMPORTANT_FOR_AUTOFILL for form timing.

React Native additionally: AccessibilityInfo.isReduceMotionEnabled() checked — Animated and LayoutAnimation respect user preference.

Flutter additionally: MediaQuery.disableAnimationsOf(context) or MediaQuery.reduceMotionOf(context) checked and respected.

CLI additionally: No seizure-inducing rapid terminal updates (e.g., fast flickering progress bars). Long-running operations show progress without rapid screen clearing.

Game additionally: (1) Subtitle options with size/background/speaker-identification controls; (2) visual indicators for important audio cues (directional indicators, closed captions for sound effects); (3) screen shake toggle; (4) motion blur toggle; (5) field-of-view slider (reduces motion sickness); (6) photosensitivity mode reducing flashes/strobe effects.

Platform-Specific Patterns agent (conditional)

Dispatch when the platform has framework-specific a11y pitfalls. Include relevant examples:

React: key on lists affecting screen readers, missing aria-live on state changes, portal focus traps, onClick on non-interactive elements without role/keyboard handling.

Vue: v-html with no a11y review, missing aria bindings on dynamic attributes, router afterEach not announcing navigation.

Angular: cdkTrapFocus misconfiguration, aria-describedby with *ngIf removing referenced elements.

Svelte: Reactive declarations removing focus targets, use:action without a11y side effects.

SwiftUI: .accessibilityRepresentation missing on custom controls, @AccessibilityFocusState not managing focus on navigation, .accessibilityRotor not used for long content, List/ForEach not providing per-item actions.

Jetpack Compose: Modifier.semantics not applied to custom composables, LazyColumn items missing individual semantics, AlertDialog not moving focus on show, ModalBottomSheet not trapping focus, clickable without role parameter.

Flutter: CustomPainter without SemanticsBuilder, Navigator transitions not announcing new routes, Hero animations conflicting with semantics, PlatformView breaking a11y tree.

React Native: FlatList/SectionList items not individually accessible, Modal not managing focus, platform-specific props missing (accessibilityLanguage iOS only, accessibilityLiveRegion Android emphasis).

Game engines (Unity): UI Toolkit vs UGUI a11y gaps, EventSystem not handling keyboard/controller navigation, TextMeshPro not exposing text to accessibility APIs.

Scaling for large scope (100+ files): Partition files across 2 instances of each specialist.

Phase 3: Verification

After all specialists complete, dispatch a single Verifier agent with all findings. The verifier:

1. For each finding, reads the actual current code at the referenced file:line
2. Confirms the accessibility barrier exists and isn't handled elsewhere (e.g., by a parent component, a platform API, a framework feature, a component library, or a system-level setting)
3. Drops false positives and findings below 60% confidence
4. Confirms the correct accessibility criterion is cited
5. Assigns severity:
   • Critical — Complete barrier: users with the affected disability cannot use this feature at all
   • Serious — Major difficulty: the feature is usable but with significant hardship or workarounds
   • Moderate — Friction: causes confusion or extra effort but does not block task completion
   • Minor — Best practice improvement or AAA enhancement
6. Deduplicates findings flagged by multiple specialists (note which specialists agreed — cross-specialist agreement increases confidence)

Verifier prompt must include: "You are verifying accessibility findings. For each finding, read the actual code and confirm the barrier exists. Be skeptical — the platform, framework, or component library may already handle accessibility automatically. On iOS, UIKit provides some accessibility by default for standard controls. On Android, standard Material components include accessibility support. A finding reported by multiple specialists is more likely real. Ensure the cited criterion is correct."

Phase 4: Report

Write verified findings to paad/a11y-reviews/a11y-<YYYY-MM-DD-HH-MM-SS>.md.

Create the paad/a11y-reviews/ directory if it doesn't exist.

Report template:

# Accessibility Audit: <project-name>

**Date:** YYYY-MM-DD HH:MM:SS
**Commit:** <full-sha>
**Platform(s):** <detected platforms>
**Tech stack:** <frameworks, libraries, engines>
**Files audited:** N
**Existing a11y tooling:** <list or "none found">
**Conformance target:** WCAG 2.2 AA via WCAG2ICT (AAA noted as recommendations)
**Platform guidelines referenced:** <e.g., Apple HIG Accessibility, Material Design Accessibility, Xbox Accessibility Guidelines, or "N/A">

## Executive Summary

2-3 sentences: overall accessibility posture, highest-severity findings, estimated conformance level (A / partial AA / AA / partial AAA).

## Impact Summary by User Group

Brief summary of how the codebase affects each group:
- **Screen reader users:** <1-2 sentences>
- **Low-vision users:** <1-2 sentences>
- **Colorblind users:** <1-2 sentences>
- **Motor-impaired users (keyboard/switch/sip-and-puff):** <1-2 sentences>
- **Cognitive and learning disabilities:** <1-2 sentences>
- **Deaf and hard-of-hearing users:** <1-2 sentences>
- **Vestibular and photosensitive users:** <1-2 sentences>

## Critical Issues (Complete Barriers)

### [C1] <title>
- **File:** `path/to/file:line`
- **Platform:** <which platform this applies to>
- **Barrier:** What's wrong
- **Criterion:** <WCAG criterion or platform guideline> — Level <A/AA>
- **Affects:** Who is blocked and how
- **Fix:** Concrete code-level recommendation
- **Confidence:** High/Medium
- **Found by:** <specialist name(s)>

(Repeat for each critical issue, or "None found.")

## Serious Issues (Major Difficulty)

(Same structure as Critical, or "None found.")

## Moderate Issues (Friction)

(Same structure, or "None found.")

## Minor Issues & AAA Recommendations

One-line entries with criterion reference. Omit section if none.
Mark AAA items with [AAA] prefix.

## Conformance Checklist

For each WCAG principle, list criteria checked and their status. For non-web platforms, criteria are interpreted via WCAG2ICT. Mark criteria that do not apply to the detected platform as "N/A" with brief explanation.

### Perceivable
| Criterion | Level | Status | Finding |
|-----------|-------|--------|---------|
| 1.1.1 Non-text Content | A | Pass / Fail / Partial / N/A / Not assessed | #ID or — |
(continue for all Perceivable criteria assessed)

### Operable
(same table format)

### Understandable
(same table format)

### Robust
(same table format)

### Platform-Specific Guidelines
| Guideline | Status | Finding |
|-----------|--------|---------|
| <e.g., Apple HIG: Dynamic Type> | Pass / Fail / Partial | #ID or — |
(list platform-specific guidelines checked beyond WCAG, or omit section if web-only)

## Quick Wins

Top 5 fixes that would have the largest positive impact for the least effort. Each entry: what to fix, which findings it addresses, estimated effort (small/medium/large).

## Audit Metadata

- **Agents dispatched:** <list with focus areas>
- **Platform(s) detected:** <list>
- **Scope:** <files audited>
- **Raw findings:** N (before verification)
- **Verified findings:** M (after verification)
- **Filtered out:** N - M
- **By severity:** X critical, Y serious, Z moderate, W minor
- **By conformance level:** X Level A, Y Level AA, Z Level AAA
- **Steering files consulted:** <list or "none found">
- **Existing a11y tooling:** <list or "none found">

Common Mistakes

These patterns produce low-quality audits. Avoid them:

Post-Audit

After writing the report:

1. Tell the user the report location and finding counts by severity
2. Tell them: "To address these findings, work through the Quick Wins first, then tackle Critical and Serious issues. Fix each issue with a per-fix commit. If you have the superpowers plugin installed, you can use the receiving-code-review skill and point it at this report for a guided workflow."
3. Do not auto-fix anything. The report is the deliverable.

Source: Ovid/paad — distributed by TomeVault.