BMAD-METHOD/docs/learn/module-13-design-system/lesson-01-understanding-modes.md

Module 13: Design System

Lesson 1: Understanding the Four Modes

How component management affects your workflow

---

What Are Design System?

When you set up WDS, you chose a mode for handling design components.

This choice affects:

• How Freya works with you
• Where components are documented
• How visuals are generated
• What you deliver to developers

---

The Four Modes

Mode	Description	Best For
1. None	No design system	Quick projects, one-offs
2. Building	System grows from work	First project for client
3. Library	External library + tokens	Using shadcn/Radix/MUI
4. Existing	Import from previous	Second+ project, same client

Each mode has different implications for how you work.

---

Mode 1: None

What It Means

No formal design system. Styling is ad-hoc.

How Freya Works

• Styles defined inline in page specifications
• No component extraction
• Each element is self-contained

Example

### Submit Button
- Type: Button
- Style: Blue background (#0066FF), white text, 14px rounded
- States: Default, Hover (darker), Loading (spinner), Disabled (gray)
- Label: "Create Free Account"

Everything is specified inline. No separate component document.

Best For

• Landing pages
• Quick prototypes
• One-time projects
• Tight deadlines

Trade-off

Consistency is manual. If you want the same button elsewhere, you copy-paste.

---

Mode 2: Building

What It Means

Design system grows organically from your work.

As you design, patterns emerge. When they appear 3+ times, you extract them as components.

How Freya Works

She notices patterns:

"This button appears in three specifications. Should we extract it as a component?"

You say yes → Goes into C-UX-Scenarios/Functional-Components/

Example

After extraction:

### Submit Button
- Component: Button (primary, lg)
- Label: "Create Free Account"

The component definition lives separately. Page specs reference it.

The Evolution

Project 1: Mode 2 (Building)
    ↓
You create components
    ↓
Project 2: Mode 4 (Existing)
    ↓
You reuse what you built

Your work compounds. Each project builds on the last.

Best For

• First project for new client
• Greenfield products
• When brand is still forming

---

Mode 3: Component Library

What It Means

Using an external library (shadcn, Radix, MUI, etc.) with your branding.

The library provides base components. You apply your tokens on top.

How Freya Works

She references library components:

"This matches shadcn's Button component. Use the default variant with primary color?"

Example

### Submit Button
- Component: shadcn/Button
- Variant: default
- Size: lg
- Class: Custom styles from tokens
- Label: "Create Free Account"

# tokens/colors.yaml - Your brand applied to library
colors:
  primary: "#0066FF"  # Your blue
  destructive: "#DC2626"  # Your red

Best For

• Speed to market
• Consistent base components
• Teams familiar with the library
• When you don't need custom patterns

Trade-off

You get the library's patterns, not your own. Customization has limits.

---

Mode 4: Existing

What It Means

Import design system from a previous project.

You've built components before. Now you reuse them.

How Freya Works

She loads your existing components:

"You have a Button component from the Acme project. Use it here?"

You can extend with new variants:

### Submit Button
- Component: Button
- Variant: "outline" (NEW)

Best For

• Second+ project for same client
• Product families
• Brand consistency across projects

The Power

Your work compounds. Each project starts with a foundation.

---

Mode Selection Flow

New Project Setup
        ↓
Do you need reusable components?
        ↓
    No → Mode 1: None
        ↓
    Yes → Do you have an existing system?
              ↓
          Yes → Mode 4: Existing
              ↓
          No → External library or custom?
                    ↓
                External → Mode 3: Library
                    ↓
                Custom → Mode 2: Building

---

Changing Modes

You can upgrade modes as projects evolve:

Mode 1 → Mode 2

Start with no system, extract components as patterns emerge.

Mode 2 → Mode 4

Complete first project, import system to second project.

Mode 3 → Mode 2

Start with library, add custom components as needs grow.

---

What Each Mode Creates

Mode	Output
None	Inline styles only
Building	D-Design-System/ folder grows
Library	D-Design-System/tokens/ only
Existing	D-Design-System/ extended

---

Common Mistakes

Mistake	Fix
Building when Library works	Evaluate existing options first
None when project will grow	Anticipate future needs
Existing when brand changed	Start fresh with Building
Over-engineering early	Start None, upgrade later

---

What's Next

Understanding your mode helps you work with Freya effectively. In the tutorial, you'll review your mode choice and ensure you're using it correctly.

---

Continue to Tutorial: Apply Your Mode →

---

← Back to Module Overview

Part of Module 13: Design System