Implementing Design Tokens to Create a More Powerful, Flexible Design System
My Role: Led efforts to build and improve design system and documentation
The Team: 1 Product Designer, 4 Engineers
Project Length: Oct 2022 – May 2023 (8 months)
Overview
As our design system expanded, the BookNook product team had been running into debilitating maintenance problems – versioning and conveying changes to engineering while the changes were so continuous was becoming difficult. Updating components required a time-consuming engineering lift and documentation was laborious. Since we were in dire need of change, I spearheaded a project to implement tokens into our design system so that changes could be instantaneously documented and cascaded down to the component level.
Beginning with Option Tokens
I began the tokenization process by defining our option tokens. These represented the hard-coded values of the most common atomic design properties in our design system.
I placed properties on a scale with a standard variance or logical difference between each step of the scale.
Each token represented a design decision. When trying to consolidate all of our option tokens, I prioritized flexibility and predictability. A set of purposeful and focused option tokens that fit our product’s needs was more powerful than having every token for every possible scenario.
Defining Semantic Tokens
The second tier of abstraction was semantic tokens. Semantic tokens needed to have a purpose within a context but be abstract enough to adapt to different values. For example, a semantic token might say that the background for all primary calls-to-action was green.700. Any call-to-action with this purpose would have that background color.
If we wanted our primary calls-to-action to be blue instead, I could switch the option token referenced to a blue. This change would cascade downwards instantaneously to all our primary calls-to-action.
Now, decisions that affected large areas of our product could be made quickly and with ease. This would bring a level of consistency and clarity to our design system we hadn’t seen before, making maintenance and expansion easier.
Semantics and Naming Conventions
While defining semantic tokens, I had to define our product’s semantics and a naming structure that would work for the entire product team across all levels of tokens. This required a thorough understanding of our product, behaviors, and hierarchies — it turned out to be the most challenging part of the project. I had countless discussions with engineering to determine rules and conventions, focusing on distinguishability, flexibility, and expandability.
Creating Component Specific Tokens
I then moved on to the final tier of abstraction — component specific tokens, representing the design properties of specific components with that semantic purpose.
These tokens had complete isolation and therefore a low impact in the design system. A change in a component specific token would only be reflected in that component, allowing for more flexibility and control as we built and maintained our design system.
Cascading Changes and a New Workflow
Now, our team had a new, optimized workflow. If we wanted to make sweeping changes to certain areas of our product, we could update a semantic token’s reference from one option token
to a different option token and the design decision would cascade downwards instantaneously.
We could also create changes to individual components without those changes having a ripple effect on other components. Additionally, we had effectively moved towards a new workflow where engineering could take design updates in a language they understood and with minimal lift using JSON files from a token generator. Design and engineering had a common language with which to communicate.
A New Way to Write Documentation Using Tokens
Our team’s documentation also looked entirely different. Changes were made through the token generator and were reflected in Figma instantaneously. Keeping documentation up-to-date was no longer a behemoth of a task, giving us the flexibility to expend valuable resources elsewhere.
Results
With this new system, design and development times were sped up and we had an error-proof framework for design and engineering to collaborate. Handoff was easier and more explicit. Our design system was scalable and could evolve over time with less manual effort from engineering. This project was received ecstatically by the product team and profoundly changed the way we collaborated and codified our component library.