Accessibility
The WCAG 2.2 AA contract every ePassLive component is reviewed against — and how we verify it.
Compliance statement
The ePassLive Design System targets WCAG 2.2 Level AA as its accessibility floor. Every component page carries ARIA assertions, and no component ships with a known AA violation. Automated checks run on every push; manual assistive-technology passes run quarterly.
• Automated: axe-core in Playwright across Chromium, Firefox and WebKit, light and dark themes, EN and FR locales (pnpm check:all --playwright).
• Manual: VoiceOver (macOS) and NVDA (Windows) passes on the flagship flows, quarterly.
• Contract: interactive surfaces expose a stable accessible name (WCAG 4.1.2), color contrast meets 4.5:1 body / 3:1 large text, and nothing depends on color alone.
Keyboard navigation model
Every interactive component is fully operable from the keyboard. The model is uniform across the library:
| Key | Behaviour |
|---|---|
Tab / Shift+Tab | Move focus forward/backward through the tab order. Focus rings are always visible (focus-visible:ring-2 ring-ep-teal) — we never suppress focus indicators without replacing them. |
Enter | Activate links and default buttons (native semantics preserved). |
Space | Activate buttons and toggle switches (role="switch"). |
Escape | Close the topmost overlay (dialog, drawer, command menu, select listbox) and return focus to its trigger. |
Arrow keys | Move within composite widgets: menu items, listbox options, radio groups (roving tabindex), tab strips. |
Home / End | Jump to the first/last option in composite widgets where supported. |
Focus is never trapped outside portals: overlays trap focus only while open, restore it to the invoking trigger on close, and the docs layout ships a skip-to-content link as the first tabbable element.
Screen reader testing methodology
Automated axe-core scans catch the mechanical violations; they cannot catch experience. The methodology is two-tier:
• Every push: axe-core via Playwright on the three browser engines — the local gate that must stay green before merge.
• Quarterly manual pass: VoiceOver on macOS and NVDA on Windows walking the purchase, check-in and admin flows, verifying announced names, roles and states.
• Every new interactive component: its patterns.ts a11y assertions are reviewed in the component ADR before implementation is marked complete.
Built-in patterns
44px tap targets (--ep-tap-min)
Every interactive atom consumes min-h-[var(--ep-tap-min)] (WCAG 2.5.5). Compact visual affordances (e.g. the Switch toggle knob, Tag remove button) still get a 44px hit area via their wrapper row or an explicit min-height.
Color contrast tokens
Interactive colors come from the --ep-btn-* and --ep-semantic-* token namespaces, tuned to pass 4.5:1 in both light and dark themes. Brand tokens describe identity; interactive tokens describe surfaces — never reuse a brand token as a CTA background.
The sr-only pattern
Visually-hidden text (the .sr-only utility) provides context that icons or layouts omit — e.g. pairing a Badge count with “3 new events”. Prefer visible labels; use sr-only when the visual context genuinely suffices.
Reporting an a11y issue
Open a ClickUp task in the DS space with the “a11y” label, the route, the WCAG success criterion, and reproduction steps (browser + assistive tech + theme). Attach an axe-core or screen-reader transcript when possible. Accessibility defects triage above feature work — a component with a known AA violation is not done.