| name | write-design-system-token |
| description | Use when defining, naming, or documenting design tokens for a design system to ensure consistent visual decisions across platforms |
| source | W3C Design Tokens Community Group specification (2023); Salesforce Lightning Design System; Figma Token Studio documentation |
| tags | ["design-tokens","design-system","tokens","theming","css-variables","component-design"] |
| verified | true |
Write Design System Token
Define design tokens with clear naming, semantic layers, and platform-ready output so design decisions are consistent and themeable.
Why This Is Best Practice
Adopted by: Salesforce Lightning, IBM Carbon, Adobe Spectrum, GitHub Primer, Atlassian Design System
Impact: Spotify reported a 60% reduction in design inconsistency across platforms after adopting a structured token layer; the W3C Design Tokens format (.tokens.json) is becoming the cross-tool standard for Figma→code pipelines
Why best: Tokens transform design decisions from hardcoded values scattered across codebases into a single source of truth. Without a semantic layer, changing a brand color requires touching thousands of individual components instead of one token value.
Steps
- Define the primitive layer — Create raw value tokens with no semantic meaning. These are named for what they are:
color-blue-500: #2563EB, spacing-4: 16px, font-size-base: 16px. Never use these tokens directly in components.
- Define the semantic layer — Create tokens that reference primitives and carry meaning:
color-action-primary: {color-blue-500}, space-component-padding: {spacing-4}. Components consume semantic tokens, not primitives.
- Define component tokens (optional) — For large systems, add a third layer:
button-background-default: {color-action-primary}. This allows component-level overrides without breaking the semantic layer.
- Name tokens using the pattern —
[category]-[concept]-[variant]-[state]: color-text-primary, color-text-secondary, color-border-focus, space-inset-md. Avoid color names in semantic tokens (color-blue not allowed at semantic level).
- Document the decision — For each token, record: the problem it solves, which components use it, and what must change to update it. A token without documentation is a mystery to the next designer.
- Output platform formats — Use Style Dictionary or Token Studio to transform tokens into CSS custom properties, iOS Swift constants, Android XML, and JSON. One source, many targets.
- Version and publish — Store tokens in a shared repository. Publish changes with semantic versioning. Breaking changes (renames, deletions) are major version bumps; additions are minor.
Rules
- Components must only consume semantic tokens, never primitive tokens directly.
- Token names must describe usage (purpose), not appearance (value).
color-danger not color-red.
- Every token value must be traceable back to a primitive via a reference chain — no hardcoded values in semantic or component layers.
- Rename tokens with a deprecation period, not immediate deletion — consumers need migration time.
- Tokens and components must be versioned together; a component shipped without token updates is a breaking change.
Examples
Salesforce Lightning tokens:
- Primitive:
color-palette-brand-dark: #0176D3
- Semantic:
color-brand: {color-palette-brand-dark}
- Component:
button-color-brand: {color-brand}
A brand update changes color-palette-brand-dark to #0154A5 — every component consuming button-color-brand updates automatically.
Common Mistakes
- Semantic tokens named after values —
color-blue-primary breaks when the brand changes to green; semantic tokens must describe intent, not appearance.
- Skipping the semantic layer — Components consuming primitives directly means a brand refresh requires updating every component individually.
- No tooling for output — Hand-maintaining CSS variables and iOS Swift files from the same source diverges within weeks; automation is not optional.
