63 KiB

Raw Blame History

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)

Project Overview
Key Decisions Made
Repository Setup
Module Architecture
Output Folder Structure
Design Philosophy
Development Order
Files Created So Far
Next Steps
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

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:

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

Example - After:

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

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

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

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

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:

Define the methodology (phases, outputs, connections)
Create workflows that implement the methodology
Create agents that guide users through workflows
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

Create wds-method-guide.md
Create phase guide for each phase (6 files)
Refine all phase guides with positive language, proper naming
Create workflow-init workflow ✅
Create Phase 1-3 workflows ✅
Create Phase 4 workflow (UX Design) ✅ COMPLETE Dec 4, 2025
Create Phase 5-6 workflows
Create WDS Trigger Map (meta-example for WDS itself)
Create conversation examples
Create agents (Saga, Freyja, Baldr)
Create templates for component showcase, PRD, etc.
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):

My ICP (Who I Serve Best)
My Positioning (How I'm Different)
The Outcomes I Drive
My Offerings (What I Sell)
Social Proof (Who Can Vouch)
My Frameworks/Models/Tools (How I Work)
The Pains My ICP Articulates (Triggers/Frustrations)
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

Fork vs Standalone: Decided on fork for maximum adoption
Module Name: Whiteport Design Studio (WDS) to preserve brand
Branch Strategy: Work on main, switch to feature branches after adoption
Folder Structure: A-B-C-D-E alphabetical prefix for visual namespace
Phase Approach: Phase-selectable (not rigid tracks)
Scope: Design only, no development/backlog (handled by BMM)
E-UI-Roadmap: Integration bridge to development modules
Development Order: Methodology-first approach
Language Style: Soft, collaborative (not MUST/FORBIDDEN)
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

Soft language by design
Show, don't tell (examples over explanations)
Example projects for adoption/training
Identity-based agent personas
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

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

Purpose-Based Object IDs - IDs reflect function, remain stable when content changes
Grouped Translations - Each language reads coherently as a group
Sketch Text Analysis - Automatic capacity estimation from visual markers
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:

Specification Language - Language to write design specs in (EN, SE, etc.)
Product Languages - Array of languages the product supports

Storage:

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

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:

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
Option 2: Create Module Templates
- Template structure for each module type
- Fill in with specific content later
- Faster to generate full course
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:

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:

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

Page Spec:

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

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

# 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

Next Steps:

Create Phase 6 workflow (Integration/PRD Finalization)
Test Phase 5 workflow with real project
Refine assessment criteria based on usage
Add more shared knowledge documents as patterns emerge
Test Figma MCP integration with real components
Test catalog generation with real components

16. Future: Dogweek Design System Refactoring (Backlog)

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

Identified Issues in Dogweek:

Button Proliferation: 8 separate button files (should be 1 component with variants)
Structure/Style Confusion: H1 component hardcoded to visual style (breaks semantic HTML)
No Token Architecture: Hardcoded values instead of design tokens
No Component IDs: File-based organization, no usage tracking
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

63 KiB Raw Blame History

WDS v6 Conversion Roadmap

Table of Contents

1. Project Overview

What is WDS?

Origin

Core Purpose

Integration Model

2. Key Decisions Made

2.1 Module Name

2.2 Repository Approach

2.3 Working Branch

2.4 Workflow Approach

2.5 Development Handoff

2.6 README Convention

3. Repository Setup

3.1 Local Path

3.2 Git Remotes

3.3 Syncing with Upstream

4. Module Architecture

4.1 Module Location

4.2 Folder Structure

4.3 Agents - The Norse Pantheon 🏔️

5. Output Folder Structure

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

5.2 Why Alphabetical Prefix?

5.3 Phase-to-Folder Mapping

5.4 E-UI-Roadmap Contents

6. Design Philosophy

6.1 Core Principles

Principle 1: Soft Language

Principle 2: Show, Don't Tell

Principle 3: Example Projects for Adoption

6.2 Known Problems to Mitigate

6.3 Positive Language Guidelines

6.4 Instruction Style

6.5 Key Methodology Refinements (Dec 3, 2025)

Phase Naming Convention

Phase 2: Feature Impact Analysis

Phase 3: PRD Platform

Phase 4: Step 4E - PRD Update

Phase 5: Optional & Parallel

Phase 6: PRD Finalization

Removed from Guides

7.1 Chosen Approach: Methodology-First

7.2 Detailed Order

Phase 1: Define the Methodology

Phase 2: Create Examples

Phase 3: Create Workflows

Phase 4: Create Agents (The Norse Pantheon)

Phase 5: Finalize

8. Files Created So Far

8.1 Repository Root

8.2 Methodology Documentation

8.3 Module Structure (Folders Created, Content Pending)

9. Next Steps

Immediate Next Action

Short-term Roadmap

Commit Checkpoint

10. Reference Information

10.1 Open Design Decisions

10.2 Product Positioning Framework

10.2 BMad v6 Resources

10.3 Original WPS2C

10.4 Dog Week Project

Conversation Summary

Key Discussion Points

User's Stated Experience

Design Philosophy Established

11. WPS2C → WDS Conversion Reference

11.1 Agent Mapping

11.2 File Format Changes

11.3 Terminology Changes

11.4 Presentation Files Mapping

11.5 Templates Mapping

11.6 Standards/Data Files Mapping

11.7 Content to Preserve from WPS2C

11.8 Key Improvements in WDS v6

11.9 Migration Notes

12. Latest Updates (December 5, 2025)

63 KiB

Raw Blame History