Token Tiers: From Raw Values to Component Properties

WHY IT EXISTS To manage the complexity of a design system as it scales. Hardcoding a hex code like #007bff in multiple places is brittle. Creating a single alias like 'brand-primary' is better, but it doesn't distinguish between the brand color itself and its use as, say, a button background. Tiers create a structured, scalable way to manage these relationships, from raw values to their final application.

THE MENTAL MODEL Think of token tiers like a supply chain. The raw materials are your global tokens (e.g., color-blue-400: #3498db). These are processed into intermediate goods, which are semantic tokens (e.g., color-background-interactive: {color.blue.400}). Finally, these are assembled into a finished product, the component-specific token (e.g., button-primary-background: {color.background.interactive}). A change in the raw materials flows down the chain, not the other way around.

HOW IT WORKS Tiers are implemented using aliases, also called references. A token's value is not a literal value but a pointer to another token. The Design Tokens W3C Community Group standardizes a syntax like {path.to.token} for these references. A typical setup involves multiple files: a 'global' or 'core' file defines raw values. A 'semantic' file contains tokens that alias values from the global file to give them meaning. Finally, 'component' files alias tokens from the semantic file to style specific UI elements. This creates a directed, one-way flow of information.

WHEN TO USE IT Use tiers in any design system that needs to scale beyond a single product or theme. They are essential for supporting multiple themes (light/dark), brands, or platforms (web/iOS/Android) from a single source of truth. They allow designers and developers to work at different levels of abstraction; a product developer might only use component tokens, while a system maintainer curates the global palette.

WHEN NOT TO USE IT For very small projects with a single theme and no plans to scale, a full three-tier system can be overkill. A simple global-to-component (two-tier) or even a single layer of semantic tokens might be sufficient. The goal is clarity, not complexity for its own sake. If the hierarchy makes the system harder to reason about, it's not serving its purpose.

ONE CANONICAL EXAMPLE A three-tier system for a primary button color, based on the W3C spec format. First, the global tier (core.json): {"color": {"blue": {"500": {"value": "#007bff"}}}}. Second, the semantic tier (semantic.json) references it: {"color": {"action": {"primary": {"value": "{color.blue.500}"}}}}. Third, the component tier (button.json) references the semantic token: {"button": {"primary": {"background": {"$value": "{color.action.primary}"}}}}. Changing the core blue value automatically updates the button.