23 KiB

Raw Blame History

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:

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

Visual Design Exploration (01-Visual-Design/)

Early Design Phase - Before Scenarios:

Before diving into scenario-specific design, 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:

At project start (before Phase 4 scenarios)
When establishing brand identity
When exploring multiple visual directions
Before committing to design tokens

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:

Create functional prototype in Phase 4D
Freya identifies components needing visual polish
Freya injects components to Figma automatically (via MCP server)
Designer refines visual design in Figma
Freya reads refined components back automatically
Design system updated with new tokens/components
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

Component Extraction

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

Identify patterns - "This button style appears in multiple places"
Extract to system - Document the component with all variants
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:

# 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):

<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

Reference your WDS Design System for component names and structure
Create visual designs using those exact names
Export/handoff with matching naming to developers
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

23 KiB Raw Blame History