Naming Your Design Tokens: A Comprehensive Guide for UX Designers

Naming Your Design Tokens: A Comprehensive Guide for UX Designers

Design tokens are an essential part of modern design systems, ensuring consistency and scalability across digital products by bridging the gap between design and development. However, many UX designers looking to apply design tokens in their own work find the process challenging to implement, especially across complex platforms. Establishing foundational characteristics like effective naming sets the stage for their successful application within your design-to-dev pipeline.

Establishing effective naming conventions might seem like a straightforward task, but it requires careful consideration and a strategic approach. The names you choose will impact how easily your team can understand, search, and apply these tokens across your design and development processes. In this module, we’ll explore the principles and practices that can help you create a robust naming convention for your design tokens.

If you are new to design systems and tokens, read our series overview here.

What Are Design Tokens?

Design tokens are text-based symbols that store visual design attributes such as colors, font sizes, spacing values, and more. These tokens act as the building blocks of your design system, ensuring consistency across different platforms and devices. By using design tokens, you can create a single source of truth for your design language, which can then be easily implemented by developers. For example:

• Colors: Primary-Color, Secondary-Color, Background-Color

• Typography: Heading-Font, Body-Font, Button-Font

• Spacing: Padding-10px, Margin-5px

Reusing these tokens across various components ensures consistency throughout the design. When set up correctly, they allow for easy updates—changing a token’s value automatically updates all instances of its use across your designs.

Why Naming Design Tokens Matters

Before diving into the specifics of naming conventions, it’s important to understand why the naming of design tokens is so crucial. Design tokens are more than just variables; they are the language that designers and developers use to communicate visual decisions across platforms. A well-thought-out naming system should accomplish several things, including:

• Improving Clarity and Understanding: Clear and consistent names help team members quickly grasp the purpose and use of a token, reducing the cognitive load and minimizing the chances of errors.

• Facilitating Collaboration: Design tokens are often used by interdisciplinary teams, including designers, developers, and product managers. A common naming convention ensures that everyone is on the same page, improving collaboration and reducing miscommunication.

• Enhancing Scalability: As your design system grows, the number of tokens will increase. A logical naming structure allows your system to scale without becoming unwieldy or confusing.

• Ensuring Consistency: Consistent naming conventions help maintain visual coherence across different components, platforms, and products. This is especially important for large organizations with multiple teams working on the same design system.

Principles for Naming Design Tokens

When naming design tokens, there are several key principles to make your naming conventions practical and scalable.

1. Be Descriptive but Concise

Token names should clearly describe the attribute they represent, but also be concise, easily identified, and usable. Striking a balance between clarity and brevity is essential. For example: $color-primary-blue-dark If the context makes it clear that it’s a shade of blue, you would use: $color-primary-dark However, if the design system includes multiple primary colors, the color could be: $color-primary-blue-dark

2. Use a Consistent Structure

A consistent naming structure makes it easier to organize and locate tokens within your system. This structure often includes a combination of categories, properties, and modifiers.

For example, a common structure might be [category]-[property]-[modifier]. This would be represented as: $color-background-hover or $font-size-heading-large

3. Avoid Ambiguity

Ambiguous names can lead to confusion and misuse of tokens. Ensure that each name clearly distinguishes one token from another, particularly when they serve similar but distinct purposes.

For example, avoid generic names without context, such as: $color-secondary Instead, specify the use, such as: $color-secondary-button

4. Consider Future Scalability

As your design system evolves, you’ll likely add new tokens. Choose names that can accommodate growth without requiring a complete overhaul of your naming convention.

For example, if you anticipate adding new shades of a color, start with a structure, such as: $color-accent-1, $color-accent-2 This will allow you to easily add $color-accent-3 later.

5. Maintain a Shared Vocabulary

Ensure that your team has a shared understanding of the terms used in your token names. This might involve creating a glossary or style guide that defines key terms and their appropriate usage.

For example, define what “primary,” “secondary,” “tertiary,” “hover,” and other commonly used terms mean within the context of your design system.

Breaking Down the Components of Token Names

To create a robust naming convention, break down the components of a token name into specific levels. These levels can include categories, properties, concepts, and modifiers, each serving a distinct purpose.

1. Category

The category is the broadest level and typically represents a fundamental aspect of the design, such as color, typography, spacing, or elevation. For example:

$color, $font, $space, $shadow

2. Property

The property describes the specific attribute within the category. For color tokens, properties might include background, text, or border. For typography, properties might include size, weight, or line-height. For example:

