This is a draft.

Our team is currently cracking away at creating more content to make our Handbook something increggdible. Soon, you'll be able to explore it fully. In the meantime, think of it as a carton of eggs, each section packed with the potential to deliver something eggceptional.

Design Tokens

A short take on Why and How we use reputable Design Tokens.

When thinking about it, this entire page could be summarised in one single sentence: we use Design Tokens because they are the best way to create consistent stuff. Oh, and to maintain them as well.

But at the same time, it seems like everyone is trying to define them slightly differently. It gets impossible to get our heads around them all. Look at Mozilla's, Salesforce's, W3C's, and this arbitrary bloke's (Lukas Oppermann) definition of a Design Token.

It goes without saying, there is still room for more dangling definitions, we reckon. Not all words have yet been used to depict it, so let us have our go at it, shall we?

Here we go, stretching from all the definitions linked above in an Inception-like style, where there's a subsequent chain of references:

Design Tokens are indivisible agnostic entities that hold the smallest design values, such as colours, fonts, spacing, animations, sizes, etc. They are stored in a technology-agnostic format, made to replace hard-coded values, be reusable, and create and maintain a consistent Design System.

Or, if TL;DU – where U stands for Understood – a smaller one: Design Tokens are the smaller, indivisible bits meant to be reused within a Design System, such as colours, fonts, spacing, animations, sizes, etc.

With the definition and the punny bits set aside, Design Tokens are essential for creating sustainable interfaces. One may think it is nothing more than a fancy name for an already existing thing (like Service Designer is). It isn't, though.

Although it sits on the principle of variables, they are only a fraction of it. Design Tokens are a way of thinking. They are a methodology even. Lukas Opperman uses a fascinating analogy when quoting Jina: "saying design tokens are just variables is like saying responsive design is just media queries.".

You get it now! By being a methodology, they become part of a process. They actually define How we build interfaces.

First, they are the foundation of any Design System we create. The latter is unequivocally made with the Tokens. Always.

Second, it integrates seamlessly with your code repository. A file can be automatically generated on Figma and updated onto the latter. And vice-versa.

Systematising your Tokens and building components with them creates consistency, scalability, maintainability, and all the other things you like to hear about software development.

Deliberate constraints, Value Tokens.

Imagine, for a second, the endless amount of values available. They are the universe. Endless. Unattainable, to a certain extent. Values, in this context, are all colour references, all numbers for font sizes and spacing, and all the durations for animations. Everything.

You could work with everything, but everything is uncontrollable. Instead of navigating the entire universe searching for the perfect atom, you got to take the leap of faith and point to the atoms you think are good enough.

In other words, instead of dealing with all the values out there, you pinpoint the values you want to use. You narrow down your universe of values. You make it more manageable, easier to maintain and bound to consistency.

These, we call Value Tokens. They always point to a specific value, like Grey 900 pointing **to #1B1B1B. Or font-size-md pointing to 16px for a font size.

Semantically accurate, Semantic Tokens.

Now imagine you name a Token primary-blue because blue is your primary colour. The one you'd use for buttons and highlight sections. Picture you'd do the same literal naming across all your tokens.

All good until and rebrand happens. Blue is replaced by yellow. Shite! You've earned yourself a journey through all your Tokens: rename them all. Good luck!

To prevent this from happening, we privilege Semantic Tokens. Tokens that mean something but are not literal. Instead of primary-blue, you'd simply use primary. Instead of red, you'd go with error. Instead of green, you'd name it success.

In summary, we are left with two Token types.

  1. Value Tokens.

  2. Semantic Tokens.

And they stroll hand-in-hand. Well, kind of!

Mix and match Tokens.

Semantic Tokens don't live in their tiny, shady house by themselves. They go out, and they interact with the other friendly Semantic Tokens. On the other hand, Value Tokens are the nerdy type. They prefer to stick with numbers – the values – and keep them to themselves, in their own corner.

In other words, Semantic Tokens interact with both Token types. They may point to other Semantic Tokens or point to Value Tokens. Whereas Value Tokens don't. Values Tokens only point to values.

Using ST as short for Semantic Token and VT for, you guessed it, Value Token, here are a few of examples:

  1. background (ST) -> primary (ST) -> blue400 (VT)

  2. heading-size (ST) -> xxxxl (VT)

  3. heading-line-height (ST) -> sm (VT)

  4. heading-letter-spacing (ST) -> micro (VT)

  5. heading font-weight (ST) -> sm (VT)

Context rules.

One other great advantage of Tokens is its adaptability to their context. Tokens can be changed according to contexts, such as a Theme.

Light Theme or Dark Theme, for example. It goes without saying that both will have foreground and background Semantic Tokens. As you'd also expect, they will not be the same. For the Light Theme, foreground could be Gray900 and background Grey 50, whereas, for Dark Theme, the reverse would probably happen.

The bottom line is the context determines which Tokens to point at. Depending on the context, Semantic Tokens will point at different Value Tokens.


You can argue consistency doesn't depend on whether you use Design Tokens or not. Unless you have a fish's brain, you could probably still make reasonable choices and work with a limited set of values without Tokens*.* Indisputably, this is true!

However, by forcing yourself to create a centralised repository of Tokens and use them across your Design System, you keep your UI consistent as a principle rather than as an afterthought. Most of your visual decisions are consolidated in one single place.


Now, changing things is taken to a whole new level. Before Tokens, you'd have to replicate the same colour code or sizing dozens of times along the codebase. Nightmare: find all and replace! With Tokens, you do it once, in one place.

You'd go Grey900: #1A1A1A. Then, you'd use the Token Grey900 wherever you want. As a foreground, as a background, as anything. This means that the margin for error suddenly becomes slimmer and slimmer.

One day, should you need to change the colour, simply alter the colour code. Let's say: Grey900 now is #1A1B1C, for a warmer grey. In a split second, wherever Grey900 is used, the colour changes. Baam!

In addition, should a major redesign be required, simply alter the value of the Value Tokens. Half of the work is done!

In the end, the key takeaway: use Tokens. Tokens are nice!