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:
- Authenticates the shell via
primeAuthenticatedShellPage(mocks/api/auth/session, seeds a shell-onboarding state). - Sets a 1440×960 desktop viewport and emulates
reduced-motion: reduceso axe results don't fluctuate against motion-state DOM. - Opens the route via
openAuthenticatedShellPathand asserts the surface's ready selector. - Asserts the common shell landmarks (single
<main>). - Runs
runAccessibilityScanwithinclude: ['[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. - Filters the violation list to
serious/criticalimpact and asserts the count is zero. Any failing rule is reported with its rule ID, impact, help URL, and the failing selector(s). - 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
testfromapps/oshun/web/e2e/fixtures.tsends withexpectNoSeriousA11yViolations(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.jsonincludes the OSHUN web app on port 4176 with/,/library,/search,/notifications,/settingsURLs; the nightly job lands artifacts underinfra/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:
# 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.
Pre-existing related accessibility specs#
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.