---
name: AI Accessibility Audit
description: 'WCAG 2.2 Level AA accessibility audit for AI product surfaces - color contrast, focus order, ARIA usage, keyboard navigation, motion/animation, reduced-motion respect, alt text, and form label association. Use when: accessibility audit, a11y review, WCAG audit, screen reader compliance, keyboard-only navigation, color contrast check, focus management, ARIA review, accessible AI UX.'
---

# AI Accessibility Audit

Catch accessibility regressions in AI product surfaces *before* they ship - chat interfaces, agent dashboards, generated-content panels, streaming output regions, and consent / safety UI. WCAG 2.2 Level AA is the bar; the framework below operationalizes it for AI-specific patterns that the spec doesn't natively cover.

## Core Principle

Accessibility is a property of the *experience*, not just the markup. An AI product can pass an axe-core scan and still be unusable for a screen-reader user if streaming output isn't announced, consent UI traps focus, or "regenerate" controls are unreachable from the keyboard. This skill audits both the static layer (DOM, contrast, semantics) and the AI-specific dynamic layer (live regions, latency, motion).

---

## The CLEAR Audit Framework

| Letter | Dimension | The Question |
|--------|-----------|--------------|
| **C** | Contrast & Color | Does every text/icon/state meet 4.5:1 (or 3:1 for ≥18pt or non-text UI)? Is color the *only* signal anywhere? |
| **L** | Logic of Focus | Can a keyboard-only user reach every action in a sensible order, with a visible focus indicator and no traps? |
| **E** | Equivalents for Non-Text | Do images, charts, generated visuals, and audio have meaningful alternatives - including AI-generated content? |
| **A** | Announcements & Live Regions | Are streaming outputs, status changes, and AI errors announced to assistive tech without spamming? |
| **R** | Respect for User Preferences | Does the product honor `prefers-reduced-motion`, `prefers-color-scheme`, OS-level font scaling, and reduced-data hints? |

---

## WCAG 2.2 AA Coverage Matrix

The skill produces findings against the success criteria most commonly violated in AI product surfaces:

| Success Criterion | What Gets Checked | AI-Specific Gotchas |
|-------------------|-------------------|---------------------|
| 1.1.1 Non-text Content | Alt text on every meaningful image | AI-generated images often ship with empty alt; charts rendered as `<canvas>` lack text equivalents |
| 1.3.1 Info & Relationships | Headings, lists, landmarks, form labels | Markdown rendered from LLM output frequently produces orphan headings (h3 without h2) |
| 1.4.3 Contrast (Minimum) | 4.5:1 on all body text | "Subtle" UI states (disabled, secondary, "thinking…") often dip below threshold |
| 1.4.10 Reflow | No horizontal scroll at 320 CSS px | Long streaming code blocks and tables break this - needs horizontal-scroll container, not body scroll |
| 1.4.11 Non-text Contrast | 3:1 for UI components, focus indicators | Custom focus rings on dark backgrounds frequently fail |
| 1.4.13 Content on Hover/Focus | Tooltips dismissible, hoverable, persistent | "Why this answer?" popovers on AI citations often violate all three |
| 2.1.1 Keyboard | All functionality keyboard-operable | Send button, regenerate, stop-generation, copy-to-clipboard, model picker - audit each |
| 2.1.2 No Keyboard Trap | Focus can leave any component | Modal consent gates and citation popovers frequently trap |
| 2.4.3 Focus Order | Logical, predictable focus order | Streaming content insertion can shift focus or skip newly-rendered actions |
| 2.4.7 Focus Visible | Visible indicator on every focused element | `outline: none` with no replacement is the single most common failure |
| 2.4.11 Focus Not Obscured (2.2 new) | Focused element not hidden behind sticky UI | Sticky composer bars often cover the focused message above |
| 2.5.7 Dragging Movements (2.2 new) | Single-pointer alternative for drag | "Drag to reorder citations" patterns need keyboard alternative |
| 2.5.8 Target Size (2.2 new) | Interactive targets ≥24×24 CSS px | Inline action chips inside chat bubbles routinely fail |
| 3.2.6 Consistent Help (2.2 new) | Help mechanisms consistently located | "Report response" / feedback controls drift across surfaces |
| 3.3.7 Redundant Entry (2.2 new) | Don't make users re-type info in the same flow | Multi-step agent setup flows commonly violate |
| 3.3.8 Accessible Authentication (2.2 new) | No cognitive function test for auth | API-key paste flows that disallow paste fail this |
| 4.1.3 Status Messages | Use ARIA live regions for status without focus shift | Streaming AI output, "Thinking…", and error toasts must use `aria-live="polite"` (not `assertive` for streaming - it spams) |

---

## AI-Specific Patterns the Spec Doesn't Cover

