# Phase 5: Design System (Component Library)

**Agent:** Baldr the UX Expert  
**Output:** `D-Design-System/` (or your configured prefix)

---

## What This Phase Does

Design System builds your component library following atomic design principles. Working with Baldr, you create reusable patterns that serve user psychology and ensure visual consistency.

**The key approach:** The design system grows **alongside** Phase 4 work. As you sketch and specify pages, you simultaneously extract and document components. By the time your scenarios are complete, your design system is already built.

---

## What You'll Create

Your Design System includes:

- **Visual Design (01-Visual-Design/)** - Early design exploration before scenarios
  - Mood boards and style direction
  - NanoBanana design concepts
  - Color and typography exploration
  - Visual inspiration and references
- **Assets (02-Assets/)** - Final production assets
  - Logos and brand elements
  - Icon sets
  - Photography and illustrations
  - Custom graphics
- **Design Tokens** - Colors, typography, spacing, shadows
- **Atomic Components** - Buttons, inputs, labels, icons
- **Molecular Components** - Form groups, cards, list items
- **Organism Components** - Headers, footers, complex sections
- **Usage Guidelines** - When and how to use each component
- **Component Variants** - Different states and sizes

---

## Atomic Design Structure

Following Brad Frost's methodology:

### Foundation (Design Tokens)

The values everything else builds on:

- **Colors** - Primary, secondary, semantic (success, error, warning)
- **Typography** - Font families, sizes, weights, line heights
- **Spacing** - Consistent spacing scale
- **Shadows** - Elevation levels
- **Borders** - Radius and stroke styles
- **Breakpoints** - Responsive design points

### Atoms

The smallest building blocks:

- Buttons
- Input fields
- Labels
- Icons
- Badges
- Dividers

### Molecules

Groups of atoms working together:

- Form groups (label + input + error)
- Search bars (input + button)
- Card headers (title + action)
- Navigation items (icon + label)

### Organisms

Complex components made of molecules:

- Page headers
- Navigation bars
- Form sections
- Card layouts
- List views

---

## How It Works

### The Parallel Workflow

Phase 5 isn't a separate phase you do _after_ Phase 4 - it happens **during** Phase 4:

```
Phase 4 Page Design          →    Phase 5 Design System
─────────────────                  ─────────────────
Sketch button for Page 1.1   →    Create "Primary Button" atom
Reuse button on Page 1.2     →    Reference existing atom
Sketch input for Page 2.1    →    Create "Text Input" atom
Create form on Page 2.2      →    Create "Form Group" molecule
Notice pattern across pages  →    Extract as reusable component
```

**The rhythm:**

1. Design a page/component in Phase 4
2. Notice "This could be reusable"
3. Extract to Design System
4. Next page references the system component
5. Repeat

### Visual Design Exploration (01-Visual-Design/)

**Independent Design Phase - Can Start Anytime:**

**Key Insight:** Brand identity and visual design are NOT tied to the product! You can establish your visual identity at any time - before, during, or after product strategy work.

**Purpose:** Establish the visual language that will tie UX to Brand. This is where you define how your brand's personality will be expressed visually across all touchpoints.

**Timing Options:**
- **Before product work:** Establish brand identity first, then build products around it
- **Parallel to strategy:** Develop visual identity while defining product strategy
- **After strategy:** Use strategic insights to inform visual direction

Before diving into scenario-specific design (Phase 4), establish your visual direction:

**Mood Boards:**
- Collect visual inspiration
- Define style direction (modern, playful, professional, etc.)
- Establish visual tone and personality
- Reference examples from similar products

**Design Concepts (NanoBanana):**
- Generate design variations using NanoBanana
- Explore different visual approaches
- Create custom graphics and illustrations
- Generate placeholder assets for prototypes

**Color Exploration:**
- Test color palette options
- Define primary, secondary, and semantic colors
- Ensure accessibility (contrast ratios)
- Document color psychology and usage

**Typography Tests:**
- Experiment with font pairings
- Define hierarchy (headings, body, labels)
- Test readability at different sizes
- Document font usage guidelines

**When to Use:**
- **AFTER Phase 1 & 2** (Product Brief and Trigger Map must be complete first!)
- When establishing brand identity (with strategic context)
- When exploring multiple visual directions (informed by user psychology)
- Before committing to design tokens
- Before Phase 4 scenarios (but after strategic foundation)

