There’s so much great content out there around what design tokens are and different strategies of structure and naming, I thought I’d have a go at taking it back to basics for those new to concepts.

Let’s start with a storing a single value. As part of your brand, you have a red colour you want to store, so we create our first design token: ‘red’. You can start using that token in your designs or website either directly in styles or in components you create. The first token works!

There’s a tweak to the brand and the main colour is no longer red but kind of pink-ish. So replacing the value doesn’t make much sense as this token was called ‘red’. Oh!

OK…so maybe we got carried away and need to think about this a little more. Maybe we need some kind of abstraction so that if we need to change it again, we don’t have to make updates all over the place. So we’ll change ‘red’ to be ‘brand-colour’ — that’ll fix it!

After making that update, brand decides that red was actually the better colour to use, so this time we just changed the value of our ‘brand-colour’ token and all is good. Minimal updates needed.

Looking across the UI, having a lot of the main brand colour used everywhere seems a bit much, so working with brand, we work out a colour ramp with different hues and shades of red, so there’s some variety. Having 10 variants of the same colour means we need to revisit our ‘brand colour’ token again.

Now we can think about this kind of thing happening more than once, maybe there’s a structure that could help? What if we had tokens that told us about the value it holds in one place and then tokens that kind of described use cases?

So what we can try is two things: we now have a bunch of tokens that are from ‘red-100’ to ‘red-900’ that have steps for each part of the colour ramp, but we don’t want to use those in our work directly — we know what happened earlier! So we have another set of tokens to describe some use cases in our designs. We have links and buttons…maybe a more generic name might be actions, so we’ll create a token called ‘action’ and we can point it to one of the other tokens we’d made…hmm… ‘red-500’ will do for now.

Wait. Just ‘action’? What if we start adding more tokens to all of this and that isn’t clear enough and it gets confusing? To be safe, let’s call it ‘color-action’. In our first group of tokens (there are loads of names for this btw, from tier 1, global, base, reference and more recently, primitives) we have the values we might want to use. In the next set (also with a bunch of names from tier 2, semantic, system or alias tokens), we have more use cases. These can hold references to other tokens, kind of like wiring them up to the actual values without holding a value themselves, if that makes sense?

Over time we get really into using tokens and we have them everywhere and we bring more products or brands into the system and once again, we hit a point where we need to reevaluate. Maybe we want to be more specific about the tokens we have use cases?

Let’s start with our buttons — that should be easy! Knowing that we end up revisiting naming and structure so often, let’s be really specific. So now we have tokens for things like ‘button-primary-hover-background’ and there now seems to be loads of them as every design decision about every state of every button variant now has a token! These form a 3rd collection of component-specific tokens, so we don’t create too much mess, and we can point to other tokens that have those use cases, like our ‘color-action’ token from earlier.

That’s a lot of tokens! Maybe we didn’t need to go that far…but it does give us a load of really granular control… Not everyone on the team or consuming the components really understands why we’ve gone this far, but they get why we’ve done it, I think. Maybe that was over-engineering for our current needs and couldn’t find a middle-ground and had some more use cases in that collection of tokens.

—

The reality is that even with the best planning in the world, you might not be able to know every use case your system will need from the start. The demands made of the system and so tokens could change over time. In many ways, it’s how we manage and respond to change that is the art form. Certainly, some changes can be time-consuming and painful, but that comes with the territory. If you do the best research you can at the beginning and revisit assumptions as you go, you might need to change, but it’ll be based on your needs and responding to the change around you, so learning about different token structures and strategies can give you a toolkit of options to choose from as you go — there isn’t a silver bullet!