Best Practices in Design Tokens

This is a topic I love. Design tokens. What separates good products from great ones? It’s not having a more sophisticated token system. It’s having a token system that actually gets used consistently across design and development, creating coherent experiences without constant manual coordination.

Design tokens are the bridge between design intention and implementation reality. Get them right, and design x development collaboration becomes dramatically more efficient. Get them wrong, and you’ve added complexity without benefit.

Setting the Context

Design tokens matter more than ever because products have grown complex. You’re building for web, mobile, and possibly more platforms. You have multiple designers and multiple developers. Design systems need to scale across all of them.

Without tokens, every design decision becomes a coordination problem. “What shade of blue is that?” “What’s the spacing here?” These micro-decisions multiply across teams and platforms, consuming time and creating inconsistency.

Design tokens solve this by creating a shared vocabulary. Instead of specifying #007bff, you specify color-primary. Instead of 16px, you specify spacing-medium. The token becomes the contract between design and development.

But tokens only work if both sides actually use them. Tokens that exist in a design system document but not in real implementations are just documentation that nobody reads.

Scaling What Works

Growth Considerations

Token systems need to grow with your product:

Start minimal: Begin with the tokens you actually need. Colours, typography, spacing, and perhaps shadows cover most use cases. Elaborate token hierarchies for situations you don’t have yet are premature optimisation.

Add tokens when patterns emerge: When you find yourself repeatedly using the same value, that’s a candidate for a token. Tokens should capture decisions you’re making anyway, not force new decisions.

Build naming conventions early: How you name tokens determines how findable and usable they are. Establish conventions before you have hundreds of tokens to rename.

Plan for platform differences: Tokens might need platform-specific implementations. Your token system should accommodate this without duplicating everything.

Version deliberately: Changes to tokens affect everything that uses them. Build versioning into your process before breaking changes create cascading problems.

Maintaining Quality

Token quality degrades over time without attention:

Regular audits: Compare what’s in your token system to what’s actually used in products. Remove unused tokens. Add tokens for values that keep appearing outside the system.

Clear ownership: Someone needs to own the token system—not to do all the work, but to ensure consistency and make decisions when questions arise.

Documentation that stays current: Token documentation that’s out of sync with reality is worse than no documentation. Build update processes into your workflow.

Guard against sprawl: It’s tempting to create tokens for every variation. Resist this. More tokens means more to maintain, more to choose from, and more opportunities for inconsistency.

“The best token systems I’ve seen aren’t the most comprehensive. They’re the ones that capture 90% of use cases with 20% of the tokens.”

The Development Context

Technical Considerations

Token implementation involves real technical decisions:

Format choices: Tokens can be represented in JSON, YAML, CSS custom properties, or various other formats. Your choice affects tooling compatibility, browser support, and developer experience.

Transformation pipelines: Raw token definitions typically need transformation for different platforms. Tools like Style Dictionary help, but you need to understand the transformation process to debug issues.

Runtime vs. build-time: Are tokens compiled into your app at build time, or loaded at runtime? Runtime tokens enable theming and dynamic changes but add complexity. Build-time tokens are simpler but less flexible.

Cascade and overrides: How do tokens interact? Can component-level tokens override global tokens? How does theming work? These architectural decisions shape what’s possible later.

Performance implications: Token systems can affect bundle size and runtime performance, especially if you’re generating large CSS files or JavaScript objects. Measure early to catch issues.

Team Dynamics

Token success requires designer-developer collaboration:

Shared ownership: Tokens live at the intersection of design and development. Neither function should own them exclusively. Establish joint governance.

Clear contribution process: How do people propose new tokens? How are changes reviewed? Without process, tokens either stagnate or sprawl.

Education investment: Tokens only work if people know about them and how to use them. Invest in onboarding and documentation.

Feedback loops: Developers know which tokens are awkward to use. Designers know which values keep falling outside the system. Build channels for this feedback to improve the system.

Implementation Approach

Best Practices

Semantic over atomic naming: Name tokens by purpose, not value. color-error is better than color-red-500 because the purpose survives value changes. If you change your error colour from red to orange, semantic naming requires one change instead of finding every red-500 usage.

Layered token architecture: Consider a hierarchy: primitive tokens (raw values), semantic tokens (purpose-based), and component tokens (specific usages). This provides both flexibility and consistency.

Document the why, not just the what: Token documentation should explain when to use each token, not just list values. “Use for primary actions” is more useful than “Blue: #007bff.”

Build design tooling integration: Tokens should live in design tools, not just code. Figma variables, Sketch libraries, or similar features keep designers working with the same system developers use.

Test across platforms: Token implementations should be tested on all platforms they target. Subtle differences in colour rendering, typography metrics, or spacing calculations can undermine consistency.

Tooling and Process

Popular tools include:

Style Dictionary: Transforms token definitions into platform-specific outputs. Widely adopted and extensible.

Figma Variables: Native token support in Figma, enabling design-to-code consistency.

Theme UI: React-specific approach to design tokens and theming.

Tailwind Config: If using Tailwind, the configuration file becomes your token system. Be deliberate about customisation.

For process, consider:

PR reviews for token changes: Token changes affect the whole system and deserve careful review.
Visual regression testing: Catch unintended changes when tokens update.
Deprecation warnings: When removing tokens, provide migration paths and warnings before breaking things.

Key Takeaways

Design tokens create shared vocabulary between design and development—but only if both sides actually use them
Start minimal and add tokens when patterns emerge, not preemptively
Name tokens semantically (by purpose) rather than atomically (by value) for easier maintenance
Token governance requires shared ownership between design and development
Document when to use tokens, not just what they are

Next Steps This Week

Audit your current design x development workflow. Pick one area - say, colours - and ask:

How many different colour values appear in the product?
How many of them are intentional versus accidental variation?
Which ones could be standardised into tokens?

This audit often reveals surprising inconsistency. That inconsistency is the opportunity tokens address.

Start with the values that appear most often and standardise those first. One well-used token beats ten theoretical ones.

Have questions or thoughts? Get in touch - I’d love to hear from you!