We built an enterprise application last year with 47 screens. Three developers worked on the frontend. By the time we shipped, the primary blue was slightly different on six screens, the border radius varied between 4px and 8px depending on who built the component, and the spacing between form elements was whatever each developer thought looked right. The application worked. It just didn't feel like one application. It felt like three developers had each built their own version of the same idea.
What You Need to Know
- Design tokens are named values (colours, spacing, typography, radius) that replace hardcoded CSS values
- They create a single source of truth for visual decisions across an entire application
- Tokens work across platforms - web, iOS, Android - from a single definition
- For enterprise applications with many screens and many contributors, tokens are the difference between coherent and chaotic
What Design Tokens Are
A design token is a named variable that stores a design decision. Instead of writing
color: #2563EB, you write color: var(--color-primary). Instead of padding: 16px, you write padding: var(--space-4).The names describe the intent, not the value.
--color-primary is meaningful. #2563EB is not. When you read var(--color-primary), you know why that colour was chosen. When you read #2563EB, you know nothing about the decision behind it.47%
of design system adopters report design tokens as the most impactful single component
Source: Sparkbox Design Systems Survey, 2020
The Token Hierarchy
Tokens work in layers.
Global tokens define the raw values.
--blue-600: #2563EB. These are the palette. They don't describe intent.Semantic tokens map intent to global tokens.
--color-primary: var(--blue-600). These describe why a value is used. The primary colour happens to be blue-600, but the decision is captured in the semantic name.Component tokens map component-specific decisions to semantic tokens.
--button-background: var(--color-primary). These localise decisions to components without hardcoding values.This hierarchy means that changing the primary colour from blue to green requires updating one global token. Every semantic reference updates automatically. Every component inherits the change. In a 47-screen application, that's one edit instead of hunting through 200 CSS files.
Why Enterprise Needs Tokens
Multiple Contributors
Enterprise applications are built by teams, not individuals. Over months and years, different developers make different visual decisions. Without tokens, each decision is embedded in the code as a hardcoded value. Nobody remembers why
padding: 12px was used here and padding: 16px there. With tokens, the system enforces consistency. var(--space-3) and var(--space-4) are deliberate choices with names that communicate intent.Theme Support
Enterprise clients increasingly need dark mode, high-contrast mode, or brand-specific themes. Without tokens, theming means duplicating CSS and changing values throughout. With tokens, you swap the token values and every component updates. The dark mode definition is a set of token overrides, not a parallel stylesheet.
Multi-Platform Consistency
If your enterprise application has a web version and a mobile version, tokens can be exported to platform-specific formats. The same
--color-primary becomes a CSS variable on web, a colour asset on iOS, and a resource value on Android. The definition lives in one place.Design tokens don't prevent bad design decisions - they prevent inconsistent ones. Users can learn one pattern; they can't learn 47 variations of the same pattern.
Rainui Teihotua
Chief Creative Officer
How to Implement Tokens
Start with an Audit
Before creating tokens, audit what exists. Extract every colour, spacing value, font size, border radius, and shadow from the current CSS. You'll find duplicates, near-duplicates, and values that look intentional but aren't.
Our 47-screen application had 23 different blue values. Seven were intentional. Sixteen were developers picking "close enough" from a colour picker.
Define the Scale
Create a constrained set of values for each token category.
Colours: A primary palette, a neutral palette, and semantic colours (success, warning, error, info). Limit each to 5-8 shades.
Spacing: A consistent scale. We use multiples of 4px: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64. Ten values cover every spacing need.
Typography: A type scale with clear hierarchy. Usually 5-7 sizes, each with corresponding line-height and weight.
Radius: 3-4 values. Small (2-4px), medium (6-8px), large (12-16px), full (9999px).
Tooling
For CSS-based projects, CSS custom properties work well and have broad browser support. Define tokens in a root stylesheet, reference them throughout.
For larger organisations with multiple platforms, tools like Style Dictionary transform a single token definition file (JSON or YAML) into platform-specific output: CSS variables, iOS Swift constants, Android XML resources.
Migration Strategy
Don't migrate everything at once. Start with new components using tokens. Gradually replace hardcoded values in existing components during normal maintenance. Within three to four months, most active code will reference tokens.
Common Mistakes
Too many tokens. If you have a token for every conceivable value, the system is too complex to use. A developer shouldn't need to scroll through 200 tokens to find the right one. Keep the set tight.
Naming by appearance instead of intent.
--blue-500 is a global token. --color-primary is a semantic token. Developers should use semantic tokens in components. The appearance can change; the intent shouldn't.No governance. Tokens need someone responsible for them. Without governance, developers add new tokens instead of using existing ones. The token set grows until it's as inconsistent as the hardcoded values it replaced.
Design tokens are boring infrastructure. That's why they work. They remove the decisions that don't need to be made, so designers and developers can focus on the decisions that do.