, ,

/

September 17, 2024

Naming Design Tokens

Abstract digital illustration featuring overlapping geometric shapes including circles, squares, and lines in muted tones of orange, teal, navy, and red, interconnected by fine lines symbolizing digital networks or data flow.

Token Names

Effective token names improve and sustain a team’s shared understanding of visual style through design, code, and other interdisciplinary handoffs.

Terms matter.
We must be able to browse and search tools to quickly recognize and recall the purposeful decisions we’ve made.


Visual taxonomy of design tokens represented by six circular icons labeled Component, Category, Property, Attribute, Relationship, and State, connected by a pink line, each with a blue symbol representing its role.

Complicated tokens comprise of many levels

As tokens become more sophisticated, naming patterns matter.

Design tokens are split into different levels based on their use cases known as Token Tiers

The top layer of tokens are the “options”. It includes all the choices available to you.

At the second layer, you start making “decisions” and marking off some choices.

Flowchart illustrating a hierarchy of token tiers starting from Token Tiers at the top, followed by First Tier Tokens, Second Tier Tokens, and Third Tier Tokens in descending order.
Token Tiers
First Tier Tokens

Store the raw values and build the basis of the design system.

Mainly responsible for the look of the final product by designing all values that can be used.

Second Tier Tokens

Reference primitive tokens. Their names describe the intended use of the token.

They represent the choices the design system team made in regards to when to use which token.

Third Tier Tokens

Reference semantic tokens and tie them to a specific component value.

Vertical flowchart depicting the hierarchy of design tokens: Primitive Tokens at the top, followed by Semantic Tokens, and Component Tokens at the bottom, indicating their layered relationship.

Token Tiers

First Tier Tokens

Store the raw values and build the basis of the design system.

Mainly responsible for the look of the final product by designing all values that can be used.

Second Tier Tokens

Reference primitive tokens. Their names describe the intended use of the token.

They represent the choices the design system team made in regards to when to use which token.

Third Tier Tokens

Reference semantic tokens and tie them to a specific component value.

Vertical flowchart depicting the hierarchy of design tokens: Primitive Tokens at the top, followed by Semantic Tokens, and Component Tokens at the bottom, indicating their layered relationship.
Token Levels

To be sufficiently descriptive, a tokenized language incorporating both taxonomy and typology requires multiple levels. These levels should be detailed enough to organize tokens into coherent groups.

Hierarchy diagram of design token structure divided into four levels: Base Level (Category, Property, Concept), Modifier Level (Variant, State, Scale, Mode), Object Level (Within a Component, Nested Elements, Component Groups), and Namespace Level (System Name, Theme, Domain).

Diagram breaking down a design token name ‘color-background-container-primary--hover’ into labeled segments: category, property, surface, variant, and state, each color-coded to illustrate its semantic role.

An example of a design token name with multiple token levels.

 

Naming Methodology

Design token systems should prioritize predictability and flexibility. The overall methodology is to have a focused set of tokens rather than all possible tokens for all possible scenarios. 

UI color token mapping diagram showing how various design tokens such as Text/Default, Border/Default, Surface/Warning Default, and Action/Primary Default are applied to interface components like labels, buttons, chips, and dropdowns

Design Token Taxonomy

Building a token system should focus on use case coverage. There is a need to understand how coverage changes for the different token levels and that there is an inverse relationship between precise contextual names and their use case coverage.

Diagram illustrating the token hierarchy for a color value #0070F2, progressing from a reference token (sap-ref-color-blue-7), to a semantic token (sap-sem-color-brand-brand-1), and finally to a platform-specific token (m3-comp-filled-button-container-color)

Use case coverage reduces with each level of token categorization
Best Practices

Token names should be given such that they indicate who the design decision is for, where it belongs in the system, what its intended use is, when it applies, how the decision was made, and what its value is.

Each taxonomy needs to have as little overlap in terminology as possible. This would help to create a system with mutually exclusive options, providing clarity on each category’s purpose. 

Diagram showing a gradient triangle moving from generic to specific, accompanied by labeled prompt components including type, element, attribute, purpose, prominence, size, speed, state, and index, illustrating increasing specificity in descriptions.

An example of Taxonomy and Naming conventions with use case coverage.

A taxonomy system that is specific to the needs of your design language, products, and goals will ensure success for its users and may better stand the tests of time, and the future evolutions of your system.

Author
Pratyush Gupta

UX Designer

Ready to Collaborate?

Let's Connect

From the same category