Tokens

Where tokens live

The single source of truth is /src/styles/design-tokens.css (declared under :root). Global styling consumes these tokens from /src/styles/global.css and component styles use them via var(--token-name).

Rule of thumb

• Add tokens in design-tokens.css.
• Use tokens everywhere else.

How to use tokens

Use tokens via CSS custom properties.

Examples

.card {
  background: var(--limestone);
  color: var(--gloaming);
  border-radius: var(--border-radius-sm);
  padding: var(--space-xl);
}

.card:hover {
  transition: opacity var(--transition-fast);
}

Using a token as an inline style

<div style="background: var(--limestone-dark)">...</div>

Colour tokens

Colours are expressed as scale tokens (e.g. --fire-500) plus a small set of semantic aliases (e.g. --fire, --fire-dark, --fire-extra-dark).

Examples

color: var(--gloaming-dark);
background: var(--sunshine);
border-color: var(--limestone-extra-dark);

Semantic mappings

Some tokens exist specifically for “what” something is rather than “which colour”. For example:

color: var(--color-text-primary);
background: var(--color-bg-body);

Typography tokens

Typography is driven by a base font size plus a responsive multiplier (--text-multiplier). A few modifiers change scale for specific blocks (for example utility classes on the Utilities page).

Common tokens

• --font-body, --font-heading, --font-heading-display, --font-mono
• --base-font-size, --text-multiplier
• --line-height-normal, --line-height-relaxed

Example

.intro {
  font-family: var(--font-body);
  line-height: var(--line-height-relaxed);
  font-size: calc(1.1em * var(--text-multiplier));
}

Spacing tokens

Spacing tokens are expressed in rem and named from --space-xs up to --space-6xl.

Example

.section {
  padding: var(--space-4xl) var(--page-padding);
  margin-bottom: var(--space-3xl);
}

Layout tokens

Layout tokens describe container widths and page padding. The most commonly used are:

• --container-max-width
• --content-max-width
• --page-padding

Example

.container {
  max-width: var(--container-max-width);
  margin: 0 auto;
  padding: 0 var(--page-padding);
}

Textures

Textures are stored as CSS variables that resolve to url(...). Components typically opt into a texture by setting a background image using these tokens (sometimes with a matching “size” token).

Example

.textured {
  background-image: var(--texture-watercolour);
  background-size: var(--texture-watercolour-size);
  background-repeat: repeat;
}

Motion and timing

Animation and transition timings are standardised as duration tokens.

Example

.link {
  transition: opacity var(--transition-fast);
}

Z-index and breakpoints

Z-index values are declared as named tokens (--z-*). Breakpoints are included as reference values (--breakpoint-*).

Notes

• Z-index tokens are intended for consistent layering.
• Breakpoint tokens cannot be used directly in media queries, but are useful as documentation and for calculations.

Token types in TypeScript

Some token families are also represented as TypeScript union types for better autocomplete and safety in components. These live in /src/types/design-tokens.ts (for example ColorScheme, BorderStyle, and layout-related unions).

Example

import type { ColorScheme } from '../types/design-tokens';