Eve library

OSHUN V1 Keyboard And Focus-Path Audit

Guide

Revision 1

On this page

Status: completed on March 26, 2026

Related:

  • docs/releases/v1/scope/contrast-and-focus-indicator-rules.md
  • docs/releases/v1/specs/shared-component-accessibility-standards.md
  • docs/releases/v1/scope/action-placement-rules.md
  • docs/releases/v1/scope/interaction-feedback-rules.md
  • docs/releases/v1/audits/visual/rhythm-notification-density.md

Standard#

The governing bar for this audit is unchanged:

  • every critical customer and admin flow must remain completable from keyboard alone
  • hidden or off-state controls must not remain in the tab order
  • focus must move deliberately into the intended working region and not force repeated sidebar or chrome traversal
  • sortable, clickable, and secondary actions must use real control semantics instead of pointer-only wrappers

This audit uses the shared accessibility standards plus the contrast and focus-indicator rules as the pass/fail source of truth.

Scope#

This audit covers the clearest keyboard and focus-path risks in the current web customer and admin shells:

  • OSHUN web shell chrome in apps/oshun/web/src/components/ShellLayout.tsx
  • OSHUN web notifications interaction model in apps/oshun/web/src/components/NotificationsCenterPanel.tsx
  • Metis admin shell layout and sidebar in apps/metis/admin/src/app/layout.tsx and apps/metis/admin/src/components/AdminSidebar.tsx
  • Metis admin shared dense-data table behavior in apps/metis/admin/src/components/DataTable.tsx

Before implementation, the existing shell accessibility layer in apps/oshun/web/src/components/AccessibilityShell.tsx, the shared contrast and component accessibility standards, the Metis sidebar and layout structure, and the existing notification and table implementations were reviewed so the fixes could extend current patterns instead of introducing a second accessibility model.

Findings#

Customer shell deviation: hidden tab stop#

The customer shell kept the fixed scroll-to-top button in the DOM and tab order even when it was visually hidden through opacity and pointer suppression.

That created a keyboard stop with no visible affordance.

Customer notification deviation: hover-only secondary actions#

Full notification cards used a focusable article wrapper with nested action buttons. Secondary actions only became visible on hover, which meant the keyboard path mixed invalid nested interactive behavior with hidden tab stops.

Admin shell deviation: no direct skip path into the working surface#

Metis admin pages opened directly into a fixed sidebar layout without a dedicated skip-to-content affordance or an explicit current-page announcement on the primary nav links.

Admin dense-data deviation: mouse-only sortable headers#

The shared DataTable sorted by attaching click handlers directly to <th> elements. That left sorting without button semantics, without clear aria-sort state, and without a reliable keyboard entry point.

Implementation Approach Selected#

The selected fixes stayed close to the repo's existing accessibility posture:

  • keep the customer shell structure, but remove hidden tab stops and preserve only visible controls in the keyboard path
  • keep the existing notification visuals, but split "open card" from secondary actions so focus order becomes explicit and actions reveal on focus as well as hover
  • bring a small skip-link layer to Metis admin rather than rewriting the layout
  • fix dense-data sorting once in the shared table so every consuming admin surface inherits keyboard sorting and aria-sort

Changes Implemented#

  • removed the hidden customer shell scroll-to-top button from the tab order in apps/oshun/web/src/components/ShellLayout.tsx until it is actually visible
  • reworked apps/oshun/web/src/components/NotificationsCenterPanel.tsx so notification cards use a dedicated open button plus focus-revealed secondary actions instead of a nested interactive wrapper
  • added keyboard regression coverage for the customer shell and notification focus path in apps/oshun/web/src/components/__tests__/ShellLayout.test.tsx, apps/oshun/web/src/components/__tests__/NotificationsCenterPanel.test.tsx, and apps/oshun/web/e2e/home-keyboard-focus-path.spec.ts
  • added a lightweight Metis admin accessibility shell in apps/metis/admin/src/components/AdminAccessibilityShell.tsx
  • added a real skip-to-main-content path plus main focus target in apps/metis/admin/src/app/layout.tsx
  • added aria-current, navigation targeting, and stronger keyboard metadata in apps/metis/admin/src/components/AdminSidebar.tsx
  • converted sortable headers in apps/metis/admin/src/components/DataTable.tsx to real buttons with aria-sort
  • added shared-table coverage in apps/metis/admin/src/components/DataTable.test.tsx and keyboard browser coverage in apps/metis/admin/e2e/keyboard-focus-path.spec.ts

