# Tokens

Custom properties for colour, type, spacing and radii, in two tiers.

Design tokens are CSS custom properties, all prefixed `--govbb-`. They ship
inside the design system stylesheet (there is no separate token package)
and every component style resolves to them. Use them in your own CSS so your
service stays consistent with the components, and picks up palette changes
automatically when the system updates.

The tables on this page are generated from the design system's `tokens.css`
at build time, so the values shown are always the values that ship.

## Two tiers

Tokens come in two tiers, and the tier tells you whether you should reach for
one.

**Primitives** mirror the Figma variable ramp: the raw palette, named by hue
and step, such as `--govbb-blue-40`, `--govbb-teal-80` or `--govbb-red-10`.
Each colour family runs from a dark `00` shade through pale tints (`10`, `40`)
to the saturated `100`. Primitives say what a colour _is_, not what it is
_for_, so treat them as the source the semantic tier resolves to rather than
something to use directly.

**Semantic tokens** are the small tier built on top. Each one names a job
(`--govbb-color-brand`, `--govbb-color-error`, `--govbb-color-interactive`)
and aliases the primitive that currently does that job. Prefer these: if the
palette is retuned, the semantic name keeps meaning the right thing and your
CSS needs no changes.

## How tokens build a component

The real button, annotated. Each callout is a token its stylesheet actually
references, and the fill resolves through the semantic tier to one primitive.
Pick a new value for `--govbb-teal-80` and the button, the callout, and every
other component on the same tokens follow. No component CSS changes.

[View the interactive token example](/styles/tokens/#how-tokens-build-a-component).

## Using tokens

Import the stylesheet once. Everything else is plain CSS.

```js
import '@govtech-bb/frontend/css';
```

If you are not using a bundler, link the built file (`dist/govbb.css`) in your
page `<head>` instead. The tokens are declared on `:root`, so any rule on the
page can use them:

```css
.app-panel {
  background: var(--govbb-color-highlight);
  padding: var(--govbb-space-m);
  border-radius: var(--govbb-radius);
}
```

## Semantic colour tokens

These are the colour tokens to build with. The [Colour](/styles/colour/) page
documents the full primitive ramp each one resolves to.

Semantic colour tokens

| Token | Declared value | Resolved value | Notes |
| --- | --- | --- | --- |
| `--govbb-color-brand` | `var(--govbb-blue-40)` | `#00267f` | ultramarine |
| `--govbb-color-brand-accent` | `var(--govbb-yellow-40)` | `#ffc726` | gold |
| `--govbb-color-ink` | `var(--govbb-black-00)` | `#000` |  |
| `--govbb-color-surface` | `var(--govbb-white-00)` | `#fff` |  |
| `--govbb-color-muted` | `var(--govbb-grey-70)` | `#595959` |  |
| `--govbb-color-interactive` | `var( --govbb-teal-80 )` | `#0e5f64` | primary action, checked fill |
| `--govbb-color-interactive-active` | `var(--govbb-teal-90)` | `#0a4549` |  |
| `--govbb-color-focus` | `var(--govbb-teal-40)` | `#30c0c8` | focus ring |
| `--govbb-color-focus-danger` | `var(--govbb-red-40)` | `#ff6b6b` |  |
| `--govbb-color-error` | `var(--govbb-red-80)` | `#a42c2c` | invalid state |
| `--govbb-color-neutral` | `var(--govbb-grey-20)` | `#e0e4e9` | secondary fill, dividers |
| `--govbb-color-highlight` | `var(--govbb-blue-10)` | `#e5e9f2` | selected surfaces |
| `--govbb-color-tertiary` | `var(--govbb-green-80)` | `#00654a` | tertiary action |

`--govbb-color-interactive-active` is the one semantic token with its own
value (a darkened interactive teal) rather than a primitive alias.

## Type tokens

The typeface stack and the size ramp. The [Typography](/styles/typography/)
page pairs each size with its line height and shows the `.govbb-text-*`
utility classes that apply them.

Font stack token

| Token | Declared value | Resolved value | Notes |
| --- | --- | --- | --- |
| `--govbb-font-sans` | `'Figtree', system-ui, -apple-system, 'Segoe UI', 'Roboto', 'Helvetica', 'Arial', sans-serif` | `'Figtree', system-ui, -apple-system, 'Segoe UI', 'Roboto', 'Helvetica', 'Arial', sans-serif` |  |

Font size tokens

| Token | Declared value | Resolved value | Notes |
| --- | --- | --- | --- |
| `--govbb-font-size-display` | `5rem` | `5rem` | 80px |
| `--govbb-font-size-h1` | `3.5rem` | `3.5rem` | 56px |
| `--govbb-font-size-h2` | `2.5rem` | `2.5rem` | 40px |
| `--govbb-font-size-h3` | `1.75rem` | `1.75rem` | 28px |
| `--govbb-font-size-h4` | `1.25rem` | `1.25rem` | 20px |
| `--govbb-font-size-body-lg` | `1.5rem` | `1.5rem` | 24px |
| `--govbb-font-size-body` | `1.25rem` | `1.25rem` | 20px |
| `--govbb-font-size-body-sm` | `1rem` | `1rem` | 16px |

## Spacing tokens

A single rem-based scale, from `xxs` to `xl`. See [Spacing](/styles/spacing/)
for how to apply it.

Spacing tokens

| Token | Declared value | Resolved value | Notes |
| --- | --- | --- | --- |
| `--govbb-space-xxs` | `0.25rem` | `0.25rem` | 4px |
| `--govbb-space-xs` | `0.5rem` | `0.5rem` | 8px |
| `--govbb-space-s` | `1rem` | `1rem` | 16px |
| `--govbb-space-xm` | `1.5rem` | `1.5rem` | 24px |
| `--govbb-space-m` | `2rem` | `2rem` | 32px |
| `--govbb-space-ml` | `3rem` | `3rem` | 48px |
| `--govbb-space-l` | `4rem` | `4rem` | 64px |
| `--govbb-space-xl` | `8rem` | `8rem` | desktop-frame page gutter; 128px |

## Radius and form tokens

Rounded corners, form-control borders and form states.

Radius token

| Token | Declared value | Resolved value | Notes |
| --- | --- | --- | --- |
| `--govbb-radius` | `4px` | `4px` |  |

Form state tokens

| Token | Declared value | Resolved value | Notes |
| --- | --- | --- | --- |
| `--govbb-border-width-form` | `2px` | `2px` |  |
| `--govbb-opacity-disabled` | `0.4` | `0.4` |  |
| `--govbb-shadow-form-hover` | `inset 4px 4px 0 0 var(--govbb-overlay-dark-10)` | `inset 4px 4px 0 0 var(--govbb-overlay-dark-10)` |  |