Color
Color splits across three concerns: the surface stack (where things sit), the ink pair (what users read), and a six-color semantic palette (what's happening). No primary/secondary distinction — semantics come first, and the palette stays at six forever.
Surfaces
Three surface tokens — --bg, --panel-bg, --rail-bg — relate differently in light
vs. dark. Light separates --bg from --panel-bg (subtle cream-on-cream lift) and
shares --rail-bg with --panel-bg. Dark collapses --panel-bg onto --bg; panels
lift via 1px --faint + shadow alone, and --rail-bg drops below --bg so the rail
recedes into a deeper plane.
--uikit-segment-thumb and --uikit-segment-track are the two surfaces of a
segmented control (Tabs segment, ToggleButtons primary/secondary). Both themes
use one recipe: the thumb is the page (--bg), and the track is a recess
below the page. In light the controls' own tint (Tabs ink-5, ToggleButtons chip)
already is that recess, so --uikit-segment-track is left unset there. In dark,
ink-5 sits above the page, so the track becomes
color-mix(in srgb, #000 32%, var(--bg)) — and the thumb stays --bg instead of
being lifted to a grey. Dark text contrast: selected --ink on the thumb 11.4:1,
unselected --uikit-muted on the track 5.8:1.
Lines that cross rows
--faint is translucent, which is what you want for a hairline that should sit
on the panel it crosses. It is the wrong behaviour when the thing underneath
changes. A connector line in a tree crosses rows that hover and select, so a
translucent line is drawn in a different shade on each of them — it ends up
reporting the row's state instead of the structure it exists to describe.
--tree-guide is that line held still: #eae9e6 light, #3f3f45 dark, which
is --faint composited on --bg to within 2/255 in both themes.
Being opaque costs it something, and the number is worth knowing: against the row surfaces it crosses the line bottoms out at 1.03:1 in light and 1.10:1 in dark. It is legible on the page and faint on a filled row. The tree's surfaces sit inside 19 levels of each other in light mode, so a neutral hairline cannot clear all of them — separating them needs either a tone on the line or more room between the row fills.
--color-uikit-ink-5-solid is the same idea for a fill: identical 5% ink, mixed
over --bg instead of over transparent, so a chip reads the same on every
surface. Keep the translucent originals for washes that should tint what they
sit on.
Row states are luminance, not hue
--tree-hover used to be a warm amber against a neutral --tree-sel, so hover
and selection were told apart by hue — they were never more than 1.05:1
apart in luminance. It is now a grey, which puts both cues on the same axis and
leaves 19 levels in light mode to fit page, hover and selection into:
#fffefa → #f6f5f1 → #ececec, nine and ten levels apart.
That is enough to read and not much more. If the two ever need to be told apart at a glance rather than side by side, the room has to come from somewhere — a darker selection fill, or the accent ring a multi-row run already carries.
Ink
Two text colors carry every glyph on the page: --ink for primary content, --muted
for secondary. There is no third gray, and no paler text: both meet WCAG AA (4.5:1) on
the page background, and opacity on top of them drops text below it (--muted at 0.6
is under 3:1). Rank secondary text by size, weight and case instead. Only a purely
decorative glyph (a /, · or @ separator, aria-hidden) may be faded. Both flip
in dark mode against the inverted surface stack.
| Token | Light | Dark | Used on |
|---|---|---|---|
--ink | #1a1a1a | #ececec | Body copy, titles, ledger rows, kbd glyphs |
--muted | #6b6b6b | #999999 | Eyebrows, meta cells, placeholder text, neutral status |
Contrast on --bg: --ink 17.2 / 11.4, --muted 5.28 / 4.73 (light / dark).
Dark --muted was #8a8a8a until 2026-10, which measured 3.9:1.
Drag affordances
--uikit-handle and --uikit-handle-active colour the grab pills: the
PanelLayout divider and the dock handles in panel headers. The pill shows on
hover in --uikit-handle, painted as-is with no extra opacity, and switches to
--uikit-handle-active while held. Both tones stay in the grey band, well away
from ink.
| Token | Light | Dark | On --bg (light / dark) |
|---|---|---|---|
--uikit-handle | #c8c8c8 | #5c5c5c | 1.66 / 2.02, a hint, not a control |
--uikit-handle-active | #8a8a8a | #9a9a9a | 3.42 / 4.79, meets the 3:1 UI-component floor while dragged |
--uikit-grip-fill | rgba(255,255,255,.65) | rgba(78,78,86,.86) | resize-pill surface; read through its ring + shadow, not fill contrast |
--uikit-grip-ring / -hover | rgba(0,0,0,.08) / .12 | rgba(255,255,255,.12) / .22 | the pill's hairline edge; held = accent at 60% |
Until 2026-10 these were #8a8a8a / #4a4a4a light and #e2e2e2 / #ffffff
dark. A grabbed divider was near-black in light (8.8:1), glaring white in dark
(13.5:1), and heavier than the seam it sits on.
Semantic palette
All domain coloring — pipeline kinds, run statuses, transform types, event types,
branch identities, release kinds, diff ops — pulls from one shared 6-color set. Every
other page maps its concepts onto these six. dreamlake-pipelines is the canonical
source.
Tones as text
The six hexes are for marks — dots, fills, edges, chart series — and they do
not change with the theme. Set as small words they mostly fail WCAG AA: blue
reads 2.5:1 on the light page, purple 2.8:1 on the dark one. So each tone has a
text twin, --tone-<name>-text, per theme: the same hue, deeper in light and
lighter in dark, each the nearest step that reaches 4.5:1 on --bg and
--panel-bg. Tones that already pass keep their palette hex (purple in light,
blue and amber in dark).
| Tone | Light text | Dark text |
|---|---|---|
blue | #0077c2 · 4.59:1 | #23aaff · 5.30:1 |
green | #1d8444 · 4.57:1 | #25ac59 · 4.57:1 |
amber | #906e23 · 4.57:1 | #c0922e · 4.74:1 |
red | #c34d37 · 4.57:1 | #d77f6f · 4.59:1 |
purple | #7c5bd9 · 4.66:1 | #a088e3 · 4.57:1 |
warmGray | #7d725d · 4.57:1 | #a09580 · 4.56:1 |
Anything that colours words with a tone reads the -text twin (Tag does);
anything that colours a mark keeps --tone-*. Several dark values clear the
line by only a few hundredths — if the palette moves, re-measure these.
When adding a new concept
- Open
pipelines-canvas.jsx.PIPE_KIND_COLOR,PIPE_STATUS, andPIPE_FLOW_LABELare the canonical mappings. The legend (PipeLegend) is what users learn the palette from. - Map by function, not vibe. "Ingest" is a successful inflow → green
(
#1f8f4a), not blue. "RC release" is an active candidate → blue (#23aaff), not amber. "Draft release" is pre-success → green. The semantic bucket trumps any aesthetic preference. - Never invent a near-miss hex.
#3a7bd5,#c08a2a,#5a8fbfwere all bugs in earlier timetravel work — they tried to be "a slightly different blue/amber" and just looked broken next to pipelines. Distinguish two same-bucket concepts via glyph + label, not a third color. tokens.cssis for surface chrome, not domain coloring.--accenthappens to equal#23aaffbecause the active/running color is also the UI accent. Don't add--ok/--errortotokens.css; keep the six hex values inline at use sites sogreptells the truth.
Why six and not more
- Six is the ceiling for a legend. The pipelines flow legend is already 5 rows tall
(
running/queued/stalled/error/ok); a 7th hue pushes it past the threshold where users can hold the mapping in working memory. - Each hue does double duty. Every color carries a status meaning and a kind meaning and a domain-concept meaning. That collision is the point — if "ingest" and "ok" both mean data flowed in successfully, they should look the same.
- Outliers get caught at review. A
grep '#[0-9a-f]\{6\}'across*.jsxshould return only these six values plus surface tokens. Anything else is either a typo, a leftover from prototyping, or a missed alignment.
Chart axes
Use --uikit-axis (or text-uikit-axis) for numeric axes and tick labels: #525252 in light mode and #cccccc in dark mode. Render at full opacity; reserve faint ink for background gridlines.
Document tabs and workspace
--uikit-workspace-bg is the continuous background behind tabs and panel gutters.
Its light default is #f1eee7; its dark default is #222226. Explicit theme
selection and the system dark-mode fallback both update it. Applications can
map it to their live shell token instead of maintaining a separate theme value.
The selected tab has curved feet and shares its body's surface. Inactive tabs
sit on the workspace background with separators; hover paints a rounded
rectangle. Override these variables on the containing workspace to configure
both TabRow and PanelLayout tab groups:
| Variable | Default |
|---|---|
--uikit-document-strip-surface | var(--uikit-workspace-bg) |
--uikit-document-surface | var(--bg); match the retained panel body |
--uikit-document-inactive-bg | Strip surface |
--uikit-document-hover-bg | 4% ink mixed into the strip surface |
--uikit-document-action-bg | 3% ink mixed into the strip surface |
--uikit-document-action-hover-bg | 8% ink mixed into the strip surface |
For example, a shell can set --uikit-document-strip-surface: var(--dl-shell-bg)
and --uikit-document-surface: var(--bg). Contextual add/return controls opt into
the shared action shade through uikit-document-tab-action; they have no shadow.
These variables paint tab chrome only. The host still owns its body and terminal
canvas colors, close guards, contextual actions, and view state.
Code surfaces
CodeBlock keeps its bg-uikit-code shell in both reading and editing modes.
The Monaco content and gutter backgrounds are transparent, so switching modes
or loading the editor preserves that surface. Syntax token colors follow
Monaco's light or dark theme; they do not replace the surrounding surface tokens.