Design tokens: what they are and how to use them

A design token is a named variable that stores a design value. Instead of writing #1A73E8 directly in your CSS or in Figma, you define a token called color-primary whose value is #1A73E8. That token becomes the contract between design and development.

The concept was popularised by Salesforce with their Lightning Design System and has since been adopted by virtually every major design system. In 2024, the W3C Community Group published the Design Tokens Format Module specification, standardising the way tokens are defined in JSON.

Tokens are organised into categories that reflect the different dimensions of visual design. Each category has its own conventions and scales.

The most effective token architecture uses three tiers. Primitives define raw values (blue-600 = #1A73E8). Semantics assign intent (color-primary = blue-600). Component tokens apply values to a specific context (button-bg-primary = color-primary).

This hierarchy allows you to change a brand colour by updating a single semantic token instead of editing dozens of components. It is also the key to supporting dark mode: you redefine the semantic tokens for the dark theme and every component adapts automatically.

Good naming is the difference between an intuitive token system and one nobody understands. The most widespread convention uses kebab-case with a category-property-variant-state structure. For example: color-text-primary, spacing-inline-md, shadow-elevation-high.

Avoid names that describe the value instead of the intent. color-blue-500 is a valid primitive token, but as a semantic token it is fragile: if the brand shifts from blue to green, the name no longer makes sense. Use color-brand-primary instead.

The token workflow involves defining them in a centralised format (usually JSON or YAML), transforming them to each platform’s format (CSS custom properties, SCSS, Swift, Kotlin, XML) and syncing them between design tools and code.

The real power of design tokens emerges in projects spanning multiple platforms. You define tokens once in a neutral format and automatically transform them to CSS custom properties for the web, UIColor for iOS, ColorRes for Android, and whatever other format you need.

This ensures that a brand colour change propagates to every platform with a single commit. Without tokens, the same change would require coordinating manual updates across each team and each repository, with the inherent risk of inconsistencies.

The most common mistake is creating too many tokens too early. A system with 500 tokens from day one is unmanageable. Start with the tokens that cover 80% of your use cases and only add new ones when there is a real, recurring need.

Another frequent error is failing to distinguish between primitive and semantic tokens. If developers reference blue-500 directly instead of color-primary, you lose the ability to make global changes. Establish this rule from day one and enforce it with linting.