cairnobs/docs/design-system.md

# Cairn OBS Design System (Phase 5)

Direction: **Signal** — cockpit/ICU-monitor instrumentation logic. Color
is a rationed resource: the UI is near-neutral grayscale everywhere, so
the four severity tiers land as genuinely the most saturated colors
anywhere on screen, not one saturated color competing with a dozen
decorative ones. See the Phase 5 design-direction review (three options
were presented; Signal was the one picked) for the two rejected
directions and the full rationale.

This doc is the source of truth for the token system and component
library `/web/src/lib/components/ui` implements — read it before adding
a new color, spacing value, or component, rather than reaching for a
literal hex or one-off markup the way Phase 0-3's pages did.

## Status

**Status: Phase 5 shipped.** All ten tasks are built: the token system,
the `ui/` component library, the persistent sidebar nav + command
palette, a real ECharts-based charting layer (5 chart types, drill-down,
zoom), the dashboard panel rebuild (GridStack drag-and-drop + live-preview
panel editor), the query/search redesign (CodeMirror syntax highlighting
+ autocomplete, sortable/resizable/expandable results), the alerting UI
redesign (severity-state pill + delivery timeline), and an accessibility
pass driven by real axe-core runs against the live app (not static
analysis) — see the Accessibility section below for what that actually
caught. See `/docs/phase-5-runbook.md` for the full verification log.

Verified in a real browser against a live docker-compose stack with real
seeded data (not just fixtures): dark/light/system theme and
comfortable/compact density switching persisting across navigation and
reload; command palette open/filter/keyboard-navigate/go-to; every nav
route including dashboard/alert detail pages with real panels and real
alert history; all 6 panel viz types rendering real query results; a
firing alert rule's full state-history timeline; keyboard-only operation
of the query editor, results table (sort/expand), and dashboard grid.

## Fonts

Self-hosted (not a Google Fonts CDN link — no runtime dependency on a
third party for the app to render correctly): `web/static/fonts/`,
licensed under the SIL Open Font License (see that directory's
`LICENSE.txt`).

| Role | Typeface | Why |
|---|---|---|
| UI (nav, labels, headings, body) | Overpass | Originally drawn for U.S. highway signage — engineered to be read correctly, fast, under bad conditions. A more honest reason to pick a typeface for an incident-response tool than "it looks modern." |
| Data (log tables, code, query bar, numbers) | Overpass Mono | Same family as the UI face — one typeface end to end removes even the small cognitive cost of a font pairing, matching the direction's overall restraint. |

Both are variable fonts (one file covers the full weight range), loaded
via `@font-face` in `web/src/lib/styles/fonts.css`.

## Color tokens

Defined in `web/src/lib/styles/tokens.css`. Dark is the literal default
— `:root` defines the dark palette directly, light is the override
(both `@media (prefers-color-scheme: light)` for an unset preference and
`[data-theme="light"]` for an explicit one) — not a retrofit where light
is `:root` and dark is bolted on. Component CSS must only ever read a
token, never a literal hex; that's what makes the theme/density toggles
a token swap instead of a per-component rewrite.

| Token | Dark | Light | Use |
|---|---|---|---|
| `--color-bg` | `#0a0a0b` | `#f7f7f8` | Page background |
| `--color-surface` | `#17181a` | `#ffffff` | Cards, tables, inputs |
| `--color-surface-raised` | `#1e2023` | `#ffffff` | Hover states, popovers |
| `--color-border` / `--color-border-strong` | `#2a2c2f` / `#3a3d41` | `#dfe0e2` / `#c7c9cc` | Dividers, input borders |
| `--color-text` / `--color-text-muted` / `--color-text-faint` | `#f0f0f1` / `#85888d` / `#8a8d92` | `#101113` / `#6b6e73` / `#75787d` | Body text hierarchy |
| `--color-accent` / `--color-accent-strong` | `#3fb6ff` | `#0b84d6` | Interactive elements only — links, primary buttons, focus rings, active nav. Never reused for severity (see below); a semantic color competing with the brand accent defeats the point of "color means something." |

### Severity tiers

