vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
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.
This commit is contained in:
iris 2026-06-08 21:07:15 +02:00
commit 09787dd1c3
18 changed files with 204 additions and 84 deletions
Download patch file Download diff file Expand all files Collapse all files

126
docs/web-ui/css-vars.md
View file

@ -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).

11
frontend/packages/agent/build.mjs
View file

@ -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),

6
frontend/packages/agent/src/colors.css Normal file
View file

@ -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";

1
frontend/packages/agent/src/index.html
View file

@ -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>

1
frontend/packages/agent/src/screen.html
View file

@ -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>

1
frontend/packages/agent/src/stats.html
View file

@ -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>

10
frontend/packages/agent/src/theme.css
View file

@ -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";

11
frontend/packages/dashboard/build.mjs
View file

@ -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),

6
frontend/packages/dashboard/src/colors.css Normal file
View file

@ -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";

1
frontend/packages/dashboard/src/dashboard.html
View file

@ -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">

1
frontend/packages/dashboard/src/flow.html
View file

@ -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">

1
frontend/packages/dashboard/src/index.html
View file

@ -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">

1
frontend/packages/dashboard/src/logs.html
View file

@ -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">

10
frontend/packages/dashboard/src/theme.css
View file

@ -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";

1
frontend/packages/shared/package.json
View file

@ -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"

31
frontend/packages/shared/src/colors.css Normal file
View file

@ -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 */
}

59
frontend/packages/shared/src/theme.css
View file

@ -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 */
}

4
nix/frontend.nix
View file

@ -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