# Accessibility Baseline — WCAG 2.1 AA per Component (V1-P2-3503)

This document captures the per-component accessibility contract every UI
primitive in the monorepo must satisfy before it can ship. It is the source of
truth that the V1-P2-3500 axe auto-fixture, the V1-P2-3501 pa11y-ci nightly
sweep, the V1-P2-3502 Storybook test-runner, and the per-surface verifications
in V1-P2-3510..3519 all assert against. WCAG 2.1 AA is the hard floor; AAA
targets are noted where we already meet them or where operator-domain workflows
demand them.

> **Scope.** Applies to every shipped component in
> `libs/{shared,yemaya, aphrodite,…}/ui/`, every page-level surface in
> `apps/<domain>/<app>/`, and every Storybook story authored under those
> packages. Internal-only tooling (eg. dev panels in `apps/maat`) is exempt
> while it remains behind a feature flag.

## 1. Color and contrast

### Text contrast (WCAG 1.4.3)

| Text size                              | Minimum ratio          | Notes                                                                  |
| -------------------------------------- | ---------------------- | ---------------------------------------------------------------------- |
| Body text < 18pt (or < 14pt **bold**)  | 4.5:1 against backdrop | Includes form labels, helper text, table cells, link text.             |
| Large text ≥ 18pt (or ≥ 14pt **bold**) | 3.0:1                  | Includes display headings, hero copy.                                  |
| Disabled controls                      | 3.0:1 (visual only)    | Disabled state must still indicate that the control _exists_.          |
| Placeholder text                       | 4.5:1                  | Placeholder is not a label substitute (1.3.1) but must remain legible. |

### Non-text contrast (WCAG 1.4.11)

| Surface                            | Minimum ratio | Examples                                                                                                |
| ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| Input borders, control affordances | 3.0:1         | Buttons, checkboxes, radios, sliders, toggle borders against the immediately surrounding fill.          |
| Focus rings                        | 3.0:1         | Both against the control itself **and** against the surface the control sits on (focus-visible double). |
| State indicators (error, success)  | 3.0:1         | Required-field asterisks, destructive-action accents, badge fills.                                      |
| Iconography that conveys meaning   | 3.0:1         | Decorative icons (with `aria-hidden="true"`) are exempt.                                                |

### Implementation notes

- Color tokens live in `libs/oshun/design-tokens` (and per-domain forks). Each
  token pair (foreground, background) ships with a recorded ratio in the token
  metadata; the build fails if a documented pair drifts under the required
  threshold.
- For dynamic states (focus, hover), include the token combination in the
  contrast manifest so the regression check covers both the resting and the
  interactive state.
- Use `color-mix()` and CSS `color()` functions only when the result is also
  locked into the token manifest — opaque blends with `rgba()` over unknown
  backgrounds bypass the audit.

## 2. Focus indication

### Visible focus (WCAG 2.4.7, 2.4.11 — focus appearance)

Every interactive element MUST render a focus ring when it receives keyboard
focus. The ring is mandatory, not optional:

- **Width.** ≥ 2 CSS pixels at 100% zoom, all four sides of the control's
  bounding box (or the equivalent path for non-rectangular shapes).
- **Offset.** Use a 2px outline-offset by default so the ring sits clear of the
  control's own border. For inputs nested inside cards or popovers, the offset
  may shrink to 1px so the ring stays inside the card boundary.
- **Color.** Use the `--focus-ring` token (oshun: `#7C5CFF`; aphrodite:
  `#FF4DA6`; yemaya: `#3FE5C7`). The token-to-surface contrast is verified by
  the same manifest used for non-text contrast.
- **Style.** Solid ring; do not rely on background-color changes alone (fails at
  high zoom + Windows high-contrast).
- **Persistence.** `:focus-visible` only — pointer focus may suppress the ring
  on click-driven controls (button, link). All keyboard traversal paths must
  show the ring.

### What MUST NOT happen

- Removing the default UA outline without replacing it (`outline: none` is
  banned in shared component CSS unless paired with a `:focus-visible` ruleset
  that draws a compliant replacement).
- Using `box-shadow` alone for focus on controls that participate in the flow
  layout — the shadow is invisible against opaque backdrops in high-contrast
  mode.
- Animating the focus ring with motion that does not respect
  `prefers-reduced-motion: reduce`.

## 3. ARIA roles and semantics

### First principles (WCAG 1.3.1, 4.1.2)

- **Use the right element.** Native HTML semantics over ARIA — a `<button>`
  beats `<div role="button">`. The "first rule of ARIA" applies: don't use ARIA
  when a native element already does the job.
- **Name and role are required.** Every interactive control MUST expose an
  accessible name (visible label, `aria-label`, or `aria-labelledby`) and a
  role. The accessible name MUST be unique within its container if more than one
  control of the same role exists.
