Wcag accessibility

WCAG Accessibility Skill

Engineering standard: WCAG 2.2 Level AA (always). Legal layer: Optional, jurisdiction-specific. Applied on top of the technical standard — never mixed into it.

This skill has four modes. Detect mode from context; switch fluidly mid-conversation.

Mode	When to use
Mode 1 — Component Advisor	Building or modifying any UI component, page, or layout
Mode 2 — Test Runner	PR review, CI pipeline, or explicit audit request
Mode 3 — Issue Reporter	Formatting findings from either mode as structured issue records
Mode 4 — Jurisdiction Advisor	User asks about legal requirements, compliance scope, or jurisdiction mapping

Most build tasks use Mode 1 → Mode 3. Most audit tasks use Mode 2 → Mode 3. Mode 4 is additive — layer it on when legal context is present.

---

Mode 1: Component Advisor

Use when creating or modifying any frontend component, page, or layout.

Guiding Principle

Accessibility is structural, not cosmetic. Semantic HTML done right covers ~70% of WCAG compliance before any ARIA is needed. Work through the checklist below in order.

Build Checklist

1. Semantic Structure

• Use the right element: <button> for actions, <a> for navigation, <nav> <main> <header> <footer> <section> <article> for landmarks
• Never make a <div> or <span> interactive without role + tabindex
• Headings h1–h6 form a logical outline — never skip levels
• WCAG: 1.3.1, 4.1.2

2. Keyboard Navigation

• All interactive elements reachable and operable via keyboard alone
• Tab order matches visual reading order
• No keyboard traps — modals must trap focus intentionally but release on Escape
• Provide a skip link: <a href="#main-content" class="skip-link">Skip to main content</a>
• Custom widgets (dropdowns, tabs, date pickers, dialogs) must follow APG patterns — see references/aria-patterns.md
• WCAG: 2.1.1, 2.1.2, 2.4.1, 2.4.3

3. Focus Management

• Visible focus indicator: minimum 3:1 contrast ratio against adjacent color, non-zero area
• Never outline: none without a replacement that meets contrast
• Modal opens → move focus inside; modal closes → return focus to trigger
• SPA route changes → move focus to page <h1> or skip link
• WCAG: 2.4.7, 2.4.11, 3.2.1

4. Color & Contrast

• Normal text (< 18pt / < 14pt bold): 4.5:1 minimum
• Large text (≥ 18pt / ≥ 14pt bold): 3:1 minimum
• UI components and graphical objects: 3:1 against adjacent colors
• Never convey information by color alone — pair with text, pattern, or icon
• WCAG: 1.4.1, 1.4.3, 1.4.11

5. Images & Media

• Meaningful images: descriptive alt (what it conveys, not what it depicts)
• Decorative images: alt="" (empty string, not missing attribute)
• Complex images (charts, maps): aria-describedby pointing to a text description
• Video: captions; audio-only: transcript
• WCAG: 1.1.1, 1.2.1, 1.2.2

6. Forms

• Every input has a visible <label> using for/id — never placeholder-as-label
• Required: required attribute + visual marker + aria-required="true"
• Errors: linked via aria-describedby; describe the problem and how to fix; not color-only
• Group related inputs: <fieldset> + <legend>
• Personal data inputs: use autocomplete tokens (see references/wcag-checklist.md §1.3.5)
• WCAG: 1.3.5, 3.3.1, 3.3.2, 3.3.3, 3.3.7, 3.3.8

7. Dynamic Content & ARIA

• ARIA only when no semantic HTML alternative exists
• aria-live="polite" for non-urgent updates; aria-live="assertive" sparingly for urgent alerts only
• Live region must exist in DOM before content is injected
• Loading: aria-busy="true" on the region
• State attributes: aria-expanded, aria-controls, aria-selected, aria-pressed as appropriate
• Full widget patterns → references/aria-patterns.md
• WCAG: 4.1.2, 4.1.3

8. Motion & Timing

