# ISIS v2 WS11-006: Keyboard-First Interaction Model and Accessibility Parity

## Scope

`WS11-006` upgrades ISIS web interaction ergonomics from baseline keyboard focus
support to a keyboard-first model for power users with explicit accessibility
parity patterns.

## Research and Existing Implementation Alignment

Implementation aligns with:

- existing ISIS shell/navigation baseline:
  `apps/isis/web/src/components/AppLayout.tsx`,
  `apps/isis/web/src/components/AppLayout.css`
- primary creative workspaces with first-action search/refresh controls:
  `DashboardPage`, `WorkflowsPage`, `JobsPage`, `OutputsPage`
- current ISIS v2 creative-suite ergonomics contract from prior WS11 tasks.

Reference interaction guidance used:

- WAI-ARIA Authoring Practices: keyboard interface conventions and tab patterns
  (https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/,
  https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)
- MDN reference for `aria-keyshortcuts`
  (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts)

## Deliverables

1. Added global keyboard-first interaction model in `AppLayout`:

- `?` toggles an accessible keyboard shortcuts dialog,
- `/` focuses the active page primary search control,
- `Shift+R` triggers active page primary refresh action,
- `g` chord navigation (`g` then route key) for fast page switching,
- polite live announcements for assistive technology feedback.

2. Added keyboard parity for structure navigation:

- context tabs now support `Arrow`, `Home`, `End`, and activation keys,
- primary nav links now support roving `Arrow` traversal and `Home`/`End`.

3. Added discoverability + accessibility surfaces:

- inline shortcut hint strip in context switcher,
- modal shortcuts guide (`role="dialog"`, `aria-modal`),
- keycap visual tokens and visually hidden live-region utility.

4. Bound page-level shortcut targets on core workspaces:

- `DashboardPage`: primary refresh target,
- `WorkflowsPage`: primary focus + refresh targets,
- `JobsPage`: primary focus + refresh targets,
- `OutputsPage`: primary focus + refresh targets,
- all bound controls now expose `aria-keyshortcuts`.

5. Added focused keyboard interaction test coverage:

- `apps/isis/web/src/components/AppLayout.spec.tsx` now verifies: skip link +
  landmarks, `/` focus shortcut, `Shift+R` refresh shortcut, shortcut guide
  open/close behavior, and `g + w` navigation chord behavior.

## Verification Commands

```bash
pnpm --filter @isis/web exec vitest run src/components/AppLayout.spec.tsx src/components/CreativeWorkflowFrame.spec.tsx src/components/IsisLoadingState.spec.tsx src/components/IsisEmptyState.spec.tsx --reporter=dot
pnpm --filter @isis/web run typecheck
node scripts/isis/generate-remediation-backlog-v2.mjs
node scripts/isis/validate-v2-compliance-gate.mjs
```

## Verification Notes

- Targeted keyboard/accessibility behavior tests pass.
- Workspace typecheck remains red due pre-existing unrelated cross-package and
  rootDir/type drift issues in baseline repository state.
