refactor(frontend): base16 theme contract in a swappable colors.css

Split the palette into two standalone stylesheets: - colors.css — the 16 base16 slots (--base00..--base0F). This is the entire theme swap contract; a generator (e.g. a stylix base16 scheme, which is natively base00-base0F) replaces only this file. - theme.css — the semantic layer (--bg, --purple, …) derived from the base16 slots via var()/color-mix. Never changes on a swap. Every page links colors.css then theme.css; theme.css does NOT @import colors.css (that would re-bake the slots into it) — they're separate dist outputs so a swap touches just colors.css. Pixel-identical refactor: base16 defaults are Catppuccin Mocha and the three off-slot vars (--crust, --muted, --subtext0) derive via color-mix reproducing their exact prior hexes. Wires colors.css through both build.mjs CSS entry lists, the @hive/shared exports map, and all 7 page templates. css-vars.md + the frontend.nix output-list comment updated.
fix(frontend): var-derive hardcoded palette colours for theme-swap safety
2026-06-08 21:24:07 +02:00 · 2026-06-08 21:24:07 +02:00
24 changed files with 316 additions and 191 deletions
--- a/docs/web-ui/css-vars.md
+++ b/docs/web-ui/css-vars.md
@ -1,41 +1,57 @@
 # CSS custom properties (theme variables)

-All colour variables are declared **once** in
-`frontend/packages/shared/src/theme.css` under `:root`.
-Per-page stylesheets (`common.css`, `dashboard.css`, `flow.css`, `logs.css`, `agent.css`) must reference these
-names and must **not** redeclare them. (`base.css` holds only the
-shared `body` typography — it references the palette but no longer
-defines it.)
+Colour variables live in **two standalone stylesheets**, split so a theme
+swap touches only the first:

-`theme.css` is deliberately a **standalone** stylesheet, not `@import`ed
-into the page bundles: each package re-exports it (`src/theme.css` →
-`@import "@hive/shared/theme.css"`) so esbuild emits its own
-`dist/static/theme.css`, and every page links it **first**
-(`<link rel="stylesheet" href=".../theme.css">`) ahead of the page CSS.
-Because the palette lives in its own output file, a theme swap — e.g. a
-stylix-generated variant carrying the same variable names — can replace
-just that one file without rebuilding the rest of the frontend bundle.
+1. **`colors.css`** — the 16 `--base00`…`--base0F` base16 slots. **This is
+   the entire theme swap contract.** A generator (e.g. one fed a stylix
+   base16 scheme, which is natively base00–base0F) replaces *only this
+   file*.
+2. **`theme.css`** — the semantic layer: `--bg`, `--fg`, `--purple`, …
+   *derived* from the base16 slots (`--bg: var(--base00)` etc.). This is
+   what the app references and it **never changes on a swap**.

-## Palette (`theme.css`)
+Both files live in `frontend/packages/shared/src/`. Per-page stylesheets
+(`common.css`, `dashboard.css`, `flow.css`, `logs.css`, `agent.css`)
+reference the **semantic** names and must **not** redeclare them or reach
+for the raw `--baseNN` slots directly. (`base.css` holds only the shared
+`body` typography — it references the palette but no longer defines it.)

-| Variable | Hex | Catppuccin Mocha | Use |
+Both are deliberately standalone, not `@import`ed into the page bundles:
+each package re-exports them (`src/{colors,theme}.css` →
+`@import "@hive/shared/…"`) so esbuild emits its own
+`dist/static/colors.css` + `dist/static/theme.css`, and every page links
+them **first** (`colors.css` then `theme.css`) ahead of the page CSS. Note
+`theme.css` does **not** `@import` `colors.css` — that would bake the
+slots back into it; they're two separate output files so a swap replaces
+just `colors.css`. (Load order doesn't actually affect resolution —
+custom properties resolve at computed-value time — but `colors.css` is
+linked first for clarity.)
+
+## Semantic palette (`theme.css`)
+
+Each semantic var derives from a base16 slot (or, for the three that have
+no clean slot, a `color-mix()` over base16 — pixel-identical under the
+default palette). Default hexes shown are Catppuccin Mocha.
+
+| Variable | Derives from | Default hex | Use |
 |---|---|---|---|
-| `--bg` | `#1e1e2e` | base | page background |
-| `--bg-elev` | `#181825` | mantle | elevated surfaces: floating dropdowns, popovers |
-| `--crust` | `#11111b` | crust | terminal / code block background |
-| `--fg` | `#cdd6f4` | text | primary text colour |
-| `--muted` | `#7f849c` | overlay1 | secondary / dimmed text |
-| `--purple` | `#cba6f7` | mauve | accent — active tabs, links, highlights |
-| `--purple-dim` | `#45475a` | surface1 | subtle borders, terminal chrome, badge backgrounds |
-| `--cyan` | `#89dceb` | sky | tool-use events, info accents |
-| `--blue` | `#89b4fa` | blue | links, interactive accent (distinct from sky) |
-| `--pink` | `#f5c2e7` | pink | thinking events |
-| `--amber` | `#fab387` | peach | warnings, pending / running state |
-| `--yellow` | `#f9e2af` | yellow | flash messages, mild warnings |
-| `--green` | `#a6e3a1` | green | success, ok state |
-| `--red` | `#f38ba8` | red | errors, fail state |
-| `--border` | `#313244` | surface0 | general borders, hover/active backgrounds |
-| `--subtext0` | `#a6adc8` | subtext0 | secondary toolbar/status text; dimmer than `--fg`, lighter than `--muted` |
+| `--bg` | `base00` | `#1e1e2e` | page background |
+| `--bg-elev` | `base01` | `#181825` | elevated surfaces: floating dropdowns, popovers |
+| `--border` | `base02` | `#313244` | general borders, hover/active backgrounds |
+| `--purple-dim` | `base03` | `#45475a` | subtle borders, terminal chrome, badge backgrounds |
+| `--fg` | `base05` | `#cdd6f4` | primary text colour |
+| `--red` | `base08` | `#f38ba8` | errors, fail state |
+| `--amber` | `base09` | `#fab387` | warnings, pending / running state |
+| `--yellow` | `base0A` | `#f9e2af` | flash messages, mild warnings |
+| `--green` | `base0B` | `#a6e3a1` | success, ok state |
+| `--cyan` | `base0C` | `#89dceb` | tool-use events, info accents |
+| `--blue` | `base0D` | `#89b4fa` | links, interactive accent (distinct from cyan) |
+| `--purple` | `base0E` | `#cba6f7` | accent — active tabs, links, highlights |
+| `--pink` | `base0F` | `#f5c2e7` | thinking events |
+| `--crust` | `mix(base00 58%, #000)` | `#11111b` | terminal / code block background (below `--bg`) |
+| `--muted` | `mix(base05 55.5%, base00)` | `#7f849c` | secondary / dimmed text |
+| `--subtext0` | `mix(base05 77.7%, base00)` | `#a6adc8` | toolbar/status text; dimmer than `--fg`, lighter than `--muted` |

 ## Common mistakes

