# 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

1. **Open `pipelines-canvas.jsx`.** `PIPE_KIND_COLOR`, `PIPE_STATUS`, and
   `PIPE_FLOW_LABEL` are the canonical mappings. The legend (`PipeLegend`) is what users
   learn the palette from.
2. **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.
3. **Never invent a near-miss hex.** `#3a7bd5`, `#c08a2a`, `#5a8fbf` were 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.
4. **`tokens.css` is for surface chrome, not domain coloring.** `--accent` happens to
   equal `#23aaff` because the active/running color is also the UI accent. Don't add
   `--ok` / `--error` to `tokens.css`; keep the six hex values inline at use sites so
   `grep` tells 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 `*.jsx` should
  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.
