ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

refactor: update agent names in documentation for clarity 

- Renamed specialized design agents in README and related documents to include "the" in their titles for consistency and clarity.
- Updated references to agents in the WDS conversion roadmap and method guide to reflect the new naming convention.
- Enhanced documentation to improve readability and user understanding of agent roles within the WDS framework.
This commit is contained in:
Mårten Angner 2025-12-02 19:50:48 +01:00
parent 47ee5a45cc
commit 3d7011ea64
10 changed files with 1354 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -114,9 +114,9 @@ WDS introduces **3 specialized design agents** named after Norse mythology:
| Agent | Role | Norse Meaning |
|-------|------|---------------|
| **Saga-Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story |
| **Freyja-PM** | Product Manager | Goddess of love, war & strategy - leads with heart and mind |
| **Baldr-UX** | UX/UI Designer | God of light & beauty - makes everything radiant |
| **Saga the Analyst** | Business & Product Analyst | Goddess of stories & wisdom - uncovers your business story |
| **Freyja the PM** | Product Manager | Goddess of love, war & strategy - leads with heart and mind |
| **Baldr the UX Expert** | UX/UI Designer | God of light & beauty - makes everything radiant |
---

54
WDS-V6-CONVERSION-ROADMAP.md
View File

@ -207,14 +207,14 @@ src/modules/wds/
| Agent | File | Role | Norse Meaning | Status |
|-------|------|------|---------------|--------|
| **Saga-Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom | TO CREATE |
| **Freyja-PM** | `freyja-pm.agent.yaml` | Product Manager | Goddess of love, war & strategy | TO CREATE |
| **Baldr-UX** | `baldr-ux.agent.yaml` | UX/UI Designer | God of light & beauty | TO CREATE |
| **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 Norse Mythology + Role Suffix?**
- Distinctive and memorable mythology names
- Role suffix makes function immediately clear
- Not too obvious (avoided Thor, Odin)
**Why "Name the Function" format?**
- Reads naturally: "Saga the Analyst"
- Distinctive Norse mythology names
- Function is immediately clear
- Creates unique WDS brand identity
---
@ -399,12 +399,12 @@ What to avoid:
| Order | Component | File | Status |
|-------|-----------|------|--------|
| 1 | Method Overview | `docs/method/wds-method-guide.md` | ✅ CREATED |
| 2 | Phase 1 Guide | `docs/method/phase-1-exploration-guide.md` | TO CREATE |
| 3 | Phase 2 Guide | `docs/method/phase-2-research-guide.md` | TO CREATE |
| 4 | Phase 3 Guide | `docs/method/phase-3-requirements-guide.md` | TO CREATE |
| 5 | Phase 4 Guide | `docs/method/phase-4-conceptual-guide.md` | TO CREATE |
| 6 | Phase 5 Guide | `docs/method/phase-5-components-guide.md` | TO CREATE |
| 7 | Phase 6 Guide | `docs/method/phase-6-integration-guide.md` | TO CREATE |
| 2 | Phase 1 Guide | `docs/method/phase-1-exploration-guide.md` | ✅ CREATED |
| 3 | Phase 2 Guide | `docs/method/phase-2-research-guide.md` | ✅ CREATED |
| 4 | Phase 3 Guide | `docs/method/phase-3-requirements-guide.md` | ✅ CREATED |
| 5 | Phase 4 Guide | `docs/method/phase-4-ux-design-guide.md` | ✅ CREATED |
| 6 | Phase 5 Guide | `docs/method/phase-5-design-system-guide.md` | ✅ CREATED |
| 7 | Phase 6 Guide | `docs/method/phase-6-integration-guide.md` | ✅ CREATED |
#### Phase 2: Create Examples
| Order | Component | Location | Status |
@ -412,6 +412,32 @@ What to avoid:
| 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 |
@ -483,7 +509,7 @@ This will include:
### Short-term Roadmap
1. [x] Create `wds-method-guide.md`
2. [ ] Create phase guide for each phase (6 files)
2. [x] Create phase guide for each phase (6 files)
3. [ ] Port Dog Week examples to `examples/dog-week-patterns/`
4. [ ] Create conversation examples
5. [ ] Create workflow-init workflow

6
src/modules/wds/README.md
View File

@ -56,9 +56,9 @@ WDS creates an alphabetized folder structure in the user's `docs/` folder:
| Agent | File | Role | Norse Meaning |
|-------|------|------|---------------|
| **Saga-Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom |
| **Freyja-PM** | `freyja-pm.agent.yaml` | Product Manager | Goddess of love, war & strategy |
| **Baldr-UX** | `baldr-ux.agent.yaml` | UX/UI Designer | God of light & beauty |
| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom |
| **Freyja the PM** | `freyja-pm.agent.yaml` | Product Manager | Goddess of love, war & strategy |
| **Baldr the UX Expert** | `baldr-ux.agent.yaml` | UX/UI Designer | God of light & beauty |
## Conventions

144
src/modules/wds/docs/method/phase-1-exploration-guide.md Normal file
View File

