Accessibility (WCAG 2.2 AA)

1. Native first

Use the real element: <button>, <a href>, <input type="checkbox">, <select>, <dialog>, <details>. ARIA is for when no element exists, and "no ARIA is better than bad ARIA".

2. Keyboard

• Everything clickable is reachable with Tab and works with Enter/Space.
• Logical tab order follows reading order; no positive tabindex.
• Composite widgets (tabs, menus, listboxes) use arrow keys inside, one tab stop.
• Esc closes overlays. No keyboard traps.
• A visible "Skip to content" link on pages with navigation.

3. Focus

• :focus-visible ring with ≥ 3:1 contrast; never outline: none without a replacement.
• Dialogs: move focus in on open, trap it, return it to the trigger on close.
• After route changes or async content, move focus or announce it.
• Focused items are not hidden behind sticky headers (2.4.11).

4. Names, roles, states

• Icon-only buttons get aria-label.
• Inputs have a visible <label>; placeholders are not labels.
• Custom switch: role="switch" + aria-checked. Toggle button: aria-pressed. Disclosure: aria-expanded + aria-controls.
• Live updates (toasts, async results) use role="status" or aria-live="polite".

5. Contrast and colour

• Text ≥ 4.5:1; large text (≥ 24 px, or 18.66 px bold) ≥ 3:1.
• UI components and focus indicators ≥ 3:1 against neighbours.
• Never convey state by colour alone: add an icon, label or pattern.
• Check both light and dark themes.

6. Motion

• Respect prefers-reduced-motion: remove parallax, auto-play, large movement.
• Nothing flashes more than 3 times per second.
• Auto-moving content longer than 5 s has pause/stop.

7. Forms and errors

• Errors are text, next to the field, linked with aria-describedby, and say how to fix.
• Don't block paste; support autocomplete attributes.
• Don't require re-entering info already given (3.3.7); allow non-puzzle auth (3.3.8).

8. Targets and zoom

• Pointer targets ≥ 24×24 CSS px (2.5.8); 44 px recommended.
• Works at 200% zoom and 320 px width without horizontal scroll.
• Drag actions have a single-pointer alternative (2.5.7).

9. Media and images

• Meaningful images have alt; decorative images use alt="".
• Video has captions; audio has transcripts.

Manual test script

1. Unplug the mouse; complete the main flow with keyboard only.
2. Run a screen reader (VoiceOver / NVDA / TalkBack) over the main flow.
3. Zoom to 200%; set the viewport to 320 px.
4. Turn on reduced motion; reload.
5. Run an automated checker (axe, Lighthouse) and fix everything it finds; it catches ~30–40% of issues.

Customize for your project

Target level ({{WCAG_LEVEL}}, default AA), supported screen readers, and the automated checker wired into CI.