Design Tokens Philosophy

A two-tier architecture that separates “what values exist” from “how values are used”—enabling scalable theming and consistent design decisions.

The Core Philosophy: Separation of Concerns

Our token system is built on a fundamental principle: separate raw values from their semantic purpose. This isn't just organizational tidiness—it's a governance strategy that enables theming, brand switching, and systematic evolution without breaking components.

When a designer specifies semantic.color.foreground.primary, they aren't picking a hex value. They're invoking a decision about hierarchy, contrast, and brand expression that has already been vetted. The token can be remapped to a different palette entry or tuned for light and dark modes, but its role and intent remain constant.

The Three Layers

Each layer represents a different level of abstraction, stability, and audience. Understanding where a token belongs helps teams make better decisions about naming, ownership, and extensibility.

Mode-Aware Tokens via Extensions

Rather than duplicating token files for light/dark themes, we use $extensions.design.paths to encode both variants in a single definition:

{
  "foreground": {
    "primary": {
      "$type": "color",
      "$value": "{core.color.mode.dark}",
      "$extensions": {
        "design.paths.light": "{core.color.mode.dark}",
        "design.paths.dark": "{core.color.mode.light}"
      }
    }
  }
}

This says: “Primary text color references core.color.mode.dark in light mode, but flips to core.color.mode.light in dark mode.” The token definition stays in one place while encoding both theme variants.

The Reference Chain

Tokens form a directed graph where each layer can reference tokens from the same or lower layers. The depth you choose determines how changes cascade:

This means changing core.color.palette.blue.500 automatically propagates to every semantic token that references it—and from there to every component that uses those semantic tokens. Semantic-to-semantic references let you create shared roles (like status.danger) that multiple components can derive from.

Modular File Architecture

Tokens are split into focused files for maintainability. This reduces merge conflicts and makes ownership clearer:

ui/designTokens/
├── core/
│   ├── color.tokens.json      # Palettes, modes, data visualization
│   ├── typography.tokens.json # Font families, weights, scales
│   ├── spacing.tokens.json    # Spacing scale (00-10)
│   ├── motion.tokens.json     # Durations, easing curves
│   ├── shape.tokens.json      # Border radii, border styles
│   └── elevation.tokens.json  # Shadows, z-index layers
│
├── semantic/
│   ├── color.tokens.json      # Foreground, background, border, status
│   ├── typography.tokens.json # Text styles, hierarchies
│   ├── components/
│   │   └── component.tokens.json
│   └── ...
│
├── designTokens.json          # Composed aggregate (build artifact)
└── resolver.json              # Theme resolution order

Build Pipeline Outputs

The tokens compile to multiple formats for different consumers:

• CSS Custom Properties — --core-color-palette-neutral-500 for runtime theming
• SCSS Variables — Per-component token files for scoped styling
• TypeScript Types — TokenPath union for autocomplete and type safety
• Composed JSON — Single artifact for runtime or tooling consumption

The Golden Rule

Never use raw values in components. Always reference tokens so the entire system can be re-themed by changing a single source file.

This isn't just about efficiency—it's a structural guarantee of consistency. Without tokens, a change to a brand color requires hunting down dozens of places where the same decision was repeated. With tokens, a single alias change cascades predictably across the system.

Summary

Deep Dives

The following topics extend this overview into more specialized guidance:

Start Exploring