Status: completed on March 26, 2026
Related:
docs/releases/v1/scope/contrast-and-focus-indicator-rules.mddocs/releases/v1/specs/shared-component-accessibility-standards.mddocs/releases/v1/scope/action-placement-rules.mddocs/releases/v1/scope/interaction-feedback-rules.mddocs/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.tsxandapps/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.tsxuntil it is actually visible - reworked
apps/oshun/web/src/components/NotificationsCenterPanel.tsxso 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, andapps/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 inapps/metis/admin/src/components/AdminSidebar.tsx - converted sortable headers in
apps/metis/admin/src/components/DataTable.tsxto real buttons witharia-sort - added shared-table coverage in
apps/metis/admin/src/components/DataTable.test.tsxand keyboard browser coverage inapps/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:
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 --noEmitstill fails on pre-existing unrelated web issues outside this task, includinge2e/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 forShellLayout,NotificationsCenterPanel, and the new keyboard specs returned no matches after the local notification-test cast fix.pnpm --dir apps/oshun/web exec next buildstill fails on pre-existing unrelated analytics and studio issues outside this task, including missing exported studio workspaces plus the existing analytics client type incompatibility atsrc/analytics/studioApiGatewayBffCompositionTelemetry.ts:61.