# OSHUN V1 Keyboard And Focus-Path Audit

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