+
+
+ Pipelines web — visual system styleguide
+
+
+
+
+
+
+
+
+
+
+
+
Design deliverable
+
Visual system
+
+ The Pipelines web client keeps the app's dark identity, its mint accent and its
+ run-status vocabulary. This guide refines the layer model, the spacing and type
+ scales, and the component shapes so every area reads from one set of roles
+ instead of repeating its own chip, border and shadow.
+
+ Colour is assigned by layer, not by file. The page is bg;
+ a pane or card is surface; a control, row or code body is
+ surface-2; anything that floats is elevated.
+ Borders mark interactive edges. Dividers separate content inside one surface.
+
+
+
+
Canvas and surface layers
+
+
+
+ --color-bg
+ #0e1513
+
+
+
+ --color-surface
+ #161d1b
+
+
+
+ --color-surface-2
+ #1a211f
+
+
+
+ --color-elevated
+ #252c2a
+
+
+
+ --color-elevated-2
+ #2f3634
+
+
+
+ --color-scrim
+ black 58%
+
+
+
+
+
+
Text, lines and focus
+
+
+
+ --color-text
+ #dee4e1
+
+
+
+ --color-muted
+ #a9bab5
+
+
+
+ --color-faint
+ #8b9b96
+
+
+
+ --color-divider
+ #2c3a36
+
+
+
+ --color-border
+ #6a7874
+
+
+
+ --color-border-strong
+ #889391
+
+
+
+ --color-focus
+ #a9f0dd
+
+
+
+
+
+
Accent and outcome
+
+
+
+ --color-accent
+ #7fd1bb
+
+
+
+ --color-accent-strong
+ #a3e4d3
+
+
+
+ --color-ok
+ #6bd39a
+
+
+
+ --color-warn
+ #e6c268
+
+
+
+ --color-bad
+ #ef8a8a
+
+
+
+
+
+
+
+
+
Type
+ 02 / 09
+
+
+ Eight sans roles and two mono roles. A screen title is
+ title; a section header is title-small; a row name is
+ body at semibold; meta is meta. Nothing picks a size
+ directly.
+
+ One 8px grid with 4px half-steps. Padding inside a component is smaller than
+ the gap between components; the gap between blocks is smaller than the gap
+ between sections. Radii collapse to five roles, and only floating surfaces
+ carry a shadow.
+
+
+
+
+
Spacing scale
+ 8px grid · 4px half-steps
+
+
+
+ --space-3xs
+
+ 2px
+
+
+ --space-2xs
+
+ 4px
+
+
+ --space-xs
+
+ 8px
+
+
+ --space-s
+
+ 12px
+
+
+ --space-m
+
+ 16px
+
+
+ --space-l
+
+ 24px
+
+
+ --space-xl
+
+ 32px
+
+
+ --space-2xl
+
+ 40px
+
+
+ --space-3xl
+
+ 48px
+
+
+ --space-4xl
+
+ 64px
+
+
+
+
+
+
+
Radii
+ one family, five roles
+
+
+
+
+ --radius-xs
+
+
+
+ --radius-s
+
+
+
+ --radius-control
+
+
+
+ --radius-card
+
+
+
+ --radius-sheet
+
+
+
+ --radius-pill
+
+
+
+
+
+
+
Elevation
+ floating surfaces only
+
+
+
+
--elevation-1
+ menu item, sticky edge
+
+
+
--elevation-2
+ menu, toast
+
+
+
--elevation-3
+ dialog
+
+
+
+
+
+
+
+
+
Rail
+ 04 / 09
+
+
+ Destinations and sections share one item shape. The active item changes its
+ surface, its weight and adds a 2px inset accent bar, so selection is never
+ colour alone. Hover is a wash, not a new layer. Width belongs to the layout
+ track; the rail never sizes itself from its labels.
+
+ A row is one control, not a box around a box. Name, status and meta share one
+ two-column grid; hover is a wash and selection adds the accent bar. The toolbar
+ uses the same 36px control height as every other button and field.
+
+
+
+
+
Toolbar
+ filter · sort · search · live
+
+
+
+
+
+ live
+
+
+
+
+
+
Rows
+ default · hover · selected
+
+
+
+
+
+
+
+
+
+
+
+
+
Density
+ light · compact
+
+
+
+
+ Light density
+ row 12px block
+
+
+
+
+
+
+
+
+
+ Compact
+ row 8px block
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Key/value and code
+ 06 / 09
+
+
+ Facts use one two-column table with the label in meta and the value
+ in body-small; hashes, sessions and paths take the mono role. A code
+ block is a single framed surface with its own header, never a bordered box
+ inside another bordered box.
+
+ Anything above the page uses elevated, the sheet radius and one
+ elevation. The scrim carries the separation; the panel does not add a second
+ border around its content. Actions sit on one row, with the primary last.
+
+
+
+
+
+
Confirm dialog
+ Cancel run 458?
+
+
+
+
+
Cancel run 458?
+
This asks the server to stop the active run.
+
+
+
+
+
+
+
+
+
+
+
Bottom sheet
+ Needs you
+
+
+
+
+
+
Needs you
+
+
+
+
+ ✕failed
+
+ Server
+ Server · failed · needs you
+
+
+
+
+ …waiting
+
+ Nightly audit
+ Nightly audit · waiting for your decision
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Conversation
+ 08 / 09
+
+
+ The operator gets a bubble; the agent gets a full-width turn. The transcript is
+ the page surface, so the agent turn does not need a second card. The composer
+ shares the control radius and focus ring, and the approval card is the one
+ place where a warning edge is warranted.
+
+
+
+
+
Show me why run 458 needed the decision, and what changed in the last stage.
+
+
+
+ Agent
+
+
+ Run 458 waited on the review stage. The landing step then completed and
+ recorded four artifacts.
+
+
+
+ Approve bash
+ Waiting for your response
+
+
+
docker build -t pipelines:dev .
+
+
+
+ RISK REVIEW
+
+ This writes an image tagged pipelines:dev on this machine.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Artifacts and empty
+ 09 / 09
+
+
+ A tile is one framed surface; the media fills it and the actions sit over it.
+ An empty state is a sentence and, when there is a way out, one action — never a
+ dashed box or an illustration competing with the text.
+
+
+
diff --git a/web/design/tokens/tokens.css b/web/design/tokens/tokens.css
new file mode 100644
index 00000000..d0e9ecfd
--- /dev/null
+++ b/web/design/tokens/tokens.css
@@ -0,0 +1,262 @@
+/* ===========================================================================
+ Pipelines web — visual system tokens
+ ---------------------------------------------------------------------------
+ The single source of truth for colour roles, spacing, radii, type, elevation,
+ focus, tints and motion. Every token is named for the job it does, never for
+ the value it happens to hold.
+
+ This file contains custom properties only. Import it first, then a component
+ stylesheet (styleguide.css is the worked example). Nothing here paints a
+ selector on its own.
+
+ Contrast contract (verified against the surfaces below):
+ --color-text 14.35:1 on --color-bg, 13.29:1 on --color-surface
+ --color-muted 9.14:1 on --color-bg, 8.47:1 on --color-surface
+ --color-border 3.71:1 on --color-surface, 3.09:1 on --color-elevated
+ --color-focus 13.21:1 on --color-surface
+ Run-status hues are the web's current values, unchanged.
+ =========================================================================== */
+
+:root {
+ /* ---- Canvas and surface layers ---------------------------------------- */
+ /* bg the page behind every pane
+ surface a pane, card or transcript group
+ surface-2 an inset control, row or code body
+ elevated a menu, dialog, sheet or toast above the page
+ elevated-2 the highest drawn surface: hover on an elevated control */
+ --color-bg: #0e1513;
+ --color-surface: #161d1b;
+ --color-surface-2: #1a211f;
+ --color-elevated: #252c2a;
+ --color-elevated-2: #2f3634;
+ --color-scrim: rgba(0, 0, 0, 0.58);
+
+ /* ---- Lines and focus --------------------------------------------------- */
+ /* divider decorative separation inside one surface (not a control edge)
+ border the edge of an interactive or focusable component; >=3:1 on
+ bg, surface, surface-2 and elevated (use border-strong on
+ elevated-2)
+ border-strong selected / pressed emphasis; >=3:1
+ focus the one focus ring colour, visible on every surface */
+ --color-divider: #2c3a36;
+ --color-border: #6a7874;
+ --color-border-strong: #889391;
+ --color-focus: #a9f0dd;
+
+ /* ---- Text -------------------------------------------------------------- */
+ --color-text: #dee4e1;
+ --color-muted: #a9bab5;
+ --color-faint: #8b9b96;
+ --color-on-accent: #06231c;
+ --color-on-bad: #1b0b0b;
+ --opacity-disabled: 0.5;
+
+ /* ---- Accent ------------------------------------------------------------ */
+ --color-accent: #7fd1bb;
+ --color-accent-strong: #a3e4d3;
+ --color-accent-pressed: #5fbfa8;
+
+ /* ---- Outcome hues (the app's own: ok / warn / bad) -------------------- */
+ --color-ok: #6bd39a;
+ --color-warn: #e6c268;
+ --color-bad: #ef8a8a;
+
+ /* ---- Run-status palette (the web's current values, unchanged) ---------- */
+ /* These are copied from the current base.css/.chip-* rules. Three values
+ (succeeded, failed, interrupted) are the web's tuned rendering; the Compose
+ RunStatusPalette uses slightly different stops. This item does not re-tune
+ any status hue. */
+ --status-queued: #9aa6a2;
+ --status-running: #7fb2f0;
+ --status-active: #7fb2f0;
+ --status-waiting: #8edff5;
+ --status-succeeded: #6bd39a;
+ --status-failed: #ef8a8a;
+ --status-canceled: #889391;
+ --status-interrupted: #e6c268;
+ --status-blocked: #f0a35e;
+ --status-skipped: #a8b8c8;
+ --status-unknown: #bec9c5;
+
+ /* Status washes tint the chip body; the neutral chip edge does the 3:1
+ boundary work, so a wash never has to carry the component alone. */
+ --status-queued-wash: rgba(154, 166, 162, 0.10);
+ --status-running-wash: rgba(127, 178, 240, 0.10);
+ --status-active-wash: rgba(127, 178, 240, 0.10);
+ --status-waiting-wash: rgba(142, 223, 245, 0.10);
+ --status-succeeded-wash: rgba(107, 211, 154, 0.10);
+ --status-failed-wash: rgba(239, 138, 138, 0.10);
+ --status-canceled-wash: rgba(136, 147, 145, 0.06);
+ --status-interrupted-wash: rgba(230, 194, 104, 0.10);
+ --status-blocked-wash: rgba(240, 163, 94, 0.10);
+ --status-skipped-wash: rgba(168, 184, 200, 0.10);
+ --status-unknown-wash: rgba(190, 201, 197, 0.10);
+
+ /* ---- Interaction tints ------------------------------------------------- */
+ /* A tint is a transparent wash laid over whatever surface is already there;
+ it never replaces a surface role. */
+ --tint-hover: rgba(222, 228, 225, 0.05);
+ --tint-pressed: rgba(222, 228, 225, 0.09);
+ --tint-selected: rgba(127, 209, 187, 0.12);
+ --tint-selected-strong: rgba(127, 209, 187, 0.20);
+ --tint-accent-soft: rgba(127, 209, 187, 0.10);
+ --tint-ok-soft: rgba(107, 211, 154, 0.10);
+ --tint-warn-soft: rgba(230, 194, 104, 0.10);
+ --tint-bad-soft: rgba(239, 138, 138, 0.10);
+ --tint-info-soft: rgba(142, 223, 245, 0.10);
+
+ /* ---- Spacing: 8px grid with 4px half-steps ----------------------------- */
+ /* 3xs is the only 2px step, reserved for optical alignment (a glyph against
+ a label), never for layout. */
+ --space-3xs: 2px;
+ --space-2xs: 4px;
+ --space-xs: 8px;
+ --space-s: 12px;
+ --space-m: 16px;
+ --space-l: 24px;
+ --space-xl: 32px;
+ --space-2xl: 40px;
+ --space-3xl: 48px;
+ --space-4xl: 64px;
+
+ /* Role aliases: use these in components, not the t-shirt scale. */
+ --space-inline-tight: var(--space-2xs); /* glyph + label */
+ --space-inline: var(--space-xs); /* buttons in a toolbar */
+ --space-inline-loose: var(--space-s); /* chips in a row */
+ --space-stack-tight: var(--space-2xs); /* title + meta */
+ --space-stack: var(--space-xs); /* lines inside a block */
+ --space-block: var(--space-m); /* block to block */
+ --space-section: var(--space-l); /* section to section */
+ --space-page: var(--space-xl); /* page / pane padding */
+ --space-field-gap: var(--space-xs); /* label to field */
+ --space-control-pad-inline: var(--space-s);
+ --space-control-pad-block: var(--space-2xs);
+ --space-row-pad-inline: var(--space-s);
+ --space-panel-pad: var(--space-m);
+ --space-pane-pad: var(--space-m);
+
+ /* ---- Density ----------------------------------------------------------- */
+ /* Density changes padding and control height, never type size, so a compact
+ list stays readable. Set data-density="compact" on a container. */
+ --density-row-pad-block: var(--space-s);
+ --density-row-pad-inline: var(--space-s);
+ --density-row-gap: var(--space-2xs);
+ --density-control-height: 36px;
+ --density-control-height-small: 30px;
+ --density-touch-target: 44px;
+ --density-touch-target-large: 48px;
+
+ /* ---- Radii ------------------------------------------------------------- */
+ --radius-xs: 4px; /* inline code */
+ --radius-s: 6px; /* tiny marker, count badge */
+ --radius-control: 8px; /* button, field, row, menu item */
+ --radius-card: 12px; /* pane, card, tile, transcript group */
+ --radius-sheet: 16px; /* dialog and sheet */
+ --radius-pill: 999px; /* chip, count pill, terminal node */
+
+ /* ---- Type -------------------------------------------------------------- */
+ --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+ --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+
+ /* Sizes: 11 / 12 / 13 / 14 / 16 / 20 / 24. Roles, not numbers, at call sites. */
+ --type-eyebrow: 600 11px/14px var(--font-sans);
+ --type-label: 600 11px/16px var(--font-sans);
+ --type-meta: 400 12px/16px var(--font-sans);
+ --type-body-small: 400 13px/18px var(--font-sans);
+ --type-body: 400 14px/20px var(--font-sans);
+ --type-title-small: 600 16px/22px var(--font-sans);
+ --type-title: 600 20px/26px var(--font-sans);
+ --type-display: 600 24px/30px var(--font-sans);
+ --type-code: 400 12px/18px var(--font-mono);
+ --type-code-small: 400 11px/16px var(--font-mono);
+
+ --weight-regular: 400;
+ --weight-medium: 500;
+ --weight-semibold: 600;
+ --tracking-eyebrow: 0.06em;
+ --tracking-tight: -0.01em;
+
+ /* ---- Elevation --------------------------------------------------------- */
+ /* Elevation is reserved for things that float above the page: a menu, a
+ dialog, a sheet, a toast. A pane or card never casts a shadow. */
+ --elevation-1: 0 1px 2px rgba(0, 0, 0, 0.32);
+ --elevation-2: 0 8px 24px rgba(0, 0, 0, 0.42);
+ --elevation-3: 0 18px 48px rgba(0, 0, 0, 0.52);
+ --elevation-sheet: 0 -16px 48px rgba(0, 0, 0, 0.55);
+ --elevation-menu: var(--elevation-2);
+ --elevation-dialog: var(--elevation-3);
+ --elevation-toast: var(--elevation-2);
+
+ /* ---- Focus ------------------------------------------------------------- */
+ --focus-ring-width: 2px;
+ --focus-ring-offset: 2px;
+ --focus-ring-color: var(--color-focus);
+ --focus-ring: 0 0 0 var(--focus-ring-width) var(--focus-ring-color);
+ --focus-ring-inset: inset 0 0 0 var(--focus-ring-width) var(--focus-ring-color);
+ --focus-halo: 0 0 0 var(--focus-ring-width) var(--color-bg),
+ 0 0 0 calc(var(--focus-ring-width) + var(--focus-ring-offset)) var(--color-focus);
+
+ /* ---- Motion ------------------------------------------------------------ */
+ /* fast hover / press feedback
+ base selection, expansion, focus colour
+ slow dialog and sheet entry
+ spin an indeterminate spinner's one rotation */
+ --motion-instant: 80ms;
+ --motion-fast: 120ms;
+ --motion-base: 180ms;
+ --motion-slow: 240ms;
+ --motion-spin: 800ms;
+ --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+ --ease-out: cubic-bezier(0, 0, 0, 1);
+ --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+
+ /* ---- Layout ------------------------------------------------------------ */
+ --layout-rail: 200px;
+ --layout-list-min: 200px;
+ --layout-list-max: 360px;
+ --layout-dock: 60px;
+ --layout-hairline: 1px;
+ --layout-measure: 72ch;
+ --layout-chat-measure: 560px;
+ --layout-dialog: 440px;
+ --layout-sheet: 560px;
+ --layout-menu: 240px;
+
+ --icon-status: 14px;
+ --icon-small: 16px;
+ --icon-inline: 18px;
+ --icon-list: 20px;
+ --icon-rail: 24px;
+
+ --layer-sticky: 10;
+ --layer-popover: 20;
+ --layer-dialog: 40;
+ --layer-toast: 50;
+
+ /* ---- Transitional aliases --------------------------------------------- */
+ /* The existing stylesheets use these short names. They map onto the roles
+ above so a file can be migrated one rule at a time; new CSS should use the
+ --color-* / --type-* / --space-* roles directly. */
+ --bg: var(--color-bg);
+ --surface: var(--color-surface);
+ --surface-2: var(--color-surface-2);
+ --elevated: var(--color-elevated);
+ --border: var(--color-border);
+ --border-strong: var(--color-border-strong);
+ --text: var(--color-text);
+ --muted: var(--color-muted);
+ --accent: var(--color-accent);
+ --ok: var(--color-ok);
+ --warn: var(--color-warn);
+ --bad: var(--color-bad);
+}
+
+/* Compact density is a scope, not a second theme: same colours, same type,
+ tighter row padding and a shorter control. */
+[data-density="compact"] {
+ --density-row-pad-block: var(--space-xs);
+ --density-row-pad-inline: var(--space-s);
+ --density-row-gap: var(--space-3xs);
+ --density-control-height: 30px;
+ --density-control-height-small: 24px;
+}
diff --git a/web/docs/visual-system.md b/web/docs/visual-system.md
new file mode 100644
index 00000000..310fb373
--- /dev/null
+++ b/web/docs/visual-system.md
@@ -0,0 +1,445 @@
+# Pipelines web client — visual system
+
+Design-only deliverable. It does not change `web/src`, `web/styles.css`,
+`web/index.html`, any area stylesheet or any test. The reference implementation is
+`web/design/tokens/styleguide.html` + `styleguide.css`, built entirely from
+`tokens.css`.
+
+Sources read for this refinement:
+
+- `web/base.css`, `lists.css`, `run-detail.css`, `chat.css`, `graph.css`,
+ `dialogs.css`, `settings.css` — the current palette, chip, radius and shadow
+ vocabulary.
+- `web/design/layout/prototype.html`, `prototype.css`, `web/docs/layout-spec.md`
+ — the target rail + list/detail shell and its 200px rail.
+- `android/.../ui/theme/Color.kt`, `Typography.kt`, `Dimens.kt`, `Theme.kt` —
+ the app's dark identity, type intent and 4dp-derived spacing.
+- `android/.../ui/components/RunStatus.kt` — the app-owned status vocabulary.
+
+The result keeps the app's dark canvas, mint accent and the web's current
+run-status hues. It is a refinement of hierarchy and reuse, not a new brand.
+
+---
+
+## 1. The layer model
+
+One canvas, four surface steps, one scrim. Every component picks a layer from this
+table; no component invents a background.
+
+| Layer | Token | Used by | Never |
+| --- | --- | --- | --- |
+| Canvas | `--color-bg` | Page, list/detail pane body, chat transcript, code body, artifact thumb base | A static card that also has a border and a shadow |
+| Base surface | `--color-surface` | Left rail, top bar, toolbar, card, detail section, composer shell, approval card, empty state | A row inside another card; use a tint instead |
+| Inset surface | `--color-surface-2` | Button/field fill, row fill when needed, chip body, inline code, code header, user bubble, sheet row, artifact tile | A card on top of a card; never `surface-2` on `surface-2` |
+| Elevated | `--color-elevated` | Menu, popover, dialog, sheet, toast, tool panel | A normal page card |
+| Highest | `--color-elevated-2` | Hover on an elevated control, gradient stop | A page background |
+| Scrim | `--color-scrim` | Behind a dialog, sheet or full-screen viewer | A content background |
+
+Rules:
+
+1. **One step per nesting level.** Pane (`bg`) → card (`surface`) → control
+ (`surface-2`). Do not put another `surface` card inside a card; use padding,
+ a divider or a tint.
+2. **A tint is not a layer.** Hover, pressed and selected are transparent washes
+ (`--tint-*`) laid over the surface that is already there. They never replace a
+ surface role.
+3. **Elevation means floating.** A shadow is reserved for menus, dialogs, sheets,
+ toasts and the tool panel. A pane or card never casts one.
+4. **The transcript is the page.** The agent turn sits directly on `bg`; only the
+ operator's bubble takes `surface-2`. This removes the current transcript →
+ agent bubble → tool section → code block stack of four fills.
+
+### Which surface for each named layer
+
+| Area | Surface |
+| --- | --- |
+| App shell / page | `bg` |
+| Rail | `surface`, separated from the workspace by a `divider` edge |
+| List pane / detail pane | `bg`; the wide split uses a divider, not a card |
+| Top bar / connection banner | `surface` + bottom divider; banner states use `surface-2`, `tint-warn-soft`, `tint-bad-soft` |
+| List row | transparent on the pane; hover `tint-hover`; selected `tint-selected` + 2px accent inset |
+| Toolbar | `surface`; its controls `surface-2` with a `border` |
+| Card / detail section | `surface`, no border; sections separated by `space-section` |
+| Key/value table | on the card surface; use spacing or a divider, never a per-row box |
+| Code block | `bg` body, `surface-2` header, one outer `border` |
+| Dialog / sheet / menu | `elevated` + `border` + matching elevation + scrim where modal |
+| Chat user bubble | `surface-2` + `border` |
+| Chat agent turn | transparent on `bg`; code block is the only framed part |
+| Composer | `surface` shell + `border`; the textarea itself is transparent |
+| Approval card | `surface` + `border` + 3px warning inset; resources `bg`; risk `tint-warn-soft` |
+| Artifact tile | `surface-2` + `border`; media fills the tile; actions overlay it |
+| Empty state | `surface` + `space-l` padding; a sentence and at most one action |
+
+---
+
+## 2. Border or background?
+
+Use **background** to group, **border** to identify a control, **divider** to
+separate content inside one surface.
+
+| Need | Use | Do not use |
+| --- | --- | --- |
+| A card or section | A `surface` step and spacing | Border + radius + shadow on a static block |
+| A button, input, tile, selected row, dialog | `--color-border` (≥3:1 on all surfaces) | `--color-divider`, which is decorative and below 3:1 |
+| A separator between rows or sections | `--color-divider` (1px) | A border around each row |
+| A selected row | `tint-selected` + 2px inset accent bar + weight | A 1px accent border alone |
+| A focused control | The 2px focus ring with a 2px offset | Recolouring the border and calling it focus |
+| A destructive confirm | `--color-bad` text/edge + `tint-bad-soft` | A red-filled button for a secondary action |
+| A floating panel | `elevated` + `border` + one elevation | A border pretending to be a shadow |
+
+Rules:
+
+1. **A border is a control edge, not decoration.** `--color-border` is `#6a7874`
+ so it stays above 3:1 on `bg`, `surface`, `surface-2` and `elevated`. The old
+ `#2c3a36` border is now `--color-divider` and is only for non-interactive
+ separation.
+2. **Never border, fill and shadow the same static box.** Pick the grouping
+ mechanism: a surface step, a divider, or a floating elevation.
+3. **No border-only selection.** The selected row also changes weight and adds the
+ accent bar; the `aria-current`/`aria-selected` state carries the semantics.
+4. **No accent border on hover.** Hover is a 5% wash. Accent is reserved for
+ active, focus and the primary action. Today every `button:hover` turns its
+ border mint, which makes ordinary hover look selected.
+5. **One border around a group.** A code card frames once; the header uses a
+ divider, not a second border. A dialog frames once; its rows use a surface or
+ spacing.
+
+---
+
+## 3. Chips and badges
+
+There is one chip component.
+
+```
+.chip
+ glyph (aria-hidden, optional) + the status word
+ height 22px · padding 1px 8px · radius pill · type-label 11/16 600
+ neutral border (3:1) · status wash background · status-colour text
+```
+
+Status mapping (the web's current status palette, unchanged):
+
+The values below are copied byte-for-byte from the current `base.css` status
+rules. They are the web's tuned rendering of the app's status vocabulary; this
+item does not re-tune a single hue.
+
+| Word | Token | Wash | Glyph |
+| --- | --- | --- | --- |
+| `queued` | `--status-queued` | `--status-queued-wash` | `◷` |
+| `running` | `--status-running` | `--status-running-wash` | `▶` |
+| `waiting` | `--status-waiting` | `--status-waiting-wash` | `…` |
+| `succeeded` | `--status-succeeded` | `--status-succeeded-wash` | `✓` |
+| `failed` | `--status-failed` | `--status-failed-wash` | `✕` |
+| `canceled` | `--status-canceled` | `--status-canceled-wash` | `⊘` |
+| `interrupted` | `--status-interrupted` | `--status-interrupted-wash` | `‖` |
+| `blocked` | `--status-blocked` | `--status-blocked-wash` | `■` |
+| `skipped` | `--status-skipped` | `--status-skipped-wash` | `»` |
+| `active` | `--status-active` | `--status-active-wash` | `◆` |
+| `unknown` | `--status-unknown` | `--status-unknown-wash` | `?` |
+
+Rules:
+
+1. **Never colour alone.** Every status chip carries its glyph and its word. The
+ glyph may be `aria-hidden` because the word is present.
+2. **Use the server's vocabulary verbatim.** Status words stay lowercase; the
+ uppercase role is the eyebrow/overline, never a status label.
+3. **One chip, tone modifiers only.** `chip--succeeded`, `chip--failed`, etc.
+ change colour and wash; they do not change height, radius or type. Delete the
+ parallel `.outcome-chip`, `.version-chip`, `.graph-type-chip` and
+ `.verdict-ref` shapes.
+4. **A chip is a fact, not an action.** A chip is never a button and never nested
+ inside another chip. If it opens something, use a row or a link.
+5. **Neutral is a tone for a non-status fact.** A version (`v5`) or a file kind
+ (`PDF`) can use `chip--neutral`; it must not borrow `--status-unknown` and must
+ not be used for a run state.
+6. **Counts are a count chip, not a status chip.** `chip--count` is a neutral
+ pill with a minimum width, used for `12` or `Filter (2)`.
+7. **Badges are attached, not inline.** The attention count is a small filled
+ bubble (`--color-bad` + `--color-on-bad`) with a number; the live badge is a
+ dot plus the word `live`. Neither replaces a status chip.
+8. **One fact, one chip.** Do not show `failed` twice in a row (chip plus a
+ coloured diagnostic line); the chip carries the state, the diagnostic carries
+ the reason.
+
+---
+
+## 4. Spacing inside vs between
+
+The layout scale is 8px with 4px half-steps. A separate 2px optical step exists
+only for aligning a glyph against a label; it is never a layout gap.
+
+| Inside | Value |
+| --- | --- |
+| Icon/label gap | 4px |
+| Control padding (block × inline) | 4 × 12px |
+| Row padding, light (comfortable) | 12 × 12px |
+| Row padding, compact | 8 × 12px |
+| Card / panel padding | 16px |
+| Dialog padding | 16px |
+| Sheet padding | 12px vertical, 16px horizontal |
+| Code body padding | 12px |
+| Chip / count padding | 1 × 8px |
+
+| Between | Value |
+| --- | --- |
+| Chips or toolbar controls | 8px |
+| Title and meta | 2–4px |
+| Lines in a block | 8px |
+| Block to block (card sections) | 16px |
+| Section to section | 24px |
+| Page / pane edge | 32px (24px narrow) |
+
+Rules:
+
+1. **One owner per gap.** Use `gap` on the container; do not add a margin to the
+ last child and a gap on the parent.
+2. **Padding inside is smaller than space between.** If a card's padding equals
+ the gap to the next card, the grouping reads as one block.
+3. **No nested padding beyond 24px.** Card 16 + panel 16 + row 12 is 44px of
+ inset for a 14px label. Remove a layer or reduce to 16 + 8.
+4. **List separation is either a gap or a divider, never both.** The refined
+ lists use a 2px gap and no row border; day headers use a divider.
+5. **Density changes geometry only.** Compact changes row block padding 12 → 8
+ and control height 36 → 30. Type, line height and touch targets do not shrink.
+ Touch surfaces (rail, dock, primary row actions) stay 44/48px.
+
+---
+
+## 5. Type roles
+
+| Role | Size / line | Weight | Use |
+| --- | --- | --- | --- |
+| `--type-eyebrow` | 11 / 14 | 600 | Overline (`WORKSPACE`, `SECTIONS`, `RISK REVIEW`); tracking 0.06em, uppercase |
+| `--type-label` | 11 / 16 | 600 | Chip and badge labels |
+| `--type-meta` | 12 / 16 | 400 | Meta lines, key labels, captions, helper text |
+| `--type-body-small` | 13 / 18 | 400 | Dialog copy, empty-state copy, dense prose |
+| `--type-body` | 14 / 20 | 400 | Default body, row titles (add 600), toolbar labels |
+| `--type-title-small` | 16 / 22 | 600 | Card title, dialog/sheet title, approval headline |
+| `--type-title` | 20 / 26 | 600 | Screen title (`Pipelines`, `Runs`) |
+| `--type-display` | 24 / 30 | 600 | The app's largest title; rare |
+| `--type-code` | 12 / 18 | 400 mono | Commands, diffs, code blocks |
+| `--type-code-small` | 11 / 16 | 400 mono | Inline code, hashes, timestamps in tables |
+
+Rules:
+
+1. **Roles, not sizes.** No `font-size` literal in an area stylesheet. The current
+ CSS has ten distinct sizes (10, 11, 12, 12.5, 13, 14, 15, 16, 18, 20) plus a
+ 40px viewer glyph; collapse to the seven sizes above.
+2. **Three weights.** 400, 500, 600. Do not introduce 650/700; the app is
+ semibold-led, not bold-led.
+3. **Sentence case for actions and titles.** Uppercase is only the eyebrow /
+ overline role. Status words stay lowercase.
+4. **Tabular numbers** for timestamps, durations, counts and IDs:
+ `font-variant-numeric: tabular-nums`.
+5. **Mono is for data, not emphasis.** Hashes, paths, commands, code and IDs in a
+ table. A pipeline name or a status word is never mono.
+6. **Measure.** Prose is capped at `--layout-measure` (72ch); a chat bubble at
+ `--layout-chat-measure` (560px).
+
+---
+
+## 6. State, focus and motion
+
+### Focus
+
+- One ring: `outline: 2px solid var(--color-focus)` with `outline-offset: 2px`.
+ `--color-focus` is `#a9f0dd`, 13.2:1 on `surface` and 11:1 on `elevated`.
+- Use `:focus-visible`; do not show the ring on a mouse click.
+- A filled accent button uses the halo (`--focus-halo`) so the ring sits on the
+ page, not on the mint fill.
+- A composite field (search wrapper, composer shell) uses `:focus-within` and
+ removes the inner input outline.
+- Never `outline: none` without a replacement. Today `.decision-feedback:focus`,
+ `.template-create-name:focus` and `.rename-input:focus` only recolour the
+ border; `.timeline-row:focus-visible` explicitly removes the outline.
+- An invalid field keeps the focus ring and uses the bad colour for the message
+ and border, not for the ring.
+
+### Interaction states
+
+| State | Treatment | Structural cue |
+| --- | --- | --- |
+| Hover | `--tint-hover` (5%) | none needed |
+| Pressed | `--tint-pressed` (9%) | none needed |
+| Selected | `--tint-selected` (12%) | 2px inset accent bar + 600 weight |
+| Active / current | `--tint-selected` + accent bar | `aria-current` / `aria-selected` |
+| Disabled | `--opacity-disabled` (0.5) | `disabled` / `aria-disabled` |
+
+Selection is never colour alone: the bar and the weight are the non-colour cue.
+
+### Motion
+
+- `--motion-fast` 120ms for hover/press, `--motion-base` 180ms for selection and
+ expansion, `--motion-slow` 240ms for dialog/sheet entry, `--motion-spin` 800ms
+ for an indeterminate spinner.
+- Standard easing `cubic-bezier(0.2, 0, 0, 1)`.
+- Under `prefers-reduced-motion: reduce`, transitions and animations collapse to
+ an immediate state, scroll behaviour becomes `auto`, and no selected or focus
+ state is removed. The styleguide implements this globally.
+
+---
+
+## 7. What to remove from today's CSS
+
+### 7.1 Nested boxes
+
+Remove the second and third frame in each chain:
+
+- `base.css` — `.list` / `.detail` (border + radius) wraps `.row` (bottom border)
+ and `.step` (border + radius), and `.artifact-tile` adds another border and
+ radius. A run detail is three borders deep.
+- `run-detail.css` — `.verdict` and `.field-block` frame content inside
+ `.stage-pane-sheet`; `.change-hunk` frames a diff inside `.change-viewer`.
+- `chat.css` — `.chat-transcript` (border) → `.chat-bubble` (border) → optional
+ `.chat-tool-section` (border) → `.chat-tool-section-body` (bg). The approval
+ card is `.chat-approval` (border) → `.chat-approval-resources` (border) →
+ `.chat-approval-risk` (wash). That is three nested boxes for one decision.
+- `dialogs.css` — `.attention-sheet-panel` → `.attention-row` → the inner
+ `.attention-row-open`; `.decision-sheet-panel` → `.decision-option`.
+- `settings.css` — each `.settings-status`, `.settings-warning`,
+ `.settings-notify-state` and `.settings-card` is its own bordered box inside the
+ section.
+
+Replace with: one pane surface, one card surface, spacing, and a divider where a
+boundary is genuinely needed.
+
+### 7.2 Duplicate chip styles
+
+There are at least six parallel chip shapes:
+
+| Selector | File | Problem |
+| --- | --- | --- |
+| `.chip` + `.chip-*` | `base.css` | The canonical shape, 11px pill |
+| `.outcome-chip` + `.outcome-*` | `run-detail.css` | Second pill, `currentColor` border |
+| `.verdict-ref` | `run-detail.css` | Third pill, 11px |
+| `.version-chip` | `lists.css` | Fourth pill, surface fill |
+| `.graph-type-chip` | `graph.css` | Fifth pill, 11px |
+| `.graph-edge-label` | `graph.css` | Sixth pill-shaped label |
+| `.attention-badge` | `dialogs.css` | A badge, correctly distinct; keep but tokenise |
+
+Delete the five chip duplicates. Keep one `.chip`, one `.chip--count`, and the
+attention badge as a badge. The graph edge label is a label, not a status chip:
+style it with `type-code-small` and no status tone.
+
+### 7.3 Inconsistent radii and heights
+
+- Radii in the current files: 0, 2px, 4px, 6px, 8px, 10px, 12px, 14px, 50%,
+ 999px. Collapse to `4 / 6 / 8 / 12 / 16 / pill`; use 50% only for a dot or a
+ circular poster.
+- Control heights: about 22px (artifact action), 30px (approval control), 32px
+ (toolbar/tool), 36px (inputs), 40px (chat send), 44px (rail/strip), 48px (dock).
+ Standardise on **30px compact**, **36px comfortable**, **44/48px touch**.
+- `.chat-send` and `.chat-stop` are 16px glyph buttons with 8px 12px padding while
+ `.chat-composer-input` is 20px line-height; they do not align. Put both on the
+ same 36px row.
+- `.artifact-action` at 22px is below the 24px minimum for a secondary target;
+ use 30px or move the actions into a menu.
+
+### 7.4 Raw colour, alpha and shadow duplication
+
+- Status hexes are repeated in `base.css` (`.chip-*`), `lists.css`
+ (`.metric-*`), `run-detail.css` (`.outcome-*`), `dialogs.css`
+ (`.decision-card`, `.decision-open`) and `graph.css` (`.chip-unknown`). One
+ `--status-*` token per state.
+- Banner and decision hexes `#2c1616`, `#12251b`, `#2a2410`, `#102329` are
+ one-off colours. Use `tint-bad-soft`, `tint-ok-soft`, `tint-warn-soft` and
+ `tint-info-soft`.
+- Floating shadows have six recipes (`0 10px 30px`, `0 12px 32px`,
+ `0 16px 40px`, `0 20px 60px`, `0 -12px 40px`, `-12px 0 40px`). Use
+ `--elevation-2` / `--elevation-3` / `--elevation-sheet`.
+- Inline `rgba(...)` tints (`rgba(127, 209, 187, 0.12)`, `rgba(0, 0, 0, 0.45)`)
+ become `--tint-*` and `--color-scrim`.
+
+### 7.5 Focus and hover
+
+- Add a base `:focus-visible` rule; today `base.css` has none, so buttons and
+ inputs rely on the browser default.
+- Remove `outline: none` from `.timeline-row:focus-visible`,
+ `.decision-feedback:focus`, `.template-create-name:focus` and
+ `.rename-input:focus`.
+- Stop using `border-color: var(--accent)` as the only hover signal on every
+ button, card, tile and menu item. Hover = tint; accent = active/focus/primary.
+- Unify the four focus offsets (`1px`, `-2px`, `-1px`, `2px`) to the token.
+
+### 7.6 Disabled and opacity
+
+The files use `opacity: 0.4`, `0.45`, `0.5`, `0.55`, `0.6` and `0.8` for
+disabled, unavailable and closed states. Use `--opacity-disabled: 0.5` for a
+disabled control; do not fade a whole card to hide it.
+
+---
+
+## 8. The six biggest before/after improvements
+
+| # | Before | After |
+| --- | --- | --- |
+| 1 | **Boxes inside boxes.** A run row is a bordered `.row` inside a bordered `.list`; a chat decision is three nested fills/borders; a settings section has a card per block. | One pane surface, one card, spacing and dividers. A row is a control on the pane; only a floating surface has elevation. |
+| 2 | **Six chip dialects.** `.chip`, `.outcome-chip`, `.verdict-ref`, `.version-chip`, `.graph-type-chip`, `.graph-edge-label` each set their own height, radius and type. | One `.chip` with tone modifiers, a count chip and one attention badge. Every status carries a glyph and its word. |
+| 3 | **Every control invents a height.** 22–48px buttons, fields, tiles and composer actions do not line up across a toolbar. | 30px compact / 36px comfortable / 44–48px touch, one control radius, one icon size. Toolbars and the composer align on one baseline. |
+| 4 | **Accent borders on hover.** Every button, tile and card turns mint on hover, making hover look focused and selection look ordinary. | Hover is a 5% wash. Accent is reserved for active, focus and the primary action; selection adds a 2px bar and weight. |
+| 5 | **Ten ad-hoc type sizes.** 10, 11, 12, 12.5, 13, 14, 15, 16, 18, 20px with three near-identical section headers. | Seven sizes across eight roles plus two mono roles: 11 / 12 / 13 / 14 / 16 / 20 / 24 with fixed line heights and 400/500/600 weights. |
+| 6 | **Focus is a border colour, when it exists at all.** Some inputs remove the outline; a focused timeline row is indistinguishable from hover; `base.css` has no focus rule. | One 2px `#a9f0dd` ring with a 2px offset on every focusable control, `:focus-within` on composite fields, and a halo on filled accent buttons. |
+
+These six are ordered for migration: each one is independently shippable and each
+removes more CSS than it adds once the old selectors are deleted.
+
+---
+
+## 9. Adopt it without a redesign
+
+1. **Add `tokens.css` first.** It is custom properties only; linking it changes
+ nothing until a rule consumes a token. The `--bg`, `--surface`, `--border`
+ aliases at the bottom of the file let the existing stylesheets keep working
+ while they migrate one rule at a time.
+2. **Collapse one area at a time.** Start with `lists.css` (rows, toolbar,
+ filter menu) because it owns the clearest box-in-box chain. Then
+ `run-detail.css`, then `chat.css`, then `settings.css`.
+3. **Delete duplicate chips in the same change that introduces the unified one.**
+ Do not leave both `.chip` and `.outcome-chip` shipping.
+4. **Move focus to the base layer.** Add the focus rule and remove the
+ `outline: none` exceptions before touching colour, so keyboard users never
+ regress.
+5. **Keep the app's words and status colours.** This system changes surfaces,
+ spacing and shape; it does not rename a run state or invent a new outcome hue.
+
+---
+
+## 10. Captures and verification
+
+Capture command (no server, no build step):
+
+```sh
+node web/design/tokens/capture.mjs
+```
+
+Captured at **1440 × 900** through the repository's read-only
+`web/test/browser.mjs` driver at device scale 1:
+
+- `web/design/tokens/captures/styleguide-01-foundations-1440x900.png`
+- `web/design/tokens/captures/styleguide-02-type-1440x900.png`
+- `web/design/tokens/captures/styleguide-03-space-1440x900.png`
+- `web/design/tokens/captures/styleguide-04-rail-1440x900.png`
+- `web/design/tokens/captures/styleguide-05-lists-1440x900.png`
+- `web/design/tokens/captures/styleguide-06-data-1440x900.png`
+- `web/design/tokens/captures/styleguide-07-overlays-1440x900.png`
+- `web/design/tokens/captures/styleguide-08-conversation-1440x900.png`
+- `web/design/tokens/captures/styleguide-09-content-1440x900.png`
+
+The captures are review evidence and are covered by the repository's root
+`captures/` ignore rule, like the layout captures.
+
+Contrast was checked against the defined surfaces:
+
+| Pair | Ratio |
+| --- | --- |
+| `--color-text` / `--color-bg` | 14.35:1 |
+| `--color-text` / `--color-surface` | 13.29:1 |
+| `--color-muted` / `--color-surface` | 8.47:1 |
+| `--color-border` / `--color-surface` | 3.71:1 |
+| `--color-border` / `--color-elevated` | 3.09:1 |
+| `--color-focus` / `--color-surface` | 13.21:1 |
+| lowest status text / its chip wash (canceled) | 4.75:1 |
+
+No production app stylesheet, view, markup or test was changed. The production
+page still renders from the current area stylesheets; this is the target system
+and its evidence, not a live restyle.