Getting Started with Tokens

What are tokens?

Design tokens are the single source of truth for Checkatrade’s visual language. They live in the @checkatrade/tokens package and are distributed as CSS custom properties — covering colour, typography, spacing, border radius, and semantic aliases.

Installation

npm install @checkatrade/tokens

Importing the tokens

Import the token CSS once at the root of your app — for example in your global stylesheet or app entry point:

import '@checkatrade/tokens/css';

This makes every --color-*, --typography-*, --spacing-*, and --border-radius-* variable available globally.

Using tokens in Tailwind v4

Map a token to a Tailwind utility in an @theme block in your global CSS:

@theme inline {
  --color-brand: var(--color-background-action-brand-primary);
}

Once mapped, use it as a standard Tailwind utility: text-brand.

Typography utilities don’t need hand-written aliases like this. @checkatrade/components-web generates a full set of @utility classes (text-header-md, text-body-md, text-headline-sm, …) directly from @checkatrade/tokens, so importing that stylesheet is enough:

@import '@checkatrade/tokens/css';
@import '@checkatrade/components-web/css';
@import 'tailwindcss';
@source '@checkatrade/components-web/src';

<p className="text-body-md">Body copy, no alias required.</p>

Each class carries font-family, font-size, font-weight, and line-height together — there’s no separate family/weight class to combine it with.

Using tokens directly in CSS

You can reference any token directly without Tailwind:

.my-component {
  color: var(--color-ink-body-default);
  font-size: var(--typography-body-font-size-md);
  padding: var(--spacing-1);
}

Available token groups

Group	Prefix	Example
Colour	--color-*	--color-ink-body-default
Typography	--typography-*	--typography-body-font-size-md
Spacing	--spacing-*	--spacing-1
Border radius	--border-radius-*	--border-radius-md

See the Colours, Typography, and Spacing pages for the full token reference.