yanacuti1121 When to Use
- Use when: user explicitly asks for an accessibility review
- Use when: UI is public-facing and will be used by real users
- Use when: product serves regulated industries (healthcare, gov, finance — a11y is often legally required)
- Use when:
output-enforcementL3 check flagged a contrast or label issue and you need the full fix - Do NOT use for quick pre-delivery sweeps — use
output-enforcementL3 baseline instead - Do NOT use when: there is no UI code to review
Pre-conditions
- UI code (HTML/JSX/TSX/CSS) is available to read
- Target WCAG level confirmed (default: AA — upgrade to AAA if user requests)
How It Works
- Run the 5-category audit (see checklist below)
- Score each item PASS / FAIL / ESTIMATED / N/A
- For each FAIL: show the specific line/element, the rule violated, and the fix
- Summary: WCAG AA level reached or not, list of blockers
Audit Checklist
Category 1 — Color & Contrast (WCAG 1.4)
□ Normal text (< 18pt): contrast ratio ≥ 4.5:1
□ Large text (≥ 18pt or ≥ 14pt bold): contrast ratio ≥ 3:1
□ UI components and icons: contrast ≥ 3:1 against adjacent color
□ Focus indicator: contrast ≥ 3:1 against both sides of the boundary
□ Information NOT conveyed by color alone (e.g. error state uses icon + color, not color only)
Category 2 — Keyboard Navigation (WCAG 2.1)
□ All interactive elements reachable by Tab key
□ Tab order follows visual reading order (no jumps)
□ No keyboard traps (user can always Tab out)
□ Custom widgets (dropdowns, modals, sliders) follow ARIA keyboard patterns
□ Skip navigation link present on pages with repeated nav
Category 3 — ARIA & Semantic HTML (WCAG 4.1)
□ Landmark roles present: <main>, <nav>, <header>, <footer>
□ All images: alt="" (decorative) or descriptive alt text (informative)
□ All form inputs have associated <label> (via for/id or aria-labelledby)
□ Icon-only buttons have aria-label
□ No positive tabindex values (tabindex > 0 breaks natural order)
□ Dynamic content changes announced via aria-live or role="alert"
□ No duplicate IDs in the document
Category 4 — Focus Management (WCAG 2.4)
□ Focus visible at all times (no outline: none without replacement)
□ On modal open: focus moves to modal
□ On modal close: focus returns to trigger element
□ On page navigation (SPA): focus moves to new page heading or main content
□ Focus style is clearly visible (not just browser default if browser default is thin)
Category 5 — Content & Structure (WCAG 1.3, 2.4)
□ Heading hierarchy: h1 → h2 → h3 (no skipping levels)
□ Lists use <ul>/<ol>/<li>, not divs styled as lists
□ Tables have <th> headers with scope attribute
□ Page has a <title> element (or document.title in SPA)
□ Language declared: <html lang="en"> (or appropriate)
□ Error messages: linked to input via aria-describedby, not just color change
Output Format
## Accessibility Audit — WCAG 2.1 AA
### Category 1 — Color & Contrast
□ Normal text contrast — PASS (ratio: 7.2:1)
□ Large text contrast — PASS (ratio: 4.8:1)
□ Focus indicator contrast — FAIL: Button focus ring is 1px solid #ccc — ratio 1.4:1
Fix: outline: 2px solid #0055FF; outline-offset: 2px; (ratio 4.8:1)
...
### Summary
PASS: 18 / 27
FAIL: 4 (see above)
ESTIMATED: 3 (color contrast — exact values not visible in code)
N/A: 2
WCAG 2.1 AA: NOT MET — 4 blockers must be resolved
Blockers: [list]
Gotchas
- Contrast ratios for dynamic colors (CSS variables) must be ESTIMATED — state the variable values used for estimation
outline: noneis almost always a FAIL unless a visible custom focus style replaces itaria-labelon a button that already has visible text creates a mismatch — screen readers read the aria-label instead of the visible text, which confuses users; prefer visible text alonerole="button"on a<div>also needstabindex="0"and keyboard event handlers — if you seerole="button"on a non-button, check for both- Color-only error states are a WCAG 1.4.1 failure — red border alone is not enough; add an icon or text
Anti-Fake-Pass Rules
Before claiming the audit is done, you MUST show:
- All 5 categories evaluated — no category skipped without N/A justification
- Every FAIL has a specific element reference and a concrete fix
- Summary line: X PASS / Y FAIL / Z ESTIMATED / W N/A
- WCAG 2.1 AA verdict: MET or NOT MET with blocker count
Reference: gates/anti-fake-pass-gate.md | gates/ui-quality-gate.md (L3)