It's no secret that a good design system requires having the right token structure in place. And while there are numerous factors that go into building the "right" structure, your token taxonomy is perhaps the most critical of them all. Having helped large organizations across the globe build and scale their design systems, proper token taxonomy should account for: the volatility of the organizational design language, design system maturity, team skills and experience, and the tooling used for token management.
Three-tiered architecture
Rangle’s preferred token structure is heavily based on the three-tiered architecture: primitive, semantic, and component tokens. As a reminder, primitive tokens are context-agnostic tokens, which means tokens that do not have any meaning tied to them (fundamental properties like colour, typography, or spacing); semantic tokens are ones that encompass system-wide design decisions; and component tokens are context-specific tokens used to help build and maintain component development. Each of the 3 tiers are aliased to each other: component tokens refer to semantic tokens, and semantic tokens refer to primitive tokens.
This is the general model of tokens and while there is no one-size-fits-all approach to making aliases for the 3 tiers, it’s possible for semantics to refer to other semantics or to have component tokens referring to primitive tokens. The best way to figure out what model works for your teams is to start from a simple system and evolve it based on the feedback and needs of the product teams who use the design system. Gall’s law is important to reflect on and something we believe to be a core guiding principle for successful design systems.
A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system. – Gall’s Law
Taxonomy & scale
When defining your token taxonomy, it’s important that each tier of token architecture is different enough that they don’t cross-pollinate each other and decrease the effectiveness of the tier level. To achieve this, it’s helpful to consider how broad vs. how specific we define the token names. We can add additional parameters to the scale such as flexibility, complexity, and ease of use based on the common factors mentioned in the beginning: volatility of the organizational design language, design system maturity, team skills and experience, and the tooling used for token management. The approach you take to naming will place your token structure somewhere on this scale.
Token structures based on design maturity
We’ve found that there are 3 levels of token models that can be defined. Most teams are likely already using tokens in their system, and this is a great start to drive consistency by defining reusable reference values rather than raw values. We say this is only a start because adding additional layers to your token structure will better prepare your system for scale. The usefulness of tokens really becomes apparent when you start moving through the levels.
The general structure of token maturity goes like this:
- Level 1 makes use of primitive and component tokens;
- Level 2 introduces semantic tokens to the structure;
- Level 3 removes the component tokens to reduce maintenance cost.
Level 1
This level is for early-stage design systems or organizations with an undeveloped design language. Jumping to component tokens may seem odd but the benefit of adding a component token layer at this level is to allow developers to directly apply unique component tokens into their code with less refactoring needed in the future. This is because component token names tend to be very stable. Without the component layer, a visual change in design would trigger a refactor for developers. However, with component tokens in place, this creates a safety net where the alias of the component token is the only area that needs to be changed, keeping component tokens static and reducing the need for costly rework.
Component token names tend to be very stable. Without the component layer, a token change in design would trigger a refactor for developers.”
Brandon Surya, Staff Product Designer
Semantic tokens are not strictly necessary at this stage as it’s expected that the design language is still being developed, and therefore quite volatile. While this may come at the cost of consistency during this early phase, it's a worthwhile tradeoff as it allows the team to move quickly and understand the system better before investing in the semantic layer.
Level 2
As the organization becomes more mature and has started to develop a proper design language and visual pattern, we can introduce the semantic layer. This layer allows the design system to maintain consistency across products, while providing the flexibility to make large aggregated design changes quickly. Together with the component layer, we've also greatly reduced the possibility of having to do a large-scale refactor.
At this stage, as the design language and patterns become more solidified, the design system team can codify these decisions into semantic tokens. Consolidating design decisions is a critical, but difficult, part of creating semantic tokens. At this level, we can define the semantic tokens more broadly to reduce the number of tokens needed, making the system easier to maintain and evolve as we continue scaling.
Most teams will spend most of their time at this level of token maturity—and that’s ok! This is the stage when teams can focus on solving any existing issues within the design language as it will pose the least risk. Jumping to Level 3 too quickly while there are still issues to solve and decisions to make can create wasted effort and create significant rework.
Level 3
Finally, as the products, design language, token system, and the teams' understanding of the design system stabilizes and matures, the need to have component tokens becomes less relevant—this is like removing the safety net or training wheels of your system. At this stage, we can consolidate the component tokens design decisions into semantic tokens, reducing the number of tokens that need to be maintained. Depending on how distinct the consolidated design decisions need to be, the semantic tokens can be defined to be more specific to allow stricter design changes. This will increase the number of tokens in the semantic layer but will make the system easier to maintain while providing the flexibility to handle design edge cases.
The biggest challenge when moving to this level is to name the semantic tokens broadly enough so a single token can represent a number of aggregated design decisions (avoiding single-use tokens), while making it specific enough that designers and developers can understand the intention of how the token should be used.
If you’re feeling overwhelmed about how to do this, here’s a tip to get started. Lay out all the components currently in the system on a whiteboard, including variants and the different properties. Then, bucket these components into similar groups, for example, controls, feedback & indicators, actionable, containment, etc. From there, codify similar design patterns and edge cases within each bucket by either adjusting the names of existing semantic tokens or expanding the flexibility by creating new semantic tokens to cover different usage.
As this is being done, it is critical that there is constant communication with designers and developers both from the design system team and product teams to ensure that there is a shared understanding on the taxonomy being established.
Conclusion
One of the biggest takeaways from our experience in this space is that there is no one-size-fits-all approach. There is, however, a clear pattern on the effectiveness of each token layer and how they interact with each other. Hopefully, you now have a better understanding of the different token structures and what purpose they each serve.
Progression through these levels is not linear and, most importantly, there is no set timeline for when to move to the next level as it needs to make sense in the context of your Design System and organization. Using token tiers can expand the capabilities of your system in an impactful way, but it’s vital to understand the purpose of each tier and the trade-offs when introducing a new layer of tokens to the system.
And one final piece of advice: find the level that works best within your organizational context and do not rush to reach Level 3. We’ve seen plenty of examples where a design system’s value was diminished by trying to move too quickly. At the end of the day, your design system will be successful if you constantly strive for consistency, maintain open communications between teams across the organization, and help product teams ship!
