Design tokens

Design tokens are named design decisions, such as colors, spacing and typography, stored as data so that every platform and application uses the same values.

A design token gives a name to a visual decision. The name color.action.primary says what the value is for. The value itself, a hex code, is stored once in a source file, usually JSON. A build step transforms that source into whatever each consumer needs: CSS custom properties for the web, constants for mobile platforms, variables for design tools.

Tokens are usually organized in layers:

• Base tokens hold the raw palette and scales, such as blue.600 or space.4.
• Semantic tokens describe a purpose and point to a base token, such as color.action.primary.
• Component tokens, used in some systems, tie a semantic token to a part of a component.

Example

:root {
  --color-action-primary: #12705f;
  --space-md: 16px;
}

.button-primary {
  background: var(--color-action-primary);
  padding: var(--space-md);
}

A rebrand or a dark theme changes the token values. The component code stays the same.

Common misunderstanding

Tokens are often equated with CSS variables. A CSS variable is one output format of a token. The token is the named decision and its place in the hierarchy. A file with hundreds of variables named after their values, such as --blue-500, used directly in components, gives little of the benefit. A theme change would still mean editing every component.

For a platform or a migration, tokens are the cheapest form of visual consistency. CSS custom properties work in AngularJS templates, in Angular components and inside Shadow DOM. The legacy application and the new one can look the same before they share a single component. More on this in micro-frontends.

Related terms

• Design system
• Web components (custom elements)