@ -0,0 +1,144 @@
# Phase 1: Product Exploration
**Agent:** Saga the Analyst
**Output:** `A-Product-Brief/` (or your configured prefix)
**Duration:** 30-60 minutes
---
## What This Phase Does
Product Exploration establishes your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
By the end, you'll have a Product Brief that captures your vision and serves as the north star for your entire project.
---
## What You'll Create
Your Product Brief includes:
- **Executive Summary** - The vision that inspires teams
- **Problem Statement** - The "why" that drives decisions
- **User Types** - The "who" that guides design (initial identification)
- **Solution Approach** - The "how" that enables development
- **Success Criteria** - The "what" that measures progress
- **Market Positioning** - How you're different (optional: ICP framework)
---
## How It Works
### The Conversational Approach
Traditional requirements gathering treats people like databases - extracting answers through rigid questionnaires. WDS does it differently.
**Instead of:** "Please complete this 47-question requirements document"
**WDS says:** "Tell me about your project in your own words"
People light up when asked to share their vision. They become collaborators, not interrogation subjects.
### The Session Flow
**Opening (5-10 minutes)**
Saga asks about your project in your own words. She listens for:
- What you emphasize naturally
- Where your energy goes
- What excites vs. what stresses you
- Your exact language and terminology
**Exploration (15-30 minutes)**
The conversation adapts to what you reveal:
- If you mention users → deeper into user insights
- If you mention problems → explore the cost of not solving
- If you mention competition → discover differentiation
- If you mention timeline → understand urgency drivers
Each answer reveals the next question. It's jazz, not classical music.
**Synthesis (10-15 minutes)**
Saga reflects back your vision in organized form:
- Connecting dots you shared across topics
- Highlighting insights you might not have seen
- Building the foundation for next phases
### Living Document
As you talk, the Product Brief grows in real-time:
- Immediate validation and refinement
- Real-time course correction
- You own the content because you helped create it
- "Yes, exactly!" moments that build trust
---
## When to Use This Phase
**Always start here if:**
- Building something new
- Starting a new project
- Need strategic clarity before diving into design
**Skip if:**
- You already have a clear, documented product brief
- Just enhancing an existing feature
- Working on a design system without new product context
---
## What to Prepare
Come ready to share:
- Your project idea (even if rough)
- The problem you're solving
- Who might use it
- Why it matters to you
You don't need polished answers. The conversation will help clarify everything.
---
## What Comes Next
Your Product Brief enables:
- **Phase 2: User Research** - Deeper into user psychology with your strategic context
- **Phase 3: Requirements** - Technical decisions aligned with your vision
- **Phase 4: UX Design** - Design work grounded in strategic purpose
The brief becomes the reference point everyone shares.
---
## Tips for Great Sessions
**Let the conversation flow**
- Share what feels important, even if it seems tangential
- Follow your energy - where you're excited matters
**Think out loud**
- Half-formed thoughts are welcome
- will help you refine them
**Be honest about uncertainty**
- "I'm not sure about X" is useful information
- Better to surface doubts now than later
**Review as you go**
- Check that what's captured matches your thinking
- Correct misunderstandings immediately
---
## Example Output
See: `examples/dog-week-patterns/A-Product-Brief/` for a complete Product Brief example from a real project.
---
*Phase 1 of the Whiteport Design Studio method*

303
src/modules/wds/docs/method/phase-2-research-guide.md Normal file
View File

