diff --git a/docs/web-ui/css-vars.md b/docs/web-ui/css-vars.md
index 54f86636..ecbdb9e9 100644
--- 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**
-(``) 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).
diff --git a/frontend/packages/agent/build.mjs b/frontend/packages/agent/build.mjs
index 60916de8..c5e1edfa 100644
--- 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),
diff --git a/frontend/packages/agent/src/colors.css b/frontend/packages/agent/src/colors.css
new file mode 100644
index 00000000..72edd746
--- /dev/null
+++ 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";
diff --git a/frontend/packages/agent/src/index.html b/frontend/packages/agent/src/index.html
index 74ac07a7..f27d2c81 100644
--- a/frontend/packages/agent/src/index.html
+++ b/frontend/packages/agent/src/index.html
@@ -5,6 +5,7 @@
hyperhive agent
+
diff --git a/frontend/packages/agent/src/screen.html b/frontend/packages/agent/src/screen.html
index ed0ce3c1..d154733a 100644
--- a/frontend/packages/agent/src/screen.html
+++ b/frontend/packages/agent/src/screen.html
@@ -5,6 +5,7 @@
screen
+
diff --git a/frontend/packages/agent/src/stats.html b/frontend/packages/agent/src/stats.html
index 8fa106f3..8ed0a608 100644
--- a/frontend/packages/agent/src/stats.html
+++ b/frontend/packages/agent/src/stats.html
@@ -5,6 +5,7 @@
hyperhive agent — stats
+
diff --git a/frontend/packages/agent/src/theme.css b/frontend/packages/agent/src/theme.css
index 941c4150..18d7d7b4 100644
--- 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";
diff --git a/frontend/packages/dashboard/build.mjs b/frontend/packages/dashboard/build.mjs
index 334a3623..6cdd553e 100644
--- 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),
diff --git a/frontend/packages/dashboard/src/colors.css b/frontend/packages/dashboard/src/colors.css
new file mode 100644
index 00000000..c3279b92
--- /dev/null
+++ 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";
diff --git a/frontend/packages/dashboard/src/dashboard.html b/frontend/packages/dashboard/src/dashboard.html
index e4f5c44a..e998e496 100644
--- a/frontend/packages/dashboard/src/dashboard.html
+++ b/frontend/packages/dashboard/src/dashboard.html
@@ -5,6 +5,7 @@
hyperhive // h1ve-c0re
+
diff --git a/frontend/packages/dashboard/src/flow.html b/frontend/packages/dashboard/src/flow.html
index 9608204a..6b3d0c7e 100644
--- a/frontend/packages/dashboard/src/flow.html
+++ b/frontend/packages/dashboard/src/flow.html
@@ -5,6 +5,7 @@
hyperhive // FL0W
+
diff --git a/frontend/packages/dashboard/src/index.html b/frontend/packages/dashboard/src/index.html
index 17611612..63ebb5d1 100644
--- a/frontend/packages/dashboard/src/index.html
+++ b/frontend/packages/dashboard/src/index.html
@@ -5,6 +5,7 @@
hyperhive // h0m3
+
diff --git a/frontend/packages/dashboard/src/logs.html b/frontend/packages/dashboard/src/logs.html
index 2dd7af56..2f6af3dc 100644
--- a/frontend/packages/dashboard/src/logs.html
+++ b/frontend/packages/dashboard/src/logs.html
@@ -5,6 +5,7 @@
hyperhive // LOGS
+
diff --git a/frontend/packages/dashboard/src/theme.css b/frontend/packages/dashboard/src/theme.css
index 5e71c223..b799ce30 100644
--- 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";
diff --git a/frontend/packages/shared/package.json b/frontend/packages/shared/package.json
index 35a885bd..1d9a7a1b 100644
--- 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"
diff --git a/frontend/packages/shared/src/colors.css b/frontend/packages/shared/src/colors.css
new file mode 100644
index 00000000..3fa8ca51
--- /dev/null
+++ 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 */
+}
diff --git a/frontend/packages/shared/src/theme.css b/frontend/packages/shared/src/theme.css
index 9c59c7e5..e7f696d8 100644
--- 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 `` 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 */
}
diff --git a/nix/frontend.nix b/nix/frontend.nix
index 9740b27f..0d50b929 100644
--- 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