StellaOps Console - Navigation
Audience: Console UX writers, UI engineers, QA, and enablement teams.
Scope: Primary route map, layout conventions, keyboard shortcuts, deep-link patterns, and tenant context switching for the StellaOps Console (Sprint 23).
The navigation framework keeps Console workflows predictable across tenants and deployment modes. This guide explains how the global shell, feature routes, and context tokens cooperate so operators can jump between findings, SBOMs, advisories, policies, and runs without losing scope.
1. Information Architecture
1.1 Primary routes
| Route pattern | Module owner | Purpose | Required scopes (minimum) | Core services |
|---|---|---|---|---|
/console/dashboard | Web gateway | Landing KPIs, feed age, queue depth, alerts | ui.read | Web, Scheduler WebService, Concelier WebService, Excititor WebService |
/console/findings | Policy Engine | Aggregated findings, explain drawer, export | findings.read | Policy Engine, Concelier WebService, SBOM Service |
/console/sbom | SBOM Service | Catalog view, component graph, overlays | sbom.read | SBOM Service, Policy Engine (overlays) |
/console/advisories | Concelier | Advisory aggregation with provenance banners | advisory.read | Concelier WebService |
/console/vex | Excititor | VEX aggregation, consensus, conflicts | vex.read | Excititor WebService |
/console/runs | Scheduler | Run list, live progress, evidence downloads | runs.read | Scheduler WebService, Policy Engine, Scanner WebService |
/console/policies | Policy Engine | Editor, simulations, approvals | policy.read (read) / policy.write (edit) | Policy Engine, Authority |
/console/downloads | DevOps | Signed artifacts, Offline Kit parity checklist | downloads.read | DevOps manifest API, Offline Kit |
/console/admin | Authority | Tenants, roles, tokens, integrations | ui.admin (plus scoped authority:*) | Authority |
/console/help | Docs Guild | Guides, tours, release notes | ui.read | Docs static assets |
1.2 Secondary navigation elements
- Left rail: highlights the active top-level route, exposes quick metrics, and shows pinned saved views. Keyboard focus cycles through rail entries with
Tab/Shift+Tab. - Breadcrumb bar: renders
Home / Module / Detailformat. Detail crumbs include IDs and titles for shareable context (for example,Findings / High Severity / CVE-2025-1234). - Action shelf: right-aligned controls for context actions (export, verify, retry). Buttons disable automatically if the current subject lacks the requisite scope.
2. Command Palette and Search
- Trigger:
Ctrl/Cmd + K. Palette opens in place, keeps focus, and announces results via ARIA live region. - Capabilities: jump to routes, saved views, tenants, recent entities (findings, SBOMs, advisories), and command actions (for example, “Start verification”, “Open explain drawer”).
- Result tokens: palette entries carry metadata (
type,tenant,filters). Selecting an item updates the URL and applies stored filters without a full reload. - Offline fallback: in sealed/offline mode, palette restricts actions to cached routes and saved views; remote-only items show a grayed-out badge.
3. Global Filters and Context Chips
| Control | Shortcut | Persistence | Notes |
|---|---|---|---|
| Tenant picker | Ctrl/Cmd + T | SessionStorage + URL tenant query | Issues fresh Authority token, invalidates caches, emits ui.tenant.switch log. |
| Filter tray | Shift + F | IndexedDB (per tenant) + URL query (since, severity, tags, source, status, policyView) | Applies instantly to compatible routes; incompatible filters show a reset suggestion. |
| Component search | / when filters closed | URL component query | Context-aware; scopes results to current tenant and module. |
| Time window | Ctrl/Cmd + Shift + 1-4 | URL since/until, palette preset | Mapped to preset windows: 24 h, 7 d, 30 d, custom. |
Context chips appear beneath page titles summarising active filters (for example, Tenant: west-prod, Severity: Critical+High, Time: Last 7 days). Removing a chip updates the tray and URL atomically.
4. Keyboard Shortcut Matrix
| Scope | Shortcut (Mac / Windows) | Action | Notes |
|---|---|---|---|
| Global | Cmd+K / Ctrl+K | Open command palette | Accessible from any route except modal dialogs. |
| Global | Cmd+T / Ctrl+T | Open tenant switcher | Requires ui.read. Confirm selection with Enter; Esc cancels without switching. |
| Global | Shift+F | Toggle global filter tray | Focus lands on first filter control. |
| Global | Cmd+1-9 / Ctrl+1-9 | Load saved view preset | Each preset bound per tenant; non-assigned keys show tooltip. |
| Global | ? | Show keyboard reference overlay | Overlay lists context-specific shortcuts; closes with Esc. |
| Findings module | Cmd+/ / Ctrl+/ | Focus explain search | Works when explain drawer is open. |
| SBOM module | Cmd+G / Ctrl+G | Toggle graph overlays | Persists per session. |
| Advisories & VEX | Cmd+Opt+F / Ctrl+Alt+F | Focus provider filter | Highlights provider chip strip. |
| Runs module | Cmd+R / Ctrl+R | Refresh SSE snapshot | Schedules soft refresh (no hard reload). |
| Policies module | Cmd+S / Ctrl+S | Save draft (if edit rights) | Mirrors Policy Editor behaviour. |
Shortcut handling follows WCAG 2.2 best practices: all accelerators are remappable via Settings -> Accessibility -> Keyboard shortcuts, and the overlay documents platform differences.
5. Deep-Link Patterns
5.1 URL schema
Console URLs adopt the format:
/console/<route>[/:id][/:tab]?tenant=<slug>&since=<iso>&severity=<list>&view=<token>&panel=<drawer>&component=<purl>
tenantis mandatory and matches Authority slugs (e.g.,acme-prod).since/untiluse ISO-8601 timestamps (UTC). Preset ranges set onlysince; UI computesuntilon load.severityaccepts comma-separated policy buckets (e.g.,critical,high,kev).viewstores module-specific state (e.g.,sbomView=usage,findingsPreset=threat-hunting).panelselects drawers or tabs (panel=explain,panel=timeline).
5.2 Copyable links
- Share links from the action shelf or context chips; both copy canonical URLs with all active filters.
- CLI parity: inline callouts provide
stellacommands derived from the URL parameters to ensure console/CLI equivalence. - Offline note: links copied in sealed mode include the snapshot ID (
snapshot=<hash>) so recipients know which offline data set to load.
5.3 Examples
since/untiluse ISO-8601 timestamps (UTC). Preset ranges set onlysince; UI computesuntilon load.severityaccepts comma-separated policy buckets (e.g.,critical,high,kev).viewstores module-specific state (e.g.,sbomView=usage,findingsPreset=threat-hunting).panelselects drawers or tabs (panel=explain,panel=timeline).componentencodes package selection using percent-encoded PURL syntax.snapshotappears when copying links offline to reference Offline Kit build hash. @@ | Use case | Example URL | Description | |----------|-------------|-------------| | Findings triage |/console/findings?v=table&severity=critical,high&tenant=west-prod&since=2025-10-20T00:00:00Z| Opens the findings table limited to critical/high for west-prod, last 7 days. | | SBOM component focus |/console/sbom/sha256:abcd?tenant=west-prod&component=pkg:npm/react@18.3.0&view=usage| Deep-links to a specific image digest and highlights an NPM package in Usage view. | | Advisory explain |/console/advisories?tenant=west-prod&source=nvd&panel=detail&documentId=CVE-2025-1234| Opens advisory list filtered to NVD and expands CVE detail drawer. | | Run monitor |/console/runs/42?tenant=west-prod&panel=progress| Focuses run ID 42 with progress drawer active (SSE stream attached). |
6. Tenant Switching Lifecycle
- Initiate: User triggers
Ctrl/Cmd + Tor clicks the tenant badge. Switcher modal lists authorised tenants and recent selections. - Preview: Selecting a tenant shows summary (environment, last snapshot, role coverage). The modal flags tenants missing required scopes for the current route.
- Confirm: On confirmation, the UI requests a new DPoP-bound access token from Authority (
aud=console,tenant=<id>). - Invalidate caches: Stores keyed by tenant purge automatically; modules emit
tenantChangedevents so in-flight SSE streams reconnect with new headers. - Restore state: Global filters reapply where valid. Incompatible filters (for example, a saved view unavailable in the new tenant) prompt users to pick a fallback.
- Audit and telemetry:
ui.tenant.switchlog writes subject, from/to tenant, correlation ID. Metricui_tenant_switch_totalincrements for observability dashboards. - Offline behaviour: If the target tenant is absent from the offline snapshot, switcher displays guidance to import updated Offline Kit data before proceeding.
7. Breadcrumbs, Tabs, and Focus Management
- Breadcrumb titles update synchronously with route data loads. When fragments change (for example, selecting a finding), the breadcrumb text updates without pushing a new history entry to keep back/forward predictable.
- Detail views rely on accessible tabs (
role="tablist") with keyboard support (ArrowLeft/Right). Tab selection updates the URLtabparameter for deep linking. - Focus management:
- Route changes send focus to the primary heading (
h1) using the live region announcer. - Opening drawers or modals traps focus until closed; ESC returns focus to the triggering element.
- Keyboard-only navigation is validated via automated Playwright accessibility checks as part of
DEVOPS-CONSOLE-23-001.
- Route changes send focus to the primary heading (
8. References
/docs/ui/console-overview.md- structural overview, tenant model, global filters./docs/ui/sbom-explorer.md- SBOM-specific navigation and graphs (pending)./docs/ui/advisories-and-vex.md- aggregation UX details (pending)./docs/ui/findings.md- findings filters and explain drawer (pending)./docs/security/console-security.md- Authority, scopes, CSP./docs/cli-vs-ui-parity.md- CLI equivalence matrix./docs/accessibility.md- keyboard remapping, WCAG validation checklists.
9. Compliance Checklist
- [ ] Route table matches Console build (paths, scopes, owners verified with Console Guild).
- [ ] Keyboard shortcut matrix reflects implemented accelerators and accessibility overlay.
- [ ] Deep-link examples tested for copy/share parity and CLI alignment.
- [ ] Tenant switching flow documents cache invalidation and audit logging.
- [ ] Filter tray, command palette, and presets cross-referenced with accessibility guidance.
- [ ] Offline/air-gap notes included for palette, tenant switcher, and deep-link metadata.
- [ ] Links to dependent docs (
/docs/ui/*,/docs/security/*) validated.
Last updated: 2025-10-26 (Sprint 23).