/wcag-accessibility

name: wcag-accessibility
description: WCAG 2.2 AA compliance as required by the European Accessibility Act. Use when designing, building or reviewing any user-facing interface for accessibility.
metadata:
  priority: 9
  docs:
    - "https://www.w3.org/TR/WCAG22/"
    - "https://www.etsi.org/deliver/etsi_en/301500_302000/301549/03.02.01_60/en_301549v030201p.pdf"
  pathPatterns:
    - "**/*.tsx"
    - "**/*.jsx"
    - "**/*.vue"
    - "**/*.svelte"
    - "**/*.html"
    - "**/*.css"
    - "**/*.scss"
    - "components/**"
    - "src/components/**"
    - "design-system/**"
  promptSignals:
    phrases:
      - "accessibility"
      - "wcag"
      - "a11y"
      - "contrast"
      - "contrast ratio"
      - "screen reader"
      - "aria"
      - "focus"
      - "focus visible"
      - "keyboard navigation"
      - "keyboard"
      - "colour blind"
retrieval:
  aliases:
    - wcag
    - accessibility
    - a11y
    - EN 301 549
    - European Accessibility Act
    - contrast
    - screen reader
    - aria
  intents:
    - check accessibility compliance
    - fix contrast ratio
    - add keyboard navigation
    - make component screen-reader friendly
    - meet EU accessibility requirements
  examples:
    - is this colour contrast accessible
    - make this component keyboard navigable
    - check this UI against WCAG
    - does this meet EU accessibility standards

WCAG Accessibility (EN 301 549 / European Standard)

The Standard

The **European Accessibility Act (EAA)** requires digital products and services in the EU to meet **EN 301 549**, which references **WCAG 2.2 Level AA** as the technical baseline. This is not optional — it is a legal requirement for products operating in the EU market.

**Default: always build to WCAG 2.2 AA.** Deviating requires explicit, documented justification. Do not skip accessibility requirements because of timeline pressure or design preference.

WCAG 2.2 AA organises requirements under four principles: **Perceivable, Operable, Understandable, Robust**.

---

Perceivable

Users must be able to perceive all content and UI components.

Colour Contrast

| Context | Minimum ratio | Enhanced (AAA) | |---|---|---| | Normal text (< 18pt / < 14pt bold) | **4.5 : 1** | 7 : 1 | | Large text (≥ 18pt / ≥ 14pt bold) | **3 : 1** | 4.5 : 1 | | UI components and graphical objects | **3 : 1** | — |

> **Check contrast on the real rendered page, not the spec (dembrandt engine, optional).** Design-time swatches lie once real text lands on real backgrounds, gradients, and overlays. `get_findings` / `render_report` run against the live DOM and surface the actual failing text/background pairs with their measured ratios — a fast way to catch the combinations a static palette review misses. See [`extract-design`](../extract-design/SKILL.md).

**Disabled elements are exempt.** WCAG explicitly excludes inactive UI components from contrast requirements (WCAG 1.4.3 exception). A disabled button may use low-contrast text — this is intentional and correct, as it communicates the unavailable state.

Do not use colour as the only means of conveying information (e.g. a red border alone to indicate an error — add an icon or text label).

**Weight is part of legibility, and the ratio cannot see it.** The contrast formula measures ink colour against background colour and nothing else. It scores a hairline and a heavy weight identically at the same hue, while perceived legibility is the product of both. So the palette's faintest legible colour and the type scale's lightest weight must not land on the same text: a muted or secondary token, the one carrying captions, labels and helper text, takes a weight of at least 500 wherever the body default reads as regular or light. *That floor is a house rule, not a WCAG requirement.* The standard has nothing to say about weight, which is exactly why the failure gets through the audit. The same physics on dark surfaces is in [[color-mode-and-theme]]. A muted colour is already the palette's least assertive choice, and pairing it with the lightest weight compounds two decisions that both mean *recede*. The result at caption sizes is text a reader has to work at consciously, while the audit reports a pass.

Text Alternatives

• Every meaningful image needs `alt` text describing its content or function
• Decorative images use `alt=""` so screen readers skip them
• Icons used as buttons need an accessible label: `aria-label` or visually hidden text
• Charts and data visualisations need a text summary or data table alternative

Captions and Transcripts

• Video content needs captions
• Audio-only content needs a transcript

---

Operable

Users must be able to operate all UI components.

Keyboard Navigation

All interactive elements must be reachable and operable by keyboard alone.

• Every button, link, input, and control must receive focus via Tab
• Focus order must follow the visual reading order of the page
• No keyboard traps — users must be able to navigate away from any component
• Modal dialogs must trap focus inside while open, and return focus to the trigger element on close

Focus Visibility

A visible focus indicator is required on every interactive element (WCAG 2.2 strengthens focus visibility requirements).

/* Minimum: do not remove focus outline without a replacement */
:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

Never use `outline: none` without providing a custom focus style. The focus ring is not a design problem to eliminate — it is a navigation tool.

Touch Target Size

Interactive elements on touch devices must be at least **24×24px** (WCAG 2.2) — **44×44px** is the recommended comfortable minimum (Apple HIG, Material Design). Small icon buttons need padding to reach this size even if the visual icon is smaller.

No Seizure Triggers

Nothing on screen should flash more than 3 times per second.

Skip Links

Pages with repeated navigation must pr