A Practical Guide to Design Tokens

Design tokens sound like something only design systems nerds care about. That is, until your button colours are defined in seventeen different places and nobody knows which one is right.

I first encountered design tokens at a company where our “primary blue” had eight different hex values across the codebase. Designers would spec one colour. Engineers would implement another. Nobody knew which was correct. Every release was a game of “guess the brand colour.”

Design tokens solved this. Not because they’re magical. Because they centralise design decisions into a single source of truth that both designers and engineers can reference.

Why this matters: as your product grows, maintaining visual consistency becomes exponentially harder. Design tokens make it scale.

Also, this is very important when working with AI agents. Nobody wants their landing page and app look like AI-slop.

Scaling What Works

Growth Considerations

Design tokens start simple. “Let’s define our colours in one place.” Then you need spacing values. Then typography. Then border radii, shadows, animation durations. The system grows.

This growth is good, but it needs structure. Without it, you end up with hundreds of tokens and nobody knows which to use when.

Organise tokens in layers. At the bottom, primitive tokens: raw values like blue-500 or spacing-16. In the middle, semantic tokens: purpose-driven like color-primary or space-large. At the top, component tokens: button-padding-horizontal. This layering creates flexibility while maintaining consistency.

The teams doing this well can change their entire colour palette by updating primitive tokens. Everything else cascades correctly. Teams doing it badly hard-code values everywhere and tokens become decorative rather than functional.

Plan for multiple platforms. Your web app probably isn’t your only interface. Mobile apps. Email templates. Marketing sites. If your tokens can’t export to all these contexts, you’ll end up maintaining separate systems. That defeats the purpose.

I worked with a team that defined tokens in JSON. Build processes transformed them into CSS variables, iOS Swift constants, Android XML resources, and React Native styles. One source of truth, many output formats.

Maintaining Quality

As token systems grow, entropy creeps in. New tokens get added without considering existing ones. Similar-but-slightly-different values proliferate. The system becomes as messy as before tokens existed.

Govern token creation. Don’t let anyone add tokens freely. Create a process. Before adding a new spacing value, check if an existing one works. Before creating a new colour, ensure it’s genuinely needed.

Audit regularly. Which tokens are actually used? Which are orphaned? Unused tokens should be deprecated. This keeps the system lean and understandable.

Document token purposes. color-gray-200 doesn’t tell you when to use it. color-background-subtle does. Good token names are semantic, not descriptive.

The best token system I’ve seen had a dedicated steward. Not full-time. Just someone who reviewed proposed tokens, maintained documentation, and periodically audited usage. That small investment prevented chaos.

The Development Context

Technical Considerations

Design tokens need technical infrastructure. You can’t just declare “we have tokens now” and expect magic. You need tooling and processes.

Choose a format. JSON is popular because it’s universal. YAML is more readable. CSS custom properties work but are web-specific. Whatever you choose, make sure it’s parseable and transformable.

Build transformation pipelines. Your tokens need to become useable code. CSS variables. SCSS variables. JavaScript constants. Native platform resources. Automate these transformations. Manual processes break.

Integrate with design tools. Designers should be able to see and use tokens directly in Figma or wherever they work. If they can’t, they’ll define values manually and your single source of truth becomes multiple sources of lies.

I’ve seen token systems fail because the technical setup was too complex. Updating tokens required running build scripts manually. Nobody bothered. The system atrophied. Make it easy or it won’t be used.

Team Dynamics

Design tokens span disciplines. Designers define them. Engineers implement them. PMs care about consistency. Everyone has opinions.

This cross-functional nature is powerful but requires coordination. Establish clear ownership. Who decides what tokens exist? Who approves additions? Who maintains the system? Without clarity, decisions stall or tokens proliferate uncontrolled.

Create shared language. Designers and engineers often talk past each other about visual properties. Tokens create shared vocabulary. “Use color-primary” means the same thing to everyone. This reduces translation errors.

Involve engineers early. Don’t let designers create a token system in isolation then hand it to engineering for implementation. Collaborate from the start. Engineers understand technical constraints. Designers understand visual requirements. Both perspectives matter.

The teams with the smoothest token adoption had joint design-engineering working groups from day one. Decisions were made collaboratively. Implementation was straightforward because engineers helped shape the system.

Implementation Approach

Best Practices

Let me share what actually works for implementing design tokens that teams actually use.

Start small. Don’t try to tokenise everything on day one. Start with colours. Get that working. Then add spacing. Then typography. Incremental adoption is more sustainable than big-bang transformations.

Use semantic naming. color-button-primary is better than color-blue-500. Semantic names communicate intent. When you rebrand and primary becomes purple instead of blue, semantic names don’t need changing.

Create clear token tiers. Separate primitive tokens (raw values) from semantic tokens (purposeful names) from component tokens (contextual usage). This creates flexibility for different use cases.

Document everything. Every token needs documentation. What is it? When should you use it? What are examples? Good documentation turns token systems from mysterious to mundane.

Make tokens easy to discover. If designers have to hunt through files to find the right token, they won’t use them. Build token browsers. Create Figma plugins. Make the right choice the easy choice.

Tooling and Process

Your tooling determines whether tokens actually get used or become abandoned good intentions.

For definition: Store tokens in version-controlled files. JSON or YAML typically. This creates an audit trail and enables collaboration through pull requests.

For transformation: Use Style Dictionary or Theo or similar. These tools transform token definitions into platform-specific code. Don’t write transformers yourself unless you have specific needs.

For integration: Build or use plugins for design tools. Figma plugins that show available tokens. Browser extensions that highlight token usage. The easier tokens are to use, the more they’ll be used.

Process-wise, treat tokens like code:

Propose token additions through pull requests
Review proposals for necessity and consistency
Update documentation
Transform to platform formats
Deploy to relevant packages
Communicate changes to teams

This level of process might feel heavy, but it prevents token chaos.

Key Takeaways

Here’s what matters for design tokens that actually create consistency:

Start with core properties like colours and spacing. Don’t try to tokenise everything immediately.
Use semantic naming over descriptive naming. Purpose-based names survive rebranding.
Organise tokens in tiers: primitives, semantics, components. This creates appropriate flexibility.
Build transformation pipelines to generate platform-specific code. Manual processes don’t scale.
Integrate tokens into design tools. If designers can’t easily use tokens, they’ll use arbitrary values.
Establish clear governance for token creation. Uncontrolled growth defeats the purpose.
Document every token’s purpose and usage. Tokens without documentation don’t get used correctly.

Final Thoughts

Design tokens aren’t glamorous. They’re infrastructure. But infrastructure determines whether your product maintains consistency as it scales.

The difference between products that feel cohesive and products that feel haphazard often comes down to whether they have systematic approaches to design decisions. Tokens are that systematic approach.

Start this week. Identify one source of inconsistency in your product. Different shades of the same colour. Inconsistent spacing. Variable border radii. Pick one thing and tokenise it.

Get that working. Let your team experience the benefit. Then expand. One decision at a time, you’ll build a system that makes consistency automatic rather than heroic.

Because maintaining visual coherence across a growing product shouldn’t be a struggle. Design tokens turn it from a struggle into a solved problem. And that’s worth the investment.