# StellaOps Console Accessibility Guide

This guide defines the StellaOps Console accessibility baseline: keyboard interaction model, screen reader behavior, color/focus expectations, and offline parity requirements.

## Principles

1. **Deterministic navigation:** focus order, deep links, and announcements remain stable across releases.
2. **Keyboard-first:** every action is reachable without a mouse; shortcuts are accelerators, not requirements.
3. **AT parity:** ARIA roles and live regions mirror visual affordances (status banners, progress, drawers).
4. **Contrast by design tokens:** color and focus rings are governed by tokens that meet WCAG 2.2 AA targets.
5. **Offline equivalence:** accessibility behavior must remain consistent in sealed/air-gapped environments.

## Keyboard Interaction Map

### Global shortcuts

| Action | macOS | Windows/Linux | Notes |
| --- | --- | --- | --- |
| Command palette | `Cmd+K` | `Ctrl+K` | Opens palette search; respects tenant scope. |
| Tenant picker | `Cmd+T` | `Ctrl+T` | Switches tenant context; `Enter` confirms, `Esc` cancels. |
| Filter tray | `Shift+F` | `Shift+F` | Focus lands on first filter control. |
| Saved view presets | `Cmd+1..9` | `Ctrl+1..9` | Presets are stored per tenant. |
| Keyboard reference | `?` | `?` | Lists context-specific shortcuts; `Esc` closes. |
| Context search | `/` | `/` | Focuses inline search when filter tray is closed. |

### Module-specific shortcuts (examples)

| Area | Action | macOS | Windows/Linux | Notes |
| --- | --- | --- | --- | --- |
| Findings | Search within explain | `Cmd+/` | `Ctrl+/` | Only when explain drawer is open. |
| SBOM Explorer | Toggle overlays | `Cmd+G` | `Ctrl+G` | Persists per session (see `docs/15_UI_GUIDE.md`). |
| Advisories & VEX | Focus provider chips | `Cmd+Alt+F` | `Ctrl+Alt+F` | Moves focus to provider chip row. |
| Runs | Refresh stream state | `Cmd+R` | `Ctrl+R` | Soft refresh; no full reload. |
| Policies | Save draft | `Cmd+S` | `Ctrl+S` | Requires edit scope. |
| Downloads | Copy CLI command | `Shift+D` | `Shift+D` | Copies the related CLI command, when available. |

## Screen Reader and Focus Behavior

- **Skip navigation:** every route exposes a "Skip to content" link on focus.
- **Headings as anchors:** route changes move focus to the primary heading (`h1`) and announce the new view.
- **Drawers and modals:** trap focus until closed; `Esc` closes; focus returns to the launching control.
- **Live regions:** status tickers and progress surfaces use `aria-live="polite"`; errors use `assertive` sparingly.
- **Tables and grids:** sorting state is exposed via `aria-sort`; virtualization retains ARIA semantics.
- **Offline banners:** use `role="status"` and provide actionable, keyboard-reachable guidance.

## Color, Contrast, and Focus

- All user-visible color must derive from a token system (light/dark variants).
- Focus indicators must be visible on all surfaces (minimum 3:1 contrast against surrounding UI).
- Status colors (critical/warning/success) must be readable without color alone (icons + text + patterns).

## Testing Workflow (Recommended)

- **Automated:** Playwright accessibility sweep (keyboard navigation + axe checks) across core routes.
- **Component-level:** Storybook + axe for shared components.
- **Contrast linting:** validate token updates with an automated contrast check.
- **Manual:** NVDA (Windows) and VoiceOver (macOS) spot checks on tenant switching, drawers, and exports.
- **Offline smoke:** run the Console against Offline Kit snapshots and validate the same flows.

## References

- `docs/15_UI_GUIDE.md`
- `docs/cli-vs-ui-parity.md`
- `docs/observability/ui-telemetry.md`
- `docs/security/console-security.md`