Eve library

V1-P2-3510 — OSHUN Web WCAG 2.1 AA Signoff

Guide

Revision 1

On this page

The master TODO requires:

"OSHUN web app — verify all primary surfaces against WCAG 2.1 AA. V: zero serious/critical axe violations on Home, Library, Search, Notifications, Settings, each domain entry."

This document is the canonical signoff for V1-P2-3510. It maps each required surface to the axe-based test that enforces the gate, names the auto-fixture contract that backs the assertion, and lists the run command that re-verifies the gate end-to-end.

Surface coverage#

V1-P2-3510 surface Route Enforcing test
Home / e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case home)
Library /library e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case library)
Search /search e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case search)
Notifications /profile?path=notifications e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case notifications)
Settings (profile) /profile e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case settings)
Tara entry /domains/tara e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case domain-tara)
Veritas entry /domains/veritas e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case domain-veritas)
Nyx entry /domains/nyx e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case domain-nyx)
Arete entry /domains/arete e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case domain-arete)
Nisaba entry /domains/nisaba e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case domain-nisaba)
Metis entry /domains/metis e2e/wcag-aa-signoff-v1-p2-3510.spec.ts (case domain-metis)

The "Settings" surface in OSHUN parlance is the /profile dashboard; account/preferences/privacy/sessions panels are selected by the path query parameter against the same DOM root. The notifications panel is therefore a sub-route of the same dashboard, scoped via ?path=notifications.

The domain-entry list comes from WEB_NAVIGABLE_DOMAIN_IDS in apps/oshun/web/src/navigation/routes.ts (tara, veritas, nyx, arete, nisaba, metis). Metis is a coming-soon shell while V1-MET launch readiness completes; the page still renders the shared shell chrome and must remain accessible.

Verification contract#

Each surface test in wcag-aa-signoff-v1-p2-3510.spec.ts:

  1. Authenticates the shell via primeAuthenticatedShellPage (mocks /api/auth/session, seeds a shell-onboarding state).
  2. Sets a 1440×960 desktop viewport and emulates reduced-motion: reduce so axe results don't fluctuate against motion-state DOM.
  3. Opens the route via openAuthenticatedShellPath and asserts the surface's ready selector.
  4. Asserts the common shell landmarks (single <main>).
  5. Runs runAccessibilityScan with include: ['[data-shell-root]']. The helper applies WCAG 2.1 A + AA tags (wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22a, wcag22aa) and excludes Next.js dev-overlay chrome.
  6. Filters the violation list to serious/critical impact and asserts the count is zero. Any failing rule is reported with its rule ID, impact, help URL, and the failing selector(s).
  7. The auto-axe fixture installed by ./fixtures (V1-P2-3500) runs an additional document-wide axe pass after each test as defense-in-depth.

The [data-shell-root] scope is the authenticated customer shell; auth / welcome / legal pages are not part of V1-P2-3510 (those are operator paths covered by V1-P2-3512+).

Defense-in-depth gates#

V1-P2-3510 is the surface-level gate; three other layers run continuously against the same surfaces and back the signoff:

  • V1-P2-3500 — auto-axe afterEach fixture. Every spec that imports test from apps/oshun/web/e2e/fixtures.ts ends with expectNoSeriousA11yViolations(page) against the rendered DOM. The same fixture runs across the route-accessibility, search-workspace-accessibility, domain-specific accessibility specs, and the new V1-P2-3510 spec.
  • V1-P2-3501 — pa11y-ci nightly sweep. tools/a11y/.pa11yci.json includes the OSHUN web app on port 4176 with /, /library, /search, /notifications, /settings URLs; the nightly job lands artifacts under infra/a11y-reports/.
  • V1-P2-3502 — Storybook a11y addon + per-story axe runner. The per-component primitive layer that backs every shell surface ships with axe violations enforced at the story level.

Run command#

The signoff spec is part of the OSHUN web e2e suite:

bash
# from repo root
pnpm --filter @oshun/web exec playwright test \
  e2e/wcag-aa-signoff-v1-p2-3510.spec.ts \
  --project=chromium --reporter=list

The Playwright config in apps/oshun/web/playwright.config.ts boots both the BFF (port 4010) and the Next dev server (port 3010) automatically; no manual infra setup is required when the Docker dev stack is up. For environments without Docker, set E2E_BASE_URL and E2E_BFF_URL against an existing deployment to skip the embedded webServer.

The same surfaces are also exercised by these pre-existing specs (each ends with axe via the V1-P2-3500 fixture); they remain in place as domain-specific assertions while V1-P2-3510 is the consolidated WCAG signoff:

  • shell-route-accessibility.spec.ts — Home, Explore, Library, Activity, Notifications, Profile, notifications drawer.
  • search-workspace-accessibility.spec.ts — search-workspace flow.
  • search-scan-density-accessibility.spec.ts — search-result density modes.
  • assistant-accessibility.spec.ts — assistant launch surface.
  • nisaba-reading-accessibility.spec.ts — Nisaba reading split-view.
  • arete-progress-maps-accessibility.spec.ts — Arete progress maps.
  • tara-session-player-accessibility.spec.ts / tara-teacher-pages-accessibility.spec.ts — Tara player + teacher pages.
  • studio-concordia-workbench-accessibility.spec.ts — operator studio workbench (V1-P2-3512 territory but referenced here for completeness).

V1-P2-3510 owns the consolidated surface checklist; the per-surface specs above own their richer interaction-level coverage.

Verification result (2026-05-05)#

11/11 tests pass against apps/oshun/web running locally on port 3010 with the BFF on port 4010. Each surface scan returns zero serious/critical WCAG 2.1 AA violations under [data-shell-root] with reduced-motion: reduce.

A precondition fix was required before the gate could pass: the global toast container (apps/oshun/web/src/design-system/components/Toast.tsx) carried aria-label="Notifications" on a bare <div> with no role, which fails axe aria-prohibited-attr (WCAG 4.1.2). The fix adds role="region" so the aria-label is the accessible name of a labeled landmark region; toast items keep their own role="alert" for assertive announcements.

The same scan run with WCAG 2.2 AA tags (wcag22a/wcag22aa) surfaces a 2.2-only target-size violation on Home (button[data-home-arete-primary-action] and button[data-home-arete-secondary-action] are nested inside a parent button card, which axe scores as partially-obscured below the 24×24 floor). That is a WCAG 2.2 AA issue and falls under V1-P2-3544 ("Verify hit targets ≥ 44×44 CSS px on touch surfaces"), not V1-P2-3510's WCAG 2.1 AA scope.