**Output Location:** `D-Design-System/01-Visual-Design/`

---

### Production Assets (02-Assets/)

**Later in Design Process - As Design Solidifies:**

Once your visual direction is established and scenarios are designed:

**Logos:**
- Final logo files (SVG, PNG)
- Logo variations (light/dark, horizontal/vertical)
- Brand mark and wordmark
- Usage guidelines

**Icons:**
- Icon sets for UI elements
- Custom icons for product features
- Consistent style and sizing
- Multiple formats (SVG, PNG)

**Images:**
- Photography for product pages
- Illustrations for empty states
- Hero images and backgrounds
- Optimized for web

**Graphics:**
- Custom graphics and elements
- Decorative elements
- Patterns and textures
- Exported from NanoBanana or Figma

**When to Add:**
- After visual direction is established
- When design is near completion
- Before development handoff
- As final assets are created

**Output Location:** `D-Design-System/02-Assets/`

---

### Figma Integration (Optional)

**Automated Visual Refinement:**

WDS supports automated Figma integration via MCP server for visual design refinement:

**Workflow:**
1. Create functional prototype in Phase 4D
2. Freya identifies components needing visual polish
3. Freya injects components to Figma automatically (via MCP server)
4. Designer refines visual design in Figma
5. Freya reads refined components back automatically
6. Design system updated with new tokens/components
7. Prototype re-rendered with polished design

**Benefits:**
- Build design system organically (no upfront investment)
- Component-level precision (not full-page extraction)
- Automated Object ID traceability
- Bidirectional sync (Prototype ↔ Figma ↔ Design System)

**Tools:**
- **Figma MCP** (recommended): Automated integration via MCP server
- **Figma**: Visual design tool for refinement
- See: [Figma Integration Guide](../src/workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md)

---

### Component Extraction

As you specify scenarios in Phase 4, components naturally emerge:

1. **Identify patterns** - "This button style appears in multiple places"
2. **Extract to system** - Document the component with all variants
3. **Reference in specs** - Link scenario specs to system components

---

## Creating Your Design System Documentation

### The Extraction Process

**Step 1: Spot the Pattern**

While working on Phase 4 scenarios, notice when you're designing something reusable:

- "I just designed this button for Page 1.1... and I need it again on Page 1.2"
- "This form input pattern will be used everywhere"
- "We have 3 different card layouts, but they share the same structure"

**Step 2: Create the Component Document**

In your `D-Design-System/` folder, create a component file:

```
D-Design-System/
├── 01-design-tokens.md
├── 02-atoms/
│   ├── primary-button.md          ← Create this
│   ├── text-input.md
│   └── ...
├── 03-molecules/
│   └── form-group.md
└── 04-organisms/
    └── page-header.md
```

**Step 3: Document the Component**

Use this template for each component:

````markdown
# Primary Button

## Overview

The primary button is used for the main call-to-action on any page or section.

## Component Details

**Category:** Atom
**Object ID Pattern:** `*-primary-button`
**Component Library:** [If using one, e.g., "Chakra UI Button"]
**Figma Component:** Primary Button

## Variants

### Size

- **Small:** Compact spaces, secondary actions
- **Medium:** Default size for most use cases
- **Large:** Hero sections, important CTAs

### State

- **Default:** Ready for interaction
- **Hover:** Visual feedback on mouse over
- **Active:** Currently being clicked
- **Disabled:** Action not available
- **Loading:** Processing user action

## Visual Specifications

**Design Tokens:**

- Background: `color-primary-500`
- Text: `color-white`
- Border Radius: `radius-md`
- Padding: `spacing-3` (vertical), `spacing-6` (horizontal)
- Font: `font-semibold`, `text-base`

**States:**

- Hover: `color-primary-600`
- Active: `color-primary-700`
- Disabled: `color-gray-300`, opacity 50%

## Usage Guidelines

**When to use:**

- Primary action on a page or modal
- Main CTA in hero sections
- Form submissions
- Confirmation actions

**When NOT to use:**

- Multiple primary actions (use secondary instead)
- Destructive actions (use danger variant)
- Navigation (use links or secondary buttons)

## Accessibility

- Minimum contrast ratio: 4.5:1
- Keyboard accessible (Enter/Space)
- Focus visible indicator
- ARIA label when icon-only

