accessibility-audit

Accessibility Audit — the table-stakes layer

Top-tier studios treat accessibility as non-negotiable craft, not a compliance checkbox. It's also where "premium" UI most often quietly fails: beautiful low-contrast text, custom controls that don't work with a keyboard, focus that vanishes. This audit catches those. WCAG 2.2 AA is the bar.

When to run

• Before shipping any interactive UI
• As a standing gate in the design-studio chain (alongside /design-critique)
• Whenever custom (non-native) controls are introduced

Input

A screenshot + the component code (ideally both). Code is essential — most a11y defects (focus, ARIA, semantics, keyboard) are invisible in a screenshot.

Audit passes

1. Contrast (WCAG 1.4.3 / 1.4.11)

• Body text ≥ 4.5:1; large text (≥18.66px bold or ≥24px) ≥ 3:1.
• UI components + graphical objects (icons, borders that convey state, focus rings) ≥ 3:1.
• Compute the actual ratio from hex values; flag each failure with current ratio + a passing alternative.
• Check disabled/placeholder text too (commonly fails, and "it's meant to be subtle" is not an exemption if it conveys info).

2. Keyboard (WCAG 2.1.1 / 2.4.3 / 2.4.7)

• Every interactive element reachable + operable by keyboard alone.
• Logical tab order matching visual order.
• Visible focus indicator on every focusable element (not outline: none with no replacement — the cardinal sin).
• No keyboard traps. Modals trap focus WHILE open and restore it on close.
• Custom controls (dropdowns, tabs, sliders) implement the expected key interactions (arrow keys, Esc, Enter/Space) per the ARIA Authoring Practices.

3. Semantics & ARIA (WCAG 1.3.1 / 4.1.2)

• Native elements first: <button> not <div onclick>, <a> for navigation, <nav>/<main>/<header> landmarks.
• ARIA only to fill gaps native HTML can't (and correct roles/states — aria-expanded, aria-selected, aria-current).
• First rule of ARIA: don't use ARIA if a native element does it. Flag every role="button" on a div that should just be a button.
• Form inputs have associated <label> (not placeholder-as-label).
• Icon-only buttons have aria-label.

4. Screen-reader experience

• Images: meaningful alt, decorative ones alt="".
• Dynamic updates announced (aria-live for toasts, async results, validation).
• Heading hierarchy logical (one h1, no skipped levels) — SR users navigate by headings.
• Hidden-but-present helper text where visual context isn't enough.

5. Motion & sensory (WCAG 2.3.3 / 1.4.13)

• prefers-reduced-motion honored.
• No info conveyed by color alone (add icon/text/pattern) — WCAG 1.4.1.
• Hover-revealed content also keyboard/focus-accessible and dismissible.

6. Target size & spacing (WCAG 2.5.8, new in 2.2)

• Interactive targets ≥ 24×24px (AA), ideally ≥ 44×44px for touch.
• Adequate spacing between adjacent targets.

Output format

## Accessibility audit — <surface>  (WCAG 2.2 AA)
**Verdict:** PASS / FAILS AA (N blocking)

### Blocking (fails WCAG AA)
1. [SC 1.4.3] Muted text #9CA3AF on #FFFFFF = 2.8:1 (needs 4.5:1) → use #6B7280 (4.6:1)
2. [SC 2.4.7] Custom dropdown has outline:none with no focus style → add visible focus ring (--color-focus-ring)
...

### Should-fix (AAA / best practice)
...

### Already compliant (keep)
...

Discipline

• Compute contrast ratios from actual hex — never assert "passes" without the number.
• If you only have a screenshot (no code), explicitly scope: "contrast + visual checks done; keyboard/ARIA/semantics require the code — not audited."
• Prioritize blocking (AA failures) over nice-to-have.

Chain position

Standing gate alongside /design-critique. Run on ui-engineer output before ship. A surface isn't "done" until it passes both the taste gate and this.

Anti-hallucination

Real WCAG success-criteria numbers only (1.4.3, 2.4.7, etc. are real). Real contrast math only. If unsure whether a custom control's ARIA pattern is correct, point to the WCAG ARIA Authoring Practices pattern by name rather than inventing required attributes.