If you’re not using semantic design tokens — you should be
We recently updated the Purplebricks website and new mobile app to align with a change in brand direction. This was historically a high effort, long process, but we were able to make wholesale changes at unprecedented speed because of the super power of Semantic design tokens.
Having learned the lessons from building the original version of our design system, I knew that when we rebuilt the system a couple of years back, we needed to fully embrace design tokens to build in future flexibility.
Design tokens and semantics
Ok, let’s take a step back and talk about the basics of design tokens first.
Colours, sizes, spacing, and typefaces are tokens: the intangible foundational values that define your design system.
What about semantic tokens?
Semantic: relating to meaning in language
Semantic tokens means naming them based on their purpose rather than their physical appearance. Instead of text-grey you might use colour-text-secondary. The name tells you how it should be used. This is powerful—it becomes its own documentation and advocates for consistent usage.
Getting started with semantic tokens
1. Align product and brand
In our case, we were working with a newly created brand. Aligning with the brand team was the first step to ensure that the core assets would work in our digital products. Colours normally require the most consideration here, especially for accessibility. There’s a great article by Design Systems Collective about this.
By the way, I created a tool to help check multiple colour contrasts quickly.
2. Collaborate with your engineers
You’ll also need to work closely with your engineering team and agree on a shared naming language. They’re used to working with naming conventions and abstraction, so they are a valuable partner in this early phase.
By this point you should have a good idea of the tokens you’ll need and how you’ll likely be using your design system.
3. Create a layered structure
In our case, we defined two sets of tokens that would create a strong foundation with flexibility.
Foundation Tokens
These are the raw values (colours, typefaces, spacing) and should never be used directly.
Semantic Tokens
These are meaningful token names that reference the foundations. These are what designers and engineers use when designing and building products.
Good semantic names should:
- Convey their intended purpose
- Be specific enough to remove ambiguity
- Be broad enough to ensure a manageable set of tokens
Our system uses names based on four identifiers: {category}-{element}-{variant}-{property}
This creates names like:
colour-foreground-primarycolour-background-brand-secondarytypography-heading-large
Semantics in action
This abstraction allowed us to easily update the system when we needed to change the brand. We simply added new foundation tokens and switched what the semantic tokens referenced.
Because semantic naming encouraged consistent use of colours and typography, we confidently made wholesale changes with minimal effort.
Semantic design tokens encapsulate three things that are important in good design and design systems: shared language, documentation, and purpose over presentation. As foundations, they literally bake in the principles that purpose over presentation is what everything else should follow.