Design tokens

The web UI’s entire visual language — colour, type, spacing, elevation, corner radii, motion — is expressed as a small set of CSS custom properties (“design tokens”) defined once at the top of crates/birdnet-web/static/css/app.css. Components read tokens; a colour or a pixel pad written into a rule is a defect unless this page says why it is allowed (see What stays literal). This page is the reference for what each token means and what value it carries in each theme.

Two principles govern them:

• Colours are OKLCH. OKLCH is perceptually uniform, so a hue stays the same “colour” as its lightness changes, and light/dark themes can be derived by moving lightness rather than re-picking hex values. The format is oklch(L C H) — lightness %, chroma, hue degrees — with an optional / alpha. Every colour in the stylesheet, the categorical chart palette included, is written that way, so a colour-blind-safety check runs on the exact values that ship (see Chart colours).
• The token set grows by decision, not by accident. New UI is built by composing existing tokens into new classes. Adding a token is a deliberate, reviewed design decision (see Adding or changing a token), and the gates below refuse a raw colour, shadow, radius, duration, curve, layer or on-ladder gap where a token exists.

At a glance

The stylesheet’s light block declares

app.css by the test below, so they cannot go stale; every other number on this page that describes the present is read from the stylesheet the same way.

Every token, drawn

Both pictures are rendered from the stylesheet the station serves, so they are the tokens and not a drawing of them. tools/visual-qa/token-swatches.mjs regenerates them; a token added to app.css appears without the script changing.

Themes

Tokens are defined for two themes, selected by the data-theme attribute on the :root element (set early by static/theme-guard.js to avoid a flash):

Because components only ever read tokens, switching data-theme reskins the whole UI with no per-component dark-mode CSS. A token that differs between the two blocks must also be listed in static/css/print.css, which forces the light values on paper (print_forces_every_theme_flipped_token.rs enforces it).

Colour — surfaces & lines

The greys that build the page: backgrounds, card surfaces, and dividers.

Colour — text

A four-step text hierarchy, brightest (most important) to faintest.

Colour — semantic hues

Four hue families carry meaning across the app, and the legacy names --success, --warning, --danger (below) say which: success is moss, warning is dawn, danger is rare, and information is its own cool blue so that “for your information” never reads as either “all is well” or “look at this”. Each has a base, a -soft tint (for fills/badges) and an -ink (for text/icons on a soft fill; --rare is dark enough to be its own ink).

Colour — confidence tiers

How sure the identifier was, painted the same way on every surface that shows it (the Today feed, species, recordings, the review and quarantine queues, the share page). One rule picks the tier — crates/birdnet-web/src/routes/pages/confidence.rs — and these tokens only say what each tier looks like.

The borderline edge follows the station’s own confidence cut-off: the cut-off plus ten points, never above 90. At a 70 % cut-off, 80–89 is mid and 70–79 is low; a strict station (85 % or more) has no mid tier. The scale never uses --rare: a detection the station accepted at 72 % is not a fault.

Colour — special surfaces

Colour — text on a filled surface

Two inks are fixed because the fill they sit on does not change between themes:

Elevation — shadows

Three elevations (and the rest of the family under More scales). Each layers a tight contact shadow, a long soft one and a hairline 0 0 0 0.5px ring so a card reads as lifted on both themes. The shadows are mixed from --shadow-tint (a warm brown on paper, a cool near-black on night), never from pure black, so a lifted card throws a shadow the colour of the page it sits on. The dark theme deepens them and switches the ring to a faint light edge, and the large one carries a one-pixel light along its top edge.

Focus & scrim

Radii

Borders

Spacing & density

Padding is derived from a single --density multiplier, so the operator’s density preference (Settings → General → Display) rescales the whole UI by changing one value rather than re-spacing every component.

--pad-* is the rhythm between blocks and inside cards, and it moves with density. The small gaps within a component — an icon beside its label, the cells of a calendar, the gap under an eyebrow — are optical adjustments to that component’s own size and must not move with density, so they have their own, fixed ladder. --space-N is N pixels. It is the set of values the stylesheet used most, not a modular scale. The odd in-between gaps (3, 5, 7, 9, 11, 13 px) are still written as literals where a component’s own optical balance depends on them; a new rule should use the nearer rung.

