12 KiB
CSS custom properties (theme variables)
Colour variables live in two standalone stylesheets, split so a new theme touches only the first:
colors.css— the 16--base00…--base0Fbase16 slots. This is the whole theme contract. A theme is 16 colours here and nothing else.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 doesn't change per theme.
Both files live in frontend/packages/shared/src/. Per-page stylesheets
(common.css, dashboard.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.)
colors.css declares each theme's 16 hex values exactly once, as
--<theme>-baseNN, for five themes that are each light or dark:
| Theme | Id | Scheme | Palette |
|---|---|---|---|
| hyperhive light | hyperhive-light |
light | Latte's neutrals, accents darker than stock to clear WCAG AA |
| hyperhive dark | hyperhive-dark |
dark | Mocha's neutrals, the light accents' hues lifted to suit a dark bg |
| catppuccin latte mauve | catppuccin-latte-mauve |
light | Catppuccin Latte as published |
| catppuccin mocha mauve | catppuccin-mocha-mauve |
dark | Catppuccin Mocha as published |
| catppuccin mocha mara | catppuccin-mocha-mara |
dark | Mocha with the accents mara picked |
The hyperhive light accents (base08-base0F) run darker than stock Latte
because the stock ones fail contrast as badge text and as plain text; the
comment above them in colors.css has the numbers. The hyperhive dark
accents keep those hues and saturations and raise the lightness until each
clears 6:1 against base02.
Everything else in the file points the active --baseNN slots at one of
those raw palettes via var(), never a second copy of a hex value: an
unconditional default (hyperhive dark), a block gated behind
@media (prefers-color-scheme: light) (hyperhive light, the OS-level
default), and one :root[data-theme='<id>'] block per theme, which the
settings menu's theme select sets. An attribute selector always outranks
the plain :root inside the media query, so a picked theme wins whatever
the OS prefers. The select's auto choice sets no data-theme, so the
media query decides.
frontend/packages/shared/src/settings/themes.ts lists the ids, labels and
schemes; adding a theme is one entry there and one palette plus one block in
colors.css.
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 each page still
links colors.css 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 |
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%, #000000) |
#11111b |
scrims and shadows (below --bg) |
--code-bg |
mix(base00 58%, #000000) |
#11111b |
terminal / code block background |
--muted |
mix(base05 58%, base00) |
#8489a1 |
secondary / dimmed text |
--subtext0 |
mix(base05 77.7%, base00) |
#a6adc8 |
toolbar/status text; dimmer than --fg, lighter than --muted |
The shares in the --muted, --subtext0 and --code-bg rows are the dark palette's.
The light palette keeps more of the text colour (85% and 93%, set in colors.css as
--muted-share and --subtext0-share), because the dark shares leave its dimmed
text at 2.4:1 against a card, short of the 4.5:1 AA asks for. For the same reason it
keeps 95% of its background in --code-bg (--code-bg-share), as --crust is a mid
grey on a light palette and text on it fell to 2:1. A palette that sets none of these
variables, such as a generated one, keeps the dark shares.
The frosted surfaces (the headers, the badges, the terminal panes, the message box and the
dashboard's banner) read two derived variables from theme.css. --glass-clear is 1
for glass and 0 for solid: a surface keeps calc(100% - its-share * var(--glass-clear))
of its fill colour. --glass-filter is its backdrop-filter: a blur on the dark palette,
none on the light one, where bright content behind the glass would wash the text out.
The light palette sets --palette-glass-clear and --palette-glass-filter in colors.css,
and the dark palette resets them; the solid-backgrounds setting sets the two derived
variables itself. A new glass surface uses the two variables and needs no theme rules of its own.
Common mistakes
The Catppuccin colour names don't map 1:1 to the variable names. Variables to avoid (undefined — they will silently resolve to transparent / inherited):
| Wrong | Correct |
|---|---|
--text |
--fg |
--mauve |
--purple |
--surface0 |
--bg-elev (float bg) or --border (border/hover) |
--surface1 |
--border |
--surface2 |
--purple-dim |
--overlay0, --overlay1 |
--muted |
--base, --mantle |
--bg, --bg-elev |
Usage guide
Floating menus and dropdowns (for example 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 */
Themes — the base16 contract
The theme interface is colors.css — the 16 base16 slots, not the
semantic names. The semantic layer in theme.css derives everything
else, so a new theme needs nothing else to template or regenerate. The
base16 slot → semantic mapping is internal to theme.css (the "Derives
from" column above): a theme never needs the semantic var names, and
theme.css and the page bundles stay untouched.
Five palettes, one contract. colors.css ships the five themes in the
table above, each light or dark, with hyperhive dark as the unconditional
default and hyperhive light behind @media (prefers-color-scheme: light).
Each theme's block also sets color-scheme and the contrast shares of
theme.css (--muted-share and friends) for its scheme.
colors.css base16 slots in the dark palettes (the values are Catppuccin Mocha's; hyperhive dark differs in base08-base0F):
| Slot | Default | Standard base16 role | Mapped to |
|---|---|---|---|
base00 |
#1e1e2e |
default bg | --bg, (darkened) --crust and --code-bg |
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 (named sky here; Catppuccin's base0C is teal) |
base0D |
#89b4fa |
blue | --blue |
base0E |
#cba6f7 |
magenta | --purple |
base0F |
#f5c2e7 |
extra accent | --pink |
Notes for theme authors:
--crust,--code-bg,--muted,--subtext0have no own slot — they're derived viacolor-mix()over base16 (--crustand--code-bg= a darkenedbase00,--code-bgless so on a light palette;--muted/--subtext0=base05↔base00blends). They still track a swap automatically; no generator action needed.- A standard Catppuccin base16 scheme uses teal for
base0C;colors.cssuses sky (#89dcebin Mocha) to keep the historical accent. base04/base06/base07aren'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).