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.
