491e883653
- Created `StellaOps.TestKit.Tests` project for unit tests related to determinism. - Implemented `DeterminismManifestTests` to validate deterministic output for canonical bytes and strings, file read/write operations, and error handling for invalid schema versions. - Added `SbomDeterminismTests` to ensure identical inputs produce consistent SBOMs across SPDX 3.0.1 and CycloneDX 1.6/1.7 formats, including parallel execution tests. - Updated project references in `StellaOps.Integration.Determinism` to include the new determinism testing library.
66 lines
3.7 KiB
Markdown
66 lines
3.7 KiB
Markdown
# 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`
|