Design tokens are the smallest decisions in a design system. A color value. A spacing unit. A font weight. Individually, they are trivial. Collectively, they define the entire visual language of a product.
What Are Design Tokens
A design token is a named value that represents a design decision. Instead of using #1c1917 directly in your code, you use --foreground. Instead of 0.75rem, you use --space-3.
This indirection serves two purposes:
- Consistency - Every use of
--foregroundis guaranteed to be the same value - Flexibility - Changing the value of
--foregroundupdates it everywhere simultaneously
The Token Hierarchy
Not all tokens are created equal. A well-structured token system has three layers:
Primitive tokens are raw values with descriptive names. --gray-9 is a primitive token. It describes what the value is, not how it should be used.
Semantic tokens map primitives to purposes. --foreground is a semantic token. It describes the role the value plays in the interface.
Component tokens are scoped to specific components. --button-bg is a component token. It allows individual components to diverge from the global system when necessary.
Why This Matters
The real power of tokens emerges when you need to support multiple themes, brands, or platforms.
Consider dark mode. Without tokens, implementing dark mode means finding and replacing hundreds of color values across your entire codebase. With tokens, it means redefining a few dozen semantic tokens.
:root {
--foreground: oklch(0.15 0.005 80);
--background: oklch(0.99 0.002 80);
}
.dark {
--foreground: oklch(0.93 0.003 80);
--background: oklch(0.13 0.003 80);
}
Two declarations. Every element in the interface updates automatically.
Naming Conventions
Token naming is deceptively important. A few principles:
- Be descriptive, not prescriptive -
--space-3is better than--space-mediumbecause "medium" is relative and will change - Use scales - Numbered scales (1-12) provide clear ordering without implying specific use cases
- Separate what from why - Primitive tokens describe what (
--gray-9), semantic tokens describe why (--muted-fg)
The Adoption Challenge
The hardest part of design tokens is not the technical implementation. It is getting people to use them consistently. Every hardcoded value is a token that should exist but does not.
The solution is tooling. Linters that flag raw values. Autocomplete that suggests token names. Documentation that makes the right choice easier than the wrong one.
Design tokens are not glamorous. They do not show up in portfolio pieces or design awards. But they are the foundation that makes everything else possible.