Design Tokens
Design tokens are named, reusable values that store design decisions, such as colors, font sizes, spacing, border radii, and shadows, in a format that both designers and developers can use. Instead of hard-coding #1A73E8 in dozens of places, a team defines a token like color-primary once and references it everywhere: in Figma, in CSS, and in mobile apps.
Design tokens are the foundation of a modern design system. They make it possible to change a brand color, adjust spacing, or add a dark mode by editing a single source of truth rather than hunting through every file.
Why It Matters
- Consistency: every button, heading, and card uses the same values across pages, products, and platforms.
- Faster changes: a rebrand or theme update becomes a token update instead of a full redesign of the codebase.
- Better design-to-code handoff: designers and developers speak the same language, which reduces mistakes and back-and-forth.
- Theming: light and dark modes, white-label versions, or sub-brands can share components with different token values.
- Accessibility: contrast-safe color pairs can be defined once and reused, rather than checked page by page.
Types of Design Tokens
- Primitive (global) tokens → raw values, such as
blue-600: #1A73E8orspace-4: 16px. - Semantic (alias) tokens → values with meaning, such as
color-action-primarypointing toblue-600. Components use these, so the underlying color can change safely. - Component tokens → values for a specific component, such as
button-padding-xorcard-radius.
Example
Tokens are often stored in JSON and transformed into CSS custom properties, Sass variables, or native mobile values with tools like Style Dictionary:
{
"color": {
"blue-600": { "value": "#1A73E8" },
"action-primary": { "value": "{color.blue-600}" }
},
"space": { "4": { "value": "16px" } }
}
Which becomes, in CSS:
:root {
--color-blue-600: #1A73E8;
--color-action-primary: var(--color-blue-600);
--space-4: 16px;
}
.button {
background: var(--color-action-primary);
padding: var(--space-4);
}
Best Practices
- Start with a small set of primitive tokens and add semantic tokens on top. Components should reference semantic tokens, not primitives.
- Name tokens by purpose (
text-muted), not appearance (gray-light), so names survive a rebrand. - Keep one source of truth, synced between the design tool and the codebase.
- Document each token with its intended use, and check color pairs against WCAG contrast requirements.
- Version your tokens like code, so changes are reviewed and reversible.
In WordPress, design tokens map naturally to global variables in theme.json or page builders such as Bricks. Our design team builds token-based design systems that developers can implement one-to-one. For more on accessible color choices, see our guide to color accessibility.