Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/web-ui/css-vars.md

12 KiB

CSS custom properties (theme variables)

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

  1. colors.css — the 16 --base00…--base0F base16 slots. This is the whole theme contract. A theme is 16 colours here and nothing else.
  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 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, --subtext0 have no own slot — they're derived via color-mix() over base16 (--crust and --code-bg = a darkened base00, --code-bg less so on a light palette; --muted/--subtext0 = base05↔base00 blends). They still track a swap automatically; no generator action needed.
  • A standard Catppuccin base16 scheme uses teal for base0C; colors.css uses sky (#89dceb in Mocha) to keep the historical accent.
  • 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).