• Wrap all non-essential animations: @media (prefers-reduced-motion: reduce)
• Auto-playing motion > 5s needs pause/stop/hide control
• WCAG: 2.2.2, 2.3.1

Mode 1 Output Format

For each component area, provide:

1. Correct implementation — semantic HTML + any needed ARIA
2. Keyboard behavior spec — what each key does
3. WCAG criteria met — criterion numbers
4. Test case — how to verify (automated and/or manual step)

---

Mode 2: Test Runner

Use during PR review, CI pipelines, or when asked to audit existing code. Run all five test categories; report findings using Mode 3 Issue Records.

T1 — axe-core Scan (automated, ~57% coverage)

// jest-axe (unit tests)
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

it('passes axe audit', async () => {
  const { container } = render(<Component />);
  expect(await axe(container)).toHaveNoViolations();
});

// Playwright (E2E)
import AxeBuilder from '@axe-core/playwright';
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);

Report every violation as a Mode 3 Issue Record.

T2 — Keyboard Navigation Check (manual simulation)

Walk through these steps; flag any failure:

1. Tab to every interactive element — all reachable?
2. Shift+Tab — reverse order correct?
3. Enter/Space on buttons — activate correctly?
4. Arrow keys on composite widgets (tabs, menus, listboxes) — follow APG patterns?
5. Escape on modals, dropdowns, tooltips — close correctly?
6. Skip link present and functional?
7. Any keyboard traps?

T3 — Form Validation Check (automated + manual)

• Every <input>, <select>, <textarea> has a programmatically associated label
• No input uses placeholder as its only label
• Required fields: required or aria-required="true" present
• Error states: aria-invalid="true" set; error message linked via aria-describedby
• autocomplete tokens present on personal data fields

T4 — Focus Check (manual)

• Focus indicator visible on every interactive element (not suppressed)
• Focus order logical and matches DOM/visual reading order
• After modal/dialog close: focus returns to trigger element
• After dynamic content insertion: focus managed appropriately

T5 — Manual Review Flags

These cannot be automated — flag them for human review:

• Screen reader announcements sensible (NVDA/JAWS on Windows; VoiceOver on Mac/iOS)
• Color contrast verified with Colour Contrast Analyser tool (not estimated)
• Alt text accurately conveys meaning, not just describes appearance
• Video captions accurate (not auto-generated only)
• Instructions clear; no unnecessary time limits
• Touch targets ≥ 24×24 CSS px with adequate spacing (WCAG 2.5.8)

CI Pipeline Recommendations

Layer	Tool	When
Lint	eslint-plugin-jsx-a11y	Every commit
Unit	jest-axe	Every PR
E2E	axe-playwright / axe-cypress	Every PR
Score	Lighthouse CI	Merge to main
Manual	Screen reader + keyboard	Before release

---

Mode 3: Issue Reporter

Use this format for every finding from Mode 1 or Mode 2. One record per issue.

### Issue: [Short descriptive title]

| Field               | Value |
|---------------------|-------|
| **WCAG Criterion**  | [X.X.X] [Name] — Level [A/AA] — introduced in WCAG [2.0/2.1/2.2] |
| **Category**        | [Structure / Keyboard / Focus / Contrast / Images / Forms / ARIA / Motion] |
| **Severity**        | [Critical / Serious / Moderate / Minor] |
| **User Impact**     | [Who is affected and how — name the disability/AT affected] |
| **Jurisdictions**   | [e.g. USA/ADA, USA/Section 508, EU/EAA, Canada/AODA] |
| **Legal Relevance** | [Legal violation / Legal gap / Best practice — with reason] |
| **Test Method**     | [Automated (axe-core) / Manual-keyboard / Manual-screen reader / Visual] |
| **Manual Review**   | [Yes / No — explain if Yes] |

**Problem**
[Plain-language description of what is wrong and why it fails WCAG]