Result#

Surface Previous failure mode Resolution Result
Customer shell Hidden scroll-top button stayed tabbable Hidden control is now disabled and removed from tab flow Pass
Customer notifications Hover-only actions and nested controls Open action and secondary actions now have a valid focus path Pass
Metis admin shell No direct skip path into main workspace Keyboard users can jump straight into #main-content Pass
Metis admin dense tables Sort headers were mouse-only <th> clicks Sorting now uses buttons and exposes aria-sort Pass

Verification#

Focused verification that passes:

bash
pnpm exec prettier --check \
  'apps/oshun/web/src/components/ShellLayout.tsx' \
  'apps/oshun/web/src/components/NotificationsCenterPanel.tsx' \
  'apps/oshun/web/src/components/__tests__/ShellLayout.test.tsx' \
  'apps/oshun/web/src/components/__tests__/NotificationsCenterPanel.test.tsx' \
  'apps/oshun/web/e2e/home-keyboard-focus-path.spec.ts' \
  'apps/metis/admin/src/app/layout.tsx' \
  'apps/metis/admin/src/components/AdminAccessibilityShell.tsx' \
  'apps/metis/admin/src/components/AdminSidebar.tsx' \
  'apps/metis/admin/src/components/DataTable.tsx' \
  'apps/metis/admin/src/components/DataTable.test.tsx' \
  'apps/metis/admin/e2e/keyboard-focus-path.spec.ts' \
  'docs/releases/v1/audits/keyboard/and-focus-path.md' \
  'docs/releases/v1/specs/readme.md' \
  'docs/releases/v1/specs/todos.md'

pnpm --dir apps/oshun/web exec eslint \
  'src/components/ShellLayout.tsx' \
  'src/components/NotificationsCenterPanel.tsx' \
  'src/components/__tests__/ShellLayout.test.tsx' \
  'src/components/__tests__/NotificationsCenterPanel.test.tsx'

pnpm --dir apps/oshun/web exec eslint --no-ignore \
  'e2e/home-keyboard-focus-path.spec.ts'

pnpm --dir apps/oshun/web exec vitest run \
  src/components/__tests__/ShellLayout.test.tsx \
  src/components/__tests__/NotificationsCenterPanel.test.tsx

pnpm --dir apps/oshun/web exec playwright test \
  e2e/home-notification-preview.spec.ts \
  e2e/home-keyboard-focus-path.spec.ts

pnpm --dir apps/metis/admin exec eslint --no-ignore \
  'src/app/layout.tsx' \
  'src/components/AdminAccessibilityShell.tsx' \
  'src/components/AdminSidebar.tsx' \
  'src/components/DataTable.tsx' \
  'src/components/DataTable.test.tsx' \
  'e2e/keyboard-focus-path.spec.ts'

pnpm --dir apps/metis/admin exec vitest run \
  src/components/DataTable.test.tsx \
  src/app/courses/page.test.tsx

pnpm --dir apps/metis/admin exec playwright test \
  e2e/visual-rhythm.spec.ts \
  e2e/keyboard-focus-path.spec.ts

pnpm --dir apps/metis/admin exec tsc --noEmit

pnpm --dir apps/metis/admin exec next build

Because js_repl is not available in the active Codex session, the playwright-interactive workflow could not run as a persistent interactive browser session here. The applicable keyboard and focus-path QA still ran through the repository Playwright CLI harnesses for both the customer and admin surfaces.

Known repo-level blockers encountered during completion:

  • pnpm --dir apps/oshun/web exec tsc --noEmit still fails on pre-existing unrelated web issues outside this task, including e2e/studio-bellona-build-artifact-management-smoke.spec.ts, src/analytics/studioApiGatewayBffCompositionTelemetry.ts, many other studio analytics files, and unrelated studio token/property mismatches. A filtered rerun for ShellLayout, NotificationsCenterPanel, and the new keyboard specs returned no matches after the local notification-test cast fix.
  • pnpm --dir apps/oshun/web exec next build still fails on pre-existing unrelated analytics and studio issues outside this task, including missing exported studio workspaces plus the existing analytics client type incompatibility at src/analytics/studioApiGatewayBffCompositionTelemetry.ts:61.