@ -81,3 +97,49 @@ color: var(--red);    /* error */
 color: var(--amber);  /* warning / running */
 color: var(--green);  /* ok */
 ```
+
+## Theme swapping — the base16 contract
+
+**The swap interface is `colors.css` — the 16 base16 slots, not our
+semantic names.** A theme generator (e.g. one reading a stylix base16
+scheme) overrides only `colors.css`; the semantic layer in `theme.css`
+derives everything else, so the whole UI re-themes with nothing else to
+template or regenerate. The base16 slot → semantic mapping is *internal*
+to `theme.css` (the "Derives from" column above) — a generator never
+needs to know our var names, and `theme.css` + the page bundles stay
+untouched.
+
+`colors.css` base16 slot defaults (Catppuccin Mocha):
+
+| Slot | Default | Standard base16 role | Mapped to |
+|---|---|---|---|
+| `base00` | `#1e1e2e` | default bg | `--bg`, (darkened) `--crust` |
+| `base01` | `#181825` | lighter bg | `--bg-elev` |
+| `base02` | `#313244` | selection/surface | `--border` |
+| `base03` | `#45475a` | comments/dim surface | `--purple-dim` |
+| `base04` | `#585b70` | dark foreground | *(unused; kept for completeness)* |
+| `base05` | `#cdd6f4` | default foreground | `--fg`, (blended) `--muted`/`--subtext0` |
+| `base06` | `#f5e0dc` | light foreground | *(unused)* |
+| `base07` | `#b4befe` | lightest | *(unused)* |
+| `base08` | `#f38ba8` | red | `--red` |
+| `base09` | `#fab387` | orange | `--amber` |
+| `base0A` | `#f9e2af` | yellow | `--yellow` |
+| `base0B` | `#a6e3a1` | green | `--green` |
+| `base0C` | `#89dceb` | cyan | `--cyan` (our *sky*; Catppuccin's `base0C` is teal) |
+| `base0D` | `#89b4fa` | blue | `--blue` |
+| `base0E` | `#cba6f7` | magenta | `--purple` |
+| `base0F` | `#f5c2e7` | extra accent | `--pink` |
+
+Notes for theme authors:
+
+- **`--crust`, `--muted`, `--subtext0` have no own slot** — they're
+  derived via `color-mix()` over base16 (`--crust` = a darkened `base00`;
+  `--muted`/`--subtext0` = `base05`↔`base00` blends). They still track a
+  swap automatically; no generator action needed.
+- A standard Catppuccin base16 scheme uses **teal** for `base0C`; we
+  default it to **sky** (`#89dceb`) to preserve the historical accent. A
+  stylix Catppuccin scheme will shift `--cyan` to teal — that's the
+  operator's chosen scheme, working as intended.
+- `base04`/`base06`/`base07` aren't consumed by a semantic var today;
+  they're kept at their standard values so the 16-slot contract is
+  complete (a partial scheme override still works).
--- a/frontend/packages/agent/build.mjs
+++ b/frontend/packages/agent/build.mjs
@ -43,11 +43,12 @@ await build({
  logLevel: 'info',
 });

-// Bundle the CSS. `theme.css` re-exports the standalone Catppuccin
-// palette (kept its own output file so a theme swap replaces only it,
-// no bundle rebuild); `agent.css`'s @import lines pull in shared
-// base.css + terminal.css from the @hive/shared workspace dep.
-for (const entry of ['theme.css', 'agent.css']) {
+// Bundle the CSS. `colors.css` re-exports the standalone base16 palette
+// (the theme swap contract — its own output file so a swap replaces only
+// it, no bundle rebuild); `theme.css` is the semantic derivation layer;
+// `agent.css`'s @import lines pull in shared base.css + terminal.css from
+// the @hive/shared workspace dep.
+for (const entry of ['colors.css', 'theme.css', 'agent.css']) {
  await build({
    entryPoints: [src(entry)],
    outfile: staticDir(entry),
--- a/frontend/packages/agent/src/agent.css
+++ b/frontend/packages/agent/src/agent.css
@ -15,7 +15,7 @@
     on top, state strip below). */
  --agent-header-h: 6em;
  --agent-composer-h: 3.6em;
-  --agent-frost-bg: rgba(30, 30, 46, 0.72);
+  --agent-frost-bg: color-mix(in srgb, var(--bg) 72%, transparent);
  --agent-frost-blur: blur(12px) saturate(140%);
 }

@ -47,7 +47,7 @@ body:not(.agent-shell):not(.screen-shell) {
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
-  filter: drop-shadow(0 0 6px rgba(203, 166, 247, 0.45));
+  filter: drop-shadow(0 0 6px color-mix(in srgb, var(--purple) 45%, transparent));
 }

 body.agent-shell {
@ -59,7 +59,7 @@ body.agent-shell {
     surface some depth and reinforce the vibec0re mood. */
  background:
    radial-gradient(ellipse 80% 60% at 50% 0%,
-                    rgba(203, 166, 247, 0.06) 0%,
+                    color-mix(in srgb, var(--purple) 6%, transparent) 0%,
                    transparent 60%),
    var(--bg);
 }
@ -136,7 +136,7 @@ h2, h3 {
  color: var(--purple);
  text-transform: uppercase;
  letter-spacing: 0.15em;
-  text-shadow: 0 0 8px rgba(203, 166, 247, 0.4);
+  text-shadow: 0 0 8px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 .agent-icon {
  /* Square identity anchor — explicit 5em sizing + align-self.
@ -148,7 +148,7 @@ h2, h3 {
  flex-shrink: 0;
  align-self: flex-start;
  border-radius: 8px;
-  box-shadow: 0 0 18px -2px rgba(203, 166, 247, 0.4);
+  box-shadow: 0 0 18px -2px color-mix(in srgb, var(--purple) 40%, transparent);
  object-fit: cover;
 }

@ -163,13 +163,13 @@ h2, h3 {
  letter-spacing: 0.04em;
  padding: 0.1em 0.35em;
  border-radius: 3px;
-  text-shadow: 0 0 4px rgba(137, 220, 235, 0.4);
+  text-shadow: 0 0 4px color-mix(in srgb, var(--cyan) 40%, transparent);
  transition: color 0.15s ease, text-shadow 0.15s ease, background 0.15s ease;
 }
 .agent-nav-link:hover {
  color: var(--fg);
-  background: rgba(137, 220, 235, 0.08);
-  text-shadow: 0 0 10px rgba(137, 220, 235, 0.85);
+  background: color-mix(in srgb, var(--cyan) 8%, transparent);
+  text-shadow: 0 0 10px color-mix(in srgb, var(--cyan) 85%, transparent);
 }

 /* Overflow menu trigger — `⋯` round button on the right of the
@ -238,7 +238,7 @@ h2, h3 {
  transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
 }
 .overflow-item:hover {
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
  border-color: var(--purple-dim);
 }
 .overflow-item-icon {
@ -251,12 +251,12 @@ h2, h3 {
 .overflow-item-new-session { color: var(--amber); }
 .overflow-item-rebuild:hover,
 .overflow-item-new-session:hover {
-  background: rgba(250, 179, 135, 0.1);
+  background: color-mix(in srgb, var(--amber) 10%, transparent);
  border-color: var(--amber);
 }
 .overflow-item-dashboard { color: var(--cyan); }
 .overflow-item-dashboard:hover {
-  background: rgba(137, 220, 235, 0.1);
+  background: color-mix(in srgb, var(--cyan) 10%, transparent);
  border-color: var(--cyan);
 }
 .overflow-item:disabled {
@ -281,13 +281,13 @@ h2, h3 {
 }
 .overflow-item-model:hover {
  color: var(--fg);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
  border-color: var(--purple-dim);
 }
 .overflow-item-model.active {
  color: var(--purple);
  border-color: var(--purple-dim);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }

 /* Header pill — inbox / loose-ends triggers. Compact, count-prominent. */
@ -324,11 +324,11 @@ h2, h3 {
  font-variant-numeric: tabular-nums;
 }
 .header-pill-inbox .header-pill-count {
-  background: rgba(250, 179, 135, 0.18);
+  background: color-mix(in srgb, var(--amber) 18%, transparent);
  color: var(--amber);
 }
 .header-pill-loose .header-pill-count {
-  background: rgba(243, 139, 168, 0.18);
+  background: color-mix(in srgb, var(--red) 18%, transparent);
  color: var(--red);
 }

@ -387,14 +387,14 @@ h2, h3 {
  padding-top: 0;
 }
 .meta { color: var(--muted); font-size: 0.85em; }
-.status-online { color: var(--green); text-shadow: 0 0 6px rgba(166, 227, 161, 0.55); }
-.status-needs-login { color: var(--amber); text-shadow: 0 0 6px rgba(250, 179, 135, 0.55); }
-code { background: rgba(203, 166, 247, 0.12); padding: 0.05em 0.3em; border-radius: 2px; }
+.status-online { color: var(--green); text-shadow: 0 0 6px color-mix(in srgb, var(--green) 55%, transparent); }
+.status-needs-login { color: var(--amber); text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent); }
+code { background: color-mix(in srgb, var(--purple) 12%, transparent); padding: 0.05em 0.3em; border-radius: 2px; }
 a {
  color: var(--cyan);
-  text-shadow: 0 0 4px rgba(137, 220, 235, 0.5);
+  text-shadow: 0 0 4px color-mix(in srgb, var(--cyan) 50%, transparent);
 }
-a:hover { color: var(--fg); text-shadow: 0 0 12px rgba(137, 220, 235, 0.9); }
+a:hover { color: var(--fg); text-shadow: 0 0 12px color-mix(in srgb, var(--cyan) 90%, transparent); }
 .btn {
  font-family: inherit;
  font-size: 1em;
@ -410,7 +410,7 @@ a:hover { color: var(--fg); text-shadow: 0 0 12px rgba(137, 220, 235, 0.9); }
  transition: box-shadow 0.15s ease, text-shadow 0.15s ease;
 }
 .btn:hover {
-  background: rgba(205, 214, 244, 0.06);
+  background: color-mix(in srgb, var(--fg) 6%, transparent);
  text-shadow: 0 0 10px currentColor;
  box-shadow: 0 0 10px -2px currentColor;
 }
@ -712,9 +712,9 @@ pre.diff {
 }
 .status-badge.status-loading      { color: var(--muted);  border-color: var(--purple-dim); }
 .status-badge.status-online       { color: var(--green);  border-color: var(--green);
-  text-shadow: 0 0 6px rgba(166, 227, 161, 0.55); }
+  text-shadow: 0 0 6px color-mix(in srgb, var(--green) 55%, transparent); }
 .status-badge.status-rate-limited { color: var(--red);    border-color: var(--red);
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.55); }
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 55%, transparent); }
 .status-badge.status-needs-login  { color: var(--amber);  border-color: var(--amber); }
 .status-badge.status-offline      { color: var(--muted);  border-color: var(--muted); }
 /* Orphaned tombstone — `.btn-dashlink` chip that lived beside the
@ -734,7 +734,7 @@ pre.diff {
  transition: box-shadow 0.15s ease, background 0.15s ease;
 }
 .btn-cancel-turn:hover {
-  background: rgba(243, 139, 168, 0.1);
+  background: color-mix(in srgb, var(--red) 10%, transparent);
  box-shadow: 0 0 10px -2px currentColor;
 }
 /* Orphaned tombstone — `.btn-new-session` round-pill moved into
@ -759,16 +759,16 @@ pre.diff {
 }
 .state-badge.state-idle {
  color: var(--cyan); border-color: var(--cyan);
-  text-shadow: 0 0 6px rgba(137, 220, 235, 0.55);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--cyan) 55%, transparent);
 }
 .state-badge.state-thinking {
  color: var(--amber); border-color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.65);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 65%, transparent);
  animation: badge-pulse 1.8s ease-in-out infinite;
 }
 .state-badge.state-compacting {
  color: var(--purple); border-color: var(--purple);
-  text-shadow: 0 0 6px rgba(203, 166, 247, 0.65);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--purple) 65%, transparent);
  animation: badge-pulse 1.8s ease-in-out infinite;
 }
 .state-badge.state-just-changed {
@ -841,7 +841,7 @@ pre.diff {
 }
 .term-input .prompt {
  color: var(--green);
-  text-shadow: 0 0 6px rgba(166, 227, 161, 0.6);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--green) 60%, transparent);
  user-select: none;
  flex: 0 0 auto;
 }
@ -1113,7 +1113,7 @@ body.screen-shell {
  bottom: 0; left: 0; right: 0;
  max-height: 40vh;
  overflow-y: auto;
-  background: rgba(17, 17, 27, 0.95);
+  background: color-mix(in srgb, var(--crust) 95%, transparent);
  border-top: 1px solid var(--purple-dim);
  font-size: 0.72rem;
  font-family: ui-monospace, monospace;
--- a/frontend/packages/agent/src/colors.css
+++ b/frontend/packages/agent/src/colors.css
@ -0,0 +1,6 @@
+/* Standalone base16 palette — re-exports the shared base16 slots so
+   esbuild emits its own `dist/static/colors.css`, linked first by every
+   agent page (before theme.css). This is the theme swap contract: a
+   stylix-generated variant replaces only this file. See
+   @hive/shared/colors.css + docs/web-ui/css-vars.md. */
+@import "@hive/shared/colors.css";
--- a/frontend/packages/agent/src/index.html
+++ b/frontend/packages/agent/src/index.html
@ -5,6 +5,7 @@
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>hyperhive agent</title>
  <link rel="icon" type="image/svg+xml" href="icon">
+  <link rel="stylesheet" href="static/colors.css">
  <link rel="stylesheet" href="static/theme.css">
  <link rel="stylesheet" href="static/agent.css">
 </head>
--- a/frontend/packages/agent/src/screen.html
+++ b/frontend/packages/agent/src/screen.html
@ -5,6 +5,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>screen</title>
 <link rel="icon" type="image/svg+xml" href="icon">
+<link rel="stylesheet" href="static/colors.css">
 <link rel="stylesheet" href="static/theme.css">
 <link rel="stylesheet" href="static/agent.css">
 </head>
--- a/frontend/packages/agent/src/stats.html
+++ b/frontend/packages/agent/src/stats.html
@ -5,6 +5,7 @@
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>hyperhive agent — stats</title>
  <link rel="icon" type="image/svg+xml" href="icon">
+  <link rel="stylesheet" href="static/colors.css">
  <link rel="stylesheet" href="static/theme.css">
  <link rel="stylesheet" href="static/agent.css">
 </head>
--- a/frontend/packages/agent/src/theme.css
+++ b/frontend/packages/agent/src/theme.css
@ -1,6 +1,6 @@
-/* Standalone theme bundle — re-exports the shared Catppuccin palette so
-   esbuild emits it as its own `dist/static/theme.css`, linked first by
-   every agent page. Kept separate from the page bundles so a theme swap
-   (e.g. stylix) replaces only this file. See @hive/shared/theme.css +
-   docs/web-ui/css-vars.md. */
+/* Standalone semantic theme layer — re-exports the shared derivation so
+   esbuild emits it as its own `dist/static/theme.css`, linked by every
+   agent page right after colors.css. The base16 slots it derives from
+   live in colors.css (the swap contract); a theme swap replaces only
+   that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
@import "@hive/shared/theme.css";
--- a/frontend/packages/dashboard/build.mjs
+++ b/frontend/packages/dashboard/build.mjs
@ -86,11 +86,12 @@ await build({
 });

 // Bundle CSS — one entry per page. esbuild resolves @import including
-// the package re-exports from @hive/shared. Each page loads theme.css
-// (the standalone Catppuccin palette — kept its own file so a theme
-// swap replaces only it) + common.css (shared typography, badges,
-// buttons, inbox, side panel) plus its own page-specific bundle.
-for (const entry of ['theme.css', 'common.css', 'dashboard.css', 'flow.css', 'logs.css', 'home.css']) {
+// the package re-exports from @hive/shared. Each page loads colors.css
+// (the standalone base16 palette — the theme swap contract, its own file
+// so a swap replaces only it) + theme.css (the semantic derivation
+// layer) + common.css (shared typography, badges, buttons, inbox, side
+// panel) plus its own page-specific bundle.
+for (const entry of ['colors.css', 'theme.css', 'common.css', 'dashboard.css', 'flow.css', 'logs.css', 'home.css']) {
  await build({
    entryPoints: [src(entry)],
    outfile: staticDir(entry),
--- a/frontend/packages/dashboard/src/colors.css
+++ b/frontend/packages/dashboard/src/colors.css
@ -0,0 +1,6 @@
+/* Standalone base16 palette — re-exports the shared base16 slots so
+   esbuild emits its own `dist/static/colors.css`, linked first by every
+   dashboard page (before theme.css). This is the theme swap contract: a
+   stylix-generated variant replaces only this file. See
+   @hive/shared/colors.css + docs/web-ui/css-vars.md. */
+@import "@hive/shared/colors.css";
--- a/frontend/packages/dashboard/src/common.css
+++ b/frontend/packages/dashboard/src/common.css
@ -12,7 +12,7 @@ h1, h2 {
  text-transform: uppercase;
  letter-spacing: 0.15em;
  margin-top: 2em;
-  text-shadow: 0 0 8px rgba(203, 166, 247, 0.4);
+  text-shadow: 0 0 8px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 .divider {
  color: var(--purple-dim);
@ -27,11 +27,11 @@ a {
  color: var(--cyan);
  text-decoration: none;
  font-weight: bold;
-  text-shadow: 0 0 4px rgba(137, 220, 235, 0.5);
+  text-shadow: 0 0 4px color-mix(in srgb, var(--cyan) 50%, transparent);
 }
 a:hover {
  color: var(--fg);
-  text-shadow: 0 0 12px rgba(137, 220, 235, 0.9);
+  text-shadow: 0 0 12px color-mix(in srgb, var(--cyan) 90%, transparent);
 }
 code {
  color: var(--amber);
@ -64,23 +64,23 @@ code {
 }
 .badge-warn {
  color: var(--amber); border-color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 50%, transparent);
 }
 .badge-rate-limited {
  color: var(--red); border-color: var(--red);
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 50%, transparent);
 }
 .badge-muted {
  color: var(--muted); border-color: var(--purple-dim);
-  background: rgba(127, 132, 156, 0.08);
+  background: color-mix(in srgb, var(--muted) 8%, transparent);
 }
 .badge-reminder {
  color: var(--cyan); border-color: var(--cyan);
-  text-shadow: 0 0 6px rgba(137, 220, 235, 0.4);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--cyan) 40%, transparent);
 }
 .badge-loose-ends {
  color: var(--purple); border-color: var(--purple);
-  text-shadow: 0 0 6px rgba(203, 166, 247, 0.4);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 /* Context-window usage badges on dashboard container rows. */
 .badge-ctx-ok {
@ -89,15 +89,15 @@ code {
 }
 .badge-ctx-caution {
  color: var(--amber); border-color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 50%, transparent);
 }
 .badge-ctx-warn {
  color: var(--red); border-color: var(--red);
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 50%, transparent);
 }
