Files
pipelines/web/docs/visual-system.md
T
alan f3c00f9ce5 web: visual system tokens, styleguide and application notes
Role-named tokens (colour, 8px spacing, radii, type scale, elevation, focus,
state tints, motion) with a styleguide built from the app's real components and a
short application guide, including what to remove from the current CSS.
2026-10-19 17:25:01 +01:00

22 KiB
Raw Blame History

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

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.