Hardcoded values like #3b82f6 or 16px scattered through your codebase cause color drift, rebranding headaches, and design-dev mismatches. Design tokens solve this by centralizing values like colors, spacing, and typography under named variables.
Why Use Design Tokens?
- Consistency: One source of truth prevents color drift across a large codebase.
- Rebranding: Change a few token values to update the entire visual identity.
- Design-Dev Parity: Designers and developers use the same token names.
- Multi-Platform: One token set can generate CSS, iOS, Android, and other formats.
Token Types
-
Primitive Tokens: Raw values like
--blue-500: #3b82f6; -
Semantic Tokens: Purpose-based aliases like
--color-primary: var(--blue-500); - Component Tokens: (Optional) Specific to individual components
Implementing Tokens in Tailwind
1. Define CSS Custom Properties
/* globals.css */
:root {
--color-primary: 37 99 235; /* blue-600 in RGB */
--radius-md: 0.375rem;
}
.dark {
--color-primary: 96 165 250; /* blue-400 for dark mode */
}
2. Map Tokens to Tailwind Theme
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
primary: `rgb(var(--color-primary) / <alpha-value>)`,
},
borderRadius: {
md: 'var(--radius-md)',
},
},
},
};
3. Use in Components
function Button() {
return (
<button className="bg-primary rounded-md px-4 py-2">
Click me
</button>
);
}
Key Gotchas
- Start small: Begin with 20-30 tokens, not 300.
-
Use semantics: Always alias primitives (
--color-primary: var(--blue-600)) -
Document purpose: Unclear names like
--color-accentcause confusion - Align design/code: Use the same token names in Figma and code
Tokens enable dark mode, accessibility features, and multi-platform styling when implemented properly. The pattern works best when combined with a utility-first framework like Tailwind.
This is a shorter version of a guide I wrote at Frontkit Studio. The full post has the complete walkthrough.
Top comments (0)