## Example Usage

**In specifications:**

```markdown
### Submit Button

**Object ID:** `contact-form-submit-button`
**Component:** primary-button
**Variant:** size=large
**State:** default → loading → success
```
````

**In Figma:**
Use "Primary Button" component from library

**In Code (if using Chakra):**

```jsx
<Button colorScheme="blue" size="lg">
  Submit
</Button>
```

## Used In

- 1.1-Start-Page: Hero CTA
- 1.2-Sign-Up: Submit registration
- 2.1-Contact-Form: Send message
- [Update as you use the component]

```

**Step 4: Update as You Go**

Each time you use this component in a new scenario:
1. Add it to the "Used In" section
2. Note any new variants discovered
3. Update specifications if the component evolves

### Interactive Component Gathering

**As you work through Phase 4:**

```

Design Page 1.1
↓
Notice: "This button is reusable"
↓
Create: primary-button.md in Design System
↓
Reference in 1.1 spec: component=primary-button
↓
Design Page 1.2
↓
Need same button: Reference existing component
↓
Design Page 2.1
↓
Need slightly different: Add variant to component doc
↓
Update all references with new variant option

```

---

## Interactive HTML Component Showcase

Beyond documentation, create an **interactive HTML guide** where stakeholders and developers can see and interact with all components.

### Structure

```

D-Design-System/
├── component-showcase.html ← Interactive guide
├── component-showcase.css
├── component-showcase.js
├── 01-design-tokens.md
├── 02-atoms/
│ ├── primary-button.md
│ └── ...

````

### What the Showcase Includes

**For each component:**
1. **Live rendered examples** - See the actual component
2. **All variants** - Size, state, and style options
3. **Interactive states** - Hover, click, focus to see behavior
4. **Visual specifications** - Design tokens, spacing, colors used
5. **Usage notes** - When to use this component

### Building the Showcase

**As you document each component:**

1. **Add to showcase HTML** - Create a card with live examples
2. **Show all variants** - Size, state, visual options
3. **Make it interactive** - Buttons click, inputs accept text, states change
4. **Display tokens** - Show the actual colors, fonts, spacing
5. **Keep it synced** - Update when components evolve

**Use the provided templates:**

Find ready-to-use templates in:
- `reference/templates/component-showcase-template.html`
- `reference/templates/component-card-template.html`

See complete examples in:
- `examples/dog-week-patterns/D-Design-System/component-showcase.html`

### Benefits

**For Designers:**
- Visual inventory of all components
- See components in isolation
- Test interactions and states
- Share with stakeholders for feedback

**For Developers:**
- Visual reference for implementation
- Understand variant options
- See all states and interactions
- Check responsive behavior

**For Stakeholders:**
- See the design language
- Review consistency
- Experience interactive components
- Provide informed feedback

**For QA:**
- Test all component states
- Verify accessibility
- Check responsive behavior
- Document expected behavior

### Maintaining the Showcase

**Keep it current:**
- Add new components as they're documented
- Update when variants change
- Remove deprecated components
- Sync with Figma library updates

**Single source of truth:**
- Markdown docs = specifications and usage
- HTML showcase = visual reference and interaction
- Figma = design source
- Code = implementation

All four should stay aligned.

---

## Component Documentation

Each component includes:

**Purpose & Usage**
- When to use this component
- When NOT to use it
- Psychological intent (connects to Trigger Map)

**Variants**
- Size options (small, medium, large)
- State options (default, hover, active, disabled)
- Visual variants (primary, secondary, ghost)

**Specifications**
- Design tokens used
- Spacing and sizing
- Responsive behavior

**Implementation Notes**
- Technical guidance for developers
- Accessibility requirements
- Animation/interaction details

---

## Choosing a Component Library

### Build vs. Use Existing

**Build your own Design System when:**
- Unique brand identity required
- Custom interactions not available in libraries
- Full control over every detail needed
- Have design resources to maintain system

**Use existing component library when:**
- Fast time to market
- Standard UI patterns sufficient
- Limited design resources
- Want battle-tested accessibility

**WDS supports both approaches** - you can document either custom components or library components using the same structure.

---

## Recommended Component Libraries

These libraries work well with WDS's specification approach:

### React Ecosystem

