Accessibility (WCAG 2.2 AA)

Every component, page, and flow ships at WCAG 2.2 AA or better. Accessibility isn't a separate phase — it's part of "done". Run this checklist on every UI PR.

Semantic HTML first

• Use the right element for the job before reaching for ARIA. ARIA fixes nothing that semantic HTML didn't break first.
• Buttons that look like links → <a>. Links styled as buttons → <button>. They are not interchangeable.
• Headings (h1–h6) reflect document structure, not visual hierarchy. Don't pick a heading for its size — that's CSS's job.
• Forms use <form>, <label>, <fieldset>, <legend>. Every input has a programmatically associated label.
• Lists use <ul> / <ol> / <li>. Don't fake a list with divs.
• Landmarks: <header>, <nav>, <main>, <aside>, <footer> — exactly one <main> per page.

Keyboard

• Every interactive element reachable with Tab, in a logical order.
• Enter activates buttons and links; Space activates buttons.
• Escape closes modals, dropdowns, popovers.
• Arrow keys navigate within composite widgets (radio groups, menus, tablists).
• Custom widgets implement the matching ARIA pattern — don't invent a new one.
• Focus is always visible. Never outline: none without a custom focus indicator at ≥3:1 contrast.
• Skip-link to <main> at the top of every page.

Focus management

• When a modal opens, focus moves into it; when it closes, focus returns to the trigger.
• When a route changes, focus moves to the new page's <h1> or main heading.
• Toasts and notifications don't steal focus. Use aria-live instead.
• Focus traps in modals and only modals — every other widget allows tabbing out.

Color & contrast

• Text contrast ≥4.5:1 against background (3:1 for ≥18pt or ≥14pt bold).
• Non-text UI (icons, focus rings, borders that convey state) ≥3:1.
• Color is never the only signal. Errors carry an icon + text, not just red. Required fields have a * and aria-required, not just a colored asterisk.
• Test in greyscale and in dark mode if you support it.

Images & media

• Every <img> has an alt. Decorative images use alt="". SVGs that are decorative get aria-hidden="true".
• Icons inside buttons that have visible text use aria-hidden="true" on the icon.
• Icon-only buttons have aria-label.
• Videos have captions (and transcripts for long-form). Auto-play with sound is forbidden.

Forms

• Every input has a <label> programmatically associated (for / id or wrapping).
• Required fields announced via aria-required="true" and visually marked.
• Error messages associated with their input via aria-describedby and aria-invalid="true".
• Errors appear inline near the field, not only at the top of the form.
• autocomplete attributes set correctly (email, current-password, cc-number).
• Don't use placeholder as a label. Placeholders disappear and have poor contrast.

Motion

• Respect prefers-reduced-motion. Disable parallax, autoplay, large animation when set.
• No flashing > 3 times per second (seizure risk).
• Carousels: pause-on-focus, and a visible pause button.

Screen-reader specific

• Live regions: aria-live="polite" for status messages, assertive only for genuine errors blocking the user.
• Don't put role="button" on a <div>. Use a <button>. The two are not equivalent for screen readers.
• Don't hide content with display: none if you need a screen reader to announce it. Use .sr-only (visually hidden, accessible).
• Test with VoiceOver (macOS / iOS) and NVDA (Windows) at least once before shipping.

What to flag in review

• <div onClick> instead of <button>.
• Custom widgets that don't implement the ARIA pattern (modal without role="dialog" and focus trap, etc.).
• Click-only handlers — every action also reachable by keyboard.
• Color-only state changes (e.g. red border on error with no text or icon).
• Missing alt on <img>, missing aria-label on icon buttons.
• Outline removed without a replacement focus indicator.
• Auto-focusing inputs that aren't expected (steals focus from screen reader users).
• tabindex values > 0 — they break logical order.

Tooling

• eslint-plugin-jsx-a11y (React) or @vue/eslint-plugin-vue-a11y (Vue) on every PR.
• axe-core integrated into component tests.
• One full-page Lighthouse run before each release; accessibility score ≥95.