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

446 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.