Eve library

OSHUN V1 Web Shell Accessibility Audit

Guide

Revision 1

On this page

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.