Introduction to design tokens

Lesson 1 · What a token is

A design token is a decision with a name. A decision is the color. Then that decision is given a name. From then on, every part of the design uses the name instead of the color itself.

How does a name know which color it is? Because somewhere, once, you write the name next to the color:

--color-green-600: #17B26A;

That line is written one time, in one file. After that, a button never says the hex code. It says the name, and var() means "look up this name and use whatever color it holds":

background: var(--color-green-600);

The green on the screen looks exactly the same as if you had typed #17B26A. What changed is what you can do with it. A hex code does not say what it is for. If someone asks "why is this green?", the hex code cannot answer. A name can. And if you want to change the green later, you change the first line, and every button that uses the name updates.

That is one name on top of a color. The case study below stacks two more names on top of it, each one pointing at the one below, until a button's name says exactly what the button is for.

Case study: breaking down a button

Say you are designing a Save button. It is green, and in your file that green is #17B26A. There are four ways to write that down, and each one is better than the last. Here are all four, with a second button, Publish, added at each level to show what goes wrong or right.

In summary

Here are the three names stacked up, and the button at the bottom asking for the top one. Each line points at the line above it.

What this gives you

"Is this consistent?" stops being a question for a person to check by eye. It becomes a check a program can run. A person needs to look at everything and remember all of it. A program does not. It can check every component, every time the code is saved, and it never gets tired.

Each level takes away one guess. Level 1 takes away "which hex code?". Level 2 takes away "which color means success?". Level 3 takes away "which version of success does this exact element use, in this exact state?". If you skip level 3, that last guess is still there. And that is the guess a program gets wrong.

Lesson 2 · How to put together the token name

A token name has five parts, in a fixed order. Each part answers one question. The first part says what sort of value it is: a color, a space, a radius, a text size. Every name on this page starts with color, so it is easy to forget it is there. The other four parts say whether the thing can be pressed, which part of it this is, what it means, and which version. Read the parts one at a time and the name tells you what the color is for.

  1     2      3  4       5--color-action-bg-primary-hover
  │      │      │    │       └── 5 variant  · which state
  │      │      │    └────────── 4 intent   · what it means
  │      │      └─────────────── 3 property · which part of the element
  │      └────────────────────── 2 nature   · interactive or not
  └───────────────────────────── 1 kind     · what sort of value: a color

Where each part is explained on this page. Kind: this page stays on color; the other kinds are their own lesson in stage 3. Nature: the next section, static versus action. Property: the alert figure, four parts of one component. Intent: lesson 3, where intent is the middle column of the tree. Variant: states versus surfaces, under the alert.

Two of the words are easy to mix up. Label means text on the interface, like the words on a button. Content means the main text people read. And the last part of the name depends on the second part. An action token gets a state, because you can press it. A static token gets a surface, because it just sits there, on a light background or a dark one.

Static versus action

The second part of the name splits everything on a screen into two kinds. An action thing is something you can press, like a button. A static thing is something you only look at, like an alert. This one split decides what the last part of the name will be, so here are both kinds with their actual colors attached. One thing to notice along the way: an intent does not promise a color. Primary does not mean blue.

Action. A primary button can be pressed, so its last part is a state: default, hover, pressed, selected. Each state is its own name and its own color.

Static. A danger alert cannot be pressed, so it has no states. Its four parts each get one name, and the last part is a surface instead.

This alert is not a surface. It sits on one. A surface is the background behind a thing, and a static thing gets a different set of colors depending on which background it is on. Put this same alert inside a dark sidebar and it would use the inverted names. A state is the other kind of last part, and only things you can press have states.

Lesson 3 · The names as a tree

Read a name the same way you read a web address: color, then static, then label, then danger, then default. The biggest decision comes first. The smallest comes last. The figure below is the whole tree, every box the rules allow, with one name traced through it in purple. Every box can be clicked, so you can trace any name you like.

Two things to try. First, click a different intent, say warning, or a different property, say border. The purple path moves, the name under the figure rewrites, and the last column stays as it was. The middle parts do not change what the ending can be.

Second, click action. The last column changes from two surfaces to four states. That is the one choice that changes what comes after it. Choose static and the last part has to be a surface, light or dark. Choose action and the last part has to be a state: default, hover, pressed, or selected. Nothing you pick in between can change that, which is why this choice sits so near the top.

In summary

The first choice is the big one. When you name a token, you make choices in order: static or action, then which part, then which meaning, then which version. Most choices just add a word. The first one does something extra. If you choose action, the last choice has to be a state, like hover or pressed. If you choose static, the last choice has to be a surface, light or dark. So the first choice controls what the last choice is allowed to be. A list cannot show that, because every item in a list is equal. A tree can, because a branch on the left can have different endings from a branch on the right.

The order matters. Suppose you put the meaning first instead: neutral, primary, information, success, warning, danger. Under each of those six, you would still have to ask "static or action?". That is the same question asked six times. Put static or action at the top and you ask it once. You end up with exactly the same names either way. One tree asks each question once. The other keeps repeating itself.

Changes near the top cost more. Adding at the bottom is cheap. A seventh meaning adds one small branch, a few new names under it. Adding at the top is expensive. A third choice next to static and action would copy the whole tree under it, doubling it. So the choices at the top are the ones to think hardest about, because they are the ones you cannot easily change later.

Many names, one color

Several names can point at the same color. Here are three that do.

--color-static-label-danger-default    ─┐
--color-static-content-danger-default  ─┼─→  --color-red-700  #B42318
--color-static-border-danger-strong    ─┘

Three names, one value. That is not a mistake or a duplicate. It is three separate decisions that happen to agree right now. If someone later decides error borders should be lighter than error text, you change one line, and the other two stay the same. If all three had said #B42318 directly, you would have to search the whole codebase for every place that used it.

The rule only works in one direction. Many names pointing at one value is fine and normal. One name pointing at many values is not allowed, because stopping that is the whole reason tokens exist. There is one exception: light mode and dark mode. A token holds one value for light and one for dark. That is still one value per mode.