Tokens - GovBB Design System

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-100, --govbb-teal-00 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-00 and the button, the callout, and every other component on the same tokens follow. No component CSS changes.

Set --govbb-teal-00 to

Demo only: nothing ships.

Using tokens

Import the stylesheet once. Everything else is plain CSS.

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:

.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 page documents the full primitive ramp each one resolves to.

Token	Resolves to	Value	Use for
`--govbb-color-brand`	`--govbb-blue-100`	`#00267f`	ultramarine
`--govbb-color-brand-accent`	`--govbb-yellow-100`	`#ffc726`	gold
`--govbb-color-ink`	`--govbb-black-00`	`#000`
`--govbb-color-surface`	`--govbb-white-00`	`#fff`
`--govbb-color-muted`	`--govbb-mid-grey-00`	`#595959`
`--govbb-color-interactive`	`--govbb-teal-00`	`#0e5f64`	primary action, checked fill
`--govbb-color-interactive-active`	`--govbb-teal-05`	`#0a4549`
`--govbb-color-focus`	`--govbb-teal-100`	`#30c0c8`	focus ring
`--govbb-color-focus-danger`	`--govbb-red-100`	`#ff6b6b`
`--govbb-color-error`	`--govbb-red-00`	`#a42c2c`	invalid state
`--govbb-color-neutral`	`--govbb-grey-00`	`#e0e4e9`	secondary fill, dividers
`--govbb-color-highlight`	`--govbb-blue-10`	`#e5e9f2`	selected surfaces
`--govbb-color-tertiary`	`--govbb-green-00`	`#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 page pairs each size with its line height and shows the .govbb-text-* utility classes that apply them.

Token	Value
`--govbb-font-sans`	`'Figtree', system-ui, -apple-system, 'Segoe UI', 'Roboto', 'Helvetica', 'Arial', sans-serif`

Preview	Token	Value
Aa	`--govbb-font-size-display`	`5rem` 80px
Aa	`--govbb-font-size-h1`	`3.5rem` 56px
Aa	`--govbb-font-size-h2`	`2.5rem` 40px
Aa	`--govbb-font-size-h3`	`1.5rem` 24px
Aa	`--govbb-font-size-h4`	`1.25rem` 20px
Aa	`--govbb-font-size-body-lg`	`2rem` 32px
Aa	`--govbb-font-size-body`	`1.25rem` 20px
Aa	`--govbb-font-size-caption`	`1rem` 16px
Aa	`--govbb-font-size-caption-sm`	`0.75rem` 12px

Spacing tokens

A single rem-based scale, from xxs to xl. See Spacing for how to apply it.

Token	Value	Use for
`--govbb-space-xxs`	`0.25rem` 4px
`--govbb-space-xs`	`0.5rem` 8px
`--govbb-space-s`	`1rem` 16px
`--govbb-space-xm`	`1.5rem` 24px
`--govbb-space-m`	`2rem` 32px
`--govbb-space-l`	`4rem` 64px	placeholder pending Figma confirmation
`--govbb-space-xl`	`8rem` 128px	desktop-frame page gutter

Radius and form tokens

Rounded corners, form-control borders and form states.

Preview	Token	Value
	`--govbb-radius`	`4px`

Token	Value
`--govbb-border-width-form`	`2px`
`--govbb-opacity-disabled`	`0.4`
`--govbb-shadow-form-hover`	`inset 4px 4px 0 0 var(--govbb-overlay-dark-10)`