Design Tokens and a Source of Truth

Over the past few weeks I’ve been talking to a lot of people about design tokens. For those who don’t know what they are, design tokens are a way of storing design decisions (most commonly variables like colour, typography, spacing and effects, but also combinations of these to make up component styles), that can then be read by all platforms. In an ideal way, this would mean that tokens are synced across the code, the design tools, and the documentation. At the moment, it mostly feeds into the code in a one-way direction. If you want to understand more about design tokens, I recommend this primer by Oscar Gonzalez.

At the moment, most platforms that deal with design tokens act as a middleman between the design tool and the engineering team. The design tool plugs into something and hands over a load of properties. Next, the middleman (zeroheight being one) takes these properties and spits it out into a file that’s easy for parsing (like JSON). Finally, engineering plug that into their workflow to then convert those properties into whatever language they’re using (using something like Style Dictionary).

It’s still a relatively manual process, and the systems don’t talk to each other in an intelligent way. A large part of this stems from the fact that there are differing views on what the Source of Truth should be. Some folks say that the code should be the Source of Truth, because that’s what ultimately gets served to the users. Others say it should exist in the design tools, as that’s where the decisions will ultimately get made and major changes will happen. Yet more folks say that to look for a single Source of Truth is folly, and that all of them just need to stay on par as much as possible.

At the moment, I’m siding with the team who say that the middleman, often the documentation system, should be the Source of Truth. Hear me out…

Trust and home ground advantage

We need a definitive place for these answers to live that everyone in the process agrees with. Otherwise, we can end up with stalemates between the two ends of the process, that can ultimately end up with divergent systems and rules, and teams that don’t trust one another. The problem with defining things in either design tools or code is that the weight of responsibility, accountability and power are unequal in both places.

From what I’ve seen, it’s rare that engineers are ok with anything that pushes directly to code, especially with concerns around formatting, naming conventions, or whether your designers know the difference between an em, a ch and a px unit. Similarly, designers can get worried when they’re handing something off that the intention of what they’ve designed may get misinterpreted.

Shifting responsibility for managing a Source of Truth to one side or the other causes a power imbalance, which can then end up with bad team dynamics and not-great decisions being made.

Enter the third-party arbiter

This is where a middleman comes in. Having a dedicated space for tokens to be managed solves a lot of these problems. If we have a neutral ground between the two sides that acts as a Source of Truth, you can have a central place where decisions are made and changes can distribute out from. For this to work, you need two things to be happening.

One: Changes need to be enabled from both ends of the process, but need to be agreed upon in the neutral space. This would require some form of approval workflow that would mean changes need sign-off, and this could come from either design or engineering, or perhaps both. Even better, peer-review and approval could be worked into the process to put in place a trust and accountability for the whole team. This also makes sure there is an accountability in the decisions making process. Using something similar to pull requests feels like an obvious candidate for this area.

Two: Approved changes need to sync in both directions, updating in both the design tools and the code. This is the biggest change from current implementations, as the entire thing flows in one direction from design tool through to code. However, this is probably necessary if you want to have a single place that works well for both engineering and design.

What’s next?

It’s worth noting that design tokens are still very much in their infancy. The W3C Working Group are still defining terminology, and every month brings new advancements and ways of thinking about what they can be. Similarly, companies are starting to implement their own thoughts on what design tokens could be, which is exciting. At zeroheight, we’re already thinking about the way we can implement things to make Tokens easy to implement and scale, and make sure you’re not locked into a rigid, specific way of doing things. I’m looking forward to what’s next for design tokens!