- **State must follow behavior.** Disclosure widgets set `aria-expanded`,
  selection widgets set `aria-selected` / `aria-checked`, controls that own a
  popup set `aria-haspopup` and `aria-controls`. Stale ARIA state is worse than
  no ARIA state.

### Required role + state map for shared primitives

| Component family        | Role(s)                                         | Required state attributes                                                        |
| ----------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------- |
| Buttons                 | `button`                                        | `aria-disabled` (when not focusable-but-disabled), `aria-pressed` for toggles.   |
| Links                   | `link`                                          | href required; never `<a>` without href for action handlers.                     |
| Form fields             | input role intrinsic                            | `aria-invalid`, `aria-describedby` (helper + error), `aria-required`.            |
| Checkboxes / radios     | intrinsic                                       | `aria-checked` for tri-state custom controls.                                    |
| Tabs                    | `tab` / `tablist` / `tabpanel`                  | `aria-selected`, `aria-controls` ↔ `aria-labelledby`.                            |
| Disclosures             | `button`                                        | `aria-expanded`, `aria-controls` pointing at the disclosed panel.                |
| Dialogs / modals        | `dialog` (or `alertdialog` for blocking errors) | `aria-modal="true"`, `aria-labelledby`, focus trap, `aria-describedby` for body. |
| Menus                   | `menu` / `menuitem`                             | `aria-haspopup="menu"` on trigger; left/right traversal between siblings.        |
| Combobox / autocomplete | `combobox`                                      | `aria-expanded`, `aria-controls`, `aria-activedescendant`, `aria-autocomplete`.  |
| Tables                  | intrinsic                                       | `<th scope>` always set; complex tables use `headers`/`id` cross-refs.           |
| Status / live regions   | `status` (polite) / `alert` (assertive)         | Announce only state _changes_, never re-announce the same string.                |

### Hidden vs visually-hidden

- `display: none` and `visibility: hidden` remove the element from the
  accessibility tree — use them when you don't want the content read out.
- `aria-hidden="true"` removes it from the tree but keeps it in the DOM —
  reserve for purely decorative elements (icons paired with adjacent visible
  labels).
- `.sr-only` / `.visually-hidden` (CSS clip pattern) keeps the element in the
  accessibility tree but renders it off-screen — use for non-visual labels (eg.
  extra context for icon-only buttons, skip-link targets).

## 4. Keyboard interaction

### Operability (WCAG 2.1.1, 2.1.2, 2.4.3)

- **Every interactive control reachable.** Tab order is the visual order unless
  `tabindex` reorders deliberately; positive `tabindex` values are banned in
  shared components.
- **Activate with the canonical key.** Buttons + links: `Enter` (and `Space` for
  buttons). Checkboxes / radios: `Space`. Menus: arrow keys inside,
  `Enter`/`Space` to commit, `Escape` to dismiss. Tabs: `ArrowLeft`/`ArrowRight`
  to move, `Home`/`End` to jump.