$color-background, $font-size, $space-padding

3. Concept

Concepts group tokens within a category by their purpose or usage. For instance, color tokens might be grouped into concepts like feedback, action, or status. For example:

$color-feedback-error, $color-action-primary, $color-status-success

4. Modifier

Modifiers refine the token by specifying variants such as states (hover, active, disabled), scale (small, medium, large), or modes (light, dark). For example:

$color-background-hover, $font-size-heading-large, $color-action-primary-on-dark

Practical Examples of Token Naming

To illustrate how these principles and components come together, let’s look at some practical examples of naming conventions for different types of tokens.

Color Tokens

Color tokens are one of the most common types in any design system. Here’s how you might structure their names:

• Primary Button Background Color: $color-button-primary-background

• Error State Text Color: $color-feedback-error-text

• Hover State for Link: $color-link-hover

Typography Tokens

Typography tokens manage text styles across your design system. Naming conventions here might include:

• Heading 1 Font Size: $font-size-heading-1

• Body Text Line Height: $font-line-height-body

• Caption Font Weight: $font-weight-caption

Spacing Tokens

Spacing tokens ensure consistent margins, padding, and gaps across your designs. Examples might include:

• Small Padding: $space-padding-small

• Medium Margin: $space-margin-medium

• Large Gap Between Components: $space-gap-large

Addressing Challenges in Token Naming

While the principles and structures outlined above provide a strong foundation, naming tokens isn’t always straightforward. Here are some common challenges and how to address them.

Handling Multiple Themes

If your design system supports multiple themes (e.g., light and dark modes, brand variants), you’ll need to account for these in your naming convention. One approach is to prepend or append theme identifiers to the token names. For example:

$color-primary-background-light

$color-primary-background-dark

Managing Complex Components

For complex components that involve multiple nested elements, naming can become unwieldy. In these cases, consider breaking down the component into its parts and naming tokens accordingly. For example:

$component-button-primary-background

$component-button-primary-text

Evolving Naming Conventions

As your design system matures, you may find that your initial naming convention no longer meets your needs. It’s important to allow for flexibility and evolve your naming strategy as necessary, but do so with care to avoid disrupting your team’s workflow. For example, when updating a naming convention, ensure that all instances of the old token names are updated consistently across your system.

Naming Hierarchies

As your product and brand evolve, your components will too, and extending your hierarchy to the level of semantic or component tokens gives your token system greater depth and specificity. Semantic tokens recodify core values like color with values based on form and usage. For example, while a core token could signify a certain shade of red, a semantic token would signify an error state or cancel action. Component tokens take semantic naming a step further to indicate characteristics of a particular component like a cancel button.

With more component level specificity, you have more granular control over the appearance of your design and a higher degree of integration between design and development, but at the cost of creating a potentially much larger token set. Our recommendation is to start simple and work at the semantic level, only adding component-level tokens when the need arises.

• Semantic examples:

surface-primary

border

borderRadius-medium

• Component examples:

card-surface-primary

inputField-border

button-borderRadius

Best Practices for Implementing Naming Conventions

To successfully implement your naming conventions, consider the following best practices:

• Document Your Conventions: Create a clear and accessible guide that outlines your naming conventions. Include examples, definitions, and any exceptions to the rules.

• Use Automation Tools: Tools like linters, token managers, and design system automation software can help enforce naming conventions and ensure consistency across your design and development environments.

• Train Your Team: Ensure that everyone involved in the design and development process understands the naming conventions and knows how to apply them. Regular training sessions or workshops can be beneficial.

• Regularly Review and Update: As your design system grows, regularly review your naming conventions to ensure they still meet the needs of your team. Be open to making adjustments as necessary.

Conclusion: The Impact of Thoughtful Naming on Your Design System

Naming your design tokens is a critical step in building a scalable, efficient, and user-friendly design system. By following the principles and best practices outlined in this post, you can create a naming convention that not only supports your current design needs but also allows your system to grow and evolve over time.

Remember, the goal is to create a shared language that facilitates collaboration, ensures consistency, and ultimately enhances the quality of your digital products. At DOOR3, we specialize in helping organizations build and optimize their design systems, including the strategic implementation of design tokens. By partnering with us, you can ensure that your design system is not only robust and scalable but also easy to use and maintain.

Stay tuned for more insights and tips on design systems, and feel free to reach out if you’re ready to take your design and development processes to the next level.