**Shadcn/ui** (Recommended for flexibility)
- Not a library, but a collection of copy-paste components
- Built on Radix UI primitives (excellent accessibility)
- [ui.shadcn.com](https://ui.shadcn.com)

*Pros:*
- Full component ownership - code lives in your repo
- Easy to customize without fighting library constraints
- No package bloat or version conflicts
- Perfect for WDS documentation (you own the code)

*Cons:*
- Manual updates when new versions release
- Need to maintain copied code yourself
- Requires understanding of component internals

---

**Chakra UI** (Recommended for speed)
- Comprehensive component library
- Excellent TypeScript support
- Built-in dark mode and theming
- [chakra-ui.com](https://chakra-ui.com)

*Pros:*
- Fast to get started - works out of the box
- Excellent accessibility defaults
- Great developer experience
- Active community and good documentation

*Cons:*
- Less control over internals
- Can be opinionated about styling approach
- Larger bundle size than headless options

---

**Radix UI** (Recommended for headless)
- Unstyled, accessible components
- Complete control over styling
- Composable primitives
- [radix-ui.com](https://radix-ui.com)

*Pros:*
- Best-in-class accessibility built-in
- Total styling freedom
- Small bundle size (only import what you need)
- No design opinions forced on you

*Cons:*
- Requires you to style everything yourself
- Steeper learning curve than styled libraries
- More initial setup work

---

**Material UI (MUI)**
- Mature, comprehensive library
- Material Design by default (can customize)
- Large ecosystem of additional packages
- [mui.com](https://mui.com)

*Pros:*
- Battle-tested with large community
- Very comprehensive component set
- Good documentation and examples
- Material Design is familiar to users

*Cons:*
- Heavy bundle size
- Material Design aesthetic hard to override
- Can feel dated for modern designs
- Customization can be complex

### Vue Ecosystem

**Nuxt UI**
- Built for Nuxt/Vue 3
- Modern, fast, accessible
- [ui.nuxt.com](https://ui.nuxt.com)

*Pros:*
- Optimized specifically for Nuxt
- Modern design aesthetics
- Good performance
- Growing ecosystem

*Cons:*
- Nuxt-specific (not for plain Vue)
- Younger library with smaller community
- Less comprehensive than mature alternatives

---

**PrimeVue**
- Rich component set
- Multiple themes available
- Enterprise-focused
- [primevue.org](https://primevue.org)

*Pros:*
- Very comprehensive component library
- Multiple pre-built themes
- Good for complex enterprise UIs
- Active development

*Cons:*
- Can feel corporate/dated
- Larger bundle size
- Theme customization can be complex

### Framework-Agnostic

**Tailwind CSS** (Recommended for design freedom)
- Utility-first CSS framework
- Combine with headless components
- Maximum flexibility
- [tailwindcss.com](https://tailwindcss.com)

*Pros:*
- Complete design freedom
- Small production bundle (unused styles purged)
- Fast prototyping with utility classes
- Pairs perfectly with WDS specifications

*Cons:*
- Not a component library (need to build or combine)
- HTML can get verbose
- Learning curve for utility-first approach
- Need separate component primitives (e.g., Radix)

### Selection Criteria

**Choose based on:**

| Priority | Consider |
|----------|----------|
| **Speed** | Chakra UI, MUI, PrimeVue (ready-to-use) |
| **Customization** | Shadcn/ui, Radix UI, Tailwind (full control) |
| **Accessibility** | Radix UI, Chakra UI (built-in a11y) |
| **Design System** | Shadcn/ui, custom components (full documentation) |
| **Team Familiarity** | What your dev team already knows |

### WDS Integration Pattern

**With existing library:**
1. Document library components in your WDS Design System
2. Reference library component names in specifications
3. Add project-specific variants/customizations
4. Maintain consistency across your product

**Example WDS entry for library component:**
```markdown
## Primary Button

**Library Component:** Chakra UI Button
**Import:** `import { Button } from '@chakra-ui/react'`

**Usage in WDS:**
- Object ID suffix: `-primary-button`
- Figma Component: Primary Button
- Props: `colorScheme="blue" size="lg"`

**Variants:**
- Default: `variant="solid"`
- Secondary: `variant="outline"`
- Ghost: `variant="ghost"`

**When to use:**
Primary call-to-action buttons...
````

---

## Design Application Integration

Your WDS component system connects to your visual design tools (Figma, Sketch, Adobe XD):

### Unified Naming Convention

**Use the exact same names across all tools:**

| WDS Component Name | Figma Component | Code Component  | Object ID          |
| ------------------ | --------------- | --------------- | ------------------ |
| `primary-button`   | Primary Button  | `PrimaryButton` | `*-primary-button` |
| `text-input`       | Text Input      | `TextInput`     | `*-text-input`     |
| `form-group`       | Form Group      | `FormGroup`     | `*-form-group`     |

### The Workflow

```
WDS Specification → Figma Design → Code Implementation
─────────────────    ─────────     ──────────────────
1. Document          2. Create      3. Build with
   "primary-button"     component      same name
   in Design System     in Figma       in code

Object IDs reference the same names:
signin-form-submit-primary-button (everywhere)
```

### Figma/Design Tool Setup

**Component Library Structure:**

Match your WDS atomic design structure:

```
Design File/
├── 🎨 Design Tokens
│   ├── Colors
│   ├── Typography
│   └── Spacing
├── ⚛️ Atoms
│   ├── primary-button
│   ├── text-input
│   └── ...
├── 🧬 Molecules
│   ├── form-group
│   ├── search-bar
│   └── ...
└── 🧩 Organisms
    ├── page-header
    └── ...
```

**Naming in Figma:**

- Component names match WDS names (kebab-case or Title Case)
- Variants match WDS variants (Primary, Secondary, Disabled)
- Properties match WDS states (default, hover, active, error)

### Benefits of Unified Naming

- **Designers:** Find components easily in Figma library
- **Developers:** No translation needed from design to code
- **Testers:** Object IDs make sense and are predictable
- **Documentation:** Single source of truth for naming
- **Handoff:** Zero ambiguity about which component to use

### When You Design in Figma

1. **Reference your WDS Design System** for component names and structure
2. **Create visual designs** using those exact names
3. **Export/handoff** with matching naming to developers
4. **Specifications remain in WDS** - Figma provides the pixels, WDS provides the logic

---

## Growing the System

The design system is living documentation that grows with your product:

### Starting Point

Begin with what you need for current scenarios:

- Extract components from Phase 4 work
- Document only what you're actually using
- Avoid speculating about future needs

### Evolution

As you design more scenarios:

- New patterns emerge → add to system
- Inconsistencies appear → consolidate
- Components evolve → update documentation

### Maintenance

- Keep specs in sync with implementation
- Remove unused components
- Update when design language evolves

---

## When to Use This Phase

**Enable Design System phase if:**

- Building reusable component library
- Multiple pages/scenarios with shared patterns
- Need design consistency across product
- Handoff requires component documentation

**Work in parallel with Phase 4 when enabled:**

- As you sketch, identify component patterns
- As you specify, extract to Design System
- Design System grows with each page completed
- No separate "design system phase" at the end

**Skip this phase if:**

- Small project (single landing page)
- Using existing design system (Material, Chakra, etc.)
- One-off designs without reuse
- Quick prototype or MVP without component library needs

**Dedicated consolidation when:**

- Multiple scenarios complete, need cleanup
- Preparing for development handoff
- Found inconsistencies to resolve
- Onboarding new team members

> **Note:** You'll choose whether to enable the Design System phase during project setup (`workflow-init`). This decision can be revisited as your project grows.

---

## What to Prepare

Bring:

- Completed or in-progress scenario specs (Phase 4)
- Any existing brand guidelines
- Technical framework constraints (React components, etc.)

---

## What Comes Next

Your Design System enables:

- **Consistent implementation** - Developers build from clear specs
- **Faster design** - Reuse components across scenarios
- **Phase 6 handoff** - Complete component inventory

---

## Tips for Great Sessions

**Extract, don't invent**

- Components should come from real design needs
- Don't create components "just in case"
- Let the system grow from actual scenarios

**Document the why**

- Why does this button look this way?
- What user trigger does it serve?
- When should developers use variant A vs B?

**Stay consistent**

- Same component = same specification
- Variations should be intentional
- When in doubt, simplify

**Connect to psychology**

- Every design choice serves a purpose
- Reference your Trigger Map
- Components should feel intentional, not arbitrary

---

## Example Output

See: `examples/dog-week-patterns/D-Design-System/` for a complete Design System from a real project.

---

_Phase 5 of the Whiteport Design Studio method_
