Design Tokens: Bridging the design-to-code gap

Updated: I presented this topic at a UIUX event in Shanghai. You can watch the recap via this link, from 00:00 to 28:00 - https://www.bilibili.com/video/BV1ix4y1L7NQ/


When I first heard about Design Tokens, I was slow to look into it. However after I finally got started picking it up, I immediately regretted not learning about it sooner.

I believe that design tokens play an important role in bridging the design-to-code gap. It can help to improve the collaboration between designers and developers, and keep the design of websites or apps aligned with the specifications of a design system.

I'll go over what a design token is and the benefits of adopting design tokens.

What is a design token

Imagine that you have this button component in your design system.

(Without peeking ahead)

Try to visualise this button broken down into the various atoms – as in Atomic Design. Try to make a guess of all the properties that make up this button. Scroll down once you're ready!

...

...

...

So, did you guess correctly?

These properties and values that make up this button are the design decisions.

Of course, the button will not be the only component in your design system. There will be design decisions made for the other components in your design system as well.

Here is a list of possible properties that you might use in your design system. From colors, fonts, spacing and even the animation properties.

You can store these properties and values in the form of a design token. A token is basically a key-value pair. This is the same button from before, and beside it I have expressed it's properties and values as JSON.

I hope that my visual example has helped you make sense of what a design token is. Let's also see how others have described a design token:

Why should we use design tokens

To answer this, let's take this example of the design handoff process.

In this scenario, assume that the design – be it a web application or app – is already live. The client wants to make changes, perhaps because of a rebrand, wants to make changes to the colours and fonts etc.

  1. The designer makes the desired changes to the UI in the Figma file.
  2. Once the changes have been reviewed and approved, the designer prepares the design specs (e.g. add redlines, annotation and design documentation)
  3. The designer then books a meeting with the developer to communicate these changes and share the specs.
  4. The developer takes over from here. They review the specs and start to write the necessary code according to the updated designs.

This entire process repeats for every new change that comes along.

As you can imagine, there is alot of communication for what may be considered "simple changes". Here are three ways that a design tokens approach may help:

Allow designers to push changes

A design tokens approach can enable designers to initiate changes from Figma. For example: the designer can push the changes from Figma to the project repository. This in turn allows the developer to retrieve the changes and make the updates seamlessly.

This approach may help to reduce lengthy discussions between designers and developers when sharing specs. This will also prevent the error of copying the wrong values to code.

Output styles for any platform

In our example scenario, you may be picturing a single website or app. But what if our client has many platforms – imagine multiple websites, an iOS and Android app – that all need to be updated?

This can be solved by using a token transformer, which allows the developer to output styles in the correct format needed (e.g. CSS, Sass, JS, XML etc) for that platform, saving them a lot of effort.

A single source of truth

You may also work with a team of designers who all have edit access to the same design file. Is there a way to keep track of what has changed and why it has changed?

Design tokens can be combined with a version control tool, such as Github, in order to provide a source of truth. Every change can be tracked, and a description of the change can be provided too.

A design tokens pipeline

This flow diagram demonstrates what a design tokens approach might look like:

  1. Following the example scenario, the designer has updated the colours and fonts. There are plugins (e.g. Tokens Studio) available to help create design tokens and push them to the project repository.

  2. Once pushed to the project repository, the developer can pull the token file and start to transform them to the correct format needed.

  3. The transformed file can then be delivered to the various platforms.

As illustrated in the above scenario, I believe that adopting a design tokens approach will save designers and developers time and effort and improve collaboration.