Making your design tokens future-proof

Over the last decade, design systems have become a mainstay in many product development teams, and for good reason! Product teams want to deliver value to their users quickly but they also want to provide a consistent experience to their users.

As a result, there’s been a huge increase in the number of products designed to help teams of all sizes manage design systems. Software like Anima, Zeroheight, and Storybook all offer slightly different ways to improve workflows around building and maintaining design systems.

While many tools work at the macro level (like offering teams and stakeholders a way to view guidelines and interact with the components) there are other, more niche tools that teams can use to iron out the finer details.

This is especially true when it comes to managing design tokens. Before we dive into design tokens tooling, let’s review what design tokens are.

What are design tokens?

Design tokens are discrete pieces of data that represent the specific values of a design system. These values are often intentional design decisions made by the product team. These design tokens will then make their way over to the codebase, commonly as CSS variables, but can be represent in many other way.

Let’s look at how design tokens can be used to represent a colour palette.

In Figma, the designer has come up with a colour palette. The primary colour is a Tomato red. Our designer has specifically chosen 12 steps of the Tomato colour, with an alternative palette for the dark theme:

Design system tools may output this information as platform-agnostic data, usually in the form of a JSON object. There might be an additional conversion step where the data is converted into something platform specific, like CSS variables.

--tomato-4: #FFDED6;
--tomato-9: #F55442;
--tomato-11: #D43029;

@media (prefers-color-scheme:dark) {
    --tomato-4: #401A12;
    --tomato-9: #F55442;
    --tomato-11: #FF7D66;
}

button {
  background: var(--tomato-11);
    border-color: var(--tomato-9):
    color: var(--tomato-4);
}

This is what the above styles would look when rendered to the browsers:

Things get messy in the in-between stages where we’re:

• Exporting the code to a platform-agnostic object.
• Converting that object to something developers can use in their projects.

Just for the sake of example, this is what the platform-agnostic data looks like when exported out of Figma using three popular tools:

Anima

Link to plugin

{
  "tomato-10-dark": {
    "id": "f991b0d7b53deca9",
    "$type": "color",
    "$value": "#ff634f",
    "$description": ""
  },
  "tomato-10-light": {
    "id": "456aff72c86eb003",
    "$type": "color",
    "$value": "#e34236",
    "$description": ""
  }
}

Design Tokens

By Lukas Oppermann

{
  "color": {
    "tomato-10-dark": {
      "description": "",
      "type": "color",
      "value": "#ff634fff",
      "blendMode": "normal"
    },
    "tomato-10-light": {
      "description": "",
      "type": "color",
      "value": "#e34236ff",
      "blendMode": "normal"
    }
  }
}

Token Studio

Link to plugin

{
  "global": {
    "tomato-10-dark": {
      "value": "#ff634f",
      "type": "color"
    },
    "tomato-10-light": {
      "value": "#e34236",
      "type": "color"
    }
  }
}

If a team wants to move away from Token Studio and use Anima instead, we’d need to ensure that the tokens we’re exporting from Token Studio are compatible with Anima’s token format.

It’s highly likely that when migrating from any tool there will be inconsistencies in the data structures. This is because there’s no definitive way of writing design tokens.

Fortunately, the people over at the Design Tokens Community Group have been hard at work creating a design tokens specification, a set of rules and guidelines about what constitutes valid design tokens. It’s a specification that library authors and design system teams can use to ensure that whatever they’re building will be interoperable with the breadth of tooling out there.

While a single design token is usually a small, discrete value. Design systems may have a collection of thousands of design tokens. These design tokens may not be values, but aliases for other design tokens. They may be heavily nested within groups. Multiple design tokens might exist for different themes. At a point, it becomes very difficult for an individual to review a set of design tokens and cross-reference it with the specification.

Having a concrete specification defined not only means that the tools can start formatting their tokens consistently, but it also unlocks improved design tokens tooling that serve the greater design and web development community. A design tokens validator is one such tool, which Anima recently released as a free open-source tool, for anyone to use.

Validating your tokens

With this validator, you’re able to check that your design system’s entire set of design tokens matches the rules of the specification. And if they don’t, the validator provides links to the right part of the specification, to help you understand the problem and how to fix it.

Let’s try it ourselves now with an invalid set of design tokens:

{
  "colors": {
    "red": {
      "100": {
        "$value": "#FFCDD2"
      },
      "200": {
        "$type": "color",
        "value": "#EF9A9A"
      }
    }
  },
  "button": {
    "primary": {
      "color": {
        "$value": "{colors.red.200}"
      },
      "padding": {
        "$type": "dimension",
        "$value": "2em"
      }
    }
  }
}

At first glance, this set of tokens makes sense. We have a handful of colors defined at the top, as well as some component-specific tokens underneath. The color of the button is even an alias to an existing token. There are, however, a small number of issues that might be tricky for an individual to spot.

Let’s begin by opening the site.

Once everything’s loaded, paste in the above tokens.

You’ll see that the validator has flagged several issues:

Why not treat this as an exercise and look to fix the tokens yourself using the validator’s hints (you can also skip to the answers below)

.

.

.

.

.

.

Fixes for the tokens:

• Give “colors.red.100” a “$type: “color”
• Update “colors.red.200” to have property “$value” and not “value”
• Update “button.primary.padding” to have a “$value” of “2rem”, as “em” is not a valid unit.

After updating the tokens with the above values, you can click validate again and the validator should pass! 🙌🏼

For the developers out there, you can even integrate the validator within your projects using the design-token-validator npm package.

Wrapping up

It’s exciting to see the Design Tokens CG specification slowly proliferate into more design tokens tooling. I hope that once the draft officially lands that design system tooling start adopting so designers and developers don’t have to worry about managing compatibility layers across tokens, but about actually building their design system.

If you enjoy the validator, please star on GitHub and share on Twitter

About me

I’m Andrico, a software engineer at Anima. If you enjoyed this piece, then please consider following me on Twitter, or checking out my personal blog.

The design tokens validator is just one of many tools created by Anima to help product teams improve their design system workflow.

Check out Anima if you'd like to:

• Convert styles to design tokens inside Figma
• Push generated tokens directly to GitHub
• Pull code updates back into Figma