-.badge-ok      { background: rgba(166,227,161,0.12); color: var(--green);  border-color: var(--green); }
-.badge-fail    { background: rgba(243,139,168,0.12); color: var(--red);    border-color: var(--red);   }
-.badge-running { background: rgba(250,179,135,0.12); color: var(--amber);  border-color: var(--amber); }
+.badge-ok      { background: color-mix(in srgb, var(--green) 12%, transparent); color: var(--green);  border-color: var(--green); }
+.badge-fail    { background: color-mix(in srgb, var(--red) 12%, transparent); color: var(--red);    border-color: var(--red);   }
+.badge-running { background: color-mix(in srgb, var(--amber) 12%, transparent); color: var(--amber);  border-color: var(--amber); }

 /* ─── buttons ───────────────────────────────────────────────────────
   .btn base + semantic colour/size modifiers. Logs page uses
@ -121,7 +121,7 @@ code {
  transition: box-shadow 0.15s ease;
 }
 .btn:hover {
-  background: rgba(205, 214, 244, 0.06);
+  background: color-mix(in srgb, var(--fg) 6%, transparent);
  text-shadow: 0 0 10px currentColor;
  box-shadow: 0 0 10px -2px currentColor;
 }
@ -151,7 +151,7 @@ code {
 .btn-move    { color: var(--purple); border-color: var(--purple); font-size: 0.75em; padding: 0.15em 0.5em; margin-left: 0.6em; }
 .btn-talk { color: var(--cyan); border-color: var(--cyan); }
 .btn-spawn { color: var(--amber); border-color: var(--amber); }
-.btn-fire-now { color: var(--mauve, #cba6f7); border-color: var(--mauve, #cba6f7); }
+.btn-fire-now { color: var(--purple); border-color: var(--purple); }
 /* Post-fire flash: report renders directly on the button for ~1.5s
   so the operator sees ok/failed/missing/consumed counts inline
   without a modal. Green when at least one ok; muted otherwise. */