The schema carries seven OTel severities
(`TRACE`/`DEBUG`/`INFO`/`WARN`/`ERROR`/`FATAL`/`UNSPECIFIED`, see
`/storage/README.md`). Seven colors would be seven things to memorize at
a glance; `web/src/lib/severity.ts`'s `severityTier()` collapses them to
four accent tiers plus one "quiet" state:

| OTel severity | Tier | Dark | Light |
|---|---|---|---|
| `TRACE`, `DEBUG`, `UNSPECIFIED` | quiet | `#85888d` | `#6b6e73` |
| `INFO` | info | `#4c8dff` | `#1a63d6` |
| `WARN` | warn | `#f5c242` | `#8c6800` |
| `ERROR` | error | `#ff6a39` | `#c94b1e` |
| `FATAL` | critical | `#ff2d78` | `#c21362` |

Chosen as a blue → amber → orange → magenta progression — hue *and*
lightness both shift at every step, so no two adjacent tiers rely on
red-vs-green to be told apart, and the sequence should survive grayscale
and protanopia/deuteranopia simulation. That reasoning hasn't been
verified with an actual simulator yet — do that before treating it as
confirmed accessible, not just plausible.

Each tier also has a translucent `-bg` token (e.g. `--color-sev-warn-bg`)
for chip/pill backgrounds. These are tuned independently of the solid
foreground colors above, not derived from them by a fixed formula: a
translucent color tints *toward* its own hue as alpha increases, which
for these saturated, low-luminance hues (critical's magenta especially)
*lowers* contrast against the foreground text the higher the alpha goes
— the opposite of the intuitive "more opaque background is safer"
assumption. `--color-sev-warn` itself was darkened in light mode
(`#9c7300` → `#8c6800`) for the same underlying reason: axe-core caught
the *plain* light-mode warn text failing AA (4.32:1) against white
before any background was even involved. See the Accessibility section.

Use `<SeverityBadge severity={row.severity} />`
(`ui/SeverityBadge.svelte`) to render one of these — it owns the OTel
string → tier mapping so call sites can't invent a sixth color by hand.
For non-log-severity status (success/danger/neutral/accent — e.g. a
"saved" confirmation), use `<Badge tone="...">` instead; the two are
deliberately separate components so a form-validation color can never
accidentally collide with a log-severity one.

## Type scale

14px base (dense-first — this is a tool for reading log tables, not
marketing copy), 1.2 modular ratio:

`--text-xs` 11px · `--text-sm` 13px · `--text-base` 14px · `--text-md`
16px · `--text-lg` 20px · `--text-xl` 28px · `--text-2xl` 40px

`--font-weight-normal` 400, `--font-weight-medium` 600,
`--font-weight-bold` 700. `font-variant-numeric: tabular-nums` is set
globally on `body` so columns of numbers/timestamps align.

## Spacing, radius, shadow

8px-based spacing scale: `--space-1` through `--space-8` (4px, 8px,
12px, 16px, 24px, 32px, 48px, 64px). Radius: `--radius-sm` 4px,
`--radius-md` 6px, `--radius-lg` 10px, `--radius-full` (pills). Shadow
is used sparingly, matching Signal's restraint — only real overlays
(modals, the command palette, tooltips) get one (`--shadow-sm/md/lg`);
inline UI never does.

## Density

Two presets, one token swap — `html.density-compact` overrides
`--row-height`, `--row-padding-y/x`, `--panel-padding`, `--control-height`,
and drops `--text-base` to `--text-sm`. Comfortable (the default) suits
dashboards and forms; compact suits log tables and query results. Toggle
via `$lib/density.svelte.ts`'s `setDensity()`/`toggleDensity()` — a
global, persisted (`localStorage['cairnobs.density']`) preference, not a
per-page setting, so switching it on one page carries to the next.
`web/src/app.html` has a synchronous inline script that applies the
stored value before first paint, so there's no flash of the wrong
density on reload; keep that script's storage key/values in sync with
`density.svelte.ts` if either changes.

## Theme

`$lib/theme.svelte.ts`, same persisted/synchronous-apply shape as
density. Three states — `'dark' | 'light' | 'system'` — but unlike most
apps, the *unset* default is `'dark'`, not `'system'`. That's the actual
point of "real dark mode as the default, not an afterthought": a
first-time visitor on a light-OS machine still lands in dark. `'system'`
is available as a deliberate opt-in for anyone who wants their OS
setting to win instead.

## Components (`web/src/lib/components/ui/`)

Import from the barrel: `import { Button, Input, ... } from
'$lib/components/ui';`

| Component | Notes |
|---|---|
| `Button` | `variant`: `primary`/`secondary`/`ghost`/`danger`. `size`: `sm`/`md`. Renders `<a>` when `href` is passed, `<button>` otherwise. |
| `Input` | Thin styled wrapper over `<input>`; `bind:value`, `invalid` sets `aria-invalid` + a danger border. |
| `Select` | Styled wrapper over native `<select>` (real `<option>` children) — not a custom listbox, so it keeps native keyboard/screen-reader behavior for free. |
| `Badge` | Generic status pill. `tone`: `neutral`/`success`/`danger`/`accent`. |
| `SeverityBadge` | `severity` prop takes a raw OTel string; maps to a tier internally. Use this instead of `Badge` for anything log-severity-shaped. |
| `Table` | A styling wrapper around real `<table>` markup (native semantics matter for screen readers) — pass real `<thead>`/`<tbody>` as children. Density-aware via the row tokens above. Not a data grid; sort/resize (Phase 5 task 6) layers on top later. |
| `Card` | `title`/`actions` (a snippet) header, `padded` toggle. |
| `Modal` | Built on native `<dialog>` — real focus trap, Escape-to-close, and top-layer stacking, not hand-rolled. `bind:open`, `title`, `footer` snippet. |
| `Tooltip` | Pure-CSS hover/focus tooltip, `role="tooltip"` + `aria-describedby`. |
| `Tabs` | Renders the tab list only (roving tabindex, arrow-key nav); the caller renders each panel's content on `bind:active` and owns `id="panel-{id}"`/`aria-labelledby="tab-{id}"`. |

`CommandPalette.svelte` and `NavSidebar.svelte`
(`web/src/lib/components/`, not under `ui/`) are app-shell components,
not general-purpose library pieces — mounted once in `+layout.svelte`.

## Navigation & tenant switching

Persistent sidebar (`NavSidebar.svelte`): Search / Dashboards / Alerts /
Data Sources / Settings, active-route highlighting, a command-palette
hint, and the theme/density quick toggles. The tenant indicator calls
`getCurrentSession()` (`$lib/api.ts`), which wraps `POST
/internal/authorize` — an endpoint that already existed (`api/authz.
HTTPAuthorizer` and `alerting` already call it) and was already reachable
from the browser (`enterprise-auth`'s whole mux is behind
`WithCredentialedCORS`, not just the tenant-picker routes), so this
needed zero backend changes.

**Known limitation, not yet solved at the API level**: there is no
"list my other tenant memberships while already logged in" endpoint —
`GET /auth/memberships` only works during the short-lived pending-login
window (see `enterprise/internal/loginhandler`'s doc comment), not for
an established session. So "Switch tenant" in the sidebar re-triggers
login (`/auth/oidc/login`) rather than offering an inline dropdown —
logging in again is the only tenant-switching mechanism this product
actually has today, and if there's more than one membership it
naturally lands back on `/select-tenant`. A real inline switcher would
need a new `GET /auth/my-memberships`-shaped endpoint (or equivalent);
that's real, disclosed future work, not a bug in what's built.

## Command palette

`⌘K`/`Ctrl+K` anywhere in the app. Indexes the five static nav
destinations plus live-fetched dashboards and alert rules
(`listDashboards()`/`listRules()`, via `Promise.allSettled` so one
failing endpoint doesn't blank the other's results or the static items).
Arrow keys + Enter to navigate, Escape to close (native `<dialog>`,
same reasoning as `Modal`). Substring filter, not fuzzy — no new
dependency pulled in for it, matching this repo's "boring,
well-understood dependencies" convention.

## Charting (`web/src/lib/charts/`)

Built on **ECharts**, via modular imports (`echarts/core` plus only the
chart/component modules actually used — `LineChart`, `BarChart`,
`HeatmapChart`, `TooltipComponent`, `GridComponent`, `LegendComponent`,
`DataZoomComponent`, `VisualMapComponent`, `MarkLineComponent`,
`CanvasRenderer`), not the full bundle. Picked over Observable Plot (SVG
rendering hits a real performance ceiling at volume, and no built-in
zoom/pan or legend-toggle) and raw D3 (too much hand-rolled engineering
for chart types this standard). Verified, not assumed: the lazy-loaded
chart chunk is 211,975 bytes gzipped, and a synthetic 30,006-row/6-series
stress fixture (`/dev/charts`, an unlisted dev-only route) renders its
first two frames in ~50ms on a production build — `npm run dev`'s
~3.1s figure for the same fixture is pure dev-mode/unminified-JS
overhead, not a real perf number, and was confirmed as such before being
discarded.

Five chart components, all consuming the same `{columns, rows}`
`QueryResult` shape Phase 2's query endpoint has always returned:
`TimeSeriesChart` (multi-series line, legend toggle), `BarChart`
(including stacked), `SingleStat` (big number + sparkline + trend),
`Heatmap`, `TopN` (ranked horizontal bars). `EChart.svelte` is the shared
base wrapper (init/resize/dispose lifecycle).

**No query-language change was needed for multi-series or drill-down** —
both are pure frontend reshaping of the existing tabular output:

- `pivot.ts`'s `pivot(columns, rows, config)` turns a "long" result (one
  row per series+x pair, e.g. `stats count by service, timestamp`) into
  one series per distinct value of the grouping column. Its value-column
  auto-detection has one sharp edge worth knowing if you touch it: when
  a result has only one non-x column (a bare `stats count`, `single_stat`'s
  most common shape), `Array.prototype.findIndex` returning `-1` for "not
  found" must be checked explicitly — `-1 ?? fallback` never falls back,
  because `-1` isn't `null`/`undefined`. This was a real, shipped bug
  (every `single_stat` panel silently rendered `0`) caught by seeding a
  live dashboard with real query results rather than only fixture data,
  not by any static check.
- `drilldown.ts` strips a panel's query down to its pre-`stats` filter
  portion, appends a clicked series/x-value as a new filter term, and
  computes a tight time window around a clicked timestamp — then
  navigates to the Search page via URL params (`?q=&earliest=&latest=`).

`theme.ts`'s `readChartTokens()` reads real computed CSS custom-property
values (`getComputedStyle`) so charts render in the actual active
theme's colors rather than a hardcoded palette — guarded with an
`SSR_FALLBACK` object for adapter-static's prerender pass, where
`document` doesn't exist.

**The one backend change in this phase**: `heatmap` as a `VizType`
(`api/dashboards/types.go`'s `validVizType()`, `web/src/lib/api.ts`'s
`VizType` union, and the `dashboard_panels` table's `viz_type` CHECK
constraint — three places, not two; the DB constraint mirrors the Go
validator and was originally missed, which meant a heatmap panel passed
API validation and then failed on insert. See
`metadata/migrations/0035_add_heatmap_viz_type.sql`). Justified under
the brief's "no query-language or data-model changes except what's
strictly needed to feed richer visualizations" exception — a heatmap is
a viz type, not a new query capability.

## Dashboard panels

Drag-and-drop grid is **GridStack**, already a Phase 3 dependency — no
new library needed, satisfying the brief's "a maintained library is
fine, don't hand-roll grid physics." `PanelEditor.svelte` (a `Modal`)
replaces the old inline add-panel form: a debounced live preview reuses
`PanelViz` directly, so what you see while editing is pixel-identical to
what renders on save, not a separate preview renderer that can drift
from the real thing. Empty/loading/error states use `EmptyState` and
`Skeleton` rather than a blank panel or a raw error string.

## Query & search (`web/src/lib/query-editor/`)

**CodeMirror 6**, not a hand-rolled textarea-plus-overlay highlighter —
picked specifically because autocomplete needs real cursor-aware popup
positioning, which a plain textarea can't give you. `language.ts` is a
`StreamLanguage` tokenizer for the pipe grammar; its `token()` function
must return real `@lezer/highlight` tag names looked up by string
(`'controlKeyword'`, `'operatorKeyword'`, `'name.function'` for
tag+modifier pairs) — a custom `Tag.define()` object's `.toString()`
looks plausible but silently fails to highlight anything, a real bug hit
and fixed while building this. `completions.ts` provides context-aware
suggestions: stage keywords after `|`, stats functions after `stats`,
field names elsewhere.

`ResultsTable.svelte`: sortable columns (click header — a real `<button>`
inside the `<th>`, not a clickable `<th>` itself, so it's keyboard-operable
for free), resizable columns (pointer-drag handles, mouse-only by
design — the `role="separator"` handle is intentionally not in the tab
order, matching how most apps treat column resize as a mouse affordance
rather than a keyboard one), and expandable rows. The row-expand
interaction was originally a bare `<tr onclick=...>` with no keyboard
equivalent at all — a real gap the accessibility pass caught (not via
axe, which doesn't flag missing keyboard handlers on custom widgets;
caught by manually tabbing through the page), fixed by adding
`tabindex="0"`, `role="button"`, `aria-expanded`, and an `Enter`/`Space`
`onkeydown` handler alongside the existing click handler.

"Add as panel to dashboard" (`AddToDashboardModal.svelte`) lets a query
built on the Search page become a saved panel without hand-copying the
query string into the dashboard editor.

## Alerting UI

`AlertStatePill.svelte` reuses the log-severity color tiers rather than
inventing a second color vocabulary: `ok → quiet`, `pending → warn`,
`firing → critical`. `DeliveryTimeline.svelte` reframes the existing
`delivery_log` data (no new backend fields) as a vertical timeline —
"why didn't I get paged" is a chronological question, and a flat table
answered it less directly than a timeline does.

## Accessibility

Automated checks ran with **axe-core**, injected into the live app in a
real browser and driven against a real seeded docker-compose stack
(dashboards with all 6 panel viz types populated with real query
results, a firing alert rule with real delivery history) — not just
static markup or empty/loading states, since several of the real
findings below only appear once real content renders. Real violations
found and fixed:

- `color-contrast`: `AlertStatePill`'s critical tier at 4.04:1 (below
  the 4.5:1 AA threshold) when rendered on an opaque `--color-surface`
  card, not the plain page background most severity chips happen to sit
  on — see the Severity tiers section above for why translucent
  backgrounds made this worse, not better, and why quiet/info (dark) and
  quiet/warn/error (light) were fixed alongside it as the same latent
  bug, not yet triggered elsewhere only because no page had rendered
  those specific tiers on an opaque surface yet.