Typography — families

Self-hosted font stacks (no external font CDNs) with broad CJK / Devanagari fallbacks so localized common names render.

Typography — sizes

The stylesheet used to carry dozens of font-size values, half-pixel steps included. They are a scale now. The first six steps are UI text; the rest are the serif display steps. Sizes at or below 16 px were snapped to the nearest step (never by more than 0.8 px); larger one-off sizes (an icon glyph, a gauge numeral, a 404 code) stay literal and are listed under What stays literal.

Typography — weights and tracking

The stylesheet writes font-weight and letter-spacing as these, never as a number. Inter Tight ships 400, 500 and 600; 700 is the browser’s synthetic bold and is asked for in a handful of places only.

Motion

Three durations and two curves. prefers-reduced-motion (and the operator’s Motion setting) flatten every transition and animation at once, so none of these needs its own opt-out.

Layers

Only the stacking layers that must agree across components are tokens. A z-index of 0 or 1 inside a component’s own stacking context is local and stays a literal.

Chart colours

A chart does not borrow UI colours. The brand greens, ambers and reds mean accepted, attention and alert elsewhere on the page, and the dark theme’s --moss is a 78 % lime chosen to read as text on near-black, which on a bar or a band glows beside the grey text it labels. Charts have their own set, defined once for each theme and graded by arithmetic, not by eye (tests/the_chart_palette_can_be_told_apart.rs, and tools/visual-qa/tokens.mjs on the colours a real page paints).

Categorical (--chart-1 … --chart-8): which species, which source. Assign them in this order and never cycle: a ninth series is --chart-other, a neutral, and means “everything else”. The order is part of the palette, not a preference. It is the best of the 20 orderings (of the 5 040 that keep green first) that clear the gates in both themes: it opens with the brand colour and keeps every neighbouring pair apart for a reader who cannot tell red from green (OKLab ΔE of at least 8 under the Machado protan and deutan simulations; the worst pair measures 12.2) and for a reader who can (at least 15; the worst is 17.4). The dark column is the same eight hues stepped to the dark band (OKLCH lightness 0.48–0.67), not an automatic flip, so no mark needs a filter to show.

Amber (--chart-7) is 2.35:1 against a white card. Darkened to 3:1 it is brown, so it stays amber and every chart that draws it names the band in a legend, in the band’s tooltip and in a table; that exemption is listed by slot in the test, with the reason.

Sequential (--heat-lo, --heat-mid, --heat-hi): how much. One hue family (sand, orange, brick in light; brown, amber, gold in dark) with lightness that only goes one way, so a cell is darker the more it holds on paper and brighter the more it holds on night, and the ramp means the same thing in both. The lowest step is held at least 8 ΔE from an empty cell (--surface-2), or a cell with one detection reads as none, and the highest step is held 3:1 against the card.

Every chart reads these and nothing else: tests/the_chart_palette_can_be_told_apart.rs scans the chart renderers for a mark painted in --moss, --dawn, --rare, --info or --accent-rgb, or in a colour literal. The exceptions are named in the test, with a reason: the sun and moon glyphs on the day strip and the polar clock are the sun and the moon. A heat cell interpolates --heat-lo → --heat-mid → --heat-hi in OKLab and is drawn at full strength with no fill-opacity, so what is painted is what was graded. The one place that keeps its own ramp is the History calendar, which prints a day number on each cell and so uses a lighter, capped tint of --moss that keeps that number at 4.5:1.

Chart ramps and data ink

The categorical set above says which. These say how much, which side, and what a chart draws that is not data. A chart renderer reads these and nothing else (no --moss, no literal), so one change here retunes every chart.

Which ramp for which question

Interpolate between two steps in OKLab (color-mix(in oklab, var(--seq-5) 40%, var(--seq-4))), never in sRGB or OKLCH, which bend through grey or swing the hue. A ramp is graded by arithmetic, not by eye: tools/visual-qa/chart-ramps.mjs reads the shipped values and fails on a step that is not monotone in lightness, a step that is not 7 to 13 dE from its neighbour, a lowest step within 8 dE of an empty cell, a highest step under 3:1 on its card, the two diverging poles within 15 dE of each other under either colour-blind simulation, or a data-ink colour under its stated contrast.

