Design System Architect

A design system is a single source of truth that brings consistency at scale.

Core Principle

Design systems are not just component libraries—they're the shared language between design and engineering. A good design system:

• Accelerates product development (reusable components)
• Ensures consistency across products (unified brand)
• Improves accessibility (baked into components)
• Enables scalability (compound growth, not linear)
• Reduces technical debt (centralized maintenance)

Goal: Build once, use everywhere. Maintain once, improve everywhere.

---

Phase 1: Design Tokens

What Are Design Tokens?

Design tokens are the atomic values of your design system. They're the smallest decisions (colors, spacing, typography) stored as data and consumed by all platforms.

Why Tokens Matter:

• Single source of truth (change once, update everywhere)
• Platform-agnostic (JSON → CSS, iOS, Android, etc.)
• Versioned and traceable (Git history for design decisions)
• Themeable (light/dark modes, brand variants)

Token Structure

// tokens/colors.json
{
  "color": {
    "brand": {
      "primary": {
        "50": { "value": "#eff6ff" },
        "100": { "value": "#dbeafe" },
        "200": { "value": "#bfdbfe" },
        "300": { "value": "#93c5fd" },
        "400": { "value": "#60a5fa" },
        "500": { "value": "#3b82f6" },
        "600": { "value": "#2563eb" },
        "700": { "value": "#1d4ed8" },
        "800": { "value": "#1e40af" },
        "900": { "value": "#1e3a8a" },
        "950": { "value": "#172554" }
      }
    },
    "semantic": {
      "background": {
        "primary": { "value": "{color.neutral.50}" },
        "secondary": { "value": "{color.neutral.100}" }
      },
      "text": {
        "primary": { "value": "{color.neutral.900}" },
        "secondary": { "value": "{color.neutral.600}" }
      },
      "feedback": {
        "success": { "value": "#10b981" },
        "warning": { "value": "#f59e0b" },
        "error": { "value": "#ef4444" },
        "info": { "value": "#3b82f6" }
      }
    }
  }
}

Token Categories

Primitive Tokens (Raw values):

{
  "color-blue-500": "#3b82f6",
  "space-4": "16px",
  "font-size-base": "16px"
}

Semantic Tokens (Named by purpose):

{
  "color-primary": "{color-blue-500}",
  "spacing-default": "{space-4}",
  "text-body": "{font-size-base}"
}

Component Tokens (Component-specific):

{
  "button-padding-x": "{spacing-default}",
  "button-background": "{color-primary}",
  "button-text": "{color-white}"
}

Token Architecture

tokens/
├── primitives/
│   ├── colors.json       # Raw color values
│   ├── spacing.json      # 4px, 8px, 16px...
│   ├── typography.json   # Font sizes, weights
│   ├── shadows.json      # Elevation system
│   └── radii.json        # Border radius values
├── semantic/
│   ├── colors.json       # background-primary, text-secondary
│   ├── spacing.json      # spacing-tight, spacing-comfortable
│   └── typography.json   # heading-xl, body-md
└── components/
    ├── button.json       # Button-specific tokens
    ├── input.json        # Input-specific tokens
    └── card.json         # Card-specific tokens

Token Transformation with Style Dictionary

Install Style Dictionary:

npm install --save-dev style-dictionary

config.json:

{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "dist/css/",
      "files": [
        {
          "destination": "variables.css",
          "format": "css/variables"
        }
      ]
    },
    "js": {
      "transformGroup": "js",
      "buildPath": "dist/js/",
      "files": [
        {
          "destination": "tokens.js",
          "format": "javascript/es6"
        }
      ]
    }
  }
}

Build tokens:

npx style-dictionary build

Output (variables.css):

:root {
  --color-brand-primary-500: #3b82f6;
  --color-semantic-background-primary: #fafafa;
  --space-4: 16px;
  --font-size-base: 16px;
  --button-padding-x: 16px;
}

Dark Mode with Tokens

// tokens/semantic/colors-light.json
{
  "background": {
    "primary": { "value": "#ffffff" },
    "secondary": { "value": "#f9fafb" }
  },
  "text": {
    "primary": { "value": "#111827" },
    "secondary": { "value": "#6b7280" }
  }
}

// tokens/semantic/colors-dark.json
{
  "background": {
    "primary": { "value": "#111827" },
    "secondary": { "value": "#1f2937" }
  },
  "text": {
    "primary": { "value": "#f9fafb" },
    "secondary": { "value": "#d1d5db" }
  }
}

CSS Output:

:root {
  --background-primary: #ffffff;
  --text-primary: #111827;
}

[data-theme='dark'] {
  --background-primary: #111827;
  --text-primary: #f9fafb;
}

---

Phase 2: Component Architecture

Atomic Design Methodology

Atoms → Molecules → Organisms → Templates → **P

...