Preparing design tokens for a design system

Four lessons on what to decide before a single token is written.

This is the second article in the design system series. The first one, Introduction to design tokens, explains what a token is. It is there if you want it, but this article stands on its own.

One phrase you will see a lot. A color family is one color together with all of its lighter and darker versions. Green is one family. Red is another.

You are here

In this article, we will cover the following:

1. Decide where the colors are kept
2. List the purposes
3. Ask the three questions and count
4. Choose one color for each family

These are lessons 2 to 5 of the thirteen it takes to build a design system. Lesson 1 was the first article in this series, Introduction to design tokens. Lessons 6 to 13 come in later articles. The full list is below, each with an example.

Lesson 2 · Decide where the colors are kept

Before a single token is written, decide three things: who edits the tokens, where the one true copy is kept, and which places need a copy of them.

Three decisions in order. One place where people edit, one place where the true copy is kept, and as many generated copies as there are places that need them.

Author. Choose one place where tokens get edited. It can be a design tool, a code editor, or a token platform. Every other tool may read. Only this one writes.

Store. Choose one place that holds the true copy. It is the place you would fix a mistake first. Everything after it is a copy.

Consume. Choose as many as you need: the design file, the documentation, the website’s code, a phone app.

Lesson 3 · List the purposes

Colors on a screen are not decoration. Each color is there to tell the user something. Try starting by making a list with what your screens need to tell users. Each line on that list is one purpose: one job that color has to do on the screen.

Most screens have the same four purposes. The fifth is anything only your product needs.

One ordinary screen with five numbered markers. A line joins each number in the list above to the same number on the screen. Marker 5 is on a bar chart with three colors for three kinds of spending. Marker 4 is on the blue message. Marker 3 is on the green, orange, and red messages. Marker 2 is on the filled button. Marker 1 is on the page behind the card.

Case Study: Shopify

Shopify is a company that makes software for running an online store. It publishes its design system, which is called Polaris, so anyone can read how its colors were decided. Shopify does not name its colors “green” or “red”. It names them by what they tell the user, and it calls each one a color role. Its documentation says that every use of color is tied to a specific meaning, and that color is not used as decoration.

Here is Shopify’s list next to the five purposes from this lesson. The numbers are the same ones as in the list and on the screen above.

A table with eight rows. Each row has a numbered purpose from this lesson, the name Shopify gives it, what Shopify uses it for, and a swatch of the color. The names and color values come from Shopify’s public Polaris documentation and token files at github.com/Shopify/polaris. Polaris also names a few roles for special places, such as form fields and the menu, which are left out here. Shopify uses orange when something needs attention and a lighter yellow when it is not urgent yet, and it gives the yellow its own name, Caution. This lesson counts the two as one.

The next four examples are Shopify’s own pictures. They come from its color documentation and show real parts of the screen a store owner uses. The numbers are added here and match the list in this lesson.

Example 1. A Shopify order screen with markers 1, 2, and 3. Two white cards on a grey page, a dark grey button, a yellow label, and a green label. Image © Shopify, from github.com/Shopify/polaris.

Example 2. Three Shopify messages, one per row, each with marker 3 and its meaning written beside it. The first has a green icon, the second an orange icon, and the third a red icon. Images © Shopify, from github.com/Shopify/polaris.

Example 3. A light blue Shopify message with marker 4, and four swatches of blue under it. Image © Shopify, from github.com/Shopify/polaris.

Example 4. Two Shopify pictures, each with marker 5. The first is a text editor with one purple button in a grey toolbar. The second is a row of three products with a blue outline and a blue tab. Images © Shopify, from github.com/Shopify/polaris.

Lesson 4 · Ask the following three questions and count

Your list of purposes says what the screens need to tell users. It does not say how many colors that takes. These three questions turn the list into a number of colors. Each question stops one common mistake.

Question 1: How many versions does each purpose have?

Stops two different messages from looking the same.

You take the list one line at a time and ask the question about that line. A version is one separate message that the user has to tell apart from the others. Most lines on the list have only one version. The background has one. The main button has one. Take “action response”. A user presses Save on a payment form. The screen can answer in three ways. Success: “Saved.” Warning: “The card expires next month.” Critical: “The bank declined this card.” Those are three versions. The user has to tell them apart at a glance, so each one needs its own color. Shopify has the same three.

Question 1, general example. Two small screens with the same two messages. In the first, both messages are red. In the second, one is orange and one is red.

Question 1, Shopify example. Three parts of Shopify screens, one per row, each with its meaning written beside it. The first is a message with a green bar. The second is a form with a pale orange notice under a phone number field. The third is a list of three products where one has a pale red label. Images © Shopify, from github.com/Shopify/polaris.