- **Composite widgets follow the WAI-ARIA Authoring Practices**
  (https://www.w3.org/WAI/ARIA/apg/) for keyboard semantics — eg. a tablist with
  manual activation requires `Enter` to switch panels.

### No keyboard traps (WCAG 2.1.2)

A modal, popover, dropdown, or other transient surface MUST:

1. Move focus into the surface when it opens (typically to the first focusable
   child or the close button).
2. Trap focus inside the surface while it is open — `Tab` and `Shift+Tab` cycle
   within the surface.
3. Restore focus to the trigger when the surface closes — never to `<body>`.
4. Dismiss with `Escape` (and any close-button keyboard activation).

The dialog primitive in `libs/yemaya/ui` and the Radix-derived overlays in
shared libraries already implement this — new components must not ship custom
focus management without using one of those primitives.

### Focus restoration after route changes

- SPA route transitions move focus to the route's primary heading (`<h1>`) or to
  a designated `<main>` landmark.
- Toast announcements never steal focus — they are status regions.

## 5. Skip links and landmarks

### Skip link (WCAG 2.4.1)

Every page-level surface ships a skip link as the first focusable element:

```tsx
<a href="#main" className="skip-link">
  Skip to main content
</a>
```

The link is visually hidden until focused (so it doesn't disrupt visual design)
and jumps to the page's `<main id="main" tabindex="-1">` landmark. The
`tabindex="-1"` makes the landmark programmatically focusable so the skip target
receives focus on activation.

For pages with multiple structural regions (eg. `apps/oshun/web/library` has
Filters, Results, Detail), provide additional skip links inside the header for
"Skip to filters", "Skip to results", "Skip to detail".

### Landmarks

| Landmark                  | Required count     | Notes                                                                                          |
| ------------------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `<header>` (banner)       | 0..1 per page      | Site-wide chrome.                                                                              |
| `<nav>`                   | ≥ 1 per page       | Each `<nav>` MUST be uniquely labeled (`aria-label="Primary"`, `"Footer"`, etc.).              |
| `<main>`                  | exactly 1 per page | The skip-link target.                                                                          |
| `<aside>` (complementary) | 0..n               | Sidebars, related-content panels.                                                              |
| `<footer>` (contentinfo)  | 0..1               | Site-wide chrome.                                                                              |
| `<form>`                  | as needed          | Group related inputs; provide `<fieldset>`/`<legend>` for sub-groups.                          |
| `<section>`               | as needed          | MUST have an accessible name (`aria-labelledby` or `aria-label`) if marked as a landmark role. |

## 6. Forms and error association

### Labels (WCAG 1.3.1, 3.3.2)

- Every form control has a programmatic label — `<label for>`,
  `aria-labelledby`, or `aria-label`. Placeholder text is **not** a label.
- Required fields announce their requirement both visually (`*` marker) and
  programmatically (`aria-required="true"` or `required`); avoid using only the
  visual marker.
- Use `<fieldset>` + `<legend>` for radio-group and checkbox-group controls so
  the group label is announced once and not on every individual option.

### Error association (WCAG 3.3.1, 3.3.3)

When a form field fails validation:

1. The field MUST set `aria-invalid="true"`.
2. The associated error message MUST be referenced via `aria-describedby`
   (alongside any helper text id) so screen readers announce the error after the
   field's name and value.
3. The first error after submit MUST move focus to the failing field — not to a
   global error summary banner alone.
4. Live error announcements (eg. inline validation as the user types) go into a
   `role="status"` (polite) region, never `role="alert"` (assertive) for
   non-destructive issues.

### Submit-time error summaries

For pages with multiple errors after submit:

- Render an error summary at the top of the form (`role="alert"` or a
  focus-managed dialog).
- Each entry in the summary is a link to the failing field's id.
- Summary appears _before_ moving focus to the first failing field, so AT users
  hear the count then traverse to the field.

## 7. Motion and reduced motion

- Honor `prefers-reduced-motion: reduce`. Components in `libs/yemaya/ui` and
  `libs/oshun/ui` use the `useReducedMotion` hook (or its CSS equivalent) to
  suppress decorative motion (parallax, auto-carousel, long-distance enter/exit
  transitions).
- Functional motion (eg. progress bars, spinners) may continue when
  `prefers-reduced-motion` is set, but at reduced amplitude (smaller deltas,
  less distance, no continuous looping where avoidable).
- Auto-playing video / canvas animations require a visible pause/stop control
  and respect `prefers-reduced-motion`.

## 8. Internationalization and language

- Set `<html lang="<bcp47>">` on every page; route-locale changes update the
  attribute on navigation.
- Use `<bdi>` for user-generated content that may include directional characters
  foreign to the surrounding locale.
- Date / number / currency formatting goes through `Intl.*` — hand-rolled
  formatters fail in non-en-US locales and break screen-reader announcement (eg.
  "1,234.56" vs "1.234,56").

## 9. Verification ladder

| Layer                                     | Owner task        | What it asserts                                                                                                            |
| ----------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Per-component Storybook snapshot + axe    | V1-P2-3502        | Each story renders without serious/critical WCAG 2.1 AA violations against `#storybook-root`.                              |
| Per-spec Playwright auto-fixture          | V1-P2-3500        | Each e2e spec ends with `expectNoSeriousA11yViolations(page)` via `axeAfterEach` (skip with `skipAxe: true`).              |
| Per-PR + nightly pa11y-ci sweep           | V1-P2-3501        | Representative routes across 11 apps fail on serious/critical violations; nightly artifact lands in `infra/a11y-reports/`. |
| Manual screen-reader walkthroughs         | V1-P2-3530..3534  | NVDA + Firefox, VoiceOver + Safari (macOS + iOS), TalkBack + Chrome, JAWS + Edge — record per-app baseline.                |
| Per-surface verification                  | V1-P2-3510..3519  | OSHUN/Metis/Iris/Lilith/Yemaya/Veritas/Aphrodite + remaining domains pass the axe + manual gates.                          |
| Continuous design-token contrast manifest | V1-P2-3503 (this) | Build fails when a documented token pair drifts below the relevant minimum ratio.                                          |

## 10. Sources

- WCAG 2.1 Recommendation — https://www.w3.org/TR/WCAG21/
- WAI-ARIA Authoring Practices 1.2 — https://www.w3.org/WAI/ARIA/apg/
- Web Content Accessibility Guidelines (WCAG) Quick Reference —
  https://www.w3.org/WAI/WCAG21/quickref/
- The first rule of ARIA — https://www.w3.org/TR/using-aria/#rule1
- `prefers-reduced-motion` —
  https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
