Skip to main content
BM

Back to Design System

Tokens

Every design token behind this site, and how they reach the page.

On this page

How a value reaches the page: a primitive holds it, a semantic token names its purpose (and picks a primitive per theme), a component token styles one part, and the component reads only its own tokens.

  1. Primitive 143 tokens

    Raw values, named by scale. Never used directly.

  2. Semantic 131 tokens

    Named by purpose. Each aliases one primitive, and themes override them.

    color.action.backgroundLight #b37500, Dark #f5e3c2

  3. Component 350 tokens

    One component's styling hooks. Each aliases one semantic token, in every theme.

    component.button.primary.backgroundaliases color.action.background

  4. Site

    Components read only their own tokens.

    Button

Naming

A token's name is a dotted path: its category, a group, then the name, as in color.text.muted. Semantic and component tokens are CSS custom properties named by the same path, with each dot as a dash: --color-text-muted. Primitives never become custom properties.

Each tier has one rule:

  • Primitive: Raw values, named by scale. Never used directly.
  • Semantic: Named by purpose. Each aliases one primitive, and themes override them.
  • Component: One component's styling hooks. Each aliases one semantic token, in every theme.

Theming

The theme menu offers System, which follows the device's setting, Light and Dark. Themes override semantic tokens only: 52 of them have a light and a dark value. Primitives and component tokens never change, and since every component token aliases a semantic one, a theme reaches every component.

Any element can set its own theme with data-theme="light" or data-theme="dark", and every token inside it follows, as in the component pages' preview panels.

When the device asks for reduced motion, the 4 motion.duration tokens are overridden, so transitions are instant.

Usage

Use semantic tokens in a page's own CSS:

CSS
.note {
  color: var(--color-text-muted);
  padding: var(--space-inset-md);
}

To restyle a component, override its --component-* tokens on a wrapper class. Each component page lists its tokens.

CSS
.brand {
  --component-button-primary-background: var(--color-accent-text);
  --component-button-primary-border: var(--color-accent-text);
}

Accessibility

Each foreground token declares the backgrounds it must be readable on, and the minimum contrast it needs there: 4.5:1 for text, 3:1 for large text and 3:1 for borders and icons (WCAG 2.2 AA). A unit test measures all 275 declared pairings in both the light and the dark theme, so a token change that breaks one fails the tests.

Another test checks that reduced motion overrides every motion.duration token.

Find a token

Name, variable, value or description

Primitives

Raw values, named by scale. Never used directly.

Semantic

Named by purpose. Each aliases one primitive, and themes override them.

Component

One component's styling hooks. Each aliases one semantic token, in every theme.