Token Architecture (Global vs. Semantic vs. Component)

What is Token Architecture?

Imagine you are building a city. You don’t want to have to paint every brick of every house individually. Instead, you define a “palette of materials” (global tokens), decide that all public buildings will be “institutional color” (semantic tokens), and finally apply that color to the “town hall main door” (component tokens).

This hierarchy is what we call token architecture. Its main goal is to separate the value (the color blue #007bff) from the meaning (this is the primary action color).

The 3 Fundamental Layers

For a design system to be scalable, the three-level model is recommended:

1. Global Tokens (Primitives)

They are the basis of the entire system. They store raw values without a specific intent for use.

• Naming: Based on value (e.g., blue-500, space-16, font-size-large).
• Function: They define the options available in the system’s palette. They should not be used directly in components, as changing the value of blue-500 could break consistency in unexpected places.

2. Semantic Tokens (Aliases)

This is the most important layer. These tokens reference global ones but add a context or intent of use.

• Naming: Based on function (e.g., color-background-primary, color-text-error, space-inset-medium).
• Function: They allow for creating themes (such as Dark Mode). For example, the color-bg-surface token can point to white in light mode and to grey-900 in dark mode. The component doesn’t know what color it is; it only knows it is its “surface color.”

3. Component Tokens (Specific)

They are the final specialization layer. They reference semantic tokens (or sometimes directly global ones) for a specific component.

• Naming: Includes the component name and the prop (e.g., button-primary-background, input-border-color-focus).
• Function: They serve to make fine adjustments to a component without affecting the rest of the system. They provide the highest level of control.

Benefits for the Team

• Scalability: Adding a new theme (e.g., a white-label version) is a matter of remapping semantic tokens.
• Maintainability: Drastically reduces technical debt. There are no “hardcoded” values in either code or design.
• Communication: Designers and developers speak the same language. They no longer say “use the light blue,” they say “use action-primary-hover.”

Mentor’s Tips

• Don’t skip layers: It’s tempting to use global tokens directly to save time, but you will regret it as the system grows.
• Keep names agnostic: Avoid names like color-text-red. If that text should be orange tomorrow, the name will no longer make sense. Use color-text-danger.
• Automate exporting: Use tools like Style Dictionary to transform your token JSON into useful formats for web, iOS, and Android.
• Document the “why”: In your design system, always indicate when each semantic token should be used to avoid confusion.

Useful Resources and Tools

• Style Dictionary (Amazon): The standard tool for transforming tokens.
• Token Studio (Figma Plugin): For managing tokens directly on your design canvas.
• W3C Design Tokens Community Group: The developing standard for token formatting.
• Books: Design Systems by Alla Kholmatova.

token-aliasing-inheritance token-parity design-system