Question 2: Is each purpose shown with color?

Stops you from using a color for everything.

Some things are shown another way. A heading is more important than the text under it, and that is shown by making the heading bigger and bolder. A button that cannot be pressed yet is shown fainter. Neither one needs a new color. Shopify’s main button is a third example. It is the darkest grey, taken from the same grey as the background, so “what to press” did not need a new color there.

Question 2, general example. Two small screens with a heading and two buttons. In the first, the heading is purple, one button is blue, and one is teal. In the second, the heading is large and dark, one button is blue, and the other is the same blue but fainter.

Question 2, Shopify example. A Shopify picture with marker A on a dark grey button and marker B on a light grey button in the same row. Image © Shopify, from github.com/Shopify/polaris.

Question 3: Does any purpose have a set of equals?

Stops one of several equals from looking more important.

A set of equals is two or more versions of the same kind that are equally important. Two teams on a scoreboard. Four people on a shared calendar. Six kinds of data on a chart. Each one needs its own color, and no color may look stronger than the others, so you choose the colors together. Most products have no set of equals. Shopify has none, so both examples here are general ones.

Question 3, first general example. Two scoreboards with an even score. In the first, one team is strong red and the other is pale. In the second, the two teams are blue and orange of equal strength.

Question 3, second general example. Two shared calendars with four events, two for each person. In the first, one person’s events are strong blue and the other’s are pale. In the second, the two people have blue and orange of equal strength.

Then count

The answers to the three questions are the result. A color family is one color in all its shades, from light to dark. Green is one family. Red is another. Go down your list. If a purpose is shown with color, write down how many versions it has. If it is shown another way, write zero. Then add the numbers.

A table that adds up Shopify’s color families, with a swatch of each color beside its number. Shopify’s list comes to seven: grey, green, orange, red, light blue, purple, and blue.

Lesson 5 · Choose one color for each family

Next is choosing a color for each family. These are the only colors in the whole system that anyone picks by looking.

Shopify’s colors, one per family, each with its purpose. Eight swatches: the dark grey is not a new family, it is the darkest shade of the grey. The values are the fill colors in Shopify’s published token files.

How to choose

Some of the colors are already decided for you. Green for success, orange for warning, and red for critical are what people expect, so you are not inventing them. You are picking which green, which orange, and which red. The choosing is in the shade. Curious about how they are already decided for you? Read Jakob’s Law on Laws of UX for more information: people expect a new product to work the way the products they already use do.

A color wheel helps with the rest. Adobe Color is free and runs in the browser. This is how to use it for this step:

1. Start with the color for “what to press”. Every other color is chosen against it. Put it in the middle slot of the wheel. If you do not have one yet, start with any color you like and adjust.
2. Pick a rule on the wheel. Triad gives three colors spaced evenly apart. Split complementary gives one main color and two that sit across from it. The wheel fills the other slots for you. Treat those as starting points for the families that have no fixed meaning: something to know, and your other considerations.
3. Drag a slot onto the green, orange, and red you expect. Then nudge them until they sit well next to the others. A slightly warmer or cooler green changes how the whole set feels.
4. Check contrast. Under Accessibility tools, the contrast checker tells you whether text in a color can be read on white and on your background grey. Text needs a ratio of at least 4.5 to 1. The color you chose will often fail as text. That is normal. A darker shade of it will pass, and making those shades is lesson 6.
5. Check for color blindness. The color blind safe check shows whether two colors are still told apart by people who do not see red and green the way most people do. Check orange against red, and check any set of equals.
6. Look at them together on grey, not one at a time on white. Colors change next to each other. Save the set as a theme so you can come back to it.

Your product may already have a brand color. If so, it goes in the middle slot, and the question is only which green, orange, and red sit well beside it.

Judge your colors against what they are for. Do the colors for Action Response read in order from good to bad without a label? If some purposes are a set of equals, do they look like equals, or does one look more important? Is the background warm or cool on purpose, or does it just look like a dirty white? Is the main button color one you would be happy to see on every button for two years?

What you can do now

Decide where your colors are kept: one place to edit, one true copy, and a copy for every place that needs one. List the purposes your screens have. Ask the three questions of each purpose and count how many color families that makes. Choose one color for each family. And answer the question that starts stage 3: how does one green become all the shades a screen needs?

Next · Stage 3 · Build the three tiers: making the shades for each color, then naming each color by its purpose, then naming where each color is used. Coming soon.

Preparing design tokens for a design system was originally published in Bootcamp on Medium, where people are continuing the conversation by highlighting and responding to this story.