Using tokens in code

Design tokens are published as CSS custom properties (variables). Every token in the system has a corresponding --token-* variable that you can reference in any stylesheet or component.

CSS

Reference tokens using var():

.button-primary {
  background: var(--token-color-action-primary);
  padding: var(--token-spacing-md);
  border-radius: var(--token-border-radius-md);
}

Avoid hard-coding raw values. Even if you know the hex code today, it won't automatically update when the theme or brand changes.

/* Avoid */
.button-primary {
  background: #175AB2;
  padding: 6px;
}

JavaScript / TypeScript

You can read a token value at runtime by resolving it from the document's computed styles:

const value = getComputedStyle(document.documentElement)
  .getPropertyValue('--token-color-action-primary')
  .trim();

For static references (e.g. passing a value into a JS animation library), import the token map directly:

import tokens from '@site/src/data/tokens/mode.json';

const primary = tokens.variables.find(t => t.name === 'light/fg/interactive/selected');

Naming pattern

Token CSS variable names follow the structure of the token path, with slashes replaced by hyphens and prefixed with --:

Token name	CSS variable
color/action/primary	--token-color-action-primary
spacing/md	--token-spacing-md
border/radius/md	--token-border-radius-md

When to use tokens vs hard-coded values

Use tokens when:

• Defining colors, spacing, typography, radius, or shadow in UI components.
• The value should change with theme (e.g. light/dark) or brand.
• The value is shared across multiple components or screens.

Hard-coding is acceptable when:

• The value is purely presentational and will never be themed (e.g. a one-off illustration size).
• The value is a layout constant specific to a single page and has no design-system meaning.

Figma source

Tokens are maintained as Figma variables and exported as JSON via the token conversion scripts in /scripts/. The CSS variables in src/css/design-tokens.css are generated from that same JSON, so Figma, JSON, and CSS all stay in sync.