git.stella-ops.org/docs/ui/navigation.md

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 / Detail format. 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>

• tenant is mandatory and matches Authority slugs (e.g., acme-prod).
• since / until use ISO-8601 timestamps (UTC). Preset ranges set only since; UI computes until on load.
• severity accepts comma-separated policy buckets (e.g., critical,high,kev).
• view stores module-specific state (e.g., sbomView=usage, findingsPreset=threat-hunting).
• panel selects 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 stella commands 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 / until use ISO-8601 timestamps (UTC). Preset ranges set only since; UI computes until on load.
• severity accepts comma-separated policy buckets (e.g., critical,high,kev).
• view stores module-specific state (e.g., sbomView=usage, findingsPreset=threat-hunting).
• panel selects drawers or tabs (panel=explain, panel=timeline).
• component encodes package selection using percent-encoded PURL syntax.
• snapshot appears 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

1. Initiate: User triggers Ctrl/Cmd + T or clicks the tenant badge. Switcher modal lists authorised tenants and recent selections.
2. Preview: Selecting a tenant shows summary (environment, last snapshot, role coverage). The modal flags tenants missing required scopes for the current route.
3. Confirm: On confirmation, the UI requests a new DPoP-bound access token from Authority (aud=console, tenant=<id>).
4. Invalidate caches: Stores keyed by tenant purge automatically; modules emit tenantChanged events so in-flight SSE streams reconnect with new headers.
5. 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.
6. Audit and telemetry: ui.tenant.switch log writes subject, from/to tenant, correlation ID. Metric ui_tenant_switch_total increments for observability dashboards.
7. 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 URL tab parameter 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.

---

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