---
name: 'accessibility'
description: 'WCAG 2.2 accessibility rules for OUDS Web. Use this skill when creating or editing interactive components, writing HTML templates, adding ARIA attributes, handling focus states, or reviewing accessibility. Covers WCAG 2.2 Level AAA target (AA fallback), ARIA patterns for every component type, focus-visible mixin, color contrast (7:1 AAA / 4.5:1 AA), 44×44px touch targets, reduced motion, RTL, focus trapping, and cognitive accessibility. Always invoke this skill for any work touching user interaction or markup structure.'
---

# Accessibility (WCAG 2.2)

## Compliance target

**WCAG 2.2 Level AAA** primary, with **Level AA as documented fallback** when brand constraints make AAA infeasible. Every component meets at least AA.

---

## ARIA patterns (quick reference)

| Pattern | Required ARIA |
|---|---|
| Decorative icons | `aria-hidden="true"` on `<svg>` |
| Close buttons | `aria-label="Close"` or `aria-labelledby` |
| Toggles | `aria-pressed="true/false"` |
| Expandable | `aria-expanded` + `aria-controls="id"` |
| Form validation | `aria-invalid="true"` + `aria-describedby` |
| Disabled | `aria-disabled="true"` |
| Loading | `aria-busy="true"` |
| Icon-only buttons | `aria-label="Action"` + `aria-hidden` on icon |

---

## Focus management

- Use `@include focus-visible()` mixin — never `outline: none` without alternative
- Focus indicators: 3:1 contrast minimum, 2px thick (AAA: 3-4px)
- Modal/offcanvas: trap focus via `focustrap.js`, Escape closes, focus returns to trigger
- Focused elements must not be obscured by sticky headers or overlays

---

## Color contrast

| Content | AAA target | AA fallback |
|---|---|---|
| Text | 7:1 | 4.5:1 |
| UI components | 4.5:1 | 3:1 |

When AA fallback needed: use larger/bolder text, redundant visual cues (never color alone), document with `// OUDS mod: AA fallback — [reason]`.

---

## Touch targets (WCAG 2.5.8)

Minimum 44×44px on all interactive elements. Use `@include target-size()` mixin.

---

## Reduced motion (WCAG 2.3.3)

All animation respects `prefers-reduced-motion: reduce`. The `@include transition()` mixin handles this — which is why direct `transition:` is forbidden.

---

## Semantic HTML

- `<button>` for actions, `<a>` for navigation — never `<div>`/`<span>` as interactive
- Heading hierarchy: `<h1>` → `<h2>` → `<h3>` (never skip)
- `role="alert"` for auto-announced; `role="status"` for polite
- `.visually-hidden` for SR content — never `display: none`

---

## Color modes

Use `data-bs-theme` attribute, never `prefers-color-scheme` media queries.

---

## WCAG 2.2 specifics

| Criterion | Requirement |
|---|---|
| Consistent Help (3.2.6) | Help mechanisms in same order across pages |
| Accessible Auth (3.3.8/9) | Support `autocomplete`, offer passkey/magic-link |
| Dragging (2.5.7) | Click/keyboard alternative to all drag |
| Redundant Entry (3.3.7) | Auto-populate previously entered data |
| Focus Not Obscured (2.4.11/12) | Never fully hidden by sticky elements |