Where to Start with Design Tokens

If you’ve been researching design systems, you’ve probably come across the term “design tokens.” (If you haven’t, no worries! You can read about them here.) Even if you’ve heard the term, you might not really understand what they are or where to start.

Design tokens are an approach to storing style attributes like color, typography, and spacing in a pre-determined structure. They are an alternative to directly hard-coding style data that allow designers and developers to build consistent, pleasing layouts, quickly accomplish redesigns, and add a theming layer to their applications.

You can think of a design token as a variable that points to a primitive like a hex code or pixel value.

In my opinion, design tokens are a great way to dip your toes into the world of design systems. I like to think of a design system as having 5 layers to it. Design tokens are the smallest building block of that system (or the first layer). They’re also the key to unlocking multi-platform design systems.

Usually, when designers and developers start work on an app, they don’t create a centralized and structured way to organize style data like colors and fonts. This is totally fine for few years, but eventually, the team runs into one of the following issues:

  • Marketing wants to redesign the site, but hard-coded colors across design files and codebase are too tricky to keep track of and to change
  • The team wants to add dark mode but realizes it’s really difficult without centralized style data
  • The team wants to start supporting multiple applications without building each one entirely from scratch

So once you find yourself in this situation, what do you do?

1. Decide to invest in design tokens

The first step is recognizing that design tokens are a great tool for addressing the three situations listed above. At this point, you’ll need to encourage your team to invest in researching and implementing design tokens.

2. Educate and socialize

It’s more than likely that some of your teammates will never have heard of design tokens. You’ll need to begin to educate them on the value of the tool and encourage them to do their own research. You can use Theme UI’s demo to help make your case, or you can create your own proof-of-concept.

3. Choose how you’ll implement your tokens

You have a couple of options for how to implement your tokens. A lot of teams choose to implement their own structure and naming scheme. This approach prevents your team from having to depend on an external library. The key is to make sure that your tokens are named really generically! Take a look at examples from companies like Salesforce to get ideas for how to structure your tokens. I write about this topic in more depth here if you are interested.

You also have the option to use a third-party library like Theme UI. Theme UI lets you implement your tokens according to their Theme Specification and offers you some helpful syntactic sugar like their sx prop and variants key to make using your tokens easier. Even if the library isn’t for you, you can use the Theme Specification as inspiration.

4. Implement the tokens

At this point, you’ll work with designers on the team to agree on naming and structure for the tokens, and you’ll create an object that contains your structured style data. The final step is to configure the components in your application to read from the tokens instead of from hardcoded values.

So if your tokens look like this:

const tokens = {
colors: {
primary: "pink",

Your components would no longer look like this:

const Nav = styled("nav")`
color: pink;

They would instead read from the theme object:

const Nav = styled("nav")`
color: ${(props) => props.tokens.colors.primary};

Now, if you change the values of your tokens:

const tokens = {
colors: {
primary: "green",

You no longer need to update the styles in your component.

Are you researching design tokens for something you’re building? What are you stuck on? I’d love to hear from you. You can reach me on Twitter. Or, you can sign up for my newsletter!

Software engineer. Opinions are my own. ~ https://maecapozzi.com

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store