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

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`.

## 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.