@ -0,0 +1,303 @@
# Phase 2: User Research (Trigger Mapping)
**Agent:** Saga the Analyst
**Output:** `B-Trigger-Map/` (or your configured prefix)
**Duration:** 2-3 hours
---
## What This Phase Does
User Research connects business goals to user psychology through Trigger Mapping. You discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
By the end, you'll have a Trigger Map that visually shows how user success drives business success.
---
## What You'll Create
Your Trigger Map includes:
- **Business Goals** - What success looks like for your organization
- **Target Groups** - User types who can help achieve those goals
- **Personas** - Detailed profiles with psychological depth
- **Usage Goals** - What users want vs. what they fear
- **Visual Trigger Map** - Diagram connecting all the pieces
- **Priority Rankings** - Which goals, users, and drivers matter most
- **Feature Impact Analysis** - Scored feature list ranked by strategic value
---
## From Effect Mapping to Trigger Mapping
WDS Trigger Mapping is based on the groundbreaking **Effect Management** methodology from inUse, Sweden.
### Credits & Foundation
**Effect Management** was created by **Mijo Balic** and **Ingrid Domingues (Ottersten)** at **inUse**, Sweden. Their pioneering work on connecting business goals to user behavior through visual mapping - the **Effect Map** - laid the foundation for how we think about strategic software design.
The methodology gained wider recognition through Gojko Adzic's book **"Impact Mapping: Making a Big Impact with Software Products and Projects"** (2012), which acknowledges Effect Mapping as a key influence.
> **Founder's Note:** I personally acquired the insights about the power of the Effect Map back in 2007, and it has served as the philosophical basis for all of my work in UX for almost 20 years. I am eternally grateful for this model that I now have the pleasure to share with the world in an updated version suitable for modern projects.
> — *Martin Eriksson, WDS Creator*
📚 **Further Reading:**
- [Impact Mapping on Amazon](https://www.amazon.com/Impact-Mapping-Software-Products-Projects/dp/0955683645) - Gojko Adzic's book building on Effect Mapping concepts
- [impactmapping.org](https://www.impactmapping.org) - Resources and community
### What is Effect Mapping?
Effect Mapping is the original model that connects business goals to user behavior through a visual map. It includes business goals, target groups, usage goals, and the specific actions/features that enable those goals.
### What is Trigger Mapping?
Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf life and deeper psychological insight:
**Simplified:**
- Leaves out actions/features from the map
- Focuses on the strategic connections
- Map stays relevant even as features evolve
**Enhanced:**
- Adds **negative driving forces** (fears, frustrations)
- Creates fuller picture of user psychology
- Both what users want AND what they want to avoid
### The Core Insight
Any software is about **flow of value**. There's always a group of people who, through their use of the software, make your success happen.
These users have their own goals:
- **GAIN** - Benefits and positive outcomes they achieve
- **PAIN** - Resistance and friction they experience
**The key:** Make GAIN > PAIN for users, so through their usage, they add value to your system.
### The Three Layers
The Trigger Map combines three critical layers in one picture:
1. **Business Goals** - Your WHY (Vision that motivates, and SMART objectives that measure success)
2. **Target Groups** - The WHO (User types whose success drives your success)
3. **Usage Goals** - Their WHY (Driving forces both positive - what they wish to achieve, and negative - what they wish to avoid)
When all levels are then prioritized, you have perfect guidance for design:
- Present features that add value to your most prioritized goal first
- To the highest prioritized target group
- In a way that best suits their most prioritized usage goal
- Make sound decisions about priority of bugs or features based on the total impact on users' goals
---
## How It Works
### Stage 1: Business Goals (15-20 minutes)
Starting question: "Looking at your product brief, what does 'winning' look like for your organization?"
Business goals work at two levels:
**Vision (Motivating, not easily quantifiable)**
A statement that inspires and guides direction:
- "Become the most popular free and open source design support framework"
- "Be the go-to partner for SMB digital transformation"
- "Make professional UX accessible to every startup"
**Objectives (SMART metrics)**
Specific, measurable targets that indicate progress toward the vision:
- "10,000 active designer users by 2027"
- "100 community contributions accepted by Q4 2026"
- "50% of users complete full 6-phase workflow"
- "NPS score of 60+ from design professionals"
You'll define both levels:
- Vision that motivates the team
- Objectives with clear success metrics
### Stage 2: Target Groups (20-30 minutes)
Key question: "Who needs to succeed for YOU to succeed?"
Instead of demographics, you discover:
- User types who can drive business success
- The role each type plays in your strategy
- How different users contribute differently
- Why each user type matters to business goals
Users become strategic assets, not just audience segments.
### Stage 3: Psychological Deep Dive (30-40 minutes)
For each user type:
"When this user type is at their best - when they're succeeding - what are they accomplishing? What are they feeling?"
"Now the flip side: What do they desperately want to avoid? What would feel like failure?"
This reveals:
- **Positive Triggers** - What motivates action
- **Negative Triggers** - What prevents engagement
- **Emotional Drivers** - The psychology behind decisions
- **Behavioral Patterns** - When and why they act
### Stage 4: Visual Strategy Map (15-20 minutes)
Saga helps build the complete trigger map:
- Connecting every user insight to business goals
- Creating the visual strategy guide
- Validating the strategic logic together
### Stage 5: Prioritization (20-30 minutes)
This stage is critical for shaping the final product concept. You systematically prioritize each column of the Trigger Map.
**The Prioritization Process:**
1. **Rank Business Goals** - Which goal matters most right now? Which is secondary?
2. **Rank Target Groups** - Which user types have the most impact on your top goal?
3. **Rank Usage Goals** - For your top users, which driving forces are most urgent?
**Why This Matters:**
Different prioritizations lead to fundamentally different products. The same Trigger Map can produce wildly different concepts depending on what you prioritize first.
### Stage 6: Feature Impact Analysis (20-30 minutes)
Now the magic happens. You connect strategy to concrete features using a systematic impact scoring approach.
**The Process:**
1. **Gather Feature Ideas** - Pull from your Product Brief, stakeholder input, and brainstorming
2. **Map to Target Groups** - For each feature, identify which target groups it serves
3. **Map to Driving Forces** - Which positive and negative drivers does it address?
4. **Score the Impact** - Features serving multiple groups and drivers score higher
**The Scoring System:**
For each feature, award points:
| Impact | Points |
|--------|--------|
| Serves Priority 1 Target Group | +3 |
| Serves Priority 2 Target Group | +2 |
| Serves Priority 3 Target Group | +1 |
| Addresses Priority 1 Positive Driver | +3 |
| Addresses Priority 2 Positive Driver | +2 |
| Addresses Priority 3 Positive Driver | +1 |
| **Addresses Priority 1 Negative Driver** | **+4** |
| **Addresses Priority 2 Negative Driver** | **+3** |
| **Addresses Priority 3 Negative Driver** | **+2** |
| Serves multiple target groups | +2 bonus |
| Addresses both positive AND negative drivers | +2 bonus |
> **Why negative drivers score higher:** Loss aversion is a well-documented psychological principle - humans work harder to avoid pain than to pursue gain. Features that remove friction, fear, or frustration create stronger user loyalty than features that simply add benefits.
**Example:**
| Feature | Target Groups | Driving Forces | Score |
|---------|---------------|----------------|-------|
| One-click booking | P1 Dog Owner (+3), P2 Walker (+2) | Convenience (+3), Fear of complexity (-P1: +4), Multi-group (+2), Both types (+2) | **16** |
| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** |
| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** |
**The Output:**
A ranked feature list showing:
- Which features have the broadest impact
- Which features are "single-purpose" vs "multi-impact"
- Natural MVP candidates (highest scores)
- Features to defer (low scores but still valuable)
**Why This Works:**
Features that resonate with multiple target groups and address multiple driving forces are inherently more valuable. They create more value per development effort and satisfy more users simultaneously.
---
## Personas with Depth
Traditional personas describe demographics: "Jennifer, 34, likes yoga and lattes."
WDS personas capture psychology:
**Alliterative Naming** - Each persona gets a memorable name that hints at their role:
- "Patrick the Professional" - Decision-maker focused on efficiency
- "Sophie the Socializer" - Values connection and community
- "Tyler the Technical" - Wants control and customization
**What Each Persona Includes:**
- Role and context
- Goals they're trying to achieve
- Fears and frustrations
- How they'd describe their problem
- What success looks like to them
- Triggers that motivate action
---
## When to Use This Phase
**Use after Phase 1 if:**
- Building a new product
- Need clarity on who you're building for
- Want design decisions grounded in user psychology
**Start here if:**
- You have product vision but unclear user strategy
- Existing personas feel shallow or unused
- Features aren't connecting with users
**Skip if:**
- Quick enhancement to existing feature
- Users are already well-documented and validated
- Design system work without new user research
---
## What to Prepare
Bring:
- Your completed Product Brief (Phase 1)
- Any existing user research (even informal)
- Stakeholder availability for the workshop
---
## What Comes Next
Your Trigger Map enables:
- **Phase 3: Requirements** - Technical decisions aligned with user priorities
- **Phase 4: UX Design** - Design work grounded in user psychology
- **Development priorities** - Clear guidance on what to build first
The trigger map becomes the strategic brain of your product.
---
## Tips for Great Sessions
**Think strategically, not demographically**
- "Who needs to win for us to win?" not "Who might use this?"
- Connect every user insight to business outcomes
**Go deep on psychology**
- Push beyond surface responses
- Ask "why" multiple times
- Understand motivations, not just behaviors
**Build the map live**
- See connections as they emerge
- Validate strategic logic together
- Make it visual and shareable
---
## Example Output
See: `examples/dog-week-patterns/B-Trigger-Map/` for a complete Trigger Map with personas from a real project.
---
*Phase 2 of the Whiteport Design Studio method*

159
src/modules/wds/docs/method/phase-3-requirements-guide.md Normal file
View File

@ -0,0 +1,159 @@
# Phase 3: Requirements (PRD)
**Agent:** Freyja the PM
**Output:** `D-PRD/` (or your configured prefix)
**Duration:** 1-2 hours
---
## What This Phase Does
Requirements defines the technical foundation and functional specifications. This phase bridges strategic vision with implementation details, creating the PRD (Product Requirements Document) that guides development.
By the end, you'll have clear requirements that development teams can act on.
---
## What You'll Create
Your PRD includes:
- **Platform Architecture** - Technology stack and infrastructure decisions
- **Data Model** - Core entities and relationships
- **API Specifications** - Endpoints and data contracts
- **Integration Requirements** - External services and dependencies
- **Security Framework** - Authentication, authorization, data protection
- **Performance Requirements** - Speed, scale, reliability expectations
- **Functional Specifications** - Feature-level requirements
---
## How It Works
### Platform Foundation First
Before diving into features, establish the technical foundation:
**Architecture Decisions:**
- What technology stack fits your needs?
- Monolith vs. microservices vs. serverless?
- What hosting/infrastructure approach?
- What are the key technical constraints?
**Data Model:**
- What are the core entities?
- How do they relate to each other?
- What's the database strategy?
**Integration Points:**
- What external services are needed?
- Authentication providers?
- Payment systems?
- Third-party APIs?
### Security & Performance
**Security Framework:**
- How do users authenticate?
- What authorization model?
- Data encryption approach?
- Compliance requirements?
**Performance Requirements:**
- Expected load and scale?
- Response time expectations?
- Availability requirements?
- Caching strategy?
### Functional Requirements
After the foundation is set, define feature-level requirements:
- User stories or use cases
- Acceptance criteria
- Edge cases and error handling
- Integration with the technical foundation
---
## The Design Connection
PRD work in WDS is informed by:
- **Product Brief** (Phase 1) - Strategic vision and success criteria
- **Trigger Map** (Phase 2) - User priorities and business goals
And it enables:
- **UX Design** (Phase 4) - Technical context for design decisions
- **Design System** (Phase 5) - Component technical requirements
- **Development** - Clear implementation guidance
---
## When to Use This Phase
**Use this phase when:**
- Building platform/infrastructure for a new product
- Need technical decisions documented before design
- Development team needs architectural clarity
**Timing considerations:**
- Can run parallel to Phase 4 (UX Design) once foundation is set
- Platform infrastructure can start while UX design continues
- Functional requirements often finalize after Phase 4
**Skip or minimize if:**
- Simple project with obvious technical approach
- Working within existing platform/infrastructure
- Enhancement that doesn't change architecture
---
## What to Prepare
Bring:
- Product Brief (Phase 1)
- Trigger Map (Phase 2)
- Any existing technical constraints
- Development team input if available
---
## What Comes Next
Your PRD enables:
- **Phase 4: UX Design** - Design within technical constraints
- **Phase 6: Dev Integration** - Handoff with complete technical context
- **Development** - Backend/platform work can begin
---
## Tips for Great Sessions
**Balance depth with progress**
- Document decisions, not every detail
- Focus on what developers need to start
- Iterate as design clarifies requirements
**Stay connected to strategy**
- Reference trigger map priorities
- Ensure technical decisions serve user goals
- Don't over-engineer for hypothetical needs
**Collaborate with development**
- Technical decisions benefit from dev input
- Early alignment prevents rework
- Architecture is a conversation, not a decree
---
## Example Output
See: `examples/dog-week-patterns/D-PRD/` for a complete PRD from a real project.
---
*Phase 3 of the Whiteport Design Studio method*

236
src/modules/wds/docs/method/phase-4-ux-design-guide.md Normal file
View File

@ -0,0 +1,236 @@
# Phase 4: UX Design (Conceptual Specifications)
**Agent:** Baldr the UX Expert
**Output:** `C-Scenarios/` (or your configured prefix)
**Duration:** 2-4 hours per scenario (varies by complexity)
---
## What This Phase Does
UX Design transforms ideas into detailed visual specifications. Working with Baldr, you conceptualize, sketch, and specify every interaction until your design can be logically explained without gaps.
**The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals holes in your thinking before they become expensive development problems.
---
## What You'll Create
For each scenario/page:
- **Scenario Structure** - Numbered folder hierarchy
- **Page Specifications** - Complete documentation of each screen
- **Component Definitions** - Every element with Object IDs
- **Interaction Behaviors** - What happens when users interact
- **State Definitions** - All possible states for dynamic elements
- **Multilingual Content** - Text in all supported languages
- **HTML Previews** - Interactive prototypes for validation
---
## Three Ways to Work
### 4A: Scenario Exploration
**When:** No sketch exists, discovering the solution together
Baldr helps you:
- Think through the user's journey
- Explore content and feature options
- Consider psychological triggers from your Trigger Map
- Arrive at a clear solution ready for sketching
### 4B: Sketch Analysis
**When:** You have a sketch, need to specify it
Baldr helps you:
- Analyze what the sketch shows
- Ask clarifying questions
- Identify all components and states
- Create complete specifications
### 4C: Specification Creation
**When:** Design is clear, need development-ready specs
Baldr helps you:
- Document every detail systematically
- Assign Object IDs for testing
- Define all interactions and states
- Prepare multilingual content
### 4D: HTML Preview
**When:** Specifications complete, need visual validation
Baldr helps you:
- Create interactive HTML prototypes
- Test the design in browser
- Discover gaps and issues
- Refine specifications before development
---
## The Scenario Structure
Scenarios organize your design work into a clear hierarchy:
```
C-Scenarios/
├── 00-Scenario-Overview.md
├── 01-User-Onboarding/
│ ├── 1.1-Welcome-Page/
│ │ ├── 1.1-Welcome-Page.md
│ │ ├── Sketches/
│ │ └── Frontend/
│ └── 1.2-Sign-Up/
│ ├── 1.2-Sign-Up.md
│ └── ...
├── 02-Core-Feature/
│ └── ...
```
**Numbering Convention:**
- Scenarios: 01, 02, 03...
- Pages within scenarios: 1.1, 1.2, 2.1, 2.2...
---
## Object IDs
Every interactive element gets an Object ID for:
- Consistent naming across specs and code
- Test automation with stable selectors
- Analytics tracking
- Design-dev communication
**Format:** `{page}-{section}-{element}` in kebab-case
**Example:**
```
welcome-page-hero-cta-button
signin-form-email-input
signin-form-error-email
```
---
## The Pressure-Testing Process
Specification isn't just documentation - it's design validation.
When you try to specify every detail, you discover:
- "What happens when this is empty?"
- "How does this look on mobile?"
- "What if the user does X before Y?"
- "Where does this data come from?"
Finding these gaps now is cheap. Finding them during development is expensive.
---
## HTML Previews
Interactive prototypes that validate your design:
**What they include:**
- Semantic HTML matching your specs
- CSS using your Design System tokens
- JavaScript for interactions and validation
- Multilingual content switching
**What they reveal:**
- Visual gaps ("the spacing doesn't match")
- Interaction issues ("we forgot the loading state")
- Component needs ("we need a phone input component")
- Content problems ("the translation is too long")
- Flow issues ("this navigation doesn't make sense")
**File Structure:**
```
1.1-Welcome-Page/
├── 1.1-Welcome-Page.md (specification)
├── Sketches/
│ └── concept-sketch.jpg
└── Frontend/
├── 1.1-Welcome-Page-Preview.html
├── 1.1-Welcome-Page-Preview.css
└── 1.1-Welcome-Page-Preview.js
```
---
## When to Use This Phase
**Use this phase when:**
- Ready to design specific screens/pages
- Have strategic clarity from Phase 1-2
- Want to validate designs before development
**Start with exploration (4A) if:**
- No existing sketches
- Unsure how to approach a feature
- Need to think through the user journey
**Start with analysis (4B) if:**
- Have sketches ready to specify
- Know what you want, need to document it
**Use HTML previews (4D) if:**
- Specifications feel complete
- Want to validate before development
- Need stakeholder sign-off
---
## What to Prepare
Bring:
- Trigger Map (Phase 2) - for user psychology reference
- Any existing sketches or wireframes
- Technical constraints from PRD (Phase 3)
- Content in all supported languages (or draft it together)
---
## What Comes Next
Your specifications enable:
- **Phase 5: Design System** - Components extracted and documented
- **Phase 6: Dev Integration** - Complete handoff package
- **Development** - Specs so clear they eliminate guesswork
---
## Tips for Great Sessions
**Think out loud with Baldr**
- Share your reasoning
- Explore alternatives together
- Let the conversation reveal insights
**Be thorough with states**
- Empty states
- Loading states
- Error states
- Success states
- Edge cases
**Don't skip the preview**
- Click through your design
- Find the gaps before development
- Refine specs based on what you learn
**Reference your Trigger Map**
- Does this serve the user's goals?
- Does this avoid their fears?
- Does this support business objectives?
---
## Example Output
See: `examples/dog-week-patterns/C-Scenarios/` for complete scenario specifications from a real project.
---
*Phase 4 of the Whiteport Design Studio method*

212
src/modules/wds/docs/method/phase-5-design-system-guide.md Normal file
View File

@ -0,0 +1,212 @@
# Phase 5: Design System (Component Design)
**Agent:** Baldr the UX Expert
**Output:** `D-Design-System/` (or your configured prefix)
**Duration:** Ongoing (grows with your product)
---
## What This Phase Does
Design System builds your component library following atomic design principles. Working with Baldr, you create reusable patterns that serve user psychology and ensure visual consistency.
The design system grows organically from your Phase 4 specifications - as you design scenarios, components are extracted and documented here.
---
## What You'll Create
Your Design System includes:
- **Design Tokens** - Colors, typography, spacing, shadows
- **Atomic Components** - Buttons, inputs, labels, icons
- **Molecular Components** - Form groups, cards, list items
- **Organism Components** - Headers, footers, complex sections
- **Usage Guidelines** - When and how to use each component
- **Component Variants** - Different states and sizes
---
## Atomic Design Structure
Following Brad Frost's methodology:
### Foundation (Design Tokens)
The values everything else builds on:
- **Colors** - Primary, secondary, semantic (success, error, warning)
- **Typography** - Font families, sizes, weights, line heights
- **Spacing** - Consistent spacing scale
- **Shadows** - Elevation levels
- **Borders** - Radius and stroke styles
- **Breakpoints** - Responsive design points
### Atoms
The smallest building blocks:
- Buttons
- Input fields
- Labels
- Icons
- Badges
- Dividers
### Molecules
Groups of atoms working together:
- Form groups (label + input + error)
- Search bars (input + button)
- Card headers (title + action)
- Navigation items (icon + label)
### Organisms
Complex components made of molecules:
- Page headers
- Navigation bars
- Form sections
- Card layouts
- List views
---
## How It Works
### Component Extraction
As you specify scenarios in Phase 4, components naturally emerge:
1. **Identify patterns** - "This button style appears in multiple places"
2. **Extract to system** - Document the component with all variants
3. **Reference in specs** - Link scenario specs to system components
### Component Documentation
Each component includes:
**Purpose & Usage**
- When to use this component
- When NOT to use it
- Psychological intent (connects to Trigger Map)
**Variants**
- Size options (small, medium, large)
- State options (default, hover, active, disabled)
- Visual variants (primary, secondary, ghost)
**Specifications**
- Design tokens used
- Spacing and sizing
- Responsive behavior
**Implementation Notes**
- Technical guidance for developers
- Accessibility requirements
- Animation/interaction details
---
## Trigger Map Connection
Components aren't just visual - they serve user psychology:
**Example: Primary Button**
- **Serves trigger:** Reduces decision anxiety for professional users
- **Design intent:** Bold, confident, clear
- **Psychological purpose:** Makes taking action feel safe
**Example: Error Message**
- **Serves trigger:** Prevents frustration and abandonment
- **Design intent:** Clear, helpful, non-judgmental
- **Psychological purpose:** Recovery feels possible
---
## Growing the System
The design system is living documentation that grows with your product:
### Starting Point
Begin with what you need for current scenarios:
- Extract components from Phase 4 work
- Document only what you're actually using
- Avoid speculating about future needs
### Evolution
As you design more scenarios:
- New patterns emerge → add to system
- Inconsistencies appear → consolidate
- Components evolve → update documentation
### Maintenance
- Keep specs in sync with implementation
- Remove unused components
- Update when design language evolves
---
## When to Use This Phase
**Build alongside Phase 4:**
- As you design scenarios, extract components
- Design system grows organically with specs
**Dedicated design system work when:**
- Consolidating after multiple scenarios
- Preparing for development sprint
- Onboarding new team members
**Skip formal documentation if:**
- Very small project
- One-off design without reuse
- Using existing design system
---
## What to Prepare
Bring:
- Completed or in-progress scenario specs (Phase 4)
- Any existing brand guidelines
- Technical framework constraints (React components, etc.)
---
## What Comes Next
Your Design System enables:
- **Consistent implementation** - Developers build from clear specs
- **Faster design** - Reuse components across scenarios
- **Phase 6 handoff** - Complete component inventory
---
## Tips for Great Sessions
**Extract, don't invent**
- Components should come from real design needs
- Don't create components "just in case"
- Let the system grow from actual scenarios
**Document the why**
- Why does this button look this way?
- What user trigger does it serve?
- When should developers use variant A vs B?
**Stay consistent**
- Same component = same specification
- Variations should be intentional
- When in doubt, simplify
**Connect to psychology**
- Every design choice serves a purpose
- Reference your Trigger Map
- Components should feel intentional, not arbitrary
---
## Example Output
See: `examples/dog-week-patterns/D-Design-System/` for a complete Design System from a real project.
---
*Phase 5 of the Whiteport Design Studio method*

245
src/modules/wds/docs/method/phase-6-integration-guide.md Normal file
View File

@ -0,0 +1,245 @@
# Phase 6: Dev Integration (UI Roadmap)
**Agent:** Freyja the PM
**Output:** `E-UI-Roadmap/` (or your configured prefix)
**Duration:** 1-2 hours
---
## What This Phase Does
Dev Integration prepares everything development teams need. This phase creates the bridge between design and implementation - the handoff package that enables development to begin without additional discovery work.
By the end, developers have a clear roadmap for building the UI you've designed.
---
## What You'll Create
Your UI Roadmap includes:
- **Priority Sequence** - What to build first and why
- **Scenario Mapping** - How scenarios translate to development order
- **Component Inventory** - All components needed, with status
- **Technical Notes** - Design constraints and decisions
- **Object ID Inventory** - Complete list for testing
- **Handoff Checklist** - Verification that everything is ready
- **Open Questions** - Items for the dev team to decide
---
## The Handoff Package
### Priority Sequence
Based on your Trigger Map priorities:
- Which scenarios serve the most important user triggers?
- What's the critical path for MVP?
- What can be deferred to later releases?
**Example:**
```
Priority 1: User Onboarding (Scenarios 1.1-1.3)
- Serves highest-priority business goal
- Enables all other user scenarios
Priority 2: Core Feature (Scenarios 2.1-2.4)
- Primary value delivery
- Most important user trigger activation
Priority 3: Settings & Account (Scenarios 3.1-3.2)
- Supporting functionality
- Can launch with minimal version
```
### Scenario-to-Development Mapping
How design scenarios map to development work:
| WDS Scenario | Development Epic | Dependencies |
|--------------|------------------|--------------|
| 01-User-Onboarding | Epic 1: Auth System | None |
| 02-Core-Feature | Epic 2: Main Feature | Epic 1 |
| 03-Settings | Epic 3: User Settings | Epic 1 |
### Component Inventory
All components from your Design System with development status:
| Component | Design Status | Dev Status | Notes |
|-----------|--------------|------------|-------|
| Button Primary | Complete | Ready | Use existing library |
| Phone Input | Complete | Needs Build | Custom with country selector |
| Calendar Widget | Complete | Needs Build | Complex interactions |
### Object ID Inventory
Complete list for test automation:
| Scenario | Object ID | Element Type | Notes |
|----------|-----------|--------------|-------|
| 1.1 | `welcome-hero-cta` | Button | Primary action |
| 1.1 | `welcome-signin-link` | Link | Secondary action |
| 1.2 | `signin-email-input` | Input | Required field |
| 1.2 | `signin-error-email` | Error | Validation message |
---
## How It Works
### Review Completeness
Before handoff, verify:
- All scenarios specified and reviewed
- Design system covers all components
- Object IDs assigned throughout
- Multilingual content complete
- HTML previews validated
### Identify Priorities
With Freyja, map your Trigger Map priorities to development order:
- Which user triggers are most critical?
- What's the minimum viable experience?
- What can wait for later releases?
### Document Technical Context
Capture what developers need to know:
- Design decisions and their rationale
- Technical constraints discovered during design
- Interaction patterns that need special attention
- Performance considerations
### Create the Handoff
Organize everything into the UI Roadmap folder:
- Clear priority sequence
- Complete component inventory
- Technical notes and open questions
- Verification checklist
---
## The Handoff Checklist
```markdown
## Design Handoff Verification
### Product Foundation
- [ ] Product Brief complete and current
- [ ] Trigger Map with prioritized users and goals
- [ ] ICP clearly defined
### Requirements
- [ ] PRD with technical specifications
- [ ] Platform architecture documented
- [ ] Integration requirements listed
### Visual Design
- [ ] All scenarios have specifications
- [ ] All pages have Object IDs
- [ ] States documented (empty, loading, error, success)
### Design System
- [ ] All components documented
- [ ] Design tokens defined
- [ ] Usage guidelines written
### Validation
- [ ] HTML previews created for key scenarios
- [ ] Stakeholder review complete
- [ ] Open questions documented
### Ready for Development ✅
```
---
## When to Use This Phase
**Use this phase when:**
- Design work is substantially complete
- Ready to hand off to development
- Need to coordinate design-to-dev transition
**Start here if:**
- Joining a project with existing designs
- Need to organize existing documentation
- Preparing for development sprint planning
**Run continuously if:**
- Working in parallel with development
- Gradual handoff as scenarios complete
---
## What to Prepare
Bring:
- Completed scenario specifications (Phase 4)
- Design System (Phase 5)
- PRD (Phase 3)
- Trigger Map priorities (Phase 2)
---
## What Comes Next
Your UI Roadmap enables:
- **Development kickoff** - Clear starting point
- **Sprint planning** - Prioritized work items
- **Test automation** - Object ID inventory
- **QA validation** - Specifications to verify against
---
## Tips for Great Sessions
**Think from dev perspective**
- What questions will developers have?
- What decisions can't you make for them?
- What context will save them time?
**Be explicit about priorities**
- Not everything is Priority 1
- Make trade-offs visible
- Connect priorities to business goals
**Document the unknowns**
- Open questions are valuable
- Don't pretend certainty you don't have
- Let dev team contribute decisions
**Keep it updated**
- Handoff is ongoing, not one-time
- Update as design evolves
- Maintain as source of truth
---
## Integration with BMM
When handing off to BMad Method (BMM) for development:
```
WDS → E-UI-Roadmap/ → BMM Architecture & Stories
```
The UI Roadmap provides:
- Context for architecture decisions
- Specifications for story creation
- Priorities for sprint planning
- Test automation foundations
---
## Example Output
See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a real project.
---
*Phase 6 of the Whiteport Design Studio method*

18
src/modules/wds/docs/method/wds-method-guide.md
View File

@ -45,7 +45,7 @@ WDS follows six phases, each producing artifacts in your project's `docs/` folde
### Phase 1: Product Exploration
**Output:** `A-Product-Brief/`
**Agent:** Saga-Analyst
**Agent:** Saga the Analyst
Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
@ -59,7 +59,7 @@ Establish your strategic foundation through conversational discovery. Instead of
### Phase 2: User Research
**Output:** `B-Trigger-Map/`
**Agent:** Saga-Analyst
**Agent:** Saga the Analyst
Connect business goals to user psychology through Effect Mapping. Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
@ -74,7 +74,7 @@ Connect business goals to user psychology through Effect Mapping. Discover not j
### Phase 3: Requirements
**Output:** `D-PRD/`
**Agent:** Freyja-PM
**Agent:** Freyja the PM
Define the technical foundation and functional requirements. Bridge the gap between strategic vision and implementation details.
@ -89,7 +89,7 @@ Define the technical foundation and functional requirements. Bridge the gap betw
### Phase 4: Conceptual Design
**Output:** `C-Scenarios/`
**Agent:** Baldr-UX
**Agent:** Baldr the UX Expert
Transform ideas into detailed visual specifications. Your agent helps you think out the design, assists in sketching, then specifies and pressure-tests every detail.
@ -107,7 +107,7 @@ Transform ideas into detailed visual specifications. Your agent helps you think
### Phase 5: Component Design
**Output:** `D-Design-System/`
**Agent:** Baldr-UX
**Agent:** Baldr the UX Expert
Build your component library following atomic design principles. Create reusable patterns that serve user psychology.
@ -122,7 +122,7 @@ Build your component library following atomic design principles. Create reusable
### Phase 6: Dev Integration
**Output:** `E-UI-Roadmap/`
**Agent:** Freyja-PM
**Agent:** Freyja the PM
Prepare everything development teams need. Create the bridge between design and implementation.
@ -220,7 +220,7 @@ Your agents will help you identify which phases fit your project.
Three specialized agents guide you through WDS:
### Saga-Analyst 📚
### Saga the Analyst 📚
*"The one who tells your business story"*
Saga guides you through discovery and research. She's curious, patient, and helps you uncover insights you might not have seen yourself.
@ -229,7 +229,7 @@ Saga guides you through discovery and research. She's curious, patient, and help
- Phase 1: Product Exploration
- Phase 2: User Research (Trigger Mapping)
### Freyja-PM ⚔️
### Freyja the PM ⚔️
*"The strategic leader who sees what must be done"*
Freyja helps you define requirements and prepare for development. She balances passion with strategy, knowing when to be fierce and when to be patient.
@ -238,7 +238,7 @@ Freyja helps you define requirements and prepare for development. She balances p
- Phase 3: Requirements
- Phase 6: Dev Integration
### Baldr-UX ✨
### Baldr the UX Expert ✨
*"The one who brings light and beauty"*
Baldr transforms your ideas into beautiful, detailed specifications. He cares deeply about craft and ensures every detail serves the user experience.