Design tokens — What are they & how will they help you?

Last iteration • 
Design Tokens

Translating designs into products is hard! Learn how design tokens make building products easier for both designers and developers.

Design tokens ease building products by improving the communication around design. They help scale your product by separating design decisions from specific platforms & technologies.

They improve communication with build-in documentation & promoting design decisions out of design files.

What are design tokens

Design tokens are a very “hot” topic at the moment. You may think it's only a fancy name for a design related variable. While you may find them as variables in your files, this is only part of the truth. Let's have a look at some common definitions to make sense of this confusion.

Descriptions of design tokens in the field

According to the w3c working group in design tokens, design tokens are:

Design tokens are indivisible pieces of a design system such as colors, spacing, typography scale.

Mozilla defines design tokens like this:

A design token is an abstraction of a visual property such as color, font, width, animation, etc. These raw values are language application agnostic and once transformed and formatted can be used on any platform.

The “inventors” of the design token idea, Salesforce, define them as:

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.

Design tokens — a definition

Pulling from the descriptions above, this is my definition of design tokens:

Design tokens are named entities that store raw, indivisible design values like colors or sizes. They are the core pieces of a design system. Stored in a technology agnostic format they can be transformed for use on any platform, replacing hard-coded values.

Choices & decisions

Design tokens come in two varieties, choices & decisions. The difference is rather conceptual than technical. The idea is that there is a finite amount of defined choices e.g. all available colors in your design system. With those choices you can make decisions, e.g. which color to use for your primary button.


A choice is a core design token. It represents a value and is not related to a specific use case. This can be a color, font size or any other primitive.
Some examples are:


A decision is a choice applied to a use case. It references a choice and its name represents a use case / a decision, but not the value.

You can change the value (referenced choice) without renaming the token. By reading the token name and referenced value you understand the decision that has been made.
Some examples are:

Design tokens are a methodology

Design Tokens are a methodology. IMHO, saying “design tokens are just variables” is like saying “responsive design is just media queries”. It’s a technology-agnostic architecture and process for scaling design across multiple platforms and devices, including native, and more.

Variables are just part of that story.

~ Jina @jina Nov 14, 2018

Why is the distinction important?

If we elevate design tokens to a methodology they can change the whole industry. A methodology is an approach to how we do something and not just a new tool. If we change how we build software this can have interesting ripple effects.

We will look at 3 of the more interesting side effects: 

  1. standardisation

  2. software integration

  3. development tooling

w3c design token standard

A w3c community group is working on a standard for design tokens.

01 Standardisation

A methodology may create enough attention to bring open standards. Actually there is already a w3c community group working on one.

A standard may seem boring at first, but look at what it did for markdown:
Hundreds of tools support it, thousands of packages exist to work the format. All this is only possible because of the open markdown standard.

A design token standard can do the same for us:

02 Software integration

An established methodology used throughout the industry will become interesting for software manufacturers. The people building Sketch, Figma, Framer and XD will think twice before ignoring it. Especially if standardised, native support in design tools will be a question of when, not if. When one tool implements it, others will soon follow.

Official integration into our design tools will in turn further promote the methodology.

Design token developer tooling

03 Development tooling

Design tools are only the beginning of the product building process. For design tokens to reach their full potential they need to be integrated into the development pipeline. 

Developer tooling for design tokens already starts to become easily available. Tools like Amazon Style Directory, Theo or Diez make a first attempt at bridging the gap. 

Over time tooling will evolve so that developing with design tokens will be easier than without. For developers, design tokens will be a requirement to consider a new job. Just like agile is today.

Fitting design tokens into your existing style guide / design system

Starting with the core

If you work with a style guide or design system you may already be using design tokens. Your "core styles" (colors, sizes, type scale, etc.) are design tokens. 

To go all the way there are three more steps:

  1. Give every style a good name following a logical naming convention

  2. Store them in a technology agnostic file (e.g. json). 

  3. Make sure everyone in your org can access them (like a dedicated github repo).

Extracting design tokens from your products

To get the most of design tokens you should probably do a design token audit. This means looking at your components and creating design tokens for all values. This can mean one of two things: 

The added side-effect is that you make your product more consistent.

As inspiration you can find a list of common categories for design tokens below. While not exhaustive it should provide a very solid starting point.

Benefits of using design tokens

Design tokens benefit the entire organisation:


A main idea of design tokens is moving design decisions to a technology agnostic space. For example a design-tokens git repository. The tokens are stored in a format like json that can be transformed for any language or platform. 

Moving design decisions out of the sass and xml and into one place has a huge advantage. If you change the file, all platforms can regularly pull it in and get the updated values.

Once you start working with centralised design tokens, creating "one-offs" feels wrong. It nudges you towards sticking with the established design system, ensuring consistent products.


Maintainability in this context refers to two things. Assuring correct implementation and ease of changing.

Assuring correct implementation

By using design tokens we remove two common steps that can lead to mistakes. The use of direct values e.g. copying a hex value from Figma to css. And the use of hand-coded variables e.g. copying a hex value from Figma to a sass variable.

This leaves only one possibility for mistakes: using a wrong variable. Luckily the risk of this is low.

Ease of changing

Centralised design tokens make visual updates to your products happen nearly automatically. 

The new, simplified update process is:

  1. Update to the central design token repository

  2. Product teams pull in the changes

  3. Recompile and release

You can rest assured that no screen was left with outdated styles. Without manual change no new bugs can be introduced. This also saved time and money that was previously spent changing styles.

When it comes to theming, or more likely, implementing dark mode, design tokens help even more. Since everything is dynamic, all you need to do is load a different set of design tokens.


With your design decisions extracted from a specific code base, scaling becomes easier. Think of it like a micro service. Similar to extracting business logic. 

The less you have to rebuild when scaling to new platforms the better. You will have less errors, less work and an easier time doing QA.


Without design tokens designers use values, 5px for the radius, blue for the button. But when following the design token methodology, every value has to be a named entity. This forces designers to think more about components and systems. 

Maybe the button color is now button-color-primary. This helps other people understand what decisions were made. 

All this information can be derived from reading the name of the design token.

Some tooling around design tokens encourages this even more, by allowing for descriptions. This could be a use case for a token or additional information.

Key takeaways