Create a scalable design token system using CSS custom properties that works across any framework.
What Are Design Tokens
Design tokens are the smallest pieces of your design system — colors, spacing, typography, shadows. Instead of hardcoding #8B5CF6 everywhere, you define --color-primary once and reference it.
Start with CSS Custom Properties
CSS custom properties (variables) are the simplest way to implement tokens. No build tools required, works everywhere.
:root {
--color-primary: #8B5CF6;
--color-bg: #0a0a0a;
--space-sm: 0.5rem;
--space-md: 1rem;
--radius-md: 0.75rem;
}
Organize by Category
Group tokens into clear categories:
- Colors: primary, secondary, surface, border, text
- Spacing: consistent scale (4px base, or 0.25rem increments)
- Typography: font families, sizes, weights, line heights
- Borders: radii, widths
- Shadows: elevation levels
- Motion: durations, easing functions
Semantic Tokens
Raw values like --blue-500 are primitive tokens. Layer semantic tokens on top:
:root {
--blue-500: #3b82f6;
--color-interactive: var(--blue-500);
--color-interactive-hover: var(--blue-600);
}
This lets you change the interactive color globally by updating one variable.
Dark Mode with Tokens
Tokens make theming trivial. Override the same variable names under a different selector:
[data-theme="dark"] {
--color-bg: #0a0a0a;
--color-text: #e5e5e5;
}
Components reference the same token names — the values just change.
Framework Integration
Whether you use React, Vue, or plain HTML — CSS custom properties work the same. Tailwind v4 even lets you define your tokens as CSS variables directly.
Scaling the System
Start small. Five colors, four spacing values, two font sizes. Add tokens only when you need them. An over-designed token system that nobody remembers is worse than a small one that covers 90% of cases.