If you’re managing a design system without semantic tokens, you’re missing out on a key tool for scalability and efficiency.
What
Semantic tokens allow you to create a structured, flexible system where design decisions are defined by purpose rather than raw values. Instead of assigning a fixed colour code to buttons or text, you use tokens like primary-button-bg or warning-text.
This means that your primary button background colour won’t be blue/500, but instead will be primary-button-bg, which has the value blue/500 attached to it (which has the HEX colour code #5A8DD7 applied as well).
Let’s try with a visual example, but keep in mind that it’s difficult to understand how useful this is until you see it in action.
Normally, this is how you’d apply variables to your elements:
Now, let’s say you want to change the stroke in component-2 to #0D0D0D. You would need to do this:
While it doesn’t seem like much, if you start scaling this system up, it will soon become difficult to understand which HEX value should be applied to which component and/or element.
What you need to do instead is apply semantic tokens as a way to make it clear which variables to apply to each element.
This makes updates easier—change the token once, and it applies everywhere! Let me show you how…
Why
Scalability
As your design system grows, manually updating styles across multiple components becomes unmanageable. Semantic tokens allow you to make changes in one place and see them applied consistently across the system.
Let’s say you decide your primary colour should change, but only in the page-title component. If you applied the semantic tokens correctly, you won’t need to modify the component itself; you only need to change its associated token from the variables window.
Or maybe you realise that #black/600 doesn’t work well as a background colour in your design system. Well, you just have to head to the variables and replace surface-alt with another one of your primitive tokens.
Consistency and maintainability
By focusing on function rather than specific values, semantic tokens ensure a more cohesive and consistent look across products. You no longer have to guess or remember which values to use—simply select the semantic token with the appropriate name.
Trying to remember which colour should be used for main borders? It’s easy, it’s stroke-primary.
Theming and customisation
Whether you’re introducing dark mode, brand customisations, or A/B testing different styles, semantic tokens streamline the process. Instead of modifying raw colour values across the board, you can swap out tokens at a higher level.
Future-proof design system
With a clear abstraction layer between design and implementation, semantic tokens make it easier to evolve your system over time without breaking existing designs.
Need to release a new colour scheme to match the company’s updated branding? Just modify your primitive values.
How
Define core design tokens
Start by creating foundational tokens for colours, typography, spacing, and other key design properties.
Usually, I create these raw values in a separate collection called primitives.
Pro-tip: Use the Tailwind CSS Color Generator to quickly load primary colour palettes, and the Export/Import Variables plugin to import and export your setups between files.
Map core tokens to semantic tokens
Next, define semantic tokens that describe how these values are used in the UI. These act as an abstraction layer, making it easier to update styles without affecting the underlying structure.
Setting up semantic tokens takes time, and your approach may need refining along the way. However, once implemented, they significantly improve scalability and maintainability, reducing inconsistencies and accelerating development. It’s an investment that pays off.
Restrict variables scope
Finally, restrict which elements certain variables can be applied to. To do this, first head over to your primitives and disable them all.
Then, go through your tokens and define their scopes. In the example below, I’m restricting the border ones to be applicable to stroke elements only.
Now, when I want to apply a variable to a stroke, only the applicable variables will appear, making it super-easy to select the right one!
This is not a full tutorial
If you want to learn more about how to apply semantic tokens to your design system, I suggest starting with this tutorial from Figma. After that, the best way to understand how you want to use semantic tokens is to play around with them and try applying them to your design system.
Yes, setting up semantic tokens can be a long and tedious process, but the benefits are immense. If your design system doesn’t use semantic tokens yet, I suggest giving it a try!