The Pyramid Design Token Structure: The Best Way to Format, Organize, and Name Your Design Tokens
What are design tokens?
Design tokens are a common language and design decisions that form a system — in the form of UI characteristics. This might include things like colors, spacing, typography, radii, even animation. They are the structure and manifestation of your brand, and of your visual language.
Why are design tokens important?
Design tokens are invaluable for some many reasons.
First of all, it gets cross-functional departments, such as designers and developers, or developers and product owners, talking the same language which translates into many synergies.
Second, it reinforces a more structured and systemic approach to design decisions, and forces discussions around any exceptions that don’t adopt those formats.
Lastly, the beauty of design tokens once implemented, is that because tokens are part of a logical system, making changes are much much easier to implement. Say you have 50 components and your primary brand color changes from blue to yellow. Making this change might mean only changing one design token that feeds into every single component and how that primary color is being used. Before, my friends, this would potentially be done one by one across all 50 components and the different ways that primary color might be used.
The Pyramid Design Token Structure
Design token structures and organization — now here is where it gets interesting!
Sometimes getting started can be a bit overwhelming, especially when you want to introduce a solid foundation, and maybe even support growth and multiples brands. That is where what I call the Pyramid Design Token Structure comes in to play.
The Pyramid Design Token Structure layers and abstracts variables and design tokens so that you can keep foundational items (think, more variables) separately from design decisions. The three layers consist of reference tokens, system tokens, and component tokens — each with more decisions and granularity built in; all referencing from each other. Let’s dive into the token layers.
1. Reference Tokens
Reference Tokens as act our base layer of property definitions. They are global tokens that will be called upon by the next layer. Reference tokens are first-level, meaning, they are directly tied to values (ex. HEX color value #FFFFFF, or pixel value of 16px). Think of them as variables.
The goal of Reference Tokens is to provide design systems with a set of pre-defined, yet broad, variables to choose from. This layer would define tokens to cover areas such as colors, shadows, borders, and typography. Next, let’s dive into the system tokens layer.
2. System Tokens
System Tokens define your ‘system’, product, application or sub-brand. These tokens reference the Reference Tokens directly to form your visual interpretation of your brand and design system. This set of tokens make opinionated choices around base sizing, typography scales, main border radiuses, status colors, etc.
System Tokens act as the foundational layer individual building blocks are constructed upon. This is where patterns become apparent (or perhaps you uncover that there are many inconsistencies) — spend your time really defining those consistencies for your design system. Finally, let’s take a look at the component tokens layer.
3.Component Tokens
Component Tokens are the easy part — here you are simply referencing your System Tokens to define the bits and pieces that make up your component, such as a button or an input field.
Don’t worry if you find yourself going back to add more system tokens as you uncover patterns from your components.
Putting It Together
Here it is all put together:
In the example above you can see a primary button. It’s color might start with a reference token available to all, xx-ref-color-palette-moss-50. It proceeds to be defined by the system as xx-sys-color-primary, and then is finally consumed at a component level as the xx-button-primary-color.
Naming
Naming design tokens can be tricky. The important part is that it makes sense to your users, and if using the Pyramid Design Token Structure, that you are naming things as ref or sys when it comes to those foundational layers.
The xx and sys values can be exchanged for your design system and product name abbreviations. For example, company Stanger Things might have a Design System called Hawkins and two products named Eleven and Vecna. Their system might use hw (for Hawkins) and el for their product Eleven. Put together their tokens might read hw-ref-color-palette-moss-50 and hw-el-color-primary or even hw-sys-el-color-primary if there were plans to have multiple “systems” or products.
When it comes to naming reference tokens — simply make sure you have your ref indicator at the beginning and that each category design token has a unique value.
You have two options for system design tokens, either preface the token with sys (instead of ref) or if you anticipate multiple products and brands, you can give it a name as well, such as sys-brandA-....
Component tokens are more what you might be used to. You can certainly add a comp prefix, but I find that it make a lot of the tokens too long and that they are easily recognizable without that prefix. In this button example, you can get more specific as well and have color-background or color-text, etc.
Naming Tips: Things to Consider
When choosing between naming with integers, pixel-representative integers, t-shirt sizing, or others, there are some things to consider.
Sequential leveling numbers allow for little change. Imagine you have drop-shadows xx-ref-shadow-2 and xx-ref-shadow-3 and you decide you need a value in between those, now what? Do you bump everything over for levels 3+? Do you add a half value? Even more awkward! Leveling works when you know it won’t ever change, but even that’s a bit scary.
T-shirt sizing (xs, sm, md, lg, xl, etc.) makes it clear which is the base (medium/regular) that everything else is built off of, are likely easy for users to remember, and can follow a similar pattern. This has been my go-to recently. Unless you are changing your base, this gives you flexibility to go as many xxxxxxxs as you need to!
Pixel-representative integers allow for the most flexibility so long as you don’t plan on changing the scale. This might be something like xx-ref-border-width-2 (2px) and xx-ref-border-width-4 (4px). This type of naming is always straight forward but can sometimes loose a bit of ‘meaning’.
Theming
Theming is where the magic happens and is where this Design System structure shines — especially when it comes to building a robust front end solution that is easily modifiable to accommodate sub-brands and themes.
Let’s take the same button component for example — let’s say your main brand uses the green, but you have a sub brand or sub-product that uses blue as primary. With the Pyramid Structure you should in theory only have to define (or override) the primary color, and the rest would work.
Of course, there are more complex scenarios where you might want to change additional items at a component level, which the Pyramid System is flexible enough to account for, however, it would reduce a lot of overhead if that wasn’t the case. If teams can agree to a general design system structure, you won’t have to account for edge cases.
Summary
Design tokens are the best and everyone should be using them — they are here to stay! Organizing, structuring and naming tokens can be challenging and hard to decide on, and the Pyramid Design Token Structure offers a great solution that is flexible, theme-able and, well, structured, to give you a good foundation to managing your token sets. I hope it helps, and would love your thoughts on it — leave me a comment 😊
Happy designing, coding and organizing!
Reference Links
Here are some really useful links and design systems I’ve found along the way and a few design systems I like to reference for inspo:
- Alaska Airlines Auro Design System (good example of tokens applied)
- Atlassian Design System
- REI Cedar Design System (really robust tokens set)
- Adobe Spectrum Design System (good overview on what tokens are)
- Google Material Design Tokens Overview (this write-up gave me the ah-hah on how to best structure token sets)
- Figma Tokens Plugin / Website
- This amazing talk about headless design systems! by a co-author of the Figma Tokens Plugin (the demo will blow your mind)
- Design Systems Slack group (not sure how to get access anymore, but great discussions happening there)
- Design Tokens Community Group (working on standardizing formats, looking forward to what that effort yields)
Who am I?
Stefanie here — I am a design systems leader, UX designer and front-end coder. I love SCSS, your basic HTML & SCSS, and play around with Angular/TypeScript. Lately I’ve been having fun with StencilJS.
