Using design tokens on your design system for better cross-functional collaboration — Part 1
Design systems have become an essential tool for product teams and companies. They have enabled users to agree to standardized outcomes and processes in exchange for consistency and efficiency. There might be different reasons why you might need a design system, but some of the common goals are:
- Create an accurately branded experience
- Increase delivery speed
- Eliminate rogue decisions
- Improve collaboration
- Be a governance tool
- Etc
But, successful design systems are a collaborative effort. They are a constant work in progress. Over the past years, I’ve helped and contributed to several design systems and experienced the benefits of reusable components, aligned teams, and the ability to deliver value faster to the end user. But on the other hand, I have also experienced the gap between design and development, and as the teams grow, this gap becomes more and more evident.
Having a design system and governance in place allows us to scale good design work, but how to scale it more collaboratively while being less limiting? Here is where design tokens become an essential part of the system.
What are design tokens?
Design tokens are a single source of truth represented as a value and a name that captures brand decisions in an agnostic way that can be leveraged by design and implementation tools. They are a great way to bridge the gap between design and development, allowing you to abstract away the implementation details without losing any of the design intent in translation.
The purpose of this article will be to design and implement a process where the design tokens (source of truth) will be defined outside our design tool. A process where both the design tool and code implementation can read and write from and to this source of truth, allowing everyone to speak the same language using the tools each individual is most comfortable with.
I’ll be dividing this topic into three different parts:
- Part I: Understanding how to get started with design tokens
- Part II: Using design tokens in Figma
- Part III: How to integrate design tokens into the development pipeline as a collaborative process
Understanding how to get started with design tokens
First and foremost, we need to understand how tokens can add value to our design system. Think of design tokens as the smallest building blocks for your design system. They can be anything you would like to define as a design decision describing a design intent. This is very important: building a framework where the design intent is preserved, allowing for scalability. For instance, if someone looks at a single value on your design tokens, it should be clear to others how they can use it and when to use it.
But how can we store and share design system decisions while having shared tooling that different disciplines can use to improve the process and collaboration?
Then, let’s dive into very introductory but essential steps:
1. Defining the token creation criteria
We will design and define the tokens from scratch for the example we will build during these articles. However, if you want to create design tokens for an ongoing project, you will find the interface inventory an excellent method to start with. There are also helpful Figma templates to help you with that, including the Interface Inventory Blueprint by Honza Toman.
As a criteria convention, we could establish that we will map all reusable global tokens (primitive values in our design language) and alias tokens (a token that refers to another value by adding the intended purpose to it) from our design system foundation. These can include typography, color, spacing, grid, layout, borders, shadows, iconography, etc.
In summary, our framework for design decisions will be represented as data to help ensure flexibility, scalability, and maintainability across different teams, products, and experiences. Furthermore, as they need to be platform agnostic to increase interoperability, the recommendation is to define them in JSON format so that they can be used by web frameworks as well as iOS, Android, etc. It is worth keeping an eye on the W3C Community Group Draft Report for Design Tokens, where many experts are looking at defining the best specification for a file format to exchange design tokens between different tools. We will be following these recommendations.
2. Defining the naming structure
Naming your tokens is hard, but the naming should be done collectively. In theory, you could call them anything as long as all parties understand them and agree. But the more you can describe the design intent or context, the better.
To describe the context and intent of a token name, we need to think of a system that allows us to include all the pattern levels we need. It is essential to think through which patterns could compose each token and group them meaningfully. There are several ways you could proceed with that. It is worth investigating further with your team and how others have done it. Here are a few useful links on this matter:
- Naming tokens in design systems, by Nathan Curtis
- Naming design tokens, by Lukas Oppermann
- Design token scales, by Chien-Chun Wu
Assuming that in our implementation, we would like to allow different themes and let the user choose which theme to set as a preference, then we need to consider assigning all the required tokens to the correct theme. For that, we will decide to have global tokens as tokens that don’t depend on the theme but are applied consistently throughout our interfaces. Aliases tokens will mostly be the ones controlled/updated by themes, and that will reference the global tokens in return.
2.1 Global tokens
We will define our global tokens with the help of the following pattern levels: system-category type -scale.
First, let’s look at the color category type. At first glance, we need to know what color each value represents.
blue: hsla(243, 75%, 47%, 1);
green: hsla(119, 89%, 28%, 1);
...On top of that, we also need to understand the scale or tonal direction in this case.
...
blue-300: hsla(238, 87%, 78%, 1);
blue-400: hsla(238, 83%, 72%, 1);
blue-500: hsla(238, 79%, 57%, 1);
...An example of how our structure might look like is the following:
2.1 Aliases tokens
Now that we have our global tokens, we need to apply context, i.e., the design intent. We will cross-reference our global tokens and provide the necessary intent by using the following pattern:
system-theme-concept|group|component-category type -property-variant-state
Example: skala-light-surface-color-background-hover or skala-light-form-color-border-error
Be sure to provide enough semantics but also the intent for the specific token value. These will guarantee that in the future, any updates in token values to be an easy and scalable change. There is no right or wrong convention but certify that you and your team use it intentionally and consistently among different stakeholders.
3. Defining the tooling
We have to look at tooling from the perspective of cross-functional teams and token management functionality. We need the tools to make creating, managing and translating design decisions possible.
UI design: several tools can be used for UI design. Figma, Sketch, and Adobe XD are the most known in the industry. We will be using Figma for this example.
Storage: To have shared value references from Figma to JSON, we also have a few options. We could use Figma natively to define our values and translate them to JSON via API calls, or we could use plugins to help. Again, we want a “single source of truth” for design tokens and automatically keep our design system and development tools in sync. During these articles, I’ll first use the Figma tokens plugin by Jan Six but later explore other options such as Specify and Supernova.
Translation: Since most platforms cannot natively render JSON format, we will have to choose a translation tooling to define the outcomes we would like to receive from the JSON format, such as css, sass, common js, etc. Together with the Figma token plugin, we will be using Amazon’s Style Dictionary, a very flexible option with many references across the industry. You can also look at Diez, Open Design, Lona, Interplay, and Specify.
There is a need for traceability, transparency, and accountability when it comes to design systems and design tokens.
Documentation: Regarding traceability, documentation becomes an essential part of the process. It is important to state how a token comes to be, its purpose, and when and why it was last changed. Having all the information in one place makes it accessible to everyone on the team and encourages a more collaborative and strategic culture.
Depending on your organization’s setup and what you’re already using, documentation can happen in various ways. The more your design system is organized and documented in one place, the better it will ensure increasing everyone’s collective knowledge, which is crucial.
We will document hand-off specs in Figma for our components with the help of the Figma tokens plugin and have Storybook handling all the tooling complexity to create a static site with our tokens and any design system component documentation.
Defining the cross-collaboration process
Concerning accountability, think of a process that considers an end-to-end experience. A design system is only a low-level abstraction of the design process, but we want to be able to manage all tokens in a central place and distribute these decisions to our components and layouts in Figma, as well as distribute them for implementation.
Sharing responsibility can effectively get things done, but it can also lead to problems if nobody takes charge. Therefore, for a design process to run smoothly, it’s essential to define who is in charge of what, who oversees the suggestions, and who manages and modifies design tokens and any design system content, ensuring that each team member’s input is heard and valued.
In regards to the process, this is how we are going to build like:
- Designers define design decisions.
- A designer manages/create these decisions either from a JSON file or with the help of the Figma Tokens Plugin.
- The design tokens are stored in a github repository.
- A designer changes the design token, can see the immediate result in Figma, and push the change as a PR to the github repository and provide release notes.
- Upon PR merge, the tokens are transformed into something that Style Dictionary can read, and then Style Directionary generates all necessary outcomes to be usable by all platforms (sass, CSS, commonJS, etc.).
- Any implemented component using the modified tokens immediately changes with the update.
- The team can use visual regression to investigate what has been changed and approve it or request further changes (We will be using Chromatic).
We will discuss each of these steps in more detail in the following articles, but of course, you could have a different process out of this example. For instance, we could modify the tokens directly on code and get the changes in both development and design environments. With visual regression testing, a PR approval with mandatory people could also be implemented.
Structuring our initial design tokens JSON draft
Here is a very simplified version of how you could draft your JSON file:
{
"global": {
"color": {
"neutral": {
"100": {
"value": "hsla(60, 10%, 96%, 1)",
"type": "color",
"description": "grayscale palette",
},
...
}
},
"fontSize": {
"md": {
"value": "17",
"type": "fontSizes",
"description": "base value for type size",
}
...
},
...
},
"light": {
"feedback": {
"color": {
"background": {
"success": {
"hover": {
"value": "{color.forest.500}",
"type": "color",
"description": "Used as the background color for feedback elements on hover interaction states.",
},
}
}
}
}
}
}Summary
So far, we have looked at the following:
- How design tokens can be leveraged to establish a common language that enables better collaboration between designers and developers.
- How to structure and start with design tokens
- Structuring our initial design tokens draft
- How cross-functional collaboration/pipeline could work.
Next, we will look into how to use Figma tokens and how to set up your design system with the help of the plugin. Finally, as per the last article, we will use these tokens in our development pipeline.
The result? A more streamlined workflow and a more efficient process that brings everyone together with their responsibilities. The centralized nature of design systems helps keep product maintenance effortless and improves speed and consistency in the long run.
