Token Tier System

A token tier system organizes tokens into hierarchical levels of abstraction, each serving a distinct purpose in the design system architecture. Tiers create a structured approach to token relationships, clarifying which tokens reference which and guiding appropriate usage. Well-designed tier systems enable theming, improve maintainability, and provide clear mental models for token consumers.

What Is a Token Tier System

A token tier system is a layered architecture where tokens at each tier have defined relationships with tokens at other tiers. Lower tiers contain concrete values, while higher tiers contain references to lower tiers, building abstraction progressively.

The most common tier systems use two or three tiers, though some organizations implement more complex hierarchies for specific needs. Each tier answers a different question: “What values exist?” at the primitive tier, “What are values for?” at the semantic tier, and “How do components use values?” at the component tier.

How Token Tier Systems Work

A three-tier system typically includes primitives, semantics, and component tokens.

The primitive tier contains raw values without usage context. These tokens answer “what” without explaining “why”:

{
  "color": {
    "blue": {
      "500": { "value": "#3B82F6" },
      "600": { "value": "#2563EB" }
    },
    "gray": {
      "100": { "value": "#F3F4F6" },
      "900": { "value": "#111827" }
    }
  }
}

Primitives form the complete palette of available values. They are stable, typically changing only during major rebranding.

The semantic tier maps primitives to purposes. These tokens answer “why this value”:

{
  "color": {
    "action": {
      "primary": { "value": "{color.blue.500}" },
      "primary-hover": { "value": "{color.blue.600}" }
    },
    "background": {
      "default": { "value": "{color.gray.100}" },
      "inverse": { "value": "{color.gray.900}" }
    }
  }
}

Semantics express design intent. They are the primary consumption layer for most applications. Theming operates by changing which primitives semantics reference.

The component tier (optional) creates component-specific applications:

{
  "button": {
    "background": {
      "default": { "value": "{color.action.primary}" },
      "hover": { "value": "{color.action.primary-hover}" }
    }
  }
}

Component tokens enable per-component customization beyond semantic patterns.

Key Considerations

• Each tier should have a clear, distinct purpose
• Tokens should only reference tokens from lower or equal tiers
• Primitives should never reference semantic or component tokens
• The semantic tier is typically the primary consumption interface
• Not all systems need a component tier
• Tier structure should be documented and enforced
• Tooling can validate tier relationships automatically
• Migration between tiers requires careful coordination

Common Questions

How many tiers should a system have?

Most systems work well with two or three tiers. Two tiers (primitives and semantics) suit simpler systems. Three tiers (adding component tokens) support complex customization needs.

Two-tier systems keep architecture simple. Primitives define values; semantics assign meaning. Components consume semantics directly. This simplicity reduces cognitive overhead and works well for organizations without complex theming or multi-brand requirements.

Three-tier systems add flexibility for component-specific customization. Component tokens can diverge from semantic patterns when justified. This flexibility serves enterprise systems, multi-brand platforms, and products requiring deep customization.

More than three tiers is rarely justified. Four or five tiers create confusion about where values should come from and complicate debugging. If a system seems to need many tiers, reconsider whether the complexity genuinely adds value.

Should applications ever use primitive tokens directly?

In most architectures, applications should consume semantic tokens rather than primitives. Semantic tokens express design intent and participate in theming; primitives are raw values without context.

Exceptions exist for specific scenarios. Data visualization often requires palette colors without semantic mapping. Illustration work might need direct primitive access. These specialized uses justify primitive references when semantic tokens do not fit.

When primitives are used directly, the usage should be intentional and documented. Accidental primitive usage breaks theming and indicates either missing semantic tokens or developer misunderstanding.

Some organizations enforce primitive restriction through tooling. Linters can flag direct primitive references in application code, requiring semantic tokens or explicit override justification.

How should tier validation be implemented?

Tier validation ensures tokens follow the hierarchical rules: lower tiers do not reference higher tiers, and references resolve correctly within the structure.

Build-time validation in token transformation tools checks references during compilation:

function validateTiers(tokens) {
  const tierOrder = ['primitive', 'semantic', 'component'];

  tokens.forEach(token => {
    if (token.reference) {
      const referencedToken = resolveReference(token.reference);
      const tokenTier = getTier(token);
      const referencedTier = getTier(referencedToken);

      if (tierOrder.indexOf(referencedTier) > tierOrder.indexOf(tokenTier)) {
        throw new Error(
          `${token.name} (${tokenTier}) cannot reference ${referencedToken.name} (${referencedTier})`
        );
      }
    }
  });
}

Token metadata can explicitly declare tiers:

{
  "color": {
    "blue": {
      "500": {
        "value": "#3B82F6",
        "$tier": "primitive"
      }
    }
  }
}

Explicit tier declaration enables precise validation and documentation generation.

Summary

Token tier systems organize tokens into hierarchical abstraction levels with defined relationships. Primitives contain raw values, semantics assign meaning and enable theming, and optional component tokens provide component-specific customization. Two or three tiers serve most needs, with clear rules about which tiers can reference which. Validation ensures tier relationships remain consistent, maintaining the architectural benefits of structured token hierarchy.