How a renderer reads them

An SVG mark takes its colour from a class (the stylesheet, not a presentation attribute, so the theme can change it) or from a custom property set on the element through data-style. Never a literal, never --moss.

.my-grid   { stroke: var(--chart-grid); stroke-width: 1; }
.my-axis   { stroke: var(--chart-axis); stroke-width: 1; }
.my-label  { fill: var(--chart-label); font-size: var(--fs-2xs); }
.my-line   { stroke: var(--chart-1); stroke-width: var(--chart-stroke); fill: none; }
.my-bar    { fill: var(--chart-2); stroke: var(--chart-gap); stroke-width: var(--chart-gap-w); }
.my-dim    { opacity: var(--chart-dim); }          /* the marks that are not hovered */
/* A cell a quarter of the way from step 4 to step 5, as OKLab: */
.my-cell   { fill: color-mix(in oklab, var(--seq-5) 25%, var(--seq-4)); }
/* One value either side of a baseline: */
.my-up     { fill: var(--div-pos-2); }
.my-down   { fill: var(--div-neg-2); }

A tooltip is background: var(--chart-tip-bg); color: var(--chart-tip-fg); border: var(--bw-strong) solid var(--chart-tip-border), with --shadow-md under it. Text on a chart is never drawn in a series colour: the mark carries the identity, the label stays in --chart-label or --chart-annot.

Sequential (the sun ramp)

Light runs pale to brick, dark runs ember to gold: in both, the more a cell holds, the more it stands out from the card.

Sequential (the moss ramp)

Diverging

Data ink and mark anatomy

The rest of the ink is the same in both themes, or reads a token that already flips:

More scales

The scales the first sections do not cover: layered surfaces and tinted shadows, the rest of the radius, spacing, type and motion ladders, layers, the focus ring and density. Each table is generated from app.css by tools/visual-qa/token-doc.mjs, so a value here is the value the stylesheet has.

Surfaces

Shadows

A shadow is mixed from --shadow-tint, so a lifted card throws a warm shadow on paper and a cool one on night, never a grey smudge.

Radius

Edges

Spacing

Type

Motion

Layers

Focus

Icons

Density

Legacy aliases

A handful of tokens from before the v3 redesign are kept as aliases of the current set, so pre-redesign partials stay visually consistent without being rewritten. Prefer the modern token in new code.

One alias differs by theme, because amber is a fill and not a text colour:

--accent-rgb (a comma-separated RGB triple, listed above) is the one non-OKLCH value, kept for the few rules that still need rgba() with a variable alpha.

What stays literal

A literal is allowed when it is not a design choice that a theme or a density change should move. The clusters that remain, and why:

Adding or changing a token

The token set was closed by the v3 spine (protect list: “OKLCH token set: zero new tokens”), and was then opened once, on purpose, by a pass that measured what the stylesheet actually wrote (the numbers are in Known problems) and added the ramps, the layered surfaces, the tinted shadows, the rest of the motion, layer and radius ladders and the focus and density tokens. Each replaced a cluster of ad-hoc literals or described a thing the stylesheet could not yet say, rather than introducing a new idea. A refactor of the first kind is proven pure with tools/visual-qa/style-snapshot.mjs (snapshot every element’s computed style before, and after, from the same running fixture, and diff).

• Build new UI from existing tokens. Compose them into new CSS classes; that is the additive path and needs no token change.
• A genuinely new token is a design decision. Justify it in the PR, give it values for both themes when it is a colour (keep light and dark in lockstep), add it to this page in the same commit, and prefer extending a hue family (-soft / -ink) over inventing a new hue.
• A token whose value differs between the themes also goes in print.css.
• Mix a tint in oklab, never oklch. color-mix(in oklch, var(--moss) 16%, var(--surface)) interpolates hue, and a neutral has none (light --surface is oklch(100% 0 0), so hue 0; dark is 250): the amber tint came out pink (hue 10), the moss one brown (24), and in dark the warning toast was magenta (344). in oklab mixes the colour’s coordinates and has no hue to carry. A test refuses a new in oklch, and tools/visual-qa/tokens.mjs reads the hue of what each tinted surface paints.
• Never hard-code a colour or pad in a component — read the token, so a future theme or density change stays a one-line edit.