audit-accessibility-wcag

name	audit-accessibility-wcag
description	Audits and fixes markup/JSX for WCAG 2.2 AA compliance — alt text, ARIA, heading order, contrast, keyboard nav, focus management; used before shipping UI or preparing an a11y review.
when_to_use	When the user wants an accessibility (a11y) check or fix, mentions WCAG, screen readers, ARIA, keyboard navigation, color contrast, or is preparing for an accessibility audit.

When to Use

Trigger this skill when the task is to audit or fix UI for accessibility: WCAG 2.2 AA, screen readers, ARIA, keyboard nav, color contrast, focus management, or preparing an a11y review.

NOT this skill: pure visual/layout polish (no a11y intent), or security/XSS concerns — that is security-review. ARIA/role injection that touches dangerouslySetInnerHTML or user-controlled markup overlaps both; flag the a11y part here and hand the injection risk to security-review.

Steps

Work in this order. Earlier rules outrank later ones — never reach for ARIA to patch a problem that semantic HTML already solves.

1. Scope the surface. Identify the files/components in the diff or named target. Grep for the smells that produce most findings: rg -n 'role=|aria-|onClick=|<div|<span|tabindex|tabIndex|alt=|<img|placeholder=' across the target. Build a checklist; do not audit the whole repo unless asked.

2. Semantic HTML first. Replace <div onClick> / <span onClick> with a real <button type="button">. Use <a href> only for navigation (has a destination), <button> for actions (no navigation). Use <nav>, <main>, <header>, <footer>, <ul>/<li>, <table> over <div role="...">. One <main> per page. A native element is keyboard-operable and announced for free; a styled div is not.

3. Images & icons. Every <img> needs alt. Informative image → describe its meaning (alt="Quarterly revenue up 12%"), not the filename. Decorative/redundant image → alt="" (empty, not missing — missing alt makes SRs read the URL). Icon-only buttons need an accessible name via aria-label or visually-hidden text; an inline SVG that conveys meaning needs role="img" + aria-label, a decorative one needs aria-hidden="true".

4. Heading hierarchy. Exactly one <h1>. No skipped levels (h2 → h4 is a fail; reflows the SR outline). Headings describe structure, not font size — never pick a level for its default styling. Don't fake headings with bold <p>/<div>.

5. ARIA only where native fails. First rule of ARIA: don't use ARIA. Apply it only for patterns HTML can't express (tabs, comboboxes, live regions, disclosure). When you do: every role must carry its required states (e.g. role="tab" needs aria-selected + aria-controls; aria-expanded on every disclosure/menu trigger; role="dialog" needs aria-modal="true" + aria-labelledby). Never put an interactive role on a non-interactive element without also making it focusable (tabindex="0") and key-handled. Remove redundant roles (role="button" on a <button>).

6. Forms. Every input has a programmatic label: <label for> / htmlFor, wrapping <label>, or aria-label/aria-labelledby. Placeholder is NOT a label (vanishes on input, low contrast). Required → required + visible indicator. Errors: link the message with aria-describedby on the field, set aria-invalid="true", and announce dynamic errors via an aria-live="polite" (or role="alert" for assertive) region. Group radios/related fields in <fieldset> + <legend>.

7. Color contrast (WCAG 2.2 AA). Body text ≥ 4.5:1; large text (≥ 24px, or ≥ 18.66px bold) ≥ 3:1; UI components, icons, and focus indicators ≥ 3:1 against adjacent colors. Compute ratios from the actual hex values (resolve CSS vars/Tailwind tokens to real colors first). Never rely on color alone to convey state — pair it with text/icon/shape. Check disabled, hover, and dark-mode states too.

8. Keyboard. Everything operable by mouse must work by keyboard. Tab order follows DOM order — fix with DOM/flexbox order reasoning, never positive tabindex (1+). tabindex="-1" = focusable by script only; 0 = in natural order. Every interactive element needs a visible focus indicator — do NOT outline: none without a replacement (:focus-visible ring). Add a "Skip to main content" link as the first focusable element. No keyboard traps (you can Tab out of every widget). Custom widgets implement expected keys (Esc closes, Arrow keys move within tabs/menus/listbox per ARIA APG).

9. Focus management (dynamic UI). On modal/dialog open: move focus into it, trap Tab within it, restore focus to the trigger on close, Esc closes. On client-side route change: move focus to the new page's <h1> or a focusable container so SR users aren't stranded. Toasts/async results → announce via live region, don't steal focus mid-task.

10. Report. Output a prioritized list grouped Blocker → Major → Minor, each entry = file:line, the WCAG criterion (e.g. 1.1.1, 2.4.7), the concrete problem, and a copy-pasteable fix (before → after). Blocker = blocks a user from completing a task (unlabeled control, keyboard trap, no focus on modal). Major = significant barrier (contrast fail, skipped heading). Minor = friction (redundant role, missing lang). Apply the fixes when asked; otherwise leave them as ready-to-paste diffs.

Common Errors

• alt="" vs missing alt — empty is intentional "decorative, skip me"; missing makes SRs announce the file path. Not interchangeable.
• Placeholder used as the only label. Fails 1.3.1/4.1.2 and disappears once typing starts.
• outline: none / outline: 0 in a CSS reset with no :focus-visible replacement — silently removes the focus ring for keyboard users. Single most common keyboard fail.
• Positive tabindex ("1", "2"…) to "fix" order — creates a brittle parallel tab sequence ahead of everything else. Fix DOM order instead.
• aria-label on a non-interactive, non-role'd element (plain <div>/<span>/<p>) — most SRs ignore it. The name needs an element that takes a name.
• role="button" on a <div> without tabindex="0" AND onKeyDown for Enter/Space — looks clickable, dead to keyboard. Just use <button>.
• Click handler only on the icon <svg>/<i> inside a control — enlarge the hit target and put the handler + name on the <button>.
• aria-hidden="true" on a focusable element (or an ancestor of one) — hides it from SRs while it stays in the tab order: a focusable ghost. Never wrap interactive content in aria-hidden.
• Live region added to the DOM at the same time as its message — SRs only announce changes to an already-present region. Render the empty aria-live container first, then inject text.
• Tailwind/utility color audit done on class names — text-gray-400 on bg-white is not a contrast value. Resolve to hex, then compute the ratio.
• Trusting the linter as "done" — eslint-plugin-jsx-a11y/axe catch static markup issues only. They cannot see contrast against rendered backgrounds, focus order, trap behavior, or whether a name actually makes sense. Keyboard/SR behavior needs manual or automated runtime checks.

Verify

Static (always): rg -n 'outline:\s*(none|0)|tabindex=["\x27][1-9]|aria-hidden=["\x27]true' <target> returns no unjustified hits. If the project has it, run npx eslint --no-eslintrc --plugin jsx-a11y (or the existing a11y lint task) → zero errors. Confirm exactly one <h1> and no skipped heading levels.

Runtime (when a browser is available): load the page, run an axe-core scan (or lighthouse accessibility category) and capture the score + violations. Then keyboard-walk it: Tab from the top — every interactive element is reachable, in logical order, with a visible focus ring; the skip link appears first; open a modal and confirm focus enters it, Tab is trapped, Esc closes, and focus returns to the trigger.

Contrast: for each flagged pair, state the computed ratio and the threshold it must clear (4.5:1 / 3:1) — a fix isn't done until the number passes.

Report is complete only when every Blocker has a concrete code fix attached (not just a description) and each finding cites its WCAG success criterion.