- `landmark-main-is-top-level` / `landmark-no-duplicate-main` /
  `landmark-unique`: the layout shell's content wrapper was a second
  `<main>` nested around each page's own top-level `<main>`.
- `landmark-one-main` / `region`: `/data-sources` was the one page using
  a plain `<div>` instead of `<main>` as its top-level element.
- `heading-order`: `Card` and `EmptyState` both jumped from `<h1>` to
  `<h3>`, skipping `<h2>`.
- `aria-input-field-name`: the CodeMirror query editor's `.cm-content`
  had no accessible name — fixed via `EditorView.contentAttributes.of({
  'aria-label': ... })`.
- `empty-table-header`: the alerts list table's trailing actions column
  had a bare `<th></th>` — fixed with visually-hidden text (`.sr-only`,
  now a shared utility in `app.css`) rather than a visible "Actions"
  label that would've added a fifth, less-necessary heading.

Keyboard-only operation was verified by tabbing through, not just
inferred from markup: sidebar nav → command-palette hint → theme/density
controls → into main content, with a visible focus ring
(`--focus-ring`, a two-layer box-shadow so it's visible on both light
and dark surfaces) at every stop; the query editor is reachable and
labeled; sort buttons are real `<button>`s; the results table's row
expansion works via `Enter`/`Space` after the fix above. Responsive:
the sidebar collapses to an off-canvas drawer under 860px
(`NavSidebar.svelte`'s `mobileOpen`/`onCloseMobile`, a transform-based
slide-in with a backdrop button), verified down to tablet-landscape
width, not just described in CSS.