Design System Architecture: Tokens, Components, and Themes

When a global financial enterprise acquired three regional fintech brands, executive leadership requested a brand re-skin: updating the application UI themes to match corporate branding.

Engineering estimated 8 months of work. Because component styles were hardcoded with magic hex values (#1e293b) across 400 repositories, updating a primary brand color required manual code changes in 12,000 files.

Design systems provide the visual foundation for multi-product organizations.

This article deconstructs design system architecture: Three-Tier Design Tokens, Compound Component APIs, and Zero-Runtime Theme Engines.

---

1. Three-Tier Design Token Architecture

[ Tier 1: Global / Reference Tokens ] (Raw Values: --color-blue-500: #3b82f6)
                  |
                  v
[ Tier 2: Semantic Tokens ]          (Intent Values: --color-interactive-primary: var(--color-blue-500))
                  |
                  v
[ Tier 3: Component Tokens ]         (Scoped Values: --button-bg-primary: var(--color-interactive-primary))

---

2. Complete Implementation: Zero-Runtime CSS Custom Property Engine

export class ThemeEngine {
  private root = document.documentElement;

  public setTheme(theme: "light" | "dark"): void {
    if (theme === "dark") {
      this.root.style.setProperty("--color-bg-primary", "#0f172a");
      this.root.style.setProperty("--color-text-primary", "#f8fafc");
      this.root.style.setProperty("--color-brand", "#38bdf8");
    } else {
      this.root.style.setProperty("--color-bg-primary", "#ffffff");
      this.root.style.setProperty("--color-text-primary", "#0f172a");
      this.root.style.setProperty("--color-brand", "#0284c7");
    }
  }
}

---

Summary & Key Takeaways

• Three-Tier Tokens: Decouple raw visual values from component styles via semantic token abstractions.
• Zero-Runtime Theming: Leverage CSS Custom Properties (var(--...)) for instant, zero-re-render dark mode toggling.

---

References & Further Reading

1. W3C Design Tokens Community Group. Design Tokens Format Module Specification. W3C Community Group.

---