Refactoring Token Names for Seamless Design System Maintenance
Written by Mark Malek and Rebecca Hemstad
Maintaining consistency across various platforms and applications is a critical challenge. Design tokens, as the fundamental units of visual styling, are the backbone to delivering cohesive user experiences. In this article, we delve into the process of creating design token names that are meaningful to both the designers and developers within a unified repository.
Initial Challenge
The necessity for standardizing our token names became apparent when efforts were made to create internal documentation outlining our existing token naming conventions. Any early attempts at a naming convention had clearly derailed because this documentation could not be achieved. It was obvious that this was a situation that had to be resolved.
Refactoring Process
Collaborative Analysis
We started with the slow and laborious process of analyzing and categorizing each existing token. We identified naming discrepancies, token redundancies and outliers. For example, we had tokens with identical color values named differently but meant to refer to the same item. Some of our tokens were given non-semantic names — such as “dark.” Since we support theme switching, “dark” held no meaning when the themes were switched. We also lacked a color system that would scale.
Once we sorted through all the issues, a. token analysis was undertaken to attempt to discern common patterns in what remained.
What we discovered was the following identifiers: category, group, property, variant, and state. The naming patterns turned out to be a multi directional narrative of sorts. It started with a more universal concept and progressed to more unique instances.
During this process, we identified additional semantic discrepancies and resolved them. Once this was achieved, we finally had a comprehensive list of all our existing tokens and a much deeper understanding of it. It was a daunting process to get to this stage. At the end of the review meetings, many attendees described feeling mentally exhausted because of the complex and detailed nature of the task.
Naming Convention Alignment
The next step was establishing a standardized naming convention. The convention needed to be intuitive, reflecting the purpose and role of each token, and it needed to ensure easy recognition by both designers and developers.
To avoid re-inventing the wheel, we scoured the web for existing naming standards that might simplify our task. From the W3C Design Tokens Community Group we found that we would need to think deeper about token types, groups, alias, and composite tokens if we wanted our tokens to scale well in the future. This meant looking at tokens not only from the perspective of a designer but from a developer as well, and specifically in terms of a technical schema — notably JSON (JavaScript Object Notation) and understanding how tokens are compiled and parsed into packages that serve as deliverables to the products.
After reading Nathan Curtis’ article Naming Tokens in Design Systems, we re-evaluated the evolving token name to avoid homonyms. The idea of a universal to unique structure continued to prevail. We landed on starting with a base token definition and extending the tokens names in both directions to proceed from a global (universal) to a more specific (unique) token definition.
Tokens were grouped hierarchically based on their properties. For instance, we grouped the colors by variant, action, and base categories. (For more information on variant, action, and base categories, reference the article linked above.)
Typography was particularly thorny to resolve. We wanted to be able to switch out values of tokens for localization requirements and that meant looking at creating a token for word spacing, work break, line-height, among others. These were commonly used CSS (Cascading Style Sheets) properties, and we needed tokens for those values. We had to determine if each of these took a scale value or a variant value.
With this solved, we met with development to get their feedback. We made additional tweaks based on the suggestions and in the end, they seem pleased with the direction we were taking.
Implementation Planning
We needed to determine the most efficient way to introduce the new tokens into our existing component libraries. Our design team led a workshop to figure out the next steps for updating our tokens. The workshop addressed what design needed to do, what developers needed to do, and when. For example, we knew we needed to update our specs in Figma before development could begin updating code. The result was a carefully planned migration strategy for updating the existing components and layouts to the new token names. This gradual process minimizes disruption to ongoing projects.
Centralized Repository
The next step was to create a repository that designers and developers could both access to update the token names and values. Token Depot emerged as a centralized repository for the tokens. Token Depot houses token Warehouse and Token Exchange. The Warehouse enables updates to be made collaboratively by visual designers or developers. Token Exchange produces the distribution packages. Token Emporium became the in-house web based visual reference of our tokens for designers. (No more spreadsheets! Yay!) Finally, we created clear documentation detailing our new naming hierarchy and conventions. This repository serves as a reference point for both designers and developers, ensuring the same tokens are being used in our Figma specs and code.
Testing
We tested the newly refactored design tokens across various scenarios and context. The objective was to guarantee that these design tokens remained consistent across themes and similar components. In another context, the design tokens were put through real-world scenarios involving internationalization and localization. This involved examining how the tokens performed when adapting to different languages, cultures, and regional preferences.
Furthermore, testing extended to scenarios involving accessibility and compliance with web content accessibility guidelines (WCAG). It was imperative to ensure that the design tokens not only looked good but also facilitated an inclusive user experience
Testing at this stage proved beneficial, as we resolved bugs identified during testing before implementation began.
Integration
Finally, we updated our Figma component libraries to refer to the new token names. Luckily, at the time we refactored our tokens, Figma introduced variables, and our new token structure integrated perfectly into our design specs in Figma.
Benefits
Enhanced Collaboration
With a unified naming convention and hierarchy, designers and developers can communicate more effectively, streamlining the design-to-development handoff.
Time Savings
Efficiently named tokens mean reduced time spent deciphering design specs and searching for corresponding values in the codebase. This results in faster implementation and reduced project timelines.
Consistency Across Platforms
By aligning naming conventions, the design system ensures that consistent experiences are delivered across various platforms and devices, fostering a seamless user journey.
Scalability and Flexibility
An efficiently refactored design system is scalable. As the system expands, new tokens can be seamlessly integrated, knowing that the naming structure can accommodate future growth.
Ease of Maintenance
Updates to base values become a breeze. Designers and developers can now change colors, font sizes, and other properties in a single repository, confident that the changes will reflect accurately across the entire ecosystem.
Final Thoughts
Token refactoring at this scale required a lot of thought and coordination to achieve a system that was both unified and flexible. The process brought together design and development in a way that felt truly synchronized and collaborative. Feel free to reach out with questions or to share your own experiences!
