# WDS v6 Conversion Roadmap

**Document Purpose:** Complete record of all decisions, context, and progress for converting Whiteport Design Studio to BMad Method v6 format. This document allows continuation of work if the conversation is lost.

**Created:** December 2, 2025  
**Last Updated:** December 9, 2025  
**Status:** In Progress - Course Development Phase (Getting Started Complete)

---

## Table of Contents

1. [Project Overview](#1-project-overview)
2. [Key Decisions Made](#2-key-decisions-made)
3. [Repository Setup](#3-repository-setup)
4. [Module Architecture](#4-module-architecture)
5. [Output Folder Structure](#5-output-folder-structure)
6. [Design Philosophy](#6-design-philosophy)
7. [Development Order](#7-development-order)
8. [Files Created So Far](#8-files-created-so-far)
9. [Next Steps](#9-next-steps)
10. [Reference Information](#10-reference-information)

---

## 1. Project Overview

### What is WDS?

**Whiteport Design Studio (WDS)** is a design-focused methodology module for the BMad Method ecosystem. It provides a complete UX/UI design workflow from product exploration through detailed component specifications.

### Origin

WDS evolves from **Whiteport Sketch-to-Code (WPS2C)**, a BMad v4 "expansion pack." The v6 conversion transforms it into a proper BMad module following v6 architecture.

### Core Purpose

WDS focuses **exclusively on design** - it creates the design artifacts that feed into development modules like BMad Method (BMM). WDS does NOT include development/backlog functionality.

### Integration Model

```
WDS (Design) ────────► E-UI-Roadmap/ ────────► BMM (Development)
    │                       │                       │
    │ Creates:              │ Bridge:               │ Consumes:
    │ • Product Brief       │ • Priority mapping    │ • Architecture
    │ • Trigger Map         │ • Technical notes     │ • Stories
    │ • Scenarios           │ • Handoff checklist   │ • Implementation
    │ • PRD                 │                       │
    │ • Design System       │                       │
```

---

## 2. Key Decisions Made

### 2.1 Module Name

**Decision:** Whiteport Design Studio (WDS)

**Alternatives Considered:**
- BMad Design Studio
- BMad UX

**Reasoning:** Preserve brand identity, acknowledge contribution origin, maintain "Whiteport" recognition.

### 2.2 Repository Approach

**Decision:** Fork BMad-METHOD repository

**Alternatives Considered:**
- Standalone repository
- Rename existing WPS2C repo

**Reasoning:**
- Maximum adoption through BMad ecosystem
- Path to official module status via PR
- Shared core infrastructure
- Automatic ecosystem integration

**Fork Details:**
- Origin: `https://github.com/whiteport-collective/whiteport-design-studio.git`
- Upstream: `https://github.com/bmad-code-org/BMAD-METHOD.git`

### 2.3 Working Branch

**Decision:** Work directly on `main` branch

**Reasoning:**
- Simpler workflow during development
- WDS is substantial addition, not small tweak
- Fork effectively becomes WDS home
- Will switch to feature branches after official adoption

### 2.4 Workflow Approach

**Decision:** Phase-selectable (not rigid tracks)

**Description:** Users select individual phases based on project needs rather than choosing from predefined tracks.

**Examples:**
- Landing page → Phases 1, 4, 5
- Full product → All 6 phases
- Design system only → Phases 4, 5

### 2.5 Development Handoff

**Decision:** No development artifacts in WDS

**Description:** WDS creates design artifacts only. Development (backlog, stories, architecture) handled by BMM. `E-UI-Roadmap/` serves as the integration bridge.

### 2.6 README Convention

**Decision:** One README.md per repository

**Convention:** Only `README.md` at module root; all other documentation uses `xxx-guide.md` naming pattern.

**Examples:**
- ✅ `wds/README.md` (only one)
- ✅ `wds/docs/method/wds-method-guide.md`
- ✅ `wds/docs/quick-start-guide.md`
- ❌ `wds/docs/README.md` (not allowed)
- ❌ `wds/examples/README.md` (not allowed)

---

## 3. Repository Setup

### 3.1 Local Path

```
C:\dev\WDS\whiteport-design-studio
```

### 3.2 Git Remotes

```
origin   → https://github.com/whiteport-collective/whiteport-design-studio.git
upstream → https://github.com/bmad-code-org/BMAD-METHOD.git
```

### 3.3 Syncing with Upstream

```bash
git fetch upstream
git merge upstream/main
git push origin main
```

---

## 4. Module Architecture

### 4.1 Module Location

```
src/modules/wds/
```

### 4.2 Folder Structure

```
src/modules/wds/
├── _module-installer/          # Installation configuration
│   └── install-config.yaml     # TO CREATE
│
├── agents/                     # WDS agents (v6 YAML format) - Norse Pantheon
│   ├── saga-analyst.agent.yaml    # Saga-Analyst - TO CREATE
│   ├── freyja-pm.agent.yaml       # Freyja-PM - TO CREATE
│   └── baldr-ux.agent.yaml        # Baldr-UX - TO CREATE
│
├── workflows/                  # Phase workflows
│   ├── 0-init/                 # Entry point - TO CREATE
│   ├── 1-product-exploration/  # Phase 1 - TO CREATE
│   ├── 2-user-research/        # Phase 2 - TO CREATE
│   ├── 3-requirements/         # Phase 3 - TO CREATE
│   ├── 4-conceptual-design/    # Phase 4 - TO CREATE
│   ├── 5-component-design/     # Phase 5 - TO CREATE
│   └── 6-dev-integration/      # Phase 6 - TO CREATE
│
├── data/                       # Standards, frameworks
│   ├── presentations/          # Agent intro presentations
│   ├── positioning-framework.md # ICP framework - TO CREATE
│   └── ...
│
├── docs/                       # Documentation (xxx-guide.md)
│   ├── method/                 # Methodology guides
│   │   ├── wds-method-guide.md # Main overview - TO CREATE
│   │   └── phase-guides/       # Per-phase guides - TO CREATE
│   └── images/                 # Diagrams, visuals
│
├── examples/                   # Example projects
│   ├── dog-week-patterns/      # Full reference implementation
│   ├── conversation-examples/  # Dialog flow examples
│   └── starter-project/        # Try-it-yourself project
│
├── reference/                  # Templates, checklists
│   ├── templates/              # Document templates
│   └── checklists/             # Phase completion checklists
│
├── teams/                      # Team configurations
│
└── README.md                   # Module entry point ✅ CREATED
```

### 4.3 Agents - The Norse Pantheon 🏔️

| Agent | File | Role | Norse Meaning | Status |
|-------|------|------|---------------|--------|
| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | TO CREATE |
| **Freyja the PM** | `freyja-pm.agent.yaml` | Product Manager | Goddess of love, war & strategy | TO CREATE |
| **Baldr the UX Expert** | `baldr-ux.agent.yaml` | UX/UI Designer | God of light & beauty | TO CREATE |

**Why "Name the Function" format?**
- Reads naturally: "Saga the Analyst"
- Distinctive Norse mythology names
- Function is immediately clear
- Creates unique WDS brand identity

---

## 5. Output Folder Structure

### 5.1 The A-B-C-D-E Convention

WDS creates an alphabetized folder structure in the user's project `docs/` folder:

```
docs/
├── A-Product-Brief/            # Phase 1 outputs
├── B-Trigger-Map/              # Phase 2 outputs
├── C-Scenarios/                # Phase 4 outputs
├── D-PRD/                      # Phase 3 outputs
├── D-Design-System/            # Phase 5 outputs
└── E-UI-Roadmap/               # Phase 6 outputs (dev bridge)
```

### 5.2 Why Alphabetical Prefix?

| Reason | Benefit |
|--------|---------|
| Visual namespace | Clearly grouped in file explorers |
| Brand signature | "A-B-C-D-E = WDS" recognition |
| Non-conflicting | Won't clash with other docs folders |
| Natural sort | Always grouped together |
| Professional | Enterprise documentation feel |

### 5.3 Phase-to-Folder Mapping

| Phase | # | Name | Output Folder |
|-------|---|------|---------------|
| 1 | Product Exploration | Strategic foundation | `A-Product-Brief/` |
| 2 | User Research | Personas, business goals | `B-Trigger-Map/` |
| 3 | Requirements | Functional & technical | `D-PRD/` |
| 4 | Conceptual Design | Scenarios, sketches | `C-Scenarios/` |
| 5 | Component Design | Design system | `D-Design-System/` |
| 6 | Dev Integration | Handoff bridge | `E-UI-Roadmap/` |

### 5.4 E-UI-Roadmap Contents

The integration bridge folder contains:

```
E-UI-Roadmap/
├── ui-roadmap-guide.md             # Overview
├── priority-sequence.md            # What to build first
├── scenario-mapping.md             # Scenarios → Dev order
├── component-inventory.md          # All components needed
├── technical-notes.md              # Design constraints
└── open-questions.md               # For dev team to decide
```

---

## 6. Design Philosophy

### 6.1 Core Principles

#### Principle 1: Soft Language

**Instead of:** "MUST", "FORBIDDEN", "NEVER", "SYSTEM FAILURE"

**Use:** Collaborative, identity-based guidance

**Reasoning:** User experience shows that harsh enforcement language makes agents MORE likely to ignore instructions, not less.

**Example - Before:**
```markdown
## MANDATORY RULES
- 🛑 NEVER generate without input
- 🚫 FORBIDDEN: Multiple questions
- ❌ SYSTEM FAILURE if you skip
```

**Example - After:**
```markdown
## How We Work Together

You're a thoughtful guide who helps designers create great products.

Your rhythm:
- Ask one question, then listen
- Reflect back what you heard
- Build the document together
```

#### Principle 2: Show, Don't Tell

**Instead of:** Explaining rules

**Use:** Concrete examples

**Reasoning:** People (and LLMs) learn better from examples than abstract rules.

**Implementation:**
- Complete artifacts as examples (not rule descriptions)
- Conversation flow examples
- Dog Week as reference implementation

#### Principle 3: Example Projects for Adoption

**Purpose:**
- Let people try before adopting
- Show what success looks like
- Lower barrier to entry
- Build credibility

**Implementation:**
- Dog Week patterns as full reference
- Starter project for practice
- Conversation examples showing dialog flow

### 6.2 Known Problems to Mitigate

| Problem | Observed Behavior | WDS Solution |
|---------|-------------------|--------------|
| Agents ignore instructions | Generate without thinking | Identity-based personas + examples |
| Inconsistent output formats | Specs look different each time | Complete template examples |
| Question dumping | 20 questions at once | Conversation examples showing one-at-a-time |

### 6.3 Positive Language Guidelines

**Principle:** Frame everything in terms of benefits and opportunities, not problems and costs.

**Patterns to Avoid:**

| Negative Pattern | Positive Alternative |
|------------------|---------------------|
| "Nothing kills a project faster than..." | "It's valuable to discover early..." |
| "expensive development problems" | "easy to address while solutions are flexible" |
| "Finding them later is expensive" | "Finding them now means more options" |
| "Don't do X" | "What works well is Y" |
| "Avoid these mistakes" | "Successful patterns include..." |
| "This prevents failure" | "This enables success" |
| "You'll waste time if..." | "You'll save time by..." |

**The Reframe Test:**

When writing guidance, ask: *"Am I describing what TO DO or what NOT to do?"*

Good WDS documentation:
- Celebrates early discovery (not fears late discovery)
- Describes successful patterns (not failure modes)
- Frames constraints as opportunities (not limitations)
- Uses "enables" not "prevents"

**Example Transformation:**

Before:
> "Nothing kills a project faster than discovering in development that a core feature is technically impossible."

After:
> "It's a great morale boost when you've proven your core features will work. And if you discover limitations, it's valuable to know them early so design can account for them from the start."

### 6.4 Instruction Style

**Identity-First:**
```markdown
## Who You Are

You're Saga, a thoughtful analyst who genuinely cares 
about understanding the product before documenting it.

You prefer deep conversations over quick surveys. You ask one 
thing at a time because you're actually listening.
```

**Experience-Focused:**
```markdown
## The Conversation Style

A good session feels like coffee with a wise mentor:
- They ask something interesting
- You share your thinking
- They reflect it back
- Together you discover something new
```

**Gentle Reminders:**
```markdown
## Helpful Patterns

What works well:
- One question at a time keeps things focused
- Reflecting back shows you're listening

What tends to feel less collaborative:
- Listing many questions (feels like a survey)
- Generating without checking in
```

---

## 6.5 Key Methodology Refinements (Dec 3, 2025)

### Phase Naming Convention
Each phase title now includes the artifact in parentheses:
- Phase 1: Product Exploration (Product Brief)
- Phase 2: Trigger Mapping (Trigger Map)
- Phase 3: PRD Platform (Technical Foundation)
- Phase 4: UX Design (UX-Sketches & Usage Scenarios)
- Phase 5: Design System (Component Library)
- Phase 6: PRD Finalization (Complete PRD)

### Phase 2: Feature Impact Analysis
Added a scoring system (Beta) for prioritizing features:
- Positive drivers: +3/+2/+1 by priority
- Negative drivers: +4/+3/+2 (higher due to loss aversion)
- Bonuses for multi-group and multi-driver features
- Outputs ranked feature list for MVP planning

### Phase 3: PRD Platform
Renamed from "Requirements" to emphasize:
- Technical foundation work (platform, infrastructure)
- Proofs of concept for risky features
- Experimental endpoints that can start before design
- Parallel with design work, not sequential

### Phase 4: Step 4E - PRD Update
Added step 4E after each page design:
- Extract functional requirements discovered during design
- Add to PRD with page references
- PRD grows incrementally throughout Phase 4
- Creates traceability: page → feature → epic

### Phase 5: Optional & Parallel
Clarified that Design System is:
- **Optional** - chosen during project setup
- **Parallel** - builds alongside Phase 4, not after
- Includes unified naming for Figma/Code integration
- Component library selection guidance added

### Phase 6: PRD Finalization
Renamed from "Dev Integration" to emphasize:
- Compiling all functional requirements from Phase 4
- Organizing by epic/feature area
- Continuous handoff model (not single event)
- First handoff at MVP, then ongoing updates

### Removed from Guides
- Duration estimates (project-dependent)
- Inline code examples (belong in templates/examples)
- Negative language ("expensive problems", "kills projects")

---

### 7.1 Chosen Approach: Methodology-First

**Order:**
1. Define the methodology (phases, outputs, connections)
2. Create workflows that implement the methodology
3. Create agents that guide users through workflows
4. Create examples that demonstrate the methodology

**Reasoning:**
- The methodology IS the product
- Agents serve the methodology, not vice versa
- User is crystal clear on the workflow (already proven in WPS2C v4)
- Not inventing new process, porting existing one

### 7.2 Detailed Order

#### Phase 1: Define the Methodology
| Order | Component | File | Status |
|-------|-----------|------|--------|
| 1 | Method Overview | `docs/method/wds-method-guide.md` | ✅ COMPLETE |
| 2 | Phase 1 Guide | `docs/method/phase-1-Product-exploration-guide.md` | ✅ COMPLETE |
| 3 | Phase 2 Guide | `docs/method/phase-2-trigger-mapping-guide.md` | ✅ COMPLETE |
| 4 | Phase 3 Guide | `docs/method/phase-3-PRD-Platform-guide.md` | ✅ COMPLETE |
| 5 | Phase 4 Guide | `docs/method/phase-4-ux-design-guide.md` | ✅ COMPLETE |
| 6 | Phase 5 Guide | `docs/method/phase-5-design-system-guide.md` | ✅ COMPLETE |
| 7 | Phase 6 Guide | `docs/method/phase-6-PRD-Finalization-guide.md` | ✅ COMPLETE |

**Methodology Phase Complete!** All phase guides refined with:
- Positive language throughout (no "expensive problems", "kills projects", etc.)
- Phase titles with artifacts in parentheses
- Removed duration estimates (project-dependent)
- Feature Impact Analysis with scoring system (Phase 2)
- Step 4E: PRD Update during design (Phase 4)
- Design System as optional parallel workflow (Phase 5)
- PRD Finalization with continuous handoff model (Phase 6)
- Unified naming conventions for Figma/Code integration
- Code examples moved to templates/examples (not in guides)

#### Phase 2: Create Examples
| Order | Component | Location | Status |
|-------|-----------|----------|--------|
| 8 | Dog Week Examples | `examples/dog-week-patterns/` | TO CREATE |
| 9 | Conversation Examples | `examples/conversation-examples/` | TO CREATE |
| 10 | Starter Project | `examples/starter-project/` | TO CREATE |
| 10b | **WDS Trigger Map** | `examples/wds-trigger-map/` | TO CREATE |
| 10c | **Trigger Mapping Workshop** | `workflows/trigger-mapping-workshop/` | TO CREATE |

**WDS Trigger Map Example:**
Create a Trigger Map for WDS itself as a meta-example - shows the methodology applied to the methodology. Includes:
- WDS Vision & SMART Objectives
- Target Groups (designers, teams, agencies)
- Personas with alliterative names
- Usage goals (positive & negative)
- Visual trigger map diagram

This serves as both documentation and inspiration for users.

**Trigger Mapping Workshop (Standalone):**
Create a standalone Trigger Mapping workshop that can be used:
- In WDS as part of Phase 2
- In BMM as a brainstorming/strategic alignment session
- In any project needing user-business alignment

This makes the Trigger Mapping methodology available even in projects not driven by designers. Could be contributed to BMM's brainstorming workflows or CIS (Creative Intelligence Suite).

Includes:
- Workshop facilitation workflow
- Agent instructions for running the workshop
- Template for Trigger Map output
- Integration points with BMM workflows

#### Phase 3: Create Workflows
| Order | Component | Location | Status |
|-------|-----------|----------|--------|
| 11 | workflow-init | `workflows/workflow-init/` | ✅ COMPLETE |
| 12a | Phase 1 Workflow | `workflows/1-project-brief/` | ✅ COMPLETE |
| 12b | Phase 2 Workflow | `workflows/2-trigger-mapping/` | ✅ COMPLETE |
| 12c | Phase 3 Workflow | `workflows/3-prd-platform/` | ✅ COMPLETE |
| 12d | **Phase 4 Workflow** | `workflows/4-ux-design/` | ✅ **COMPLETE (Dec 4)** |
| 12e | **Phase 5 Workflow** | `workflows/5-design-system/` | ✅ **COMPLETE (Dec 9)** |
| 12f | Phase 6 Workflow | `workflows/6-integration/` | TO CREATE |

#### Phase 4: Create Agents (The Norse Pantheon)
| Order | Component | File | Status |
|-------|-----------|------|--------|
| 13 | Saga-Analyst | `agents/saga-analyst.agent.yaml` | TO CREATE |
| 14 | Freyja-PM | `agents/freyja-pm.agent.yaml` | TO CREATE |
| 15 | Baldr-UX | `agents/baldr-ux.agent.yaml` | TO CREATE |

#### Phase 5: Finalize
| Order | Component | File | Status |
|-------|-----------|------|--------|
| 16 | Install Config | `_module-installer/install-config.yaml` | TO CREATE |
| 17 | Teams | `teams/` | TO CREATE |

---

## 8. Files Created So Far

### 8.1 Repository Root

| File | Purpose | Status |
|------|---------|--------|
| `README.md` | Fork overview, WDS contribution explanation | ✅ CREATED |
| `WDS-V6-CONVERSION-ROADMAP.md` | This document | ✅ CREATED |

### 8.2 Methodology Documentation

| Path | Purpose | Status |
|------|---------|--------|
| `src/modules/wds/docs/method/wds-method-guide.md` | Main methodology overview | ✅ COMPLETE |
| `src/modules/wds/docs/method/phase-1-Product-exploration-guide.md` | Phase 1 guide | ✅ COMPLETE |
| `src/modules/wds/docs/method/phase-2-trigger-mapping-guide.md` | Phase 2 guide | ✅ COMPLETE |
| `src/modules/wds/docs/method/phase-3-PRD-Platform-guide.md` | Phase 3 guide | ✅ COMPLETE |
| `src/modules/wds/docs/method/phase-4-ux-design-guide.md` | Phase 4 guide | ✅ COMPLETE |
| `src/modules/wds/docs/method/phase-5-design-system-guide.md` | Phase 5 guide | ✅ COMPLETE |
| `src/modules/wds/docs/method/phase-6-PRD-Finalization-guide.md` | Phase 6 guide | ✅ COMPLETE |

### 8.3 Module Structure (Folders Created, Content Pending)

| Path | Purpose | Status |
|------|---------|--------|
| `src/modules/wds/` | Module root | ✅ CREATED |
| `src/modules/wds/README.md` | Module entry point | ✅ CREATED |
| `src/modules/wds/_module-installer/` | Install config folder | EMPTY |
| `src/modules/wds/agents/` | Agents folder | PARTIAL (saga skeleton) |
| `src/modules/wds/workflows/` | Workflows folder | ✅ **PHASE 5 COMPLETE** |
| `src/modules/wds/workflows/workflow-init/` | Workflow initialization | ✅ COMPLETE |
| `src/modules/wds/workflows/1-project-brief/` | Phase 1 workflow | ✅ COMPLETE |
| `src/modules/wds/workflows/2-trigger-mapping/` | Phase 2 workflow | ✅ COMPLETE |
| `src/modules/wds/workflows/3-prd-platform/` | Phase 3 workflow | ✅ COMPLETE |
| `src/modules/wds/workflows/4-ux-design/` | **Phase 4 workflow** | ✅ **COMPLETE (Dec 4)** |
| `src/modules/wds/workflows/4-ux-design/substeps/` | **Phase 4 substeps (4A-4E)** | ✅ **COMPLETE (Dec 4)** |
| `src/modules/wds/workflows/5-design-system/` | **Phase 5 workflow** | ✅ **COMPLETE (Dec 9)** |
| `src/modules/wds/workflows/5-design-system/assessment/` | **Opportunity/Risk micro-instructions** | ✅ **COMPLETE (Dec 9)** |
| `src/modules/wds/workflows/5-design-system/operations/` | **Design system operations** | ✅ **COMPLETE (Dec 9)** |
| `src/modules/wds/workflows/4-ux-design/templates/` | **Phase 4 templates** | ✅ **COMPLETE (Dec 4)** |
| `src/modules/wds/workflows/5-design-system/` | Phase 5 workflow | TO CREATE |
| `src/modules/wds/workflows/6-integration/` | Phase 6 workflow | TO CREATE |
| `src/modules/wds/data/` | Data folder | EMPTY |
| `src/modules/wds/data/presentations/` | Agent presentations | TO CREATE |
| `src/modules/wds/docs/method/` | Methodology guides | ✅ COMPLETE |
| `src/modules/wds/docs/images/` | Images folder | EMPTY |
| `src/modules/wds/examples/` | Examples folder | EMPTY |
| `src/modules/wds/examples/dog-week-patterns/` | Dog Week examples | TO CREATE |
| `src/modules/wds/reference/` | Reference materials | EMPTY |
| `src/modules/wds/reference/templates/` | Templates | TO CREATE |
| `src/modules/wds/reference/checklists/` | Checklists | TO CREATE |
| `src/modules/wds/teams/` | Team configs | EMPTY |

---

## 9. Next Steps

### Immediate Next Action

**Create Examples** - Port Dog Week patterns and create conversation examples

### Short-term Roadmap

1. [x] Create `wds-method-guide.md`
2. [x] Create phase guide for each phase (6 files)
3. [x] Refine all phase guides with positive language, proper naming
4. [x] Create workflow-init workflow ✅
5. [x] Create Phase 1-3 workflows ✅
6. [x] **Create Phase 4 workflow (UX Design)** ✅ **COMPLETE Dec 4, 2025**
7. [ ] Create Phase 5-6 workflows
8. [ ] Create WDS Trigger Map (meta-example for WDS itself)
9. [ ] Create conversation examples
10. [ ] Create agents (Saga, Freyja, Baldr)
11. [ ] Create templates for component showcase, PRD, etc.
12. [ ] Port Dog Week examples to `examples/dog-week-patterns/` (last - project in active development)

### Commit Checkpoint

**Ready to commit Phase 4 workflow:**
```
feat(wds): Complete Phase 4 UX Design workflow with v6 best practices

Phase 4 Workflow Complete:
- Main workflow with goal-based instructions
- Substeps 4A-4E following v6 patterns (exploration, analysis, specification, prototype, PRD update)
- Complete page specification template with Object IDs
- Scenario overview template
- Concise, trust-the-agent instruction style
- Optional steps where appropriate

Conversion Progress:
- Merged WDS-CONVERSION-ANALYSIS.md into roadmap
- Updated roadmap with Phase 4 completion status
- Added section 11: WPS2C → WDS Conversion Reference
- Added section 12: Latest Updates (Dec 4, 2025)

Templates Created:
- page-specification.template.md (complete spec format)
- scenario-overview.template.md (scenario structure)

Next: Phase 5 (Design System) and Phase 6 (PRD Finalization) workflows
```

---

## 10. Reference Information

### 10.1 Open Design Decisions

**To resolve during porting Phase 1 & 2:**

| Decision | Options | Resolve When |
|----------|---------|--------------|
| **ICP/Positioning placement** | Phase 1 as hypothesis → Phase 2 validates, OR fully in Phase 2 | Porting Phase 1-2 |
| **Prioritization Reasoning** | Formal step with output, OR internal thinking process | Porting Phase 2 |
| **Business Goals flow** | Initial in Brief → Refined in Trigger Map, OR single location | Porting Phase 1-2 |

**Context:** The Trigger Mapping (Effect Mapping) methodology is very strong. The prioritization reasoning step (column-by-column) is specifically valuable for generating product ideas but may not need formal documentation.

---

### 10.2 Product Positioning Framework

To be included in WDS workflows (stored in memory, ID: 11785915):

**Positioning Statement Format:**
```
For (target customer)
Who (statement of need or opportunity)
And want (statement of experience expectations)
The (product/service name)
Is (product category)
That (statement of key benefits)
Unlike (primary competitive alternative)
Our product (statement of primary differentiators)
```

**ICP Framework (8 Components):**
1. My ICP (Who I Serve Best)
2. My Positioning (How I'm Different)
3. The Outcomes I Drive
4. My Offerings (What I Sell)
5. Social Proof (Who Can Vouch)
6. My Frameworks/Models/Tools (How I Work)
7. The Pains My ICP Articulates (Triggers/Frustrations)
8. Pricing Anchoring (Cost of Inaction, Bad Hire, % Revenue, Speed)

**CTA Elements:**
- Website link
- Discovery call link
- Newsletter subscription
- Social follows
- Events attending

### 10.2 BMad v6 Resources

| Resource | Location |
|----------|----------|
| BMM Module | `src/modules/bmm/` |
| BMB Builder | `src/modules/bmb/` |
| CIS Module | `src/modules/cis/` |
| Agent Schema | `src/modules/bmb/docs/agents/` |
| Workflow Docs | `src/modules/bmb/docs/workflows/` |

### 10.3 Original WPS2C

| Resource | Location |
|----------|----------|
| WPS2C Repo | `C:\dev\whiteport-sketch-to-code-bmad-expansion` |
| Method Overview | `Method/00-Whiteport-Method.md` |
| Agents (v4 format) | `bmad-whiteport-sketch/agents/` |

### 10.4 Dog Week Project

| Resource | Location |
|----------|----------|
| Project Root | `C:\dev\dogweek\dogweek-dev` |
| Product Brief | `docs/A-Product-Brief/` |
| Trigger Map | `docs/B-Trigger-Map/` |
| Scenarios | `docs/C-Scenarios/` |
| PRD | `docs/D-PRD/` |

---

## Conversation Summary

### Key Discussion Points

1. **Fork vs Standalone:** Decided on fork for maximum adoption
2. **Module Name:** Whiteport Design Studio (WDS) to preserve brand
3. **Branch Strategy:** Work on main, switch to feature branches after adoption
4. **Folder Structure:** A-B-C-D-E alphabetical prefix for visual namespace
5. **Phase Approach:** Phase-selectable (not rigid tracks)
6. **Scope:** Design only, no development/backlog (handled by BMM)
7. **E-UI-Roadmap:** Integration bridge to development modules
8. **Development Order:** Methodology-first approach
9. **Language Style:** Soft, collaborative (not MUST/FORBIDDEN)
10. **Teaching Style:** Show, don't tell (examples over rules)

### User's Stated Experience

- WPS2C v4 works well, proven methodology
- Strong language (MUST/FORBIDDEN) makes agents ignore instructions
- Softer language gets better compliance
- Examples work better than rules
- Agents tend to question-dump (20 questions at once)
- Output format inconsistency is a problem

### Design Philosophy Established

1. Soft language by design
2. Show, don't tell (examples over explanations)
3. Example projects for adoption/training
4. Identity-based agent personas
5. Conversation examples showing dialog flow

---

## 11. WPS2C → WDS Conversion Reference

### 11.1 Agent Mapping

| WPS2C v4 | WDS v6 | Status |
|----------|--------|--------|
| Mary (whiteport-analyst.md) | Saga-Analyst (saga-analyst.agent.yaml) | 🔄 Skeleton exists |
| Sarah (whiteport-pm.md) | Freyja-PM (freyja-pm.agent.yaml) | ⏳ To create |
| Sally (whiteport-ux-expert.md) | Baldr-UX (baldr-ux.agent.yaml) | ⏳ To create |
| James (whiteport-dev.md) | N/A - moved to BMM | ✅ Complete |
| Alex (whiteport-orchestrator.md) | N/A - workflow-status replaces | ✅ Complete |

**Key Changes:**
- Mary → **Saga** (Goddess of stories & wisdom)
- Sarah → **Freyja** (Goddess of love, war & strategy)  
- Sally → **Baldr** (God of light & beauty)
- Norse Pantheon theme for unique WDS identity

### 11.2 File Format Changes

**WPS2C v4:** Markdown files (.md) with embedded YAML blocks
```markdown
# agent-name.md
```yaml
agent:
  name: Mary
  commands:
    - help: Show help
```
```

**WDS v6:** Pure YAML files (.agent.yaml) following v6 schema
```yaml
# agent-name.agent.yaml
agent:
  metadata:
    id: "{bmad_folder}/wds/agents/saga-analyst.agent.yaml"
    name: Saga
    module: wds
  persona:
    role: ...
    identity: ...
  menu:
    - trigger: command-name
      workflow: path/to/workflow.yaml
```

### 11.3 Terminology Changes

| WPS2C v4 | WDS v6 |
|----------|--------|
| Whiteport Sketch-to-Code | Whiteport Design Studio |
| WPS2C | WDS |
| Commands | Menu Triggers |
| Tasks | Workflows |
| `*command-name` | Workflow triggers |

### 11.4 Presentation Files Mapping

| WPS2C v4 File | WDS v6 Location | Purpose |
|---------------|-----------------|---------|
| mary-analyst-personal-presentation.md | data/presentations/saga-intro.md | Saga activation speech |
| sarah-pm-personal-presentation.md | data/presentations/freyja-intro.md | Freyja activation speech |
| sally-ux-expert-personal-presentation.md | data/presentations/baldr-intro.md | Baldr activation speech |
| wps2c-analyst-business-presentation.md | examples/conversation-examples/analyst-session.md | Example session |
| wps2c-pm-product-presentation.md | examples/conversation-examples/pm-session.md | Example session |
| wps2c-ux-design-system-presentation.md | examples/conversation-examples/ux-session.md | Example session |

### 11.5 Templates Mapping

| WPS2C v4 Template | WDS v6 Location | Status |
|-------------------|-----------------|--------|
| product-brief-tmpl.yaml | workflows/1-project-brief/complete/project-brief.template.md | ✅ Created |
| trigger-map-tmpl.yaml | workflows/2-trigger-mapping/templates/trigger-map.template.md | ✅ Created |
| persona-tmpl.yaml | workflows/2-trigger-mapping/templates/persona.template.md | ⏳ To create |
| scenarios-tmpl.yaml | workflows/4-ux-design/templates/scenario-overview.template.md | ✅ **Created Dec 4** |
| page-spec-tmpl.yaml | workflows/4-ux-design/templates/page-specification.template.md | ✅ **Created Dec 4** |
| design-system-structure-tmpl.yaml | workflows/5-design-system/templates/component.template.md | ⏳ To create |
| component-tmpl.yaml | reference/templates/component.template.md | ⏳ To create |
| sketch-review-tmpl.yaml | workflows/4-ux-design/templates/review.template.md | ⏳ To create |

### 11.6 Standards/Data Files Mapping

| WPS2C v4 File | WDS v6 Location | Purpose |
|---------------|-----------------|---------|
| wps2c-compliance-standards.md | data/wds-standards.md | Core methodology standards |
| analyst-documentation-standards.md | data/documentation-standards.md | Documentation conventions |
| sketch-documentation-standards.md | workflows/4-ux-design/sketch-standards.md | Sketch specification standards |
| pm-documentation-standards.md | workflows/3-prd-platform/prd-standards.md | PRD writing standards |
| mermaid-github-standards.md | data/mermaid-standards.md | Diagram standards |
| technical-documentation-patterns.md | data/technical-patterns.md | Technical writing patterns |

### 11.7 Content to Preserve from WPS2C

**Core Methodology Elements:** ✅
- Product Brief structure and process
- Trigger Mapping (Effect Mapping) methodology
- Feature Impact Analysis with scoring
- Scenario-driven design approach  
- Design System integration patterns

**Agent Personalities:** 🔄
- Mary's analytical, thoughtful approach → Saga
- Sarah's strategic PM mindset → Freyja
- Sally's design expertise and creativity → Baldr

**Quality Patterns:** ✅
- One question at a time (not survey-style)
- Collaborative document building
- Evidence-based analysis
- Soft, encouraging language

**Technical Patterns:** ✅
- A-B-C-D-E folder structure
- Title-Case-With-Dashes naming
- Professional markdown formatting
- Mermaid diagram standards

### 11.8 Key Improvements in WDS v6

**1. Soft Language Design Philosophy**
- Removed MUST/FORBIDDEN/NEVER language
- Identity-based persona definitions
- Collaborative, not interrogative approach
- Positive framing (enables vs prevents)

**2. Example-Driven Learning**
- Complete reference implementations
- Conversation flow examples
- Real project patterns (Dog Week)
- Starter projects for practice

**3. Phase Flexibility**
- Phase-selectable (not rigid tracks)
- Path presets for common scenarios
- Optional phases (Design System)
- Parallel workflows supported

**4. Better Integration**
- Clean handoff to BMM via E-UI-Roadmap
- No development artifacts in design module
- Clear separation of concerns
- Continuous handoff model

**5. Professional Tooling**
- Proper v6 YAML schema compliance
- Workflow validation support
- Installation via BMad CLI
- Module ecosystem integration

### 11.9 Migration Notes

**Breaking Changes:**
- Agent activation syntax changes (*command → workflow trigger)
- File format changes (.md → .agent.yaml)
- Folder structure reorganization
- Terminology updates throughout

**Backward Compatibility:**
- WPS2C v4 users must migrate to WDS v6
- No automatic migration path
- Dog Week project uses mixed terminology (in transition)
- Old repo remains for reference

**User Communication:**
- WDS is evolution, not replacement
- Same methodology, better implementation
- Migration guide needed for v4 users
- Clear benefits explanation

---

## 12. Latest Updates (December 5, 2025)

### Phase 4 Workflow - Dog Week Pattern Implementation ✅

#### Phase 4 Architecture (December 4)

**Step-File Architecture:**
- `workflows/4-ux-design/workflow.yaml` - Main workflow configuration
- `workflows/4-ux-design/workflow.md` - Workflow orchestrator
- `workflows/4-ux-design/steps/step-01-init.md` - Workflow initialization
- `workflows/4-ux-design/steps/step-02-define-scenario.md` - Scenario structure
- `workflows/4-ux-design/steps/step-03-design-page.md` - Page design orchestration
- `workflows/4-ux-design/steps/step-04-complete-scenario.md` - Scenario completion
- `workflows/4-ux-design/steps/step-05-next-steps.md` - Next actions

**4C Micro-Steps (Specification Breakdown):**
- `substeps/4c-01-page-basics.md` - Page basic information
- `substeps/4c-02-layout-sections.md` - Layout sections definition
- `substeps/4c-03-components-objects.md` - Components & objects identification
- `substeps/4c-04-content-languages.md` - Content & language specs
- `substeps/4c-05-interactions.md` - Interaction definitions
- `substeps/4c-06-states.md` - Object states
- `substeps/4c-07-validation.md` - Validation rules
- `substeps/4c-08-generate-spec.md` - Final spec generation

#### Dog Week Pattern Implementation (December 5)

**Purpose-Based Text Organization:**
- `object-types/heading-text.md` - Updated with purpose-based naming
- `object-types/object-router.md` - Enhanced with intelligent interpretation
- Text objects named by FUNCTION, not content (e.g., `start-hero-headline` not `welcome-text`)
- Structure (position/style) separated from content
- Translations grouped so each language reads coherently

**Sketch Text Analysis:**
- Horizontal line detection → text placeholders
- Line thickness → font size estimation
- Line spacing → line-height calculation
- Character capacity estimation for content validation
- `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Complete analysis methodology

**Translation Grouping:**
- Text groups keep languages together
- Each language reads as complete, coherent message
- Dog Week format standardized across all projects
- `TRANSLATION-ORGANIZATION-GUIDE.md` - Complete translation pattern
- `DOG-WEEK-SPECIFICATION-PATTERN.md` - Full workflow integration example

**Object Type Instructions:**
- `object-types/button.md` - Button documentation
- `object-types/text-input.md` - Text input fields
- `object-types/link.md` - Link elements
- `object-types/heading-text.md` - Headings & text with placeholder analysis
- `object-types/image.md` - Image elements
- `object-types/object-router.md` - Intelligent object detection & routing

**Design Principles Applied:**
- ✅ Goal-based trust-the-agent approach
- ✅ Concise instructions (vs. long procedural lists)
- ✅ Soft, collaborative language throughout
- ✅ Clear step separation with micro-steps
- ✅ Optional steps where appropriate
- ✅ v6 best practices for instruction file sizing
- ✅ Purpose-based naming (stable Object IDs)
- ✅ Grouped translations (coherent reading)
- ✅ Character capacity validation from sketches

**Key Innovations:**
1. **Purpose-Based Object IDs** - IDs reflect function, remain stable when content changes
2. **Grouped Translations** - Each language reads coherently as a group
3. **Sketch Text Analysis** - Automatic capacity estimation from visual markers
4. **Intelligent Routing** - Agent suggests object types rather than asking lists

**Architecture Documentation:**
- `workflows/4-ux-design/ARCHITECTURE.md` - Complete Phase 4 architecture
- `workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Text analysis methodology
- `workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md` - Translation patterns
- `workflows/4-ux-design/DOG-WEEK-SPECIFICATION-PATTERN.md` - Complete workflow example

**Next Actions:**
- Create Phase 5 workflow (Design System)
- Create Phase 6 workflow (PRD Finalization / Dev Integration)
- Complete agent definitions (Freyja, Baldr)
- Port agent presentations
- Create remaining object-type instruction files (~15 more types)

#### Language Configuration (December 5 - Later)

**Multi-Language Support:**
- `workflows/workflow-init/instructions.md` - Updated with language configuration (Step 4)
- `workflows/wds-workflow-status-template.yaml` - Added language fields to config
- `workflows/LANGUAGE-CONFIGURATION-GUIDE.md` - Complete multi-language guide
- `workflows/LANGUAGE-FLOW-DIAGRAM.md` - Step-by-step language flow

**Configuration Settings:**
1. **Specification Language** - Language to write design specs in (EN, SE, etc.)
2. **Product Languages** - Array of languages the product supports

**Storage:**
```yaml
config:
  specification_language: "EN"
  product_languages:
    - EN
    - SE
    - NO
```

**Impact on Workflows:**
- Specs written in `specification_language`
- All text objects include translations for ALL `product_languages`
- Agents automatically request content for each configured language
- Complete translation coverage from day one

**Example (Dog Week):**
- Specification Language: EN (specs written in English)
- Product Languages: [EN, SE] (product supports English & Swedish)
- Result: All text objects have both EN and SE content

**Benefits:**
- ✅ Flexible spec language separate from product languages
- ✅ All translations grouped and coherent
- ✅ No missing translations
- ✅ Developer-friendly config
- ✅ Easy to add languages mid-project

#### Sketch Text Analysis Corrections (December 5 - Final)

**Corrected Understanding:**
- **Line thickness** → **font weight** (bold/regular), NOT font size!
- **Distance between lines** → **font size**
- **Confusion risk:** Large spacing (>60px) might be image/colored box, not text

**Updated Files:**
- `4-ux-design/object-types/heading-text.md` - Corrected analysis logic
- `4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Updated with correct interpretation
- `4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference card
- `4-ux-design/SKETCH-TEXT-STRATEGY.md` - When to use text vs. markers

**Best Practice - Actual Text vs. Markers:**

**Use ACTUAL TEXT for:**
- Headlines (provides content guidance)
- Button labels (shows intended action)
- Navigation items (clarifies structure)
- Short, important text

**Use LINE MARKERS for:**
- Body paragraphs (content TBD)
- Long descriptions (sizing only)
- Placeholder content

**Agent Behavior:**
- Reads actual text from sketch as starting suggestion
- **Proactively suggests translations for all configured languages**
- Allows refinement during specification
- Sketch text isn't final, just guidance
- Analyzes markers for font size, weight, capacity

**Example:**
```
Every walk. on time.  ← Agent reads this
Every time.           ← Translates to all languages

EN: Every walk. on time. Every time.
SE: Varje promenad. i tid. Varje gång.  ← Agent suggests!

Do these work? [1] Use [2] Adjust [3] Manual
```

**User can:**
- Accept suggestions (fast!)
- Refine specific translations
- Provide manual input if preferred

---

## 13. WDS Course Development (December 9, 2025)

### 13.1 Course Structure Overview

**Purpose:** Educational course teaching WDS methodology to designers

**Location:** `src/modules/wds/course/`

**Format:**
- Read as documentation
- Generate videos/podcasts with NotebookLM
- Use in workshops and team training
- Apply to real projects as you learn

**Module Structure:**
Each module contains:
- **Inspiration** - Why this matters and what you'll gain
- **Teaching** - How to do it with confidence and AI support
- **Practice** - Apply it to your own project
- **Tutorial** - Quick step-by-step guide (for practical modules)

### 13.2 Course Modules Planned

**16 Total Modules:**

#### Foundation
- Module 01: Why WDS Matters ✅ COMPLETE

#### Phase 1: Project Brief
- Module 02: Create Project Brief ⏳ TO CREATE

#### Phase 2: Trigger Mapping
- Module 03: Identify Target Groups ⏳ TO CREATE
- Module 04: Map Triggers & Outcomes ⏳ TO CREATE
- Module 05: Prioritize Features ⏳ TO CREATE

#### Phase 3: Platform Requirements
- Module 06: Platform Requirements ⏳ TO CREATE
- Module 07: Functional Requirements ⏳ TO CREATE

#### Phase 4: Conceptual Design (UX Design)
- Module 08: Initialize Scenario ⏳ TO CREATE
- Module 09: Sketch Interfaces ⏳ TO CREATE
- Module 10: Analyze with AI ⏳ TO CREATE
- Module 11: Decompose Components ⏳ TO CREATE
- Module 12: Why-Based Specifications ⏳ TO CREATE
- Module 13: Validate Specifications ⏳ TO CREATE

#### Phase 5: Design System
- Module 14: Extract Design Tokens ⏳ TO CREATE
- Module 15: Component Library ⏳ TO CREATE

#### Phase 6: Development Integration
- Module 16: UI Roadmap ⏳ TO CREATE

### 13.3 Getting Started Section - COMPLETE ✅

**Location:** `src/modules/wds/course/00-getting-started/`

**Files Created:**

| File | Purpose | Status |
|------|---------|--------|
| `00-getting-started-overview.md` | Navigation hub for getting started | ✅ COMPLETE |
| `01-prerequisites.md` | Skills, tools, requirements | ✅ COMPLETE |
| `02-learning-paths.md` | Full Immersion, Quick Start, Self-Paced | ✅ COMPLETE |
| `03-support.md` | Testimonials, FAQ, community | ✅ COMPLETE |
| `00-getting-started-NOTEBOOKLM-PROMPT.md` | Podcast/video generation prompt | ✅ COMPLETE |

**Key Decisions:**
- Removed redundant "About the Course" file (merged into course overview)
- Removed "About WDS" from getting started (belongs in main docs)
- Focused on practical preparation only

### 13.4 Course Overview - COMPLETE ✅

**Location:** `src/modules/wds/course/00-course-overview.md`

**Content:**
- Welcome and paradigm shift
- Who created WDS (Mårten Angner background)
- Complete module table of contents (all 16 modules)
- Learning paths (Complete, Quick Start, Phase-Specific)
- Prerequisites summary
- Module structure pattern
- Clear call to action

**Key Changes:**
- Simplified module list to clean table of contents
- Added "Who Created WDS?" section
- Merged redundant content from getting started
- Removed verbose descriptions

### 13.5 Module 01: Why WDS Matters - COMPLETE ✅

**Location:** `src/modules/wds/course/module-01-why-wds-matters/`

**Files:**

| File | Purpose | Status |
|------|---------|--------|
| `module-01-overview.md` | Module navigation and overview | ✅ COMPLETE |
| `lesson-01-the-problem.md` | The Problem We're Solving | ✅ COMPLETE |
| `lesson-02-the-solution.md` | Becoming a Linchpin Designer | ✅ COMPLETE |
| `lesson-03-the-path-forward.md` | Your Transformation | ✅ COMPLETE |

**Content Based On:**
- Seth Godin's "Linchpin: Are You Indispensable?"
- Factory mindset vs Linchpin mindset
- 5 dimensions of design thinking
- AI as amplifier, not replacement
- Emotional labor concept adapted to design

### 13.6 NotebookLM Prompt Refinements

**Key Messaging Changes:**

**Removed:**
- ❌ Speed claims ("5x faster", "3-5x productivity")
- ❌ Fake testimonials (Sarah K., Marcus L., Priya S.)
- ❌ Unrealistic promises

**Added:**
- ✅ IDE learning curve (5-10 hours)
- ✅ GitHub workflow requirement
- ✅ Financial cost transparency ($15-80/month for Cursor)
- ✅ Frontend prototyping capability
- ✅ Usability testing without dev team
- ✅ Strategic thinker value proposition

**New Value Proposition:**
- Not about speed - about depth and completeness
- Become the strategic thinker your team needs
- Create specifications developers actually need
- Generate content that perfectly lifts your designs
- Work is deeper, more complete, more fulfilling
- Eventually deliver parts of frontend work

**Honest About Costs:**
- Learning curve: IDE and GitHub workflow
- Time: 10 hours course + 5-10 hours tools
- Money: $15-20/month (small projects) to $80/month (enterprise)
- Stepping into developer territory (uncomfortable at first)

**Benefits Emphasized:**
- Remove biggest barrier between designers and developers
- Designs live in same place as code
- No more handoff nightmares
- Create standalone frontend prototypes
- Conduct usability testing independently
- No longer blocked by development schedules

### 13.7 Next Steps for Course Development

**Immediate Priority:**
Create Module 02: Project Brief as template for remaining modules

**Recommended Approach:**
1. **Option 1: Prioritize Core Modules** (Quick Start path)
   - Module 02: Project Brief
   - Module 04: Map Triggers & Outcomes
   - Module 08: Initialize Scenario
   - Module 12: Why-Based Specifications

2. **Option 2: Create Module Templates**
   - Template structure for each module type
   - Fill in with specific content later
   - Faster to generate full course

3. **Option 3: One Phase at a Time**
   - Complete Phase 1 (Module 02) fully
   - Then Phase 2 (Modules 03-05)
   - Then Phase 3, 4, 5, 6

**Content Sources:**
- Tutorial content from `src/modules/wds/tutorial/`
- Methodology guides from `src/modules/wds/docs/method/`
- Workflow documentation from `src/modules/wds/workflows/`
- Dog Week examples (when ready)

**Module Template Structure:**
```
module-XX-name/
├── module-XX-overview.md          # Navigation and module intro
├── lesson-01-inspiration.md       # Why this matters
├── lesson-02-teaching.md          # How to do it
├── lesson-03-practice.md          # Apply it
└── tutorial.md                    # Quick step-by-step (optional)
```

**Estimated Scope:**
- 15 modules remaining (Module 02-16)
- Each module: 4 files minimum
- Total: ~60 files to create
- Content: Tens of thousands of lines

**Recommendation:**
Wait until conversion is complete, then tackle course development systematically using the proven Module 01 structure as template.

---

## 14. Latest Updates Summary

### December 9, 2025 - Course Development Session

**Completed:**
- ✅ Getting Started section (5 files)
- ✅ Course Overview refinement
- ✅ Module 01: Why WDS Matters (4 files)
- ✅ NotebookLM prompt with accurate messaging
- ✅ Removed redundant files
- ✅ Merged overlapping content

**Key Refinements:**
- Honest about IDE/GitHub learning curve
- Transparent about costs ($15-80/month)
- Focus on strategic value, not speed
- Frontend prototyping as major benefit
- Removed fake testimonials
- Removed speed claims

**Files Structure:**
```
course/
├── 00-course-overview.md                    ✅ COMPLETE
├── 00-getting-started/                      ✅ COMPLETE
│   ├── 00-getting-started-overview.md
│   ├── 01-prerequisites.md
│   ├── 02-learning-paths.md
│   ├── 03-support.md
│   └── 00-getting-started-NOTEBOOKLM-PROMPT.md
└── module-01-why-wds-matters/               ✅ COMPLETE
    ├── module-01-overview.md
    ├── lesson-01-the-problem.md
    ├── lesson-02-the-solution.md
    └── lesson-03-the-path-forward.md
```

**Next Session:**
- Continue with Module 02-16 creation
- Use Module 01 as template
- Consider prioritizing Quick Start modules first
- Reference tutorial and workflow content

---

---

## 15. Design System Architecture (December 9, 2025)

### 15.1 Core Principles

**Three-Way Split Architecture:**

```
1. Page Specification (Logical View)
   ├── Component references
   ├── Page-specific content (labels, error texts)
   ├── Layout/structure
   └── WHY this page exists

2. Design System (Visual/Component Library)
   ├── Component definitions
   ├── States & variants
   ├── Styling/tokens
   └── Reusable patterns

3. Functionality/Storyboards (Behavior)
   ├── Interactions
   ├── State transitions
   ├── User flows
   └── Component behaviors
```

**Key Separation:**
- **Specification = Content** (what the component is)
- **Organization = Structure** (where it lives)
- **Design System = Optional** (chosen in Phase 1)

### 15.2 Design System Options

**Three Modes (Chosen in Project Exploration):**

**Option A: No Design System**
- Components stay page-specific
- AI/dev team handles consistency
- Faster for simple projects

**Option B: Custom Design System**
- Designer defines in Figma
- Components extracted as discovered
- Figma MCP endpoints for integration

**Option C: Component Library Design System**
- Uses shadcn/Radix/etc.
- Library chosen during setup
- Components mapped to library defaults

### 15.3 Component Flow with Design System

**Complete Specification → Extract → Reference:**

```
1. Specification Component (Pure)
   └── Captures EVERYTHING about object (mixed content)

2. Orchestration Layer
   ├── Receives complete specification
   ├── Design system enabled?
   │
   └── YES → Design System Router
       ├── A. Extract component-level info
       ├── B. Add/update design system entry
       ├── C. Create reference ID
       ├── D. Return to page spec
       ├── E. Replace component info with reference
       └── F. Keep only page-specific info

3. Result: Clean separation
   ├── Page spec: References + page-specific content
   └── Design system: Component definitions
```

**Example:**

**Complete Specification:**
```yaml
Login Button:
  why: Submit login credentials
  label: "Log in"                    # Page-specific
  error_text: "Invalid credentials"  # Page-specific
  states: [default, hover, disabled] # Component-level
  variants: [primary, secondary]     # Component-level
  styling: {...}                     # Component-level
```

**After Split:**

**Design System:**
```yaml
# D-Design-System/components/button.md
Button Component [btn-001]:
  states: [default, hover, disabled]
  variants: [primary, secondary]
  styling: {...}
```

**Page Spec:**
```yaml
# C-Scenarios/login-page.md
Login Button:
  component: Button.primary [btn-001]  # Reference
  why: Submit login credentials
  label: "Log in"
  error_text: "Invalid credentials"
```

### 15.4 Design System Router

**Parallel to Sketch Router:**

```
Design System Router
├── Check: Does similar component exist?
│
├── NO → Route to: Create New Component
│   └── Add to design system, create reference
│
└── YES → Route to: Opportunity/Risk Assessment
    ├── Scan existing components
    ├── Compare attributes
    ├── Calculate similarity
    ├── Identify opportunities
    ├── Identify risks
    ├── Present decision to designer
    └── Execute decision:
        ├── Same → Reuse reference
        ├── Variant → Add variant to existing
        └── New → Create new component
```

**Router Characteristics:**
- Dumb and simple (just identify and route)
- Doesn't contain business logic
- Keeps orchestration clean
- Parallel pattern to sketch router

### 15.5 Opportunity/Risk Assessment

**Micro-Instruction Breakdown:**

```
workflows/5-design-system/assessment/
├── 01-scan-existing.md           # Find similar components
├── 02-compare-attributes.md      # Compare systematically
├── 03-calculate-similarity.md    # Score the match
├── 04-identify-opportunities.md  # What could we gain?
├── 05-identify-risks.md          # What could go wrong?
├── 06-present-decision.md        # Show designer options
└── 07-execute-decision.md        # Implement choice
```

**Example Conversation:**
```
Agent: "I found a button similar to btn-001 (Primary Button).

Similarities:
- Same size and shape
- Same color scheme
- Same hover behavior

Differences:
- Different label ('Continue' vs 'Submit')
- Different icon (arrow vs checkmark)

Options:
[1] Same component (just change label/icon)
[2] New variant of btn-001 (add 'continue' variant)
[3] New component btn-002 (different purpose)

If variant:
✅ Pros: Consistency, easier maintenance
❌ Cons: More complex component

If separate:
✅ Pros: Independence, flexibility
❌ Cons: Potential inconsistency

What's your call?"
```

**Key Insight:** Design systems are inherently challenging. WDS acknowledges risks and creates conversation points for designer judgment.

### 15.6 Layered Knowledge Architecture

**Centralized Concepts + Component-Specific Instructions:**

```
Core Principles (Shared)
├── data/design-system/
│   ├── token-architecture.md      # Structure vs style separation
│   ├── naming-conventions.md      # Token naming rules
│   ├── state-management.md        # Component states
│   └── validation-patterns.md     # Form validation
│
└── Referenced by component types

↓

Component-Type Instructions (Specific)
├── object-types/text-heading.md
│   ├── References: token-architecture.md
│   ├── References: naming-conventions.md
│   └── Heading-specific rules
│
├── object-types/button.md
│   ├── References: token-architecture.md
│   ├── References: state-management.md
│   └── Button-specific rules
│
└── object-types/input-field.md
    ├── References: token-architecture.md
    ├── References: validation-patterns.md
    └── Input-specific rules
```

**Benefits:**
- Small, digestible instruction files
- Shared knowledge in one place
- Selective loading (only what's needed)
- Composable knowledge
- Easy to maintain and update

**Example: Structure vs Style Separation**

**Shared Principle (`data/design-system/token-architecture.md`):**
```markdown
# Design Token Architecture

## Core Principle
Separate semantic structure from visual style.

HTML defines meaning, tokens define appearance.

<h2> = Semantic (second-level heading)
"Display Large" = Visual (48px, bold, tight spacing)

They should be independent!
```

**Component Application (`object-types/text-heading.md`):**
```markdown
# Text Heading Specification

**References:** data/design-system/token-architecture.md

## Heading-Specific Rules
1. Identify semantic level (h1-h6)
2. Map to design token (display-large, heading-1, etc.)
3. Never mix structure with style
4. Store structure in page spec
5. Store style in design system tokens
```

### 15.7 Company Customization Model

**Key Feature: Companies Can Fork WDS**

```
Company forks WDS
├── Keeps: Core workflow architecture
├── Keeps: Router logic
├── Keeps: Orchestration patterns
│
└── Customizes:
    ├── data/design-system/
    │   ├── token-architecture.md    # Company standards
    │   ├── naming-conventions.md    # Company naming
    │   └── brand-guidelines.md      # Company brand
    │
    └── object-types/
        ├── button.md                # Company button patterns
        ├── input-field.md           # Company form standards
        └── card.md                  # Company card patterns
```

**Use Cases:**

**1. Enterprise with Design System**
```
Acme Corp forks WDS:
├── Adds: data/design-system/acme-tokens.md
├── Adds: data/design-system/acme-components.md
└── Customizes: object-types/ to match Acme patterns

Result: Every project uses Acme standards automatically
```

**2. Agency with Multiple Clients**
```
Agency forks WDS:
├── Branch: client-a (Client A standards)
├── Branch: client-b (Client B standards)
└── Branch: main (Agency defaults)

Result: Switch branch = switch standards
```

**3. Design System Team**
```
Design System Team forks WDS:
├── Adds: Their component library specs
├── Adds: Their token architecture
└── Adds: Their validation rules

Result: All designers use same system
```

**Benefits:**
- ✅ Company-specific standards
- ✅ Version controlled
- ✅ Shareable across teams
- ✅ Evolvable over time
- ✅ Consistent across projects
- ✅ Open-source dream: Customize without breaking core

### 15.8 Design System Workflow Structure

**Planned Structure:**

```
workflows/5-design-system/
├── workflow.yaml                      # Main workflow entry
├── design-system-router.md            # Router logic
│
├── assessment/                        # Opportunity/Risk micro-instructions
│   ├── 01-scan-existing.md
│   ├── 02-compare-attributes.md
│   ├── 03-calculate-similarity.md
│   ├── 04-identify-opportunities.md
│   ├── 05-identify-risks.md
│   ├── 06-present-decision.md
│   └── 07-execute-decision.md
│
├── operations/                        # Design system operations
│   ├── create-new-component.md
│   ├── add-variant.md
│   ├── update-component.md
│   └── initialize-design-system.md
│
└── templates/                         # Output templates
    ├── component.template.md
    ├── design-tokens.template.md
    └── component-library-config.template.md
```

**Integration Points:**
- Called from Phase 4 orchestration (4c-03-components-objects.md)
- Triggered after component specification
- Only active if design system enabled in project
- First component triggers initialization

### 15.9 Key Risks Identified

**1. Component Matching**
- How to recognize "same" vs "similar" vs "different"
- Solution: Similarity scoring + designer judgment

**2. Circular References**
- Page → Component → Functionality → Component
- Solution: Clear hierarchy (Page → Component → Functionality)

**3. Sync Problems**
- Component evolves, references may break
- Solution: Reference IDs + update notifications

**4. Component Boundaries**
- Icon in button? Nested components?
- Solution: Designer conversation + guidelines

**5. First Component**
- When to initialize design system?
- Solution: Auto-initialize on first component if enabled

**6. Storyboard Granularity**
- Component behavior vs page flow
- Solution: Clear separation guidelines

**Mitigation Strategy:**
- AI identifies risks
- Designer makes judgment calls
- AI executes decisions
- Transparent process with pros/cons

### 15.10 Implementation Complete (December 9, 2025)

**✅ Phase 5 Design System Workflow Complete!**

**Files Created:**

**Workflow Structure:**
- `workflows/5-design-system/workflow.yaml`
- `workflows/5-design-system/README.md`
- `workflows/5-design-system/design-system-router.md`

**Assessment Micro-Instructions (7 files):**
- `assessment/01-scan-existing.md`
- `assessment/02-compare-attributes.md`
- `assessment/03-calculate-similarity.md`
- `assessment/04-identify-opportunities.md`
- `assessment/05-identify-risks.md`
- `assessment/06-present-decision.md`
- `assessment/07-execute-decision.md`

**Component Operations (4 files):**
- `operations/initialize-design-system.md`
- `operations/create-new-component.md`
- `operations/add-variant.md`
- `operations/update-component.md`

**Shared Knowledge Documents (4 files):**
- `data/design-system/token-architecture.md`
- `data/design-system/naming-conventions.md`
- `data/design-system/component-boundaries.md`
- `data/design-system/state-management.md`
- `data/design-system/validation-patterns.md`

**Templates (3 files):**
- `templates/component.template.md`
- `templates/design-tokens.template.md`
- `templates/component-library-config.template.md`

**Integration:**
- Updated `workflows/4-ux-design/substeps/4c-03-components-objects.md` to call design system router

**Total Files Created:** 27 files (22 core + 3 Figma + 2 catalog)

**Key Features Implemented:**
- ✅ Three design system modes (None/Custom/Library)
- ✅ On-demand component extraction
- ✅ Similarity detection and assessment
- ✅ Opportunity/risk analysis with designer decision
- ✅ Component operations (create/variant/update)
- ✅ Layered knowledge architecture
- ✅ Company customization support
- ✅ Integration with Phase 4 workflow
- ✅ **Figma integration (Mode B) - COMPLETE (Dec 9)**
- ✅ **Interactive HTML catalog - COMPLETE (Dec 9)**

**Figma Integration Files (Dec 9):**
- `data/design-system/figma-component-structure.md` - Component organization in Figma
- `figma-integration/figma-designer-guide.md` - Step-by-step designer instructions
- `figma-integration/figma-mcp-integration.md` - Technical MCP integration guide

**Interactive Catalog Files (Dec 9):**
- `templates/catalog.template.html` - Interactive HTML catalog template
- `operations/generate-catalog.md` - Catalog generation workflow

**Catalog Features:**
- Fixed sidebar navigation
- Live component previews with all variants/states
- Interactive state toggles
- Design token swatches
- Code examples
- Changelog tracking
- Figma links (Mode B)
- **Automatically regenerated** after every component change
- **Version controlled** with git

**Course Structure Update (Dec 9):**
- Tutorials integrated into course modules (no separate tutorial/ folder)
- Created tutorials for key modules: 02, 04, 08, 12
- Updated navigation (where-to-go-next.md, course-overview.md)
- Deprecated old tutorial/ folder with migration guide

**Tutorial Files Created:**
- `course/module-02-project-brief/tutorial-02.md` - Create Project Brief
- `course/module-04-map-triggers-outcomes/tutorial-04.md` - Map Triggers & Outcomes
- `course/module-08-initialize-scenario/tutorial-08.md` - Initialize Scenario
- `course/module-12-why-based-specs/tutorial-12.md` - Why-Based Specifications

**Excalidraw Integration (Dec 9 AM):**
- Optional sketching tool integration with project configuration
- Created comprehensive documentation and workflows
- AI collaboration patterns for generation and analysis
- Export workflows for GitHub display

**Excalidraw Files Created:**
- `workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md` - Overview and quick start
- `workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md` - Installation and configuration
- `workflows/4-ux-design/excalidraw-integration/sketching-guide.md` - How to sketch effectively
- `workflows/4-ux-design/excalidraw-integration/ai-collaboration.md` - Working with AI
- `workflows/4-ux-design/excalidraw-integration/export-workflow.md` - Export for GitHub
- `workflows/workflow-init/project-config.template.yaml` - Project configuration template
- `workflows/workflow-init/excalidraw-setup-prompt.md` - Agent setup instructions

**Excalidraw Features:**
- ✅ Optional (enable in project config)
- ✅ VS Code extension or web app
- ✅ AI can generate .excalidraw files
- ✅ AI can analyze sketches (upload PNG)
- ✅ WDS component library (future)
- ✅ Auto-export to PNG/SVG (optional)
- ✅ 20px grid system (matches WDS spacing)
- ✅ Version control friendly (JSON)

**WDS ↔ BMad Integration (Dec 9 PM):**
- Designed complete integration architecture between WDS and BMad Method
- Simplified to 3 clean touch points (not 7!)
- Created Design Delivery objects for clean handoff
- Implemented multi-agent handoff dialog
- Created test scenarios for designer validation
- Phase 6 renamed to "Design Deliveries" (single handoff point)

**Integration Files Created:**
- `src/core/resources/wds/design-delivery-spec.md` - Design Delivery specification
- `src/core/resources/wds/platform-requirements-spec.md` - Platform Requirements specification
- `src/core/resources/wds/handoff-protocol.md` - Multi-agent handoff protocol
- `src/core/resources/wds/integration-guide.md` - Complete integration overview
- `templates/design-delivery.template.yaml` - Design Delivery template
- `templates/platform-requirements.template.yaml` - Platform Requirements template
- `templates/test-scenario.template.yaml` - Test Scenario template

**The 3 Touch Points:**
1. **Platform Requirements** (WDS Phase 3 → BMad)
   - WDS overrides BMad's tech stack decisions
   - Designer defines technical foundation
   
2. **Design Deliveries** (WDS Phase 6 → BMad)
   - Complete design package handed off at once
   - Includes all scenarios, components, test scenarios
   - Single handoff with multi-agent dialog
   
3. **Designer Validation** (BMad Phase 3 → WDS Phase 7)
   - BMad requests validation when complete
   - Designer tests and creates issues if needed
   - Iterates until sign-off

**Integration Features:**
- ✅ 3 clean touch points (simplified from 7)
- ✅ Epic-based design deliveries (testable user flows)
- ✅ Multi-agent handoff dialog (20-30 min structured conversation)
- ✅ Platform requirements handoff (WDS overrides BMad)
- ✅ Complete design package at once (not incremental)
- ✅ Designer validation after implementation
- ✅ BMad works with or without WDS (graceful fallback)
- ✅ Complete traceability (design → dev → test → ship)

**WDS Workflow Files Created (Dec 9):**
- `workflows/6-design-deliveries/design-deliveries-guide.md` - Phase 6 workflow (iterative handoffs)
- `workflows/7-testing/testing-guide.md` - Phase 7 workflow (designer validation)
- `workflows/8-ongoing-development/existing-product-guide.md` - Phase 8 workflow (existing product entry point)
- `workflows/workflow-init/project-type-selection.md` - Project type selection (new vs existing)

**Two Entry Points to WDS:**
1. **New Product** (Phases 1-7)
   - Starting from scratch
   - Complete user flows
   - Full creative freedom
   
2. **Existing Product** (Phase 8)
   - Jump into existing product
   - Strategic improvements
   - Targeted updates
   - Linchpin designer role

**Complete WDS Workflow (Phases 1-8):**
- ✅ Phase 1: Project Brief (New Product)
- ✅ Phase 2: Trigger Map (New Product)
- ✅ Phase 3: Platform Requirements (Touch Point 1) (New Product)
- ✅ Phase 4: UX Design (iterative)
- ✅ Phase 5: Design System (iterative)
- ✅ Phase 6: Design Deliveries (Touch Point 2)
- ✅ Phase 7: Testing (Touch Point 3)
- ✅ Phase 8: Existing Product Development (Existing Product Entry Point)
  - Phase 8.1: Limited Project Brief
  - Phase 8.2: Existing Context
  - Phase 8.3: Critical Updates
  - Phase 8.4: System Update Delivery
  - Phase 8.5: Validation

**BMad Integration Complete (Dec 9):**
- ✅ Created WDS detection step for BMad architecture workflow
- ✅ Updated BMad Architect agent (WDS-aware)
- ✅ Updated BMad Developer agent (design system awareness)
- ✅ BMad now detects and respects WDS artifacts
- ✅ BMad reads platform requirements, design deliveries, design system
- ✅ BMad offers handoff dialog when Design Deliveries exist

**BMad Files Updated:**
- `src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01a-wds-detection.md` - WDS detection step
- `src/modules/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md` - Updated to call WDS detection
- `src/modules/bmm/agents/architect.agent.yaml` - Added WDS awareness
- `src/modules/bmm/agents/dev.agent.yaml` - Added design system awareness

**Next Steps:**
1. Complete remaining module tutorials (03, 05-07, 09-11, 13-16)
2. Create WDS Excalidraw component library (.excalidrawlib)
3. Implement auto-export automation (GitHub Actions)
4. Test complete WDS → BMad workflow with real project
5. Refine assessment criteria based on usage
6. Add more shared knowledge documents as patterns emerge
7. Test Figma MCP integration with real components
8. Test catalog generation with real components
9. Test Excalidraw integration with real scenarios

---

## 16. Future: Dogweek Design System Refactoring (Backlog)

**Purpose:** Use Dogweek as live case study to validate WDS Phase 5

**Identified Issues in Dogweek:**
1. **Button Proliferation:** 8 separate button files (should be 1 component with variants)
2. **Structure/Style Confusion:** H1 component hardcoded to visual style (breaks semantic HTML)
3. **No Token Architecture:** Hardcoded values instead of design tokens
4. **No Component IDs:** File-based organization, no usage tracking
5. **No Similarity Detection:** Manual component management

**Proposed Refactoring:**
- Consolidate 8 button files → 1 Button component [btn-001] with variants
- Separate semantic HTML (h1-h6) from visual tokens (heading-hero, heading-page)
- Implement design token system (colors, typography, spacing)
- Add component IDs and usage tracking
- Create component references in page specs

**Benefits:**
- ✅ Validates WDS Phase 5 on production system
- ✅ Improves Dogweek maintainability
- ✅ Creates migration guide for other projects
- ✅ Generates real-world examples for WDS course

**Status:** Backlog (after Phase 6 complete)

---

**End of Roadmap Document**

*To continue: Phase 6 (Integration) is the final workflow to create*

