Enterprise Design Systems, Token Architecture & Multi-Theming

In large technology organizations, a Design System is the single source of truth connecting product design in Figma with front-end code across dozens of applications. At the core of every scalable design system is a rigorous Design Token Architecture that codifies colors, typography scales, elevation shadows, border radii, and motion curves into structured, reusable CSS Custom Properties.

In this lesson, we explore the 3-Tier Design Token Architecture (Primitive, Semantic, Component), building mathematical typography and spacing scales, multi-brand theming, and high-contrast accessibility themes.

┌────────────────────────────────────────────────────────────┐
│                 3-Tier Enterprise Token Hierarchy          │
├────────────────────────────────────────────────────────────┤
│ Tier 1: Primitive Tokens (Values & Raw Palette)            │
│   `--color-blue-600: oklch(0.55 0.22 255);`                │
│       │                                                    │
│       ▼                                                    │
│ Tier 2: Semantic Tokens (Intent & Context)                 │
│   `--action-primary-bg: var(--color-blue-600);`            │
│   `--surface-elevated : var(--color-slate-900);`           │
│       │                                                    │
│       ▼                                                    │
│ Tier 3: Component Tokens (Component-Specific Overrides)    │
│   `--button-primary-bg: var(--action-primary-bg);`         │
└────────────────────────────────────────────────────────────┘

1. The 3-Tier Design Token Architecture

A robust token system isolates raw values from contextual application logic:

1. Tier 1: Global Primitive Tokens: Raw, literal design values with no implied usage context (e.g., --color-slate-900, --font-size-3xl, --radius-md).
2. Tier 2: Semantic Alias Tokens: Abstract, contextual tokens that define intent and adapt across dark/light themes (e.g., --text-primary, --bg-surface, --border-focus, --action-danger).
3. Tier 3: Component-Scoped Tokens: Dedicated variables exposed on individual component boundaries (e.g., --btn-height, --card-padding, --dialog-max-width), allowing consumers to customize component instances safely.

/* Tier 1: Primitives */
:root {
  --blue-500: oklch(0.62 0.22 255);
  --blue-600: oklch(0.55 0.22 255);
  --slate-50:  oklch(0.98 0.01 240);
  --slate-900: oklch(0.18 0.03 260);
}

/* Tier 2: Semantic Aliases (Light Theme) */
:root, [data-theme="light"] {
  --bg-page: var(--slate-50);
  --bg-surface: #ffffff;
  --text-main: var(--slate-900);
  --action-primary-bg: var(--blue-600);
  --action-primary-text: #ffffff;
}

/* Tier 2: Semantic Aliases (Dark Theme) */
[data-theme="dark"] {
  --bg-page: oklch(0.12 0.02 260);
  --bg-surface: var(--slate-900);
  --text-main: var(--slate-50);
  --action-primary-bg: var(--blue-500);
  --action-primary-text: #ffffff;
}

2. Multi-Brand Theming Architecture

When a single codebase powers multiple white-labeled brands (e.g., Brand A, Brand B, Enterprise Portal), create dedicated brand token layers that reassign Tier 1 and Tier 2 tokens:

/* Brand A Theme */
[data-brand="aurora"] {
  --brand-hue: 250;
  --action-primary-bg: oklch(0.6 0.25 var(--brand-hue));
  --radius-component: 0.5rem;
}

/* Brand B Theme (Warm, rounded aesthetic) */
[data-brand="solaris"] {
  --brand-hue: 45;
  --action-primary-bg: oklch(0.65 0.2 var(--brand-hue));
  --radius-component: 9999px; /* Pill-shaped controls */
}

Components simply consume var(--action-primary-bg) and var(--radius-component)—the entire interface transforms automatically when switching the data-brand attribute!

3. High-Contrast Accessibility Theming

Support WCAG AAA contrast and Windows High Contrast Mode (forced-colors):

@media (forced-colors: active) {
  /* System High Contrast Mode: Use System Colors */
  .btn-primary {
    forced-color-adjust: none;
    border: 2px solid ButtonText;
    background-color: ButtonFace;
    color: ButtonText;
  }
}

Summary

• 3-tier token architecture separates Global Primitives from Contextual Semantics and Component variables.
• Components must only consume Tier 2 Semantic tokens to ensure effortless dark mode and multi-branding.
• Brand theming is achieved by overriding root token layers via data-brand attributes.
• High-contrast media queries (forced-colors) ensure compliance with enterprise accessibility mandates.
• Design tokens establish a unified language between Figma design files and front-end code.

Best Practices

1. Never Allow UI Components to Consume Raw Primitive Tokens Directly: Always route styles through semantic tokens.
2. Expose Component Tokens for Customization: Let consumers tweak --card-radius without writing CSS overrides.
3. Use Style Dictionary to Export Tokens from Figma to CSS: Automate token generation in CI.
4. Test Every Token Pair for 4.5:1 WCAG AA Contrast: Guarantee readability across both light and dark themes.