Accessibility

Accessibility — Ship WCAG 2.2 AA, not vibes

The bar is conformance to WCAG 2.2 Level AA. "Looks fine to me" is not a measurement. Fix the semantics, scan what a machine can scan, then walk the part it can't.

The loop (your 30-second model)

Run these in order. Skipping a step front-loads rework.

1. Native semantics first. A real <button> ships focus, keyboard, and role for free. Most "a11y bugs" are a <div> doing a button's job.
2. Automated scan. axe-core catches roughly 57% of WCAG issues — missing labels, bad roles, contrast (in a real browser), duplicate ids. Cheap, run it every commit.
3. Manual checklist for the rest. The other ~43% — keyboard order, focus traps, meaningful alt text, screen-reader flow — no engine can judge. A human (or you, deliberately) must.

Decision rule: never ship on a green axe run alone. A clean automated scan means "no machine-detectable failures," not "accessible." Treat it as necessary, never sufficient.

Legal stakes are real: the EU European Accessibility Act became enforceable 2025-06-28 for many consumer products and services, on top of EN 301 549 / ADA. AA is the line.

Rule 0 — reach for HTML before ARIA

The first rule of ARIA is: don't use ARIA. If a native element gives you the semantics and behavior, use it. Every role you add is behavior you now owe by hand — focus, keyboard, state.

<!-- Bad: zero keyboard, no role, no focus, no Enter/Space -->
<div class="btn" onclick="save()">Save</div>

<!-- Good: focusable, Enter/Space fire it, announced as "Save, button" -->
<button type="button" onclick="save()">Save</button>

Reach for ARIA only when no native element fits (tabs, comboboxes, toasts) — and then copy a vetted pattern (→ references/aria-patterns.md).

Semantics & accessible names

• One <h1> per page. Headings describe structure; never skip a level (<h2> then <h4>) to get a font size — that's a CSS job.
• Landmark every region: <header> <nav> <main> <footer>. Exactly one <main>. Screen-reader users jump by landmark; a wall of <div> has no map.
• Skip link first in the DOM so keyboard users escape the nav: <a href="#main" class="sr-only-focusable">Skip to content</a>.
• Accessible name precedence (what a screen reader announces), highest wins: aria-labelledby → aria-label → associated <label> / element text → title. Don't stack them hoping one sticks; pick one source.

<!-- Bad: announced as just "button" -->
<button><svg aria-hidden="true">…</svg></button>

<!-- Good: announced as "Close dialog, button" -->
<button aria-label="Close dialog"><svg aria-hidden="true">…</svg></button>

A placeholder is not a label — it vanishes on input and many SRs ignore it. Use a real <label for>.

Keyboard operability

Everything a mouse can do, a keyboard must do.

• All interactive elements reachable and operable with Tab + Enter/Space. Native controls give this free; custom ones don't.
• Tab order follows the DOM. Fix order by reordering markup, not by patching tabindex.
• Never a positive tabindex. Only 0 (in natural order) or -1 (focusable by script, skipped by Tab). A positive value hijacks the whole page's order and breaks the next dev's mental model.
• Visible focus, always (see next section). If you can't tell where focus is with the mouse unplugged, neither can the user.

Overlays (dialogs, menus, drawers) need focus management — three obligations:

1. Move focus in when it opens (to the dialog or its first control).
2. Trap focus inside while open — Tab from the last element wraps to the first.
3. Escape closes, and focus returns to the trigger that opened it.

Composite widgets (menus, tabs, grids) use roving tabindex: one element is tabindex="0", the rest -1, arrow keys move the 0. Full keyboard tables per pattern — modal, disclosure, tabs, combobox, menu, toast → references/aria-patterns.md.

Visible focus & the WCAG 2.2 deltas

/* Bad: kills the focus ring with nothing in its place */
:focus { outline: none; }

/* Good: ring only for keyboard users, not mouse clicks */
:focus-visible { outline: 3px solid; outline-offset: 2px; }

WCAG 2.2 (W3C Recommendation, 2023-10-05) adds 9 success criteria and removes 4.1.1 Parsing. The six that matter at Level AA — know the numbers:

• 2.4.11 Focus Not Obscured (Minimum) — a focused element must not be fully hidden behind sticky headers/footers or cookie bars.
• 2.5.7 Dragging Movements — anything done by dragging (sliders, reorder, map pan) needs a single-pointer alternative (tap, buttons).
• 2.5.8 Target Size (Minimum) — interactive targets are at least 24×24 CSS px, unless spacing keeps a 24px-radius circle from overlapping a neighbor (the spacing exception). 44×44 is the comfort bar; 24 is the floor.
• 3.2.6 Consistent Help — help mechanisms appear in the same relative order across pages.
• 3.3.7 Redundant Entry — don't make users re-enter info they already gave in the same process; auto-fill or let them pick it.
• 3.3.8 Accessible Authentication (Minimum) — no cognitive-function test to log in (no puzzles, no "transcribe this", no math). Allow paste, password managers, and copy.

Contrast & color

Measured ratios, AA minimums:

• 4.5:1 for normal text.
• 3:1 for large text (≥24px, or ≥18.66px bold).
• 3:1 for UI components and graphical objects you must perceive (1.4.11) — input borders, icon glyphs, chart segments.

Never encode meaning in color alone (1.4.1). A red border on an invalid field is invisible to many users — pair it with text and an icon.

<!-- Bad: only color signals the error -->
<input class="border-red-500" aria-invalid="true">

<!-- Good: text + icon + programmatic association -->
<input aria-invalid="true" aria-describedby="email-err">
<p id="email-err">⚠ Enter a valid email address.</p>

Note: jsdom can't compute contrast (no real layout/paint), so jest-axe disables the rule. Verify contrast in a real browser (Playwright / Lighthouse) or by hand.