Creating a flexible design token taxonomy for Intuit’s Design System
This article covers how we evolved our tokens at Intuit to create a flexible taxonomy for a small but powerful set of semantic tokens.
Intuit is the parent company for some well-known products such as Quickbooks, TurboTax, Mint, Mailchimp, and Credit Karma. Each product has their own design system. Several of them have their own dedicated design systems teams, as well as both Product and Marketing design systems.
This makes the Intuit Design System (IDS) unique; rather than simply surfacing brand themes, it is used as a foundational system which other multidimensional design systems are built on top of. One of the core foundations of IDS and our consuming design systems is the token system.
The problem
The existing set of design tokens in IDS were comprised mainly of primitives and component-specific tokens. Only a small handful of colors were represented as semantic tokens. For IDS and our consumers, this system was problematic.
We held several rounds of interviews with our consuming design systems teams — both designers and developers. Several pain points emerged:
- Component token names were difficult to understand
- Component token names were lengthy, and were truncated in Figma
- There were too many tokens to choose from
- Teams had difficulty identifying rationale behind token use
These problems left our consuming design system teams devoid of any of the logic or rationale behind design decisions. There was no way for them to understand semantically which tokens were applied to specific use cases. This stalled their capabilities in extending the system logic to their own custom components and experiences. The usability issues left individuals at a loss; resulting in their use of primitives directly; which in IDS meant they would not have dark mode support.
Individuals explicitly, and directly requested a better set of semantic tokens so that they could apply styles with an understanding of the rationale, and to clearly communicate between designers and developers regarding how to construct their components.
Finding the solution
Token names are how design tokens are referenced and identified by consumers. But at the core, a “name” is more of an ordered representation of a catalog system and API. This catalog system and API is also known as a token taxonomy. Building a clear taxonomy assisted us in appropriately and consistently classifying tokens, as well as providing a scalable and predictable naming convention for consumers.
We started defining semantic tokens and the taxonomy system based on some criteria:
- Favor clarity over brevity
- Consistency across platforms
- Keep the set small
- Balance abstractions (keep generic but provide actionable context)
- Use an object-oriented taxonomy
With this approach, we would be able to identify tokens with broad use case coverage, and the taxonomy would be intuitive and rational. The number of tokens would be minimal to avoid extraneous use cases, but robust enough to have greater overall coverage. Finally, the tokens we created with this approach were tested with designers and developers from each of our consuming design systems teams to ensure we properly solved the problems we had.
What is use case coverage?
Use case coverage means the amount of use cases that would logically fit under a broader “umbrella” use case. For example, ‘text-color-default’ could apply to many different use cases across any component of the application, whereas ‘title-color-default’ would only apply to use cases of “title” text.
This is how we framed the problem for our partner teams. Our solution needed to focus on use case coverage. In order to define this in a token system, we expressed how coverage changes for the different token types: primitives, semantics, and component tokens. By demonstrating the inverse relationship between precise contextual names and their use case coverage, we can see the value in a robust semantic token set.
Primitive tokens
Primitive tokens have no inherent design intent for how or where they should be used. Because of this, primitive tokens have the largest use case coverage for interfaces, since they can be used nearly anywhere. However, because of their lack of contextual precision, they hold little value in creating a cohesive visual language.
Semantic tokens
Semantic tokens have a wider range of contextual precision (how or where they should be used). Because of this, semantic tokens also have a wide range of use case coverage.
Component tokens
Component tokens highly contextual names mean they have very specific usage. Because of this precision, they can’t be reused very often and have less use case coverage than other token types.
This framing of token types and how they relate to use case coverage helped to frame the problem and solidify the solution for a more comprehensive set of semantic tokens.
Creating the taxonomy system
A core working group workshopped the initial set of tokens and draft taxonomy. Starting with color, we identified existing use cases and new required or potentially valuable use cases, such as basic text color options.
We performed several exercises during our workshops to create each category. First we grouped options based on their similarities — sometimes similarities in prior names, but more importantly similarities regarding how an option changes the design. We would then do word association exercises and scour a thesaurus for terms that best expressed what the options controlled. We dot-voted and discussed our options, which we later shared with partners and consumers to verify or revise our choices.
For an example, we had notions of “primary”, “secondary”, and “tertiary”. We noticed that their usage typically related to the amount of visual prominence that was given to a component; primary had high contrast colors, tertiary had lower contrast colors. The category we landed on is called “Prominence”, which scaled nicely to incorporate additional use cases such as “accent” colors. This option was very clear for us, our partner design systems teams, and their consumers.
Each taxonomy needs to have as little overlap in terminology as possible. This would help us create a system with mutually exclusive options, providing clarity on each category’s purpose. Ambiguity leads to confusion, inconsistency, subjectivity, and fragmentation. Our system needed resiliency, scalability, and flexibility — so we needed to eliminate as much ambiguity as possible.
The purpose of this level of structure is to ensure we have a scalable, rational system for long-term stability. Without such structure, we could risk ambiguous or conflicting terminology introduced in future tokens. The result of that risk would result in some of the same usability issues we were trying to solve for our consumers (confusing, unintuitive names making it difficult to understand and find the right token).
This taxonomy provided a framework for classifying tokens of any type.
The naming convention derived from our taxonomy is ordered from the most generic categories to more specific. This is an intentional way of ordering each category to build upon one another, resulting in tokens that have natural, human-friendly names.
Categories and their options
Each category was intentionally defined with an initial set of clear options. They were intended to answer specific types of questions a person may have when trying to identify how or where to use a token. Below are a few examples of how we documented these categories and their options.
Element
The “element” category is for specifying the UI object that the token relates to. It answers the question, “what object uses this token?”
Prominence
Prominence is a signifier of visual hierarchy, or how much an element visually stands out. It answers the question, “how visually distinct is the object using this token?”
Purpose
The general purpose that the token communicates within the UI. It answers the question, “what is being said to the user?”
Our system has several other categories with specific definitions, purposes within the system, and examples for our consumers to get to know our tokens better. These were just a few to help illustrate what we defined.
Measuring our success
The effort to reimagine our semantic tokens happened synchronously with one of our product’s platform modernization efforts. This provided us with quick, real-world feedback regarding the success or failure of our system.
For the more complex semantic tokens (color, if you haven’t guessed it), we performed rounds of user testing with designers to ensure the names and structure was intuitive. The tests were structured as task-based usability studies: designers had to reassign colors to existing designs (in the style of their own redesign), as well as creating a brand new design using the new color tokens. The tokens were delivered as a Figma library, ensuring we fixed any previous usability issues (such as filtering and name clipping).
Alongside the user testing, engineers across web and mobile products were simultaneously implementing a proof-of-concept with the new tokens. We met frequently to identify any issues, missing semantic tokens, and more.
Overall, along with supporting documentation, the semantic tokens have been very successful. Designers and engineers can easily locate and identify the purpose and usage of tokens across multiple platforms. Additional interviews are continually held in order to ensure teams migrating to the new tokens can understand them and that they are meeting (or exceeding) expectations.
Summary
Creating a flexible design token taxonomy is no simple feat. When the taxonomy must support the needs of design systems that build on top of them, it becomes more complex. In order to succeed, we needed a balance of rationale, experience, and expertise combined with diligent user-centric approaches such as interviews, usability testing, and cross-functional collaborative workshops.
If you are unable to dedicate this amount of time to creating a custom design token taxonomy for your system, Nathan Curtis has a great taxonomy to use as a starting point. However, if you are able to, a taxonomy system that is specific to the needs of your design language, products, and goals will ensure success for internal users and may better stand the tests of time, and the future evolutions of your system.
