BMAD-METHOD/src/modules/wds/data/design-system/token-architecture.md

Design Token Architecture

Purpose: Core principles for separating semantic structure from visual style.

Referenced by: All component-type instructions

---

Core Principle

Separate semantic structure from visual style.

HTML/Structure = Meaning (what it is)
Design Tokens = Appearance (how it looks)

They should be independent!

---

The Problem

Bad Practice:

<h2 class="text-4xl font-bold text-blue-600">Heading</h2>

Issues:

• Visual styling mixed with semantic HTML
• Can't change h2 appearance without changing all h2s
• h2 means "second-level heading" but looks like "display large"
• Breaks separation of concerns

---

The Solution

Good Practice:

HTML (Semantic):

<h2 class="heading-section">Heading</h2>

Design Tokens (Visual):

.heading-section {
  font-size: var(--text-4xl);
  font-weight: var(--font-bold);
  color: var(--color-primary-600);
}

Benefits:

• Semantic HTML stays semantic
• Visual style is centralized
• Can change appearance without touching HTML
• Clear separation of concerns

---

Token Hierarchy

Level 1: Raw Values

--spacing-4: 1rem;
--color-blue-600: #2563eb;
--font-size-4xl: 2.25rem;

Level 2: Semantic Tokens

--text-heading-large: var(--font-size-4xl);
--color-primary: var(--color-blue-600);
--spacing-section: var(--spacing-4);

Level 3: Component Tokens

--button-padding-x: var(--spacing-section);
--button-color-primary: var(--color-primary);
--heading-size-section: var(--text-heading-large);

Use Level 2 or 3 in components, never Level 1 directly.

---

Application to WDS

In Page Specifications

Specify semantic structure:

Page Structure:
  - Section Heading (h2)
  - Body text (p)
  - Primary button (button)

NOT visual styling:

# ❌ Don't do this
Page Structure:
  - Large blue bold text
  - 16px gray text
  - Blue rounded button

In Design System

Specify visual styling:

Section Heading:
  html_element: h2
  design_token: heading-section

Design Token Definition:
  heading-section:
    font-size: text-4xl
    font-weight: bold
    color: primary-600

---

Component-Type Instructions

Text Heading Example

When specifying a heading:

1. Identify semantic level (h1-h6)

   • h1 = Page title
   • h2 = Section heading
   • h3 = Subsection heading
   • etc.

2. Map to design token

   • h1 → display-large
   • h2 → heading-section
   • h3 → heading-subsection

3. Store separately

   • Page spec: <h2> (semantic)
   • Design system: heading-section token (visual)

Example Output:

Page Spec:

Hero Section:
  heading:
    element: h2
    token: heading-section
    content: 'Welcome to Our Product'

Design System:

Tokens:
  heading-section:
    font-size: 2.25rem
    font-weight: 700
    line-height: 1.2
    color: gray-900

---

Button Example

When specifying a button:

1. Identify semantic element

   • <button> for actions
   • <a> for navigation (even if styled as button)

2. Map to component

   • Action → Button component
   • Navigation → Link component (button variant)

3. Store separately

   • Page spec: <button> + purpose
   • Design system: Button component styling

Example Output:

Page Spec:

Login Form:
  submit_button:
    element: button
    type: submit
    component: Button.primary
    label: 'Log in'

Design System:

Button Component:
  variants:
    primary:
      background: primary-600
      color: white
      padding: spacing-2 spacing-4
      border-radius: radius-md

---

Input Field Example

When specifying an input:

1. Identify semantic type

   • <input type="text"> for text
   • <input type="email"> for email
   • <input type="password"> for password

2. Map to component

   • Text input → Input Field component
   • Email input → Input Field.email variant

3. Store separately

   • Page spec: Input type + validation + labels
   • Design system: Input Field styling

Example Output:

Page Spec:

Login Form:
  email_field:
    element: input
    type: email
    component: InputField.email
    label: 'Email address'
    placeholder: 'you@example.com'
    required: true
    validation: email_format

Design System:

Input Field Component:
  base_styling:
    height: 2.5rem
    padding: spacing-2 spacing-3
    border: 1px solid gray-300
    border-radius: radius-md
    font-size: text-base

  variants:
    email:
      icon: envelope
      autocomplete: email

---

Why This Matters

For Designers

✅ Consistency: All h2s can look the same without manual styling ✅ Flexibility: Change all section headings by updating one token ✅ Clarity: Semantic meaning preserved ✅ Scalability: Easy to maintain as design system grows

For Developers

✅ Semantic HTML: Proper HTML structure ✅ Accessibility: Screen readers understand structure ✅ Maintainability: Styling centralized ✅ Performance: Reusable styles

For Design Systems

✅ Single Source of Truth: Tokens define appearance ✅ Easy Updates: Change tokens, not components ✅ Consistency: Automatic consistency across pages ✅ Documentation: Clear token → component mapping

---

Common Mistakes

Mistake 1: Mixing Structure and Style

❌ Bad:

Page:
  - "Large blue heading" (h2)

✅ Good:

Page:
  - Section heading (h2 → heading-section token)

Mistake 2: Hardcoding Visual Values

❌ Bad:

Button:
  background: #2563eb
  padding: 16px

✅ Good:

Button:
  background: primary-600
  padding: spacing-4

Mistake 3: Using Visual Names for Semantic Elements

❌ Bad:

<h2 class="big-blue-text">

✅ Good:

<h2 class="section-heading">

---

Token Naming Conventions

Colors

--color-{category}-{shade}
--color-primary-600
--color-gray-900
--color-success-500

Typography

--text-{size}
--text-base
--text-lg
--text-4xl

Spacing

--spacing-{scale}
--spacing-2
--spacing-4
--spacing-8

Component-Specific

--{component}-{property}-{variant}
--button-padding-primary
--input-border-error
--card-shadow-elevated

---

Implementation in WDS

Phase 4: Page Specification

Agent specifies:

• Semantic HTML elements
• Component references
• Content and labels

Agent does NOT specify:

• Exact colors
• Exact sizes
• Exact spacing

Phase 5: Design System

Agent specifies:

• Design tokens
• Component styling
• Visual properties

Agent does NOT specify:

• Page-specific content
• Semantic structure

Integration

Page spec references design system:

Hero:
  heading:
    element: h2
    token: heading-hero  ← Reference to design system
    content: 'Welcome'

Design system defines token:

Tokens:
  heading-hero:
    font-size: 3rem
    font-weight: 800
    color: gray-900

---

Company Customization

Companies can fork WDS and customize tokens:

Company Fork:
├── data/design-system/
│   ├── token-architecture.md (this file - keep principles)
│   ├── company-tokens.md (company-specific token values)
│   └── token-mappings.md (h2 → company-heading-large)

Result: Every project uses company's design tokens automatically.

---

Further Reading

• Naming Conventions: naming-conventions.md
• Component Boundaries: component-boundaries.md
• State Management: state-management.md

---

This is a core principle. Reference this document from all component-type instructions.