How to Use Tokens

Stable

Learn how to reference, apply, and override design tokens in your projects.

Token architecture

Tokens are organized in two layers:

Layer	Purpose	Example
Primitives	Raw values — the palette	`dark-cyan/80 = #315e59`
Semantic	Purpose-driven aliases	`background/brand/primary = {dark-cyan/80}`

Always use semantic tokens in components. Primitives exist only to feed semantic tokens — never reference them in UI code.

In Figma

Install the Tokens Studio plugin
Import tokens/tokens.updated.json from this repository
Apply tokens to layers via the Tokens Studio panel

The token file contains both Primitives and Semantic_colour sets. Enable both in Tokens Studio.

In CSS / Style Dictionary

Run Style Dictionary to generate platform-specific outputs:

npx style-dictionary build

This outputs CSS custom properties, JS/TS constants, and Swift color assets.

/* Generated CSS variables (example) */
:root {
  --color-background-brand-primary: #315e59;
  --color-text-primary: #3b3b3d;
  --color-border-default: #cccccc;
  --spacing-inline-md: 12px;
  --radius-sm: 4px;
}

Naming convention

Token names use / as a separator and follow this pattern:

{category}/{sub-category}/{variant}

Examples:

background/brand/primary — background colour, brand category, primary variant
input/border/focus — input-specific border, focus state
text/placeholder — text colour for placeholder content

Casing matters

Some tokens use capital first letters for legacy reasons: border/Default, icon/Primary, focus/Ring. Match exact casing when referencing tokens.

←

Design Principles

Contribution Workflow

→