@ -164,7 +164,7 @@ code {
 /* Inline edit button on each schedule row. Yellow reads as a
   parallel destructive-adjacent action (edit changes state, but
   isn't deletion). */
-.btn-edit-schedule { color: var(--yellow, #f9e2af); border-color: var(--yellow, #f9e2af); }
+.btn-edit-schedule { color: var(--yellow); border-color: var(--yellow); }

 /* ─── file-preview / diff panel (common.js Panel) ───────────────────
   Side-panel content rendered by openFilePanel / buildTabbedPreview
@ -184,7 +184,7 @@ code {
 .diff-base-tab.active {
  color: var(--purple);
  border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
 }
 /* Image / tabbed file preview */
 .preview-host { margin-top: 0.5em; }
@ -196,13 +196,13 @@ code {
  border: 1px solid var(--border);
  border-radius: 4px;
  /* checkerboard so transparent regions of the image read clearly */
-  background: repeating-conic-gradient(#313244 0% 25%, #1e1e2e 0% 50%) 50% / 18px 18px;
+  background: repeating-conic-gradient(var(--border) 0% 25%, var(--bg) 0% 50%) 50% / 18px 18px;
 }

 /* Path linkification — agents drop pointer strings into messages;
   clicking the anchor opens the file in the side panel. */
 .path-link {
-  color: var(--blue, #89b4fa);
+  color: var(--blue);
  text-decoration: underline dotted;
  cursor: pointer;
 }
@ -226,7 +226,7 @@ code {
  position: sticky;
  top: 0;
  z-index: 25;
-  background: rgba(30, 30, 46, 0.92);
+  background: color-mix(in srgb, var(--bg) 92%, transparent);
  -webkit-backdrop-filter: blur(8px) saturate(120%);
  backdrop-filter: blur(8px) saturate(120%);
  border-bottom: 1px solid var(--purple-dim);
@ -312,7 +312,7 @@ code {
 }
 .msg-reply-tag a:hover { color: var(--fg); }
@keyframes msg-highlight-fade {
-  from { background: rgba(203, 166, 247, 0.18); }
+  from { background: color-mix(in srgb, var(--purple) 18%, transparent); }
  to   { background: transparent; }
 }
 .msg-highlight { animation: msg-highlight-fade 1.5s ease-out forwards; }
@ -398,7 +398,7 @@ code {
 .side-panel-backdrop {
  position: absolute;
  inset: 0;
-  background: rgba(17, 17, 27, 0.55);
+  background: color-mix(in srgb, var(--crust) 55%, transparent);
  opacity: 0;
  transition: opacity 200ms ease;
 }
@ -539,11 +539,11 @@ body.side-panel-resizing * { cursor: ew-resize !important; }
 }
 .server-warn-warn {
  color: var(--amber);
-  background: rgba(250, 179, 135, 0.16);
+  background: color-mix(in srgb, var(--amber) 16%, transparent);
  border-bottom: 1px solid var(--amber);
 }
 .server-warn-crit {
  color: var(--red);
-  background: rgba(243, 139, 168, 0.18);
+  background: color-mix(in srgb, var(--red) 18%, transparent);
  border-bottom: 1px solid var(--red);
 }
--- a/frontend/packages/dashboard/src/dashboard.css
+++ b/frontend/packages/dashboard/src/dashboard.css
@ -23,7 +23,7 @@ body.dashboard-shell {
  position: sticky;
  top: 0;
  z-index: 25;
-  background: rgba(30, 30, 46, 0.86);
+  background: color-mix(in srgb, var(--bg) 86%, transparent);
  -webkit-backdrop-filter: blur(8px) saturate(120%);
  backdrop-filter: blur(8px) saturate(120%);
  border-bottom: 1px solid var(--purple-dim);
@ -83,7 +83,7 @@ body.dashboard-shell {
 }
 .tabbar .tab:hover {
  color: var(--purple);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }
 .tabbar .tab.active {
  color: var(--purple);
@ -91,7 +91,7 @@ body.dashboard-shell {
  background: var(--bg);
  /* Lift the active tab visually — the bottom border of the tabbar
     yields under it via the -1px margin above. */
-  box-shadow: 0 -2px 12px -4px rgba(203, 166, 247, 0.4);
+  box-shadow: 0 -2px 12px -4px color-mix(in srgb, var(--purple) 40%, transparent);
 }
 .tab-label { font-weight: bold; white-space: nowrap; }
 .tab-count {
@ -108,7 +108,7 @@ body.dashboard-shell {
 }
 .tab-count-attn {
  /* Y3R C4LL — operator-action-required pill colour, harder to miss. */
-  background: rgba(243, 139, 168, 0.22);
+  background: color-mix(in srgb, var(--red) 22%, transparent);
  color: var(--red);
 }

@ -145,7 +145,7 @@ body.dashboard-shell {
 }
 .tabbar-overflow-btn:hover {
  color: var(--purple);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }
 .tabbar-overflow-btn.tabbar-overflow-active {
  color: var(--purple);
@ -206,7 +206,7 @@ body.dashboard-shell {
  font-weight: bold;
 }
 .tabbar-overflow-badge.tab-count-attn {
-  background: rgba(243, 139, 168, 0.22);
+  background: color-mix(in srgb, var(--red) 22%, transparent);
  color: var(--red);
 }

@ -234,7 +234,7 @@ body.dashboard-shell {
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
-  filter: drop-shadow(0 0 6px rgba(203, 166, 247, 0.45));
+  filter: drop-shadow(0 0 6px color-mix(in srgb, var(--purple) 45%, transparent));
 }
 .banner.active {
  animation: banner-shimmer 1.8s linear infinite;
@ -263,7 +263,7 @@ body.dashboard-shell {
  padding: 0.6em 0.8em;
  border: 1px solid var(--border);
  border-radius: 4px;
-  background: rgba(24, 24, 37, 0.55);
+  background: color-mix(in srgb, var(--bg-elev) 55%, transparent);
  transition: opacity 200ms ease, border-color 200ms ease;
 }
 /* Topology indent ladder. See docs/web-ui.md::Topology tree (Indent
@ -330,7 +330,7 @@ body.dashboard-shell {
  width: 5em;
  aspect-ratio: 1;
  border-radius: 6px;
-  background-color: rgba(17, 17, 27, 0.6);
+  background-color: color-mix(in srgb, var(--crust) 60%, transparent);
  cursor: pointer;
  transition: box-shadow 120ms ease, transform 120ms ease;
 }
@ -344,7 +344,7 @@ body.dashboard-shell {
 .container-row.selected {
  border-color: var(--purple);
  box-shadow: inset 0 0 0 1px var(--purple);
-  background: rgba(203, 166, 247, 0.06);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
 }
 .container-row.selected > .container-icon {
  box-shadow: 0 0 0 2px var(--purple), 0 0 12px -4px var(--purple);
@ -392,7 +392,7 @@ body.dashboard-shell {
 }
 .agent-menu-btn:hover,
 .agent-menu-btn:focus-visible {
-  background: rgba(203, 166, 247, 0.1);
+  background: color-mix(in srgb, var(--purple) 10%, transparent);
  color: var(--purple);
  outline: none;
 }
@ -443,7 +443,7 @@ body.dashboard-shell {
 .container-row.pending .actions { opacity: 0.4; pointer-events: none; }
 .container-row.pending-running {
  border-color: var(--amber);
-  background: rgba(250, 179, 135, 0.05);
+  background: color-mix(in srgb, var(--amber) 5%, transparent);
 }
@keyframes container-icon-spin {
  from { transform: rotate(0deg); }
@ -490,9 +490,9 @@ body.dashboard-shell {
  transition: background 0.12s ease, color 0.12s ease;
 }
 .nav-link:hover {
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
  color: var(--cyan);
-  text-shadow: 0 0 6px rgba(137, 220, 235, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--cyan) 50%, transparent);
 }
 .container-row .actions {
  display: flex;
@ -503,7 +503,7 @@ body.dashboard-shell {

 .agent-status {
  font-size: 0.82em;
-  color: var(--subtext0, #a6adc8);
+  color: var(--subtext0);
  padding: 0.1em 0.3em 0.25em;
  white-space: nowrap;
  overflow: hidden;
@ -514,20 +514,20 @@ body.dashboard-shell {

 .container-row.tombstone {
  border-style: dashed;
-  background: rgba(24, 24, 37, 0.35);
+  background: color-mix(in srgb, var(--bg-elev) 35%, transparent);
  opacity: 0.85;
 }
 .container-row.tombstone .name { color: var(--muted); }

 /* Notification controls — sit between the banner and the containers. */
 .port-conflict {
-  background: rgba(243, 139, 168, 0.08);
+  background: color-mix(in srgb, var(--red) 8%, transparent);
  border: 1px solid var(--red);
  color: var(--red);
  padding: 0.5em 0.8em;
  margin-bottom: 0.6em;
  border-radius: 4px;
-  text-shadow: 0 0 6px rgba(243, 139, 168, 0.4);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--red) 40%, transparent);
  animation: questions-pulse 2.4s ease-in-out infinite;
 }
 .port-conflict strong { color: var(--red); }
@ -551,7 +551,7 @@ body.dashboard-shell {
  text-shadow: 0 0 4px currentColor;
 }
 .btn-notif:hover {
-  background: rgba(137, 220, 235, 0.1);
+  background: color-mix(in srgb, var(--cyan) 10%, transparent);
  box-shadow: 0 0 10px -2px currentColor;
 }

@ -560,7 +560,7 @@ body.dashboard-shell {
  font-size: 0.85em;
  letter-spacing: 0.08em;
  text-transform: uppercase;
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.55);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent);
  animation: badge-pulse 1.6s ease-in-out infinite;
 }
@keyframes badge-pulse {
@ -568,8 +568,8 @@ body.dashboard-shell {
  50%      { opacity: 0.7; }
 }
@keyframes questions-pulse {
-  0%, 100% { box-shadow: 0 0 12px -4px rgba(250, 179, 135, 0.55); }
-  50%      { box-shadow: 0 0 22px -2px rgba(250, 179, 135, 0.95); }
+  0%, 100% { box-shadow: 0 0 12px -4px color-mix(in srgb, var(--amber) 55%, transparent); }
+  50%      { box-shadow: 0 0 22px -2px color-mix(in srgb, var(--amber) 95%, transparent); }
 }

 /* Pending approval: a card with three stacked sections — identity
@ -596,7 +596,7 @@ body.dashboard-shell {
 }
 .approval-ts.stale {
  color: var(--amber);
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.5);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 50%, transparent);
 }
 .approval-body {
  margin: 0.45em 0;
@ -644,7 +644,7 @@ body.dashboard-shell {
 .approval-tab.active {
  color: var(--purple);
  border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
  text-shadow: 0 0 4px currentColor;
 }
 .approvals-history .status { font-size: 0.85em; padding: 0 0.5em; }
@ -667,7 +667,7 @@ body.dashboard-shell {
 .meta-inputs li {
  padding: 0.25em 0.6em;
  border: 1px solid var(--border);
-  background: rgba(24, 24, 37, 0.6);
+  background: color-mix(in srgb, var(--bg-elev) 60%, transparent);
 }
 .meta-inputs label {
  display: flex;
@ -711,7 +711,7 @@ body.dashboard-shell {
  margin-right: 0.1em;
 }
 .btn-meta-update {
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
  border: 1px solid var(--purple);
  color: var(--purple);
  text-shadow: 0 0 4px currentColor;
@ -723,7 +723,7 @@ body.dashboard-shell {
  transition: box-shadow 0.15s ease, background 0.15s ease;
 }
 .btn-meta-update:hover:not([disabled]) {
-  background: rgba(203, 166, 247, 0.22);
+  background: color-mix(in srgb, var(--purple) 22%, transparent);
  box-shadow: 0 0 10px -2px currentColor;
 }
 .btn-meta-update[disabled] {
@ -734,7 +734,7 @@ body.dashboard-shell {
  margin: 0 0 0.7em;
  padding: 0.4em 0.7em;
  border: 1px solid var(--purple);
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
  color: var(--purple);
  font-size: 0.85em;
  animation: badge-pulse 1.6s ease-in-out infinite;
@ -751,7 +751,7 @@ body.dashboard-shell {
 .rebuild-queue-entry {
  padding: 0.3em 0.6em;
  border: 1px solid var(--border);
-  background: rgba(24, 24, 37, 0.6);
+  background: color-mix(in srgb, var(--bg-elev) 60%, transparent);
  font-size: 0.9em;
  display: flex;
  flex-wrap: wrap;
@ -761,7 +761,7 @@ body.dashboard-shell {
 .rebuild-queue-entry.rqe-child { margin-left: 1.6em; border-color: var(--purple-dim); }
 .rebuild-queue-entry.rqe-running {
  border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.12);
+  background: color-mix(in srgb, var(--purple) 12%, transparent);
  animation: badge-pulse 1.6s ease-in-out infinite;
 }
 .rebuild-queue-entry.rqe-failed { border-color: var(--red); color: var(--red); }
@ -797,7 +797,7 @@ body.dashboard-shell {
  flex-basis: 100%;
  margin: 0.3em 0 0;
  padding: 0.3em 0.5em;
-  background: rgba(243, 139, 168, 0.1);
+  background: color-mix(in srgb, var(--red) 10%, transparent);
  border-left: 2px solid var(--red);
  color: var(--red);
  font-size: 0.8em;
@ -863,6 +863,8 @@ ul form.inline { display: inline-block; }
  cursor: pointer;
  margin-left: 0.4em;
 }
+/* Off-palette warm-amber hover tint: not an exact theme var (brighter than
+   --amber), left as a literal pending a dedicated named var. */
 .btn-inline:hover { background: rgba(255, 184, 77, 0.1); }
 .kind {
  display: inline-block;
@ -933,13 +935,13 @@ summary:hover { color: var(--purple); }
  margin: 0.3em 0;
 }
 .reminder-row.reminder-failed {
-  border-left: 2px solid var(--red, #f38ba8);
+  border-left: 2px solid var(--red);
  padding-left: 0.5em;
 }
 .reminder-error {
-  color: var(--red, #f38ba8);
-  background: rgba(243, 139, 168, 0.06);
-  border: 1px solid rgba(243, 139, 168, 0.25);
+  color: var(--red);
+  background: color-mix(in srgb, var(--red) 6%, transparent);
+  border: 1px solid color-mix(in srgb, var(--red) 25%, transparent);
  padding: 0.3em 0.5em;
  font-size: 0.85em;
  white-space: pre-wrap;
@ -974,11 +976,11 @@ summary:hover { color: var(--purple); }
  border-color: var(--amber);
 }
 .questions li.question-peer {
-  border-left: 2px solid var(--mauve, #cba6f7);
+  border-left: 2px solid var(--purple);
  padding-left: 0.6em;
 }
-.questions .msg-to-peer { color: var(--mauve, #cba6f7); }
-.btn-override { background: var(--mauve, #cba6f7) !important; color: var(--bg) !important; }
+.questions .msg-to-peer { color: var(--purple); }
+.btn-override { background: var(--purple) !important; color: var(--bg) !important; }
 .questions li.question {
  padding: 0.4em 0;
  border-bottom: 1px solid var(--border);
@ -1046,7 +1048,7 @@ summary:hover { color: var(--purple); }
 }
 .question-answered { opacity: 0.7; }
 .question-answered .q-body { color: var(--muted); margin-bottom: 0.15em; }
-.q-answer { font-size: 0.9em; color: var(--green, #a6e3a1); padding: 0.1em 0 0.4em 0; }
+.q-answer { font-size: 0.9em; color: var(--green); padding: 0.1em 0 0.4em 0; }
 .q-answer-text { font-style: italic; }

 footer {
@ -1141,7 +1143,7 @@ footer .banner-thin {
 .schedule-edit-form-wrapper {
  margin-top: 0.5em;
  padding-left: 0.5em;
-  border-left: 2px solid var(--yellow, #f9e2af);
+  border-left: 2px solid var(--yellow);
 }
 .schedule-edit-targets-note {
  color: var(--muted);
@ -1185,13 +1187,13 @@ footer .banner-thin {
  border-radius: 999px;
  font-size: 0.85em;
  cursor: pointer;
-  background: rgba(24, 24, 37, 0.4);
+  background: color-mix(in srgb, var(--bg-elev) 40%, transparent);
 }
 .schedule-target-chip:hover { border-color: var(--purple-dim); }
 .schedule-target-chip:has(input:checked) {
  border-color: var(--purple);
  color: var(--purple);
-  background: rgba(203, 166, 247, 0.08);
+  background: color-mix(in srgb, var(--purple) 8%, transparent);
 }
 .schedule-target-chip input { margin: 0; }
 .schedule-actions {
@ -1333,10 +1335,13 @@ footer .banner-thin {
  margin-left: 0.3em;
 }
 .schedules-table-edit-row > td {
+  /* Off-palette dim-purple surface tint: not an exact theme var, left as a
+     literal pending a dedicated named var so a theme swap can recolour it. */
  background: rgba(38, 32, 60, 0.35);
  padding: 0.5em 0.6em;
 }
 .schedules-table-create-row td {
+  /* Off-palette dim-purple surface tint — see the edit-row note above. */
  background: rgba(38, 32, 60, 0.25);
  border-top: 2px solid var(--border);
  vertical-align: top;
@ -1443,7 +1448,7 @@ footer .banner-thin {
  flex-wrap: wrap;
  gap: 0.6em;
  padding: 0.55em 1em;
-  background: var(--flow-frost-bg, rgba(30, 30, 46, 0.74));
+  background: var(--flow-frost-bg, color-mix(in srgb, var(--bg) 74%, transparent));
  -webkit-backdrop-filter: blur(12px) saturate(140%);
  backdrop-filter: blur(12px) saturate(140%);
  border-top: 1px solid var(--purple);
--- a/frontend/packages/dashboard/src/dashboard.html
+++ b/frontend/packages/dashboard/src/dashboard.html
@ -5,6 +5,7 @@
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>hyperhive // h1ve-c0re</title>
  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
  <link rel="stylesheet" href="/static/theme.css">
  <link rel="stylesheet" href="/static/common.css">
  <link rel="stylesheet" href="/static/dashboard.css">
--- a/frontend/packages/dashboard/src/flow.css
+++ b/frontend/packages/dashboard/src/flow.css
@ -10,7 +10,7 @@
     footer position. */
  --flow-header-h: 3.6em;
  --flow-composer-h: 3.6em;
-  --flow-frost-bg: rgba(30, 30, 46, 0.74);
+  --flow-frost-bg: color-mix(in srgb, var(--bg) 74%, transparent);
  --flow-frost-blur: blur(12px) saturate(140%);
 }

@ -24,7 +24,7 @@ body.flow-shell {
  overflow: hidden;
  background:
    radial-gradient(ellipse 80% 60% at 50% 0%,
-                    rgba(203, 166, 247, 0.06) 0%,
+                    color-mix(in srgb, var(--purple) 6%, transparent) 0%,
                    transparent 60%),
    var(--bg);
 }
--- a/frontend/packages/dashboard/src/flow.html
+++ b/frontend/packages/dashboard/src/flow.html
@ -5,6 +5,7 @@
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>hyperhive // FL0W</title>
  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
  <link rel="stylesheet" href="/static/theme.css">
  <link rel="stylesheet" href="/static/common.css">
  <link rel="stylesheet" href="/static/flow.css">
--- a/frontend/packages/dashboard/src/home.css
+++ b/frontend/packages/dashboard/src/home.css
@ -36,7 +36,7 @@ body.home-shell {
  padding: 1.1em 1.2em;
  border: 1px solid var(--purple-dim);
  border-radius: 6px;
-  background: rgba(24, 24, 37, 0.55);
+  background: color-mix(in srgb, var(--bg-elev) 55%, transparent);
  text-decoration: none;
  color: var(--fg);
  transition: color 0.15s ease, background 0.15s ease, border-color 0.15s ease,
@ -44,8 +44,8 @@ body.home-shell {
 }
 .home-tile:hover {
  border-color: var(--purple);
-  background: rgba(203, 166, 247, 0.06);
-  box-shadow: 0 -2px 14px -6px rgba(203, 166, 247, 0.5);
+  background: color-mix(in srgb, var(--purple) 6%, transparent);
+  box-shadow: 0 -2px 14px -6px color-mix(in srgb, var(--purple) 50%, transparent);
 }

 .home-tile-label {
--- a/frontend/packages/dashboard/src/index.html
+++ b/frontend/packages/dashboard/src/index.html
@ -5,6 +5,7 @@
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>hyperhive // h0m3</title>
  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
  <link rel="stylesheet" href="/static/theme.css">
  <link rel="stylesheet" href="/static/common.css">
  <link rel="stylesheet" href="/static/home.css">
--- a/frontend/packages/dashboard/src/logs.html
+++ b/frontend/packages/dashboard/src/logs.html
@ -5,6 +5,7 @@
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>hyperhive // LOGS</title>
  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+  <link rel="stylesheet" href="/static/colors.css">
  <link rel="stylesheet" href="/static/theme.css">
  <link rel="stylesheet" href="/static/common.css">
  <link rel="stylesheet" href="/static/logs.css">
--- a/frontend/packages/dashboard/src/theme.css
+++ b/frontend/packages/dashboard/src/theme.css
@ -1,6 +1,6 @@
-/* Standalone theme bundle — re-exports the shared Catppuccin palette so
-   esbuild emits it as its own `dist/static/theme.css`, linked first by
-   every dashboard page. Kept separate from the page bundles so a theme
-   swap (e.g. stylix) replaces only this file. See @hive/shared/theme.css
-   + docs/web-ui/css-vars.md. */
+/* Standalone semantic theme layer — re-exports the shared derivation so
+   esbuild emits it as its own `dist/static/theme.css`, linked by every
+   dashboard page right after colors.css. The base16 slots it derives
+   from live in colors.css (the swap contract); a theme swap replaces
+   only that file. See @hive/shared/theme.css + docs/web-ui/css-vars.md. */
@import "@hive/shared/theme.css";
--- a/frontend/packages/shared/package.json
+++ b/frontend/packages/shared/package.json
@ -8,6 +8,7 @@
  "exports": {
    ".": "./src/index.js",
    "./terminal.js": "./src/terminal.js",
+    "./colors.css": "./src/colors.css",
    "./theme.css": "./src/theme.css",
    "./base.css": "./src/base.css",
    "./terminal.css": "./src/terminal.css"
--- a/frontend/packages/shared/src/colors.css
+++ b/frontend/packages/shared/src/colors.css
@ -0,0 +1,31 @@
+/* base16 palette — THE THEME CONTRACT.
+
+   These 16 slots are the entire swap interface. A theme generator (e.g.
+   one fed a stylix base16 scheme, which is natively base00–base0F)
+   overrides *only this file*; `theme.css` derives every semantic var
+   (`--bg`, `--purple`, …) from these slots, so the whole UI re-themes
+   with nothing else to regenerate.
+
+   Kept as its own standalone stylesheet (not @import-ed into theme.css)
+   so a swap replaces just this ~16-line file — `theme.css` and the page
+   bundles stay untouched. Every page links this BEFORE `theme.css`. The
+   hex defaults are Catppuccin Mocha. Standard base16 slot meanings are
+   in the trailing comments. See docs/web-ui/css-vars.md. */
+:root {
+  --base00: #1e1e2e; /* default bg */
+  --base01: #181825; /* lighter bg (elevated surfaces) */
+  --base02: #313244; /* selection / surface — borders */
+  --base03: #45475a; /* comments / dim surface */
+  --base04: #585b70; /* dark foreground */
+  --base05: #cdd6f4; /* default foreground */
+  --base06: #f5e0dc; /* light foreground */
+  --base07: #b4befe; /* lightest */
+  --base08: #f38ba8; /* red */
+  --base09: #fab387; /* orange / peach */
+  --base0A: #f9e2af; /* yellow */
+  --base0B: #a6e3a1; /* green */
+  --base0C: #89dceb; /* cyan (our sky — note: Catppuccin's base0C is teal) */
+  --base0D: #89b4fa; /* blue */
+  --base0E: #cba6f7; /* magenta / mauve */
+  --base0F: #f5c2e7; /* extra accent — pink */
+}
--- a/frontend/packages/shared/src/terminal.css
+++ b/frontend/packages/shared/src/terminal.css
@ -18,7 +18,7 @@

 .terminal-wrap {
  position: relative;
-  background: rgba(17, 17, 27, 0.78);
+  background: color-mix(in srgb, var(--crust) 78%, transparent);
  -webkit-backdrop-filter: blur(8px) saturate(120%);
  backdrop-filter: blur(8px) saturate(120%);
  border: 1px solid var(--purple-dim);
@ -120,12 +120,12 @@
  font-weight: normal;
  margin-left: 0.6em;
  font-size: 0.85em;
-  text-shadow: 0 0 6px rgba(250, 179, 135, 0.55);
+  text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent);
  animation: badge-pulse 1.4s ease-in-out infinite;
 }
@keyframes badge-pulse {
-  0%, 100% { opacity: 1;   text-shadow: 0 0 6px rgba(250, 179, 135, 0.55); }
-  50%      { opacity: 0.7; text-shadow: 0 0 14px rgba(250, 179, 135, 0.95); }
+  0%, 100% { opacity: 1;   text-shadow: 0 0 6px color-mix(in srgb, var(--amber) 55%, transparent); }
+  50%      { opacity: 0.7; text-shadow: 0 0 14px color-mix(in srgb, var(--amber) 95%, transparent); }
 }
 /* "↓ N new" pill: shown when new rows arrive while the operator is
   scrolled up; click to jump to bottom. Positioned by the wrapper's
@ -136,7 +136,7 @@
  right: 1em;
  bottom: 4.2em;
  background: var(--amber);
-  color: #11111b;
+  color: var(--crust);
  font-family: inherit;
  font-size: 0.8em;
  font-weight: bold;
@ -145,7 +145,7 @@
  border-radius: 999px;
  padding: 0.35em 0.9em;
  cursor: pointer;
-  box-shadow: 0 0 14px -2px rgba(250, 179, 135, 0.85);
+  box-shadow: 0 0 14px -2px color-mix(in srgb, var(--amber) 85%, transparent);
  opacity: 0;
  transform: translateY(6px);
  pointer-events: none;
--- a/frontend/packages/shared/src/theme.css
+++ b/frontend/packages/shared/src/theme.css
@ -1,30 +1,35 @@
-/* Theme colour variables (Catppuccin Mocha) — the single source of
-   truth for the hive UI palette. Kept in a standalone file, linked as
-   its own `<link rel="stylesheet" href=".../theme.css">` by every page
-   BEFORE the page CSS, so the `:root` vars are defined for everything
-   that references them (base typography, terminal, dashboard, agent).
+/* Semantic theme layer — derived from the base16 contract in
+   `colors.css`. This is what the app references (`--bg`, `--fg`,
+   `--purple`, …); page CSS must use these names, never literal colours
+   and never the raw `--baseNN` slots.

-   Why standalone rather than `@import`ed into the page bundles: esbuild
-   inlines `@import` at build time, which would bake the palette into
-   every CSS bundle. Emitting `theme.css` as its own output file lets a
-   theme swap (e.g. a stylix-generated variant carrying the same var
-   names) replace just this one file without rebuilding the rest of the
-   frontend. See docs/web-ui/css-vars.md. */
+   Standalone stylesheet, linked by every page right AFTER `colors.css`
+   (which defines the `--baseNN` slots these rules resolve against). Kept
+   separate from the page bundles — esbuild would otherwise inline an
+   `@import` and bake the palette into every CSS bundle.
+
+   A theme swap touches only `colors.css` (the 16 base16 slots); this
+   derivation layer never changes. See docs/web-ui/css-vars.md. */
 :root {
-  --bg: #1e1e2e;        /* base */
-  --bg-elev: #181825;   /* mantle */
-  --crust: #11111b;     /* crust — terminal background */
-  --fg: #cdd6f4;        /* text */
-  --muted: #7f849c;     /* overlay1 */
-  --purple: #cba6f7;    /* mauve */
-  --purple-dim: #45475a;/* surface1 */
-  --cyan: #89dceb;      /* sky */
-  --blue: #89b4fa;      /* blue */
-  --pink: #f5c2e7;      /* pink */
-  --amber: #fab387;     /* peach */
-  --yellow: #f9e2af;    /* yellow */
-  --green: #a6e3a1;     /* green */
-  --red: #f38ba8;       /* red */
-  --border: #313244;    /* surface0 */
-  --subtext0: #a6adc8;  /* subtext0 — secondary/toolbar text, dimmer than --fg but lighter than --muted */
+  --bg: var(--base00);
+  --bg-elev: var(--base01); /* elevated surfaces: dropdowns, popovers */
+  --border: var(--base02); /* general borders, hover/active backgrounds */
+  --purple-dim: var(--base03); /* subtle borders, terminal chrome, badge bg */
+  --fg: var(--base05);
+  --red: var(--base08); /* errors, fail state */
+  --amber: var(--base09); /* warnings, pending / running state */
+  --yellow: var(--base0A); /* flash messages, mild warnings */
+  --green: var(--base0B); /* success, ok state */
+  --cyan: var(--base0C); /* tool-use events, info accents */
+  --blue: var(--base0D); /* links, interactive accent (distinct from cyan) */
+  --purple: var(--base0E); /* accent — active tabs, links, highlights */
+  --pink: var(--base0F); /* thinking events */
+
+  /* Off-base16 (no exact slot) — derived from base16 so they still track
+     a swap. Each is pixel-identical to its prior literal under the
+     default palette: --crust is a darkened bg; --muted / --subtext0 are
+     foreground↔background blends (two levels of dimmed text). */
+  --crust: color-mix(in srgb, var(--base00) 58%, #000); /* terminal / code bg, below --bg */
+  --muted: color-mix(in srgb, var(--base05) 55.5%, var(--base00)); /* secondary / dimmed text */
+  --subtext0: color-mix(in srgb, var(--base05) 77.7%, var(--base00)); /* toolbar/status text; dimmer than --fg, lighter than --muted */
 }
--- a/nix/frontend.nix
+++ b/nix/frontend.nix
@ -18,12 +18,12 @@
 #       index.html (H0M3 hub, served at /) dashboard.html (operator SPA,
 #       served at /dashboard.html) flow.html logs.html favicon.svg
 #       static/{home,tabs,flow,logs,stream-worker}.js{,.map}
-#       static/{common,home,dashboard,flow,logs,theme}.css
+#       static/{colors,theme,common,home,dashboard,flow,logs}.css
 #   $out/agent/       the per-agent default UI (layered with
 #                     hyperhive.frontend.extraFiles at activation time)
 #       index.html stats.html screen.html
 #       static/{app,stats}.js{,.map}
-#       static/agent.css
+#       static/{colors,theme,agent}.css
 #
 # The dashboard favicon lives outside the npm tree (`branding/hyperhive
 # .svg` at the repo root) — we copy it in during the install phase so