200 lines
12 KiB
Markdown
200 lines
12 KiB
Markdown
# 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 `@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 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):
|
|
|
|
```css
|
|
background: var(--bg-elev);
|
|
border: 1px solid var(--purple-dim);
|
|
```
|
|
|
|
**Hover / active state backgrounds**:
|
|
|
|
```css
|
|
background: var(--border);
|
|
```
|
|
|
|
**Active tab text / accent elements**:
|
|
|
|
```css
|
|
color: var(--purple);
|
|
```
|
|
|
|
**Muted / meta text**:
|
|
|
|
```css
|
|
color: var(--muted);
|
|
```
|
|
|
|
**Error / warning / success badges**:
|
|
|
|
```css
|
|
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).
|