These are the patterns that pass a generic scan but fail real users of AI products. The skill explicitly checks each:

| Pattern | Failure Mode | Recommended Fix |
|---------|--------------|-----------------|
| **Streaming output** | Each token announced individually → screen reader chaos | Wrap streaming region in `aria-live="polite"` and `aria-atomic="false"`; announce only on sentence boundaries or every N tokens |
| **"Thinking…" indicators** | Animated dots invisible to AT, or announced repeatedly | Single `aria-live="polite"` status text, not a loop; respect `prefers-reduced-motion` for the animation |
| **Stop-generation control** | Only appears mid-stream and steals focus | Reserve a stable focusable slot; toggle `aria-disabled`, don't add/remove from DOM |
| **Citation popovers** | Open on hover only; trap focus when keyboard-opened | Open on focus or click; ESC closes and returns focus to trigger |
| **Regenerate / variant carousel** | Right-arrow cycles, but not announced | Use `role="region"` + `aria-label` + `aria-live` on the active variant |
| **Consent / safety modals** | First-time modals trap focus before user understands | Focus headline (not first input); `Esc` closes only if the action is non-blocking |
| **Generated images** | `alt=""` or `alt="image"` | Caption with the *user's prompt* as a baseline; let users override |
| **Voice / audio output** | No transcript; no captions on TTS | Always render the spoken text; offer scrubbable transcript |
| **Color-coded confidence** | Red/yellow/green badge with no text | Pair every color with a label or icon |

---

## Output

Save to `outputs/a11y-audit-[surface]-[YYYY-MM-DD].md`

The audit produces a prioritized issue list:

| Severity | Definition | Examples |
|----------|------------|----------|
| **Critical** | Blocks a class of users from completing a core task | Send button unreachable by keyboard; modal traps focus; streaming output unannounced |
| **Serious** | Significantly degrades the experience for assistive-tech users | Focus indicator removed; contrast 3.5:1 on body text; missing form labels |
| **Moderate** | Workaround exists but cognitive load is high | Confusing focus order; redundant announcements; small touch targets |
| **Minor** | Polish-level; doesn't block any task | Decorative icons exposed; non-essential heading-level skip |

Every finding includes:
- **Where** - selector, screenshot, or step-by-step reproduction
- **WCAG criterion** - e.g., "2.4.7 Focus Visible (AA)"
- **Why** - the user impact in one sentence
- **Fix** - concrete code snippet or design change, not just "add ARIA"
- **Test** - how to verify the fix (keyboard-only walk, NVDA/VoiceOver script, contrast number)

---

## Process

### Step 1: Scope the Audit
I'll ask:
> "What surface am I auditing? (URL, route, component name, or screenshot.) What user flows must work end-to-end? (e.g., 'send a message and copy the response'.) Any known assistive-tech users I should optimize for?"

### Step 2: Static Layer Pass (CLEAR - C, E)
Walk the rendered DOM and styles for contrast, semantics, alt text, landmarks, and headings. Produce findings against 1.x and 4.1.x criteria.

### Step 3: Keyboard Layer Pass (CLEAR - L)
Tab through every focusable element from `<body>`. Note: focus visibility, focus order vs. visual order, focus traps, missing focus return after dismissals, and 2.2's new criteria (2.4.11, 2.5.7, 2.5.8).

### Step 4: Dynamic / AI Layer Pass (CLEAR - A)
Trigger streaming output, errors, stop-generation, regenerate, citation popovers, and consent modals. Verify announcements (live regions), focus behavior on insertion, and motion respect.

### Step 5: Preference Pass (CLEAR - R)
Confirm `prefers-reduced-motion`, `prefers-color-scheme`, font-size scaling to 200%, and zoom to 400% all degrade gracefully.

### Step 6: Synthesize the Report
Group findings by severity, then by CLEAR dimension. Add a one-page "ship blockers" summary at the top (Critical + Serious only) so the team knows what must be fixed before release.

### Step 7: Acceptance Tests
For each Critical and Serious finding, write a one-line acceptance test the team can paste into their PR template (e.g., "Tabbing from composer → send → response area works in this order; focus visible at every stop").

---

## Tips
1. **Audit the *flow*, not just the page** - a checkbox-clean page with a broken send-message flow is worse than a couple of contrast warnings on a perfect flow.
2. **Test with the OS, not just a browser extension** - turn on VoiceOver / NVDA for at least one full task. Extensions don't catch announcement spam.
3. **Treat 2.2's new criteria as table stakes** - 2.5.8 (target size) and 2.4.11 (focus not obscured) catch ~30% of real-world failures in chat UIs.
4. **Make accessibility part of the prompt** - when generating UI from a model, include "WCAG 2.2 AA, visible focus, semantic HTML, aria-live for streaming" in the system prompt; it raises the floor measurably.