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 inapps/<domain>/<app>/, and every Storybook story authored under those packages. Internal-only tooling (eg. dev panels inapps/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 CSScolor()functions only when the result is also locked into the token manifest — opaque blends withrgba()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-ringtoken (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-visibleonly — 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: noneis banned in shared component CSS unless paired with a:focus-visibleruleset that draws a compliant replacement). - Using
box-shadowalone 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, oraria-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 setaria-selected/aria-checked, controls that own a popup setaria-haspopupandaria-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: noneandvisibility: hiddenremove 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
tabindexreorders deliberately; positivetabindexvalues are banned in shared components. - Activate with the canonical key. Buttons + links:
Enter(andSpacefor buttons). Checkboxes / radios:Space. Menus: arrow keys inside,Enter/Spaceto commit,Escapeto dismiss. Tabs:ArrowLeft/ArrowRightto move,Home/Endto 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
Enterto switch panels.
No keyboard traps (WCAG 2.1.2)#
A modal, popover, dropdown, or other transient surface MUST:
- Move focus into the surface when it opens (typically to the first focusable child or the close button).
- Trap focus inside the surface while it is open —
TabandShift+Tabcycle within the surface. - Restore focus to the trigger when the surface closes — never to
<body>. - 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:
<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, oraria-label. Placeholder text is not a label. - Required fields announce their requirement both visually (
*marker) and programmatically (aria-required="true"orrequired); 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:
- The field MUST set
aria-invalid="true". - 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. - The first error after submit MUST move focus to the failing field — not to a global error summary banner alone.
- Live error announcements (eg. inline validation as the user types) go into a
role="status"(polite) region, neverrole="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 inlibs/yemaya/uiandlibs/oshun/uiuse theuseReducedMotionhook (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-motionis 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