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.
22 KiB
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:
- One step per nesting level. Pane (
bg) → card (surface) → control (surface-2). Do not put anothersurfacecard inside a card; use padding, a divider or a tint. - 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. - Elevation means floating. A shadow is reserved for menus, dialogs, sheets, toasts and the tool panel. A pane or card never casts one.
- The transcript is the page. The agent turn sits directly on
bg; only the operator's bubble takessurface-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:
- A border is a control edge, not decoration.
--color-borderis#6a7874so it stays above 3:1 onbg,surface,surface-2andelevated. The old#2c3a36border is now--color-dividerand is only for non-interactive separation. - Never border, fill and shadow the same static box. Pick the grouping mechanism: a surface step, a divider, or a floating elevation.
- No border-only selection. The selected row also changes weight and adds the
accent bar; the
aria-current/aria-selectedstate carries the semantics. - No accent border on hover. Hover is a 5% wash. Accent is reserved for
active, focus and the primary action. Today every
button:hoverturns its border mint, which makes ordinary hover look selected. - 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:
- Never colour alone. Every status chip carries its glyph and its word. The
glyph may be
aria-hiddenbecause the word is present. - Use the server's vocabulary verbatim. Status words stay lowercase; the uppercase role is the eyebrow/overline, never a status label.
- 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-chipand.verdict-refshapes. - 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.
- Neutral is a tone for a non-status fact. A version (
v5) or a file kind (PDF) can usechip--neutral; it must not borrow--status-unknownand must not be used for a run state. - Counts are a count chip, not a status chip.
chip--countis a neutral pill with a minimum width, used for12orFilter (2). - 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 wordlive. Neither replaces a status chip. - One fact, one chip. Do not show
failedtwice 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:
- One owner per gap. Use
gapon the container; do not add a margin to the last child and a gap on the parent. - 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.
- 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.
- 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.
- 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:
- Roles, not sizes. No
font-sizeliteral 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. - Three weights. 400, 500, 600. Do not introduce 650/700; the app is semibold-led, not bold-led.
- Sentence case for actions and titles. Uppercase is only the eyebrow / overline role. Status words stay lowercase.
- Tabular numbers for timestamps, durations, counts and IDs:
font-variant-numeric: tabular-nums. - 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.
- 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)withoutline-offset: 2px.--color-focusis#a9f0dd, 13.2:1 onsurfaceand 11:1 onelevated. - 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-withinand removes the inner input outline. - Never
outline: nonewithout a replacement. Today.decision-feedback:focus,.template-create-name:focusand.rename-input:focusonly recolour the border;.timeline-row:focus-visibleexplicitly 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-fast120ms for hover/press,--motion-base180ms for selection and expansion,--motion-slow240ms for dialog/sheet entry,--motion-spin800ms 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 becomesauto, 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-tileadds another border and radius. A run detail is three borders deep.run-detail.css—.verdictand.field-blockframe content inside.stage-pane-sheet;.change-hunkframes 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-stateand.settings-cardis 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-sendand.chat-stopare 16px glyph buttons with 8px 12px padding while.chat-composer-inputis 20px line-height; they do not align. Put both on the same 36px row..artifact-actionat 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) andgraph.css(.chip-unknown). One--status-*token per state. - Banner and decision hexes
#2c1616,#12251b,#2a2410,#102329are one-off colours. Usetint-bad-soft,tint-ok-soft,tint-warn-softandtint-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-visiblerule; todaybase.csshas none, so buttons and inputs rely on the browser default. - Remove
outline: nonefrom.timeline-row:focus-visible,.decision-feedback:focus,.template-create-name:focusand.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
- Add
tokens.cssfirst. It is custom properties only; linking it changes nothing until a rule consumes a token. The--bg,--surface,--borderaliases at the bottom of the file let the existing stylesheets keep working while they migrate one rule at a time. - Collapse one area at a time. Start with
lists.css(rows, toolbar, filter menu) because it owns the clearest box-in-box chain. Thenrun-detail.css, thenchat.css, thensettings.css. - Delete duplicate chips in the same change that introduces the unified one.
Do not leave both
.chipand.outcome-chipshipping. - Move focus to the base layer. Add the focus rule and remove the
outline: noneexceptions before touching colour, so keyboard users never regress. - 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.pngweb/design/tokens/captures/styleguide-02-type-1440x900.pngweb/design/tokens/captures/styleguide-03-space-1440x900.pngweb/design/tokens/captures/styleguide-04-rail-1440x900.pngweb/design/tokens/captures/styleguide-05-lists-1440x900.pngweb/design/tokens/captures/styleguide-06-data-1440x900.pngweb/design/tokens/captures/styleguide-07-overlays-1440x900.pngweb/design/tokens/captures/styleguide-08-conversation-1440x900.pngweb/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.