CSS custom properties (theme variables)

Colour variables live in two standalone stylesheets, split so a theme swap touches only the first:

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.

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

Both are deliberately standalone, not @imported 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.

Common mistakes

The Catppuccin colour names do not map 1:1 to the variable names. Variables to avoid (undefined — they will silently resolve to transparent / inherited):

Usage guide

Floating menus and dropdowns (e.g. agent context menu, tabbar overflow):

background: var(--bg-elev);
border: 1px solid var(--purple-dim);

Hover / active state backgrounds:

background: var(--border);

Active tab text / accent elements:

color: var(--purple);

Muted / meta text:

color: var(--muted);

Error / warning / success badges:

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):

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