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