Naming Tokens in Design Systems

Design tokens are the foundation of any strong design system. They act as small, reusable variables for things like colors, typography, spacing, and more. Instead of hardcoding values like #0070f3 or 16px, tokens like color-primary or space-md help maintain consistency and make scaling easier.

As your token library grows, one thing becomes essential: naming.

Clear naming makes tokens easier to understand and apply. It keeps designers and developers aligned, simplifies documentation, and avoids confusion during implementation.

"Tokens need names that identify what they are, followed by layers of aliasing that provide broad to specific contextual uses of the token within your system" — Nate Baldwin

In this post, we’ll walk through why naming matters, key principles for structuring token names, and real examples from our own system. Whether you're just starting out or managing a mature design system, thoughtful naming will save time and reduce friction.

Why Naming Matters

Design tokens may be small, but their names do a lot of heavy lifting. A good name makes the token's purpose clear — without needing extra explanation or documentation.

When naming is done well, it:

• Helps designers and developers stay on the same page

• Makes updates and scaling much easier

• Builds a shared language that supports collaboration across teams

Naming tokens isn’t just about order — it’s about building a shared language that works across design and engineering.

Recommended Token Naming Structure

Now that we know clear naming is key, let’s talk about how to actually name these tokens in a way that scales — without turning into an unmanageable alphabet soup.

When we set out to name our tokens, we leaned on some best practices from the design systems community (shoutout to Nathan Curtis’s excellent article). These layers describe what the token is, how it behaves, and where it’s used.

[image placeholder]

🧱 Base Level: What the token is

This includes:

• Category — e.g. color, space, font

• Property — e.g. background, text, radius

• Purpose — e.g. action, input, info

🎨 Modifier Level: How it changes

Modifiers add nuance through:

• Variant — like primary, secondary

• State — like hover, disabled, focus

• Scale — like 100, 200, or sm, lg

• Viewport — desktop, tablet, mobile

• Mode — on-light, on-dark

🧩 Object Level: Where it’s used

Defines the component or part of the component, such as:

• button, input, left-icon, label

🌍 Namespace Level: Who it’s for

For multi-brand systems, we used namespace levels like:

• Brand: bnet, blizzard

• Layer: global, semantic, component

This post explores how to approach token naming using a strong foundation, then building on it with modifiers, objects, and namespaces. Along the way, I’ll share some of the lessons we learned and the strategies that worked for our team.

Base Level: Category, Property & Purpose

Category and property form the core of most token names. These help you identify what kind of style the token refers to.

[image placeholder]

We identified the following categories to implement in our v1 of tokens sytem:

• color

• font

• space

• size

• border

• elevation

Each category is paired with a property like background, text, or radius to define what the token controls. For example:

• color-background

• space-padding

To give more context, we added a purpose level. Purpose helps group tokens by their functional role — like action, input, or feedback. This helped make tokens more meaningful and easier to apply.

[image placeholder]

Modifier Level: Adding Flexibility

Modifiers give tokens flexibility by capturing differences in use.

[image placeholder]

• Variants define visual hierarchy or tone: primary, secondary, tertiary

• States reflect interaction: hover, focus, disabled, active

• Scales define size or intensity:

  • Numeric (100, 200, etc.)

  • T-shirt sizing (sm, md, lg, etc.)

• Viewport helps with responsive design: desktop, tablet, mobile

• Mode reserves space for themes like light/dark — even if not currently in use

These layers helped us create tokens that were flexible but still easy to manage.

Object Level: Component-Specific Tokens

Sometimes tokens apply to just one component or a small group. That’s where object-level naming helps.

For example, in more complex components like banners or forms, we needed:

• Component names like announcement-banner

• Nested parts like text-box, content-gap, or left-icon

This helped teams reuse patterns where possible, but still tailor tokens to specific needs.

Namespace: Supporting Multiple Brands and Layers

As our design system supported both Battle.net and Blizzard, we introduced a namespace level to separate brand-specific tokens. These tokens mapped back to shared global tokens and fed into semantic and component-level usage.

We didn’t need to override semantic tokens with brand-specific values yet — but having this structure in place prepared us for that possibility.

We also debated whether to keep the layer (e.g. global, semantic) in the token name. We kept it for clarity — especially for onboarding and collaboration. In time, as the system matures, we may simplify this for conciseness.

Namespace

As our design system supported both Battle.net and Blizzard, we introduced a namespace level to separate brand-specific tokens. These tokens mapped back to shared global tokens and fed into semantic and component-level usage.

We didn’t need to override semantic tokens with brand-specific values yet — but having this structure in place prepared us for that possibility.

We also debated whether to keep the layer (e.g. global, semantic) in the token name. We kept it for clarity — especially for onboarding and collaboration. In time, as the system matures, we may simplify this for conciseness.

Real Example: Announcement Banner

Here's a real example of how components were used.

Color

[image placeholder]

We used semantic tokens for text to maintain consistency across the system, but introduced a new component-level token for the background. Since this component is interactive and often features game art as a background, it needed its own treatment. The token announcement-banner-color-background was created for this purpose and referenced the global token global-color-grey-300.

Space

[image placeholder]

We introduced a few component-level tokens for this banner because its spacing needed to be carefully managed.

• announcement-banner-max-width-text-desktop and announcement-banner-max-width-text-mobile were created to control the text box’s maximum width. By exposing this as a token, different teams could adjust the value to better align with their brand’s visual style.

• announcement-banner-space-padding was added to manage both vertical and horizontal padding through tokens, giving teams flexibility to adjust spacing as needed.

• announcement-banner-content-gap was introduced to handle spacing between internal elements, which needed to vary depending on the layout configuration.

These tokens helped manage a flexible but well-structured component across different teams and use cases.

Questions to Ask Along the Way

How do we create shared understanding? We ran workshops and training sessions to onboard teams to our naming system. Even with testing and feedback, ongoing education was key — especially around how to apply tokens correctly.

What challenges might come up? Conflicts in naming conventions happened early on. Teams had used similar terms differently. We had to realign and clean up inconsistencies with intent.

Is the naming system easy to use? As designers began contributing and using tokens directly, we planned follow-up studies to continue improving the structure based on real feedback.

Conclusion

In design systems, naming conventions might not be flashy — but they quietly shape how teams work, collaborate, and build together. A thoughtful naming approach that balances clarity, structure, and flexibility creates a strong foundation that can grow with your product.

As design systems evolve, it’s important to keep the human side of naming in mind. It’s not just about what makes sense in code — it’s about creating a shared language that brings teams together and supports better, faster, and more consistent design decisions.

Because in the end, the strength of a design system isn’t just in how it looks — it’s in how clearly it communicates.