# OSHUN V1 Web Shell Accessibility Audit

Date: March 30, 2026 Task: `V1-WEB-029`

## Scope

`V1-WEB-029` required durable accessibility automation for the authenticated
customer shell. The repo already had component-level accessibility fixtures and
route-level Playwright signoff, but it did not yet run browser-level axe scans
across the core shell routes that define the launch-critical web experience.

## Existing Implementation Review

Before this task:

- `apps/oshun/web/e2e/shell-route-signoff.spec.ts` already exercised the core
  customer routes and the shell notifications drawer, which made it the right
  route inventory to extend for accessibility signoff.
- `apps/oshun/web/e2e/support/shell-auth.ts` already provided the authenticated
  customer-session bootstrap needed to keep browser accessibility scans focused
  on the shell instead of welcome/login redirects.
- `apps/oshun/web/src/components/__tests__/accessibility-axe.test.tsx` covered
  selected component semantics, but it explicitly avoided real axe execution and
  did not provide browser-level route coverage.
- `apps/lilith/web/src/accessibility/playwright/helpers.ts` already showed an
  in-repo `@axe-core/playwright` helper pattern worth adapting instead of
  inventing a separate accessibility harness.

## Skill Usage Note

The repo instructions required the `playwright-interactive` workflow for
applicable UI validation. I opened that skill first, but `js_repl` is not
available in this session, so I used the strongest available equivalent:
repository Playwright specs executed directly via `pnpm exec playwright test`.

## Implementation Delivered

- Added `apps/oshun/web/e2e/support/accessibility.ts` with a reusable
  `@axe-core/playwright` wrapper that:
  - defaults to WCAG 2.x A/AA tags
  - excludes local Next.js dev-overlay selectors so scans stay bound to product
    UI
  - formats violations into actionable selector-level error output
- Added `apps/oshun/web/e2e/shell-route-accessibility.spec.ts` with browser
  accessibility coverage for:
  - home
  - explore
  - library
  - activity
  - profile notifications
  - profile
  - the open shell notifications drawer
- Each route scan verifies the shared customer shell frame first:
  - authenticated customer shell root
  - single visible `main` region
  - named shell route navigation
- Hardened `apps/oshun/web/e2e/support/shell-auth.ts` so shell-route test
  helpers wait on DOM readiness instead of brittle `networkidle`, and dismiss
  stray PWA update prompts before route-level signoff assertions run.
- Corrected invalid Lucide icon imports in the shared shell icon registry and
  preview surface so the audited shell routes render reliably during browser
  signoff instead of crashing during hydration.
- Removed nested interactive controls from the active routine status bar and
  daily plan rows, added missing accessible names in profile preferences, and
  added a close-label for the shell notifications drawer so the new route-level
  scans pass for the right reasons instead of relying on test exclusions.
- Raised low-contrast shell tokens and route-surface accent text where the axe
  scans exposed contrast debt, including tertiary/disabled text, success-state
  messaging, library domain badges, and active segmented-control labels.
- Refreshed the first-impression shell visual baselines that changed as a direct
  result of the accessibility fixes and added a hydrated home-workspace
  readiness marker used by the focused visual suite so the home snapshots wait
  for the client shell to settle before capture.
- Updated `apps/oshun/web/package.json` to declare the direct
  `@axe-core/playwright` dev dependency used by the new helper.
- Updated `apps/oshun/web/README.md` with the focused route-accessibility test
  entry point.

## Verification

Passing focused checks:

- `pnpm install --lockfile-only --filter @oshun/web`
- `pnpm --dir apps/oshun/web exec eslint e2e/support/accessibility.ts e2e/shell-route-accessibility.spec.ts --max-warnings=0`
- `pnpm --dir apps/oshun/web exec playwright test -c playwright.config.ts e2e/shell-route-accessibility.spec.ts`
- `pnpm --dir apps/oshun/web exec playwright test -c playwright.config.ts e2e/shell-route-signoff.spec.ts`
- `pnpm --dir apps/oshun/web exec playwright test -c playwright.config.ts e2e/shell-surface-states.spec.ts`
- `pnpm --dir apps/oshun/web exec playwright test -c playwright.config.ts e2e/shell-first-impression-visual.spec.ts`

## Key Outcomes

- OSHUN web now has route-level axe coverage over the entire authenticated
  customer shell instead of only component-level semantic spot checks.
- Accessibility failures now surface with concrete selector-level diagnostics,
  which makes regressions fixable inside the same browser workflow used for
  shell signoff.
- The notifications drawer is covered as an interactive accessibility state, so
  the shell is tested both at rest and with one of its highest-value overlays
  open.