**Fix**
```html
<!-- Before -->
[problematic code]

<!-- After -->
[corrected code]

Verification [How to confirm the fix — automated test, manual step, or both]

### Severity Definitions

| Level | Meaning |
|-------|---------|
| **Critical** | Blocks access entirely for one or more user groups (e.g. keyboard trap, unlabelled required field) |
| **Serious** | Causes significant difficulty; workaround exists but is unreasonable (e.g. no visible focus, color-only error) |
| **Moderate** | Causes some difficulty; workaround available (e.g. non-ideal heading order, missing landmark) |
| **Minor** | Best practice gap; low user impact (e.g. redundant ARIA, missing `lang` on single element) |

### Legal Relevance Definitions

| Label | Meaning |
|-------|---------|
| `Legal violation` | Criterion is in the jurisdiction's legal baseline — non-compliance is active legal exposure |
| `Legal gap` | Criterion is in WCAG 2.2 AA engineering target but not in the jurisdiction's legal baseline |
| `Best practice` | AAA criterion or otherwise outside any current baseline |

---

## Mode 4: Jurisdiction Advisor

Layer this on top of Mode 2/3 results when legal compliance context is present. Do not lower engineering standards to legal minimums — always target WCAG 2.2 AA.

Read full detail from `references/jurisdiction-map.md`.

### Jurisdiction Quick Reference

| Jurisdiction | Law / Standard | Legal Baseline | Engineering Target | Notes |
|---|---|---|---|---|
| USA — ADA (gov) | Title II, DOJ rule | WCAG 2.1 AA | WCAG 2.2 AA | State/local gov effective April 2026 |
| USA — ADA (private) | Title III | No federal rule; courts use 2.0/2.1 | WCAG 2.2 AA | Active litigation risk |
| USA — Federal | Section 508 | WCAG 2.0 AA | WCAG 2.2 AA | ICT procurement for federal agencies |
| EU | EAA / EN 301 549 | WCAG 2.1 AA | WCAG 2.2 AA | Effective June 28, 2025 |
| Canada | AODA (Ontario) | WCAG 2.0 AA | WCAG 2.2 AA | Private sector 50+ employees |
| UK | Equality Act + PSBAR | WCAG 2.1 AA | WCAG 2.2 AA | Public sector regulations |

### WCAG Version → Legal Coverage Matrix

Use this to determine Legal Relevance in Issue Records:

| Criterion introduced in | ADA Title II | Section 508 | EU EAA | AODA |
|---|---|---|---|---|
| WCAG 2.0 | ✅ Legal baseline | ✅ Legal baseline | ✅ Legal baseline | ✅ Legal baseline |
| WCAG 2.1 | ✅ Legal baseline | ⚠️ Legal gap | ✅ Legal baseline | ⚠️ Legal gap |
| WCAG 2.2 | ⚠️ Legal gap | ⚠️ Legal gap | ⚠️ Legal gap | ⚠️ Legal gap |

✅ = Legal violation if not met | ⚠️ = Legal gap (fix for best practice / future-proofing)

For full effective dates, sector applicability, and criterion-by-criterion mapping → `references/jurisdiction-map.md`.

---

## Reference Files

| File | When to read |
|------|-------------|
| `references/wcag-checklist.md` | Full WCAG 2.2 AA criterion table, organized by principle |
| `references/aria-patterns.md` | Implementation patterns for modals, tabs, accordions, menus, etc. |
| `references/jurisdiction-map.md` | Full legal mapping per jurisdiction with effective dates and sector scope |

### Most Commonly Violated Criteria (check first)

1.1.1 · 1.3.1 · 1.4.1 · 1.4.3 · 1.4.11 · 2.1.1 · 2.1.2 · 2.4.3 · 2.4.7 · 2.4.11 · 2.5.8 · 3.3.1 · 3.3.2 · 4.1.2 · 4.1.3

---

## Core Principles

1. **WCAG 2.2 AA always** — regardless of what the law requires today
2. **Legal ≠ Technical** — jurisdiction analysis lives in its own layer; never lower engineering standards to legal minimums
3. **Semantic HTML beats ARIA** — use ARIA to enhance, not replace
4. **Keyboard first** — if you can't tab through it, screen readers can't either
5. **Automated tools catch 30–57%** — manual review is not optional