Design tokens are the visual atoms of a design system—named entities that store visual design attributes. They enable consistency and scalability across products and platforms.
What are Design Tokens?
Design tokens are variables that hold design values like colors, spacing, typography, and more.
json
{
"color": {
"brand": {
"primary": { "value": "#0066CC", "type": "color" },
"secondary": { "value": "#00CC99", "type": "color" }
},
"neutral": {
"gray": { "value": "#666666", "type": "color" }
}
},
"spacing": {
"small": { "value": "8px", "type": "dimension" },
"medium": { "value": "16px", "type": "dimension" },
"large": { "value": "24px", "type": "dimension" }
},
"font-size": {
"base": { "value": "16px", "type": "font-size" },
"lg": { "value": "18px", "type": "font-size" }
}
}Benefits
- Consistency: Same values across platforms
- Scalability: Update once, apply everywhere
- Maintainability: Single source of truth
- Platform Agnostic: Use in any tech stack
Implementation
Style Dictionary
json
// tokens/color.json
{
"color": {
"brand": {
"primary": {
"value": "#0066CC",
"type": "color",
"description": "Primary brand color"
}
}
}
}javascript
// style-dictionary.config.js
const StyleDictionary = require('style-dictionary').extend({
source: ['tokens/**/*.json'],
platforms: {
scss: {
transformGroup: 'scss',
buildPath: 'build/scss/',
files: [{
destination: '_variables.scss',
format: 'scss/variables'
}]
},
js: {
transformGroup: 'js',
buildPath: 'build/js/',
files: [{
destination: 'variables.js',
format: 'javascript/es6'
}]
}
}
});
StyleDictionary.buildAllPlatforms();CSS Variables
css
/* tokens.css */
:root {
--color-brand-primary: #0066CC;
--color-brand-secondary: #00CC99;
--spacing-small: 8px;
--spacing-medium: 16px;
--font-size-base: 16px;
}
/* Usage */
.button {
background-color: var(--color-brand-primary);
padding: var(--spacing-medium);
font-size: var(--font-size-base);
}React Context
typescript
// DesignTokenContext.tsx
import React, { createContext, useContext } from 'react';
interface DesignTokens {
colors: {
primary: string;
secondary: string;
};
spacing: {
small: string;
medium: string;
};
}
const DesignTokenContext = createContext<DesignTokens | null>(null);
export function DesignTokenProvider({ tokens, children }) {
return (
<DesignTokenContext.Provider value={tokens}>
{children}
</DesignTokenContext.Provider>
);
}
export function useDesignTokens() {
const tokens = useContext(DesignTokenContext);
if (!tokens) {
throw new Error('useDesignTokens must be used within DesignTokenProvider');
}
return tokens;
}Best Practices
- 1Use semantic naming
- 2Document token purpose
- 3Group related tokens
- 4Version your tokens
- 5Use token aliases
- 6Test token updates
Conclusion
Design tokens are the foundation of scalable design systems. Start with core tokens and expand systematically.