What is a Design Token?
Design tokens refer to special variables that store design decisions. From a technical standpoint, they are pieces of information that are associated, at a minimum, with a name-value pair.
Design tokens act as foundational building blocks and a source of truth for design system systems. They help designers and engineers alike build more efficiently and consistently. Here are some examples of design tokens used in my personal website:
Why should I use Design Tokens?
In CSS, there are several methods to style an element. One way is to hardcode things like:
p {
color: #000000;
}h1 {
color: #000000;
}
Hardcoding style decisions can make maintaining your code very difficult, especially if your app is large. In this example, if you wanted to change all your p and h1 elements from black to white text, you’d have to find all the areas that refer to those elements and update those color hex codes individually. This is manageable in a smaller application, but you can imagine how much more time consuming and error prone it would be in larger codebases.
A much better method would be to use design tokens, which fundamentally-speaking, act very similarly to CSS variables. Instead of hardcoding things into your app, you can choose to assign variables to style decisions and then refer back to those variables when styling elements.
//base token
$color-text: #000000;//using the base token
p {
color: $color-text;
}h1 {
color: $color-text;
}
In this example, if you wanted to update the color of all of your text, all you would need to do is update in one place (the color-text hex).
In addition to giving you the scalability that variables provide, design tokens also allow for semantic meaning to be attached to their names, making it much easier to know when to use which styling in both design and code.
I will explain more about this in the next section, but here’s an example of global, generic tokens, mapped to semantic tokens:
Setting up design tokens
Define your global (primitive) tokens
Global tokens are semantically agnostic tokens that specify fundamental attributes that are used throughout your application. These global tokens are inherited by your semantic tokens.
It may be helpful to conduct an audit of your current application to understand the things you’ll want to tokenize. If you already have a style library in place, you could potentially convert most of the fundamental concepts, such as colors, into global tokens.
Some common global tokens you could define include:
//color palettes
$color-white: #FFF;
$color-black: #000;
$color-purple-10: #F3ECFE;//sizing
$spacing-x-small: 0.125rem;
$spacing-small: 0.25rem;//font related
$font-family: 'Roboto', sans-serif;
$font-size-x-small: 0.5rem;
$font-size-small: 0.75rem;
Define your semantic tokens
Semantic tokens act as a meaningful layer on top and are linked to global tokens. They are named in such a way that help convey their intent and usage guidelines.
Example of a simple semantic to global token association:
//global
$color-purple-10: #F3ECFE;//semantic
$font-link-hover: $color-purple-10;
Similarly to an audit done for global tokens, it may be helpful to conduct an audit of your app to understand the semantic tokens that you’ll need.
Setting up semantic tokens can be a bit trickier than global tokens due to more complex naming conventions.
Establish naming conventions
An important part of defining semantic tokens is to establish a naming convention. This is important because it helps create consistency in your tokens and makes it easier to identify and understand all the tokens in your system. Some common parts to include in your semantic token name include:
- Category (Colors, Fonts, etc.)
- Property (Background, Border, etc)
- Concept (Action, Alerts, etc.)
- Variant (Primary, Secondary, etc.)
- State (Default, Hover, etc.)
As an example, a category — property — concept — variant — state naming convention could output semantic tokens such as:
$color-background-primary
$color-background-action-hover
$color-font-link$font-size-2x-small
$font-size-x-small
$font-size-regular
For more detailed explanations, check out Naming Tokens in Design Systems by Nathan Curtis.
Integrating with Figma
It’s a good idea to keep your Figma style libraries consistent with your design tokens in code, including maintaining the same naming and organization structure.
Here is an example of colors organized in Figma:
There are also quite a few Figma plugins out there to make this process easier.
