From 7b6d3e9c29e7d790a07187c1218bceb857dab2d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Angner?= Date: Wed, 25 Feb 2026 11:30:22 +0100 Subject: [PATCH] Update learn section method guides for v0.3.0 - Rewrite wds-method-guide.md: 9 phases (0-8), correct agents (Saga/Freya/Idunn), updated install command, scenario-driven flow - Create phase-3-ux-scenarios-guide.md: 8-question dialog, page outline dialog, Mermaid flowchart, quality gates, Phase 4 connection - Rewrite phase-4-ux-design-guide.md: Freya as designer, scenario gate, outline-design loop, 9 activities, updated folder structure - Replace phase-3-prd-platform-guide.md with redirect to new UX Scenarios guide Co-Authored-By: Claude Opus 4.6 --- docs/method/phase-3-prd-platform-guide.md | 285 +--------------------- docs/method/phase-3-ux-scenarios-guide.md | 193 +++++++++++++++ docs/method/phase-4-ux-design-guide.md | 274 ++++++++------------- docs/method/wds-method-guide.md | 276 +++++++++++---------- 4 files changed, 445 insertions(+), 583 deletions(-) create mode 100644 docs/method/phase-3-ux-scenarios-guide.md diff --git a/docs/method/phase-3-prd-platform-guide.md b/docs/method/phase-3-prd-platform-guide.md index 5be592129..5dbf5ea0a 100644 --- a/docs/method/phase-3-prd-platform-guide.md +++ b/docs/method/phase-3-prd-platform-guide.md @@ -1,284 +1,5 @@ -# Phase 3: PRD Platform (Technical Foundation) +# Phase 3: UX Scenarios -**Agent:** Freya the PM -**Output:** `C-Requirements/` (or your configured prefix) +This guide has moved. Phase 3 is now **UX Scenarios** (not PRD Platform). ---- - -## What This Phase Does - -This phase establishes everything technical that can be done **without the final UI**. It's about platform decisions, technical feasibility, and proving that your innovative features actually work. - -By the end, you'll have a solid technical foundation and confidence that your key features are buildable. - ---- - -## The Core Principle - -**Prove our concept works technically — in parallel with design work.** - -While UX designers explore how users interact with features, technical validation runs alongside: - -- Can we actually build this? -- Do the external services we need exist and work as expected? -- What platform and infrastructure do we need? -- What constraints does design need to know about? - -Design and technical validation inform each other. Neither waits for the other to finish. - ---- - -## What You'll Create - -- **Platform Architecture** - Technology stack and infrastructure decisions -- **Data Model** - Core entities and relationships -- **Integration Map** - External services and how they connect -- **Technical Proofs of Concept** - Validation that risky features work -- **Experimental Endpoints** - API specs for known requirements (feeds into E-UI-Roadmap) -- **Security Framework** - Authentication, authorization, data protection -- **Technical Constraints Document** - What design needs to know - ---- - -## How It Works - -### Stage 1: Platform Decisions (30-45 minutes) - -Establish the technical foundation: - -**Architecture:** - -- 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? - -### Stage 2: Integration Mapping (20-30 minutes) - -Identify all external dependencies: - -- Authentication providers (OAuth, SSO) -- Payment systems (Stripe, PayPal) -- Third-party APIs (Google Maps, SendGrid, Twilio) -- Data sources and feeds -- Analytics and monitoring - -### Stage 3: Technical Proofs of Concept (Variable) - -**This is crucial.** For innovative or risky features, validate feasibility BEFORE committing to the design. - -**Examples:** - -| Feature Idea | Proof of Concept Question | -| ----------------------------------- | ------------------------------------------------------------------ | -| "Show drive time between locations" | Can we call Google Maps Directions API and get estimated duration? | -| "Real-time availability updates" | Can we set up WebSocket connections that scale? | -| "AI-powered recommendations" | Does the ML model perform well enough with our data? | -| "Offline mode" | Can we sync data reliably when connection returns? | -| "Video calling" | Which provider works best? What's the latency? | - -**What a PoC validates:** - -- The API/service exists and does what we need -- Performance is acceptable -- Cost is within budget -- Data format works for our needs -- Edge cases are handleable - -**PoC Output:** - -- Working code snippet or prototype -- Documented limitations and gotchas -- Cost estimates (API calls, compute, etc.) -- Go/No-Go recommendation for the feature - -> **Why this matters:** It's a great morale boost when you've proven your core features will work. And if you discover limitations or surprises, it's valuable to know them early so design can account for them from the start. - -### Stage 4: Security & Performance Framework (20-30 minutes) - -**Security:** - -- Authentication approach (passwords, OAuth, SSO, passwordless) -- Authorization model (roles, permissions, row-level security) -- Data encryption needs (at rest, in transit) -- Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.) - -**Performance:** - -- Expected load and scale -- Response time expectations -- Availability requirements (99.9%? 99.99%?) -- Caching strategy - -### Stage 5: Experimental Endpoints (Variable) - -**Set up the endpoints you KNOW you'll need.** - -Even before the UI is designed, you often know certain data operations are essential. Setting these up early provides: - -- **Early validation** - Does the endpoint actually return what we need? -- **Fail fast** - Discover problems before investing in design -- **Developer head start** - Backend work can begin immediately -- **Design confidence** - Designers know what data is available - -**What to set up:** - -| Endpoint Type | Example | Why Early? | -| --------------------- | ---------------------------------------- | --------------------------- | -| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything | -| External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works | -| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven | -| Key calculations | `/api/availability/check` | Business logic validated | - -**Output:** - -For each experimental endpoint, document: - -- Endpoint specification (method, path, request/response) -- What it validates -- Current status (stub, working, blocked) -- Dependencies and notes - -These specifications go in your Requirements folder AND become tasks in the `E-UI-Roadmap/` handover folder for development teams. - -> **The mindset:** Every endpoint you validate early is one less surprise during development. Every endpoint that fails early saves weeks of wasted design work. - -### Stage 6: Technical Constraints Document (15-20 minutes) - -Create a summary of what UX design needs to know: - -- **What's possible** - Features validated by PoCs -- **What's not possible** - Technical limitations discovered -- **What's expensive** - Features with high API/compute costs -- **What affects design** - Loading times, offline behavior, real-time vs. polling -- **Platform capabilities** - What the framework/platform provides out of the box - -This document becomes essential input for Phase 4 (UX Design). - ---- - -## The Design Connection - -Phase 3 is informed by: - -- **Product Brief** (Phase 1) - Strategic vision and constraints -- **Trigger Map** (Phase 2) - Prioritized features from Feature Impact Analysis - -And it enables: - -- **UX Design** (Phase 4) - Design within known technical constraints -- **Design System** (Phase 5) - Component technical requirements -- **Development** - Platform work can begin in parallel with design - ---- - -## Parallel Streams - -Once Phase 3 is complete: - -``` -Phase 3 Complete - │ - ├──► E-UI-Roadmap/ receives: - │ • Experimental endpoint specs - │ • API implementation tasks - │ • Infrastructure setup tasks - │ - ├──► Platform/Backend Development can START - │ (Infrastructure, APIs, data model) - │ - └──► Phase 4: UX Design can START - (Informed by technical constraints) -``` - -This parallelism is one of WDS's key efficiency gains. Development teams can begin backend work while designers continue with UX. - ---- - -## When to Use This Phase - -**Use this phase when:** - -- Building platform/infrastructure for a new product -- Features depend on external APIs or services -- Innovative features need technical validation -- Development team needs architectural clarity before design - -**Skip or minimize if:** - -- Simple project with obvious technical approach -- Working within existing platform/infrastructure -- Enhancement that doesn't change architecture -- All features use proven, familiar technology - ---- - -## What to Prepare - -Bring: - -- Product Brief (Phase 1) -- Trigger Map with Feature Impact Analysis (Phase 2) -- Any existing technical constraints -- Development team availability for PoC work - ---- - -## What Comes Next - -Your technical foundation enables: - -- **Phase 4: UX Design** - Design with confidence about what's technically possible -- **Phase 6: Dev Integration** - Handoff with complete technical context -- **Development** - Backend/platform work can begin immediately - ---- - -## Tips for Great Sessions - -**Validate risky features first** - -- If the Google Maps API doesn't return drive times in a usable format, you need to know NOW -- Don't design features you can't build - -**Document constraints clearly** - -- Designers need to know what's possible -- "Loading state required" vs "instant" changes UX significantly - -**Involve developers** - -- Technical decisions benefit from dev input -- PoC work may require developer time -- Architecture is a conversation, not a decree - -**Stay connected to strategy** - -- Reference Feature Impact Analysis scores -- High-impact features deserve more PoC investment -- Don't over-engineer for hypothetical needs - ---- - -## Example Output - -See: `examples/dog-week-patterns/C-Requirements/` for the Dog Week technical foundation. - -**What Dog Week needed to prove early:** - -- _"Can we show dog owners how long it takes to walk to a dog walker?"_ → Google Maps Directions API returns walking time between coordinates ✓ -- _"Can we check real-time availability across multiple walkers?"_ → Endpoint aggregates calendar data in <200ms ✓ -- _"Can we handle Swish payments for Swedish users?"_ → Swish API integration validated with test transactions ✓ -- _"Can walkers see their schedule on mobile?"_ → Responsive calendar component renders correctly on iOS/Android browsers ✓ - -These early discoveries shaped both the design AND the development approach. - ---- - -_Phase 3 of the Whiteport Design Studio method_ +See: [Phase 3: UX Scenarios Guide](./phase-3-ux-scenarios-guide.md) diff --git a/docs/method/phase-3-ux-scenarios-guide.md b/docs/method/phase-3-ux-scenarios-guide.md new file mode 100644 index 000000000..7a6e0a264 --- /dev/null +++ b/docs/method/phase-3-ux-scenarios-guide.md @@ -0,0 +1,193 @@ +# Phase 3: UX Scenarios (Scenario Outlines) + +**Agent:** Saga the Analyst +**Output:** `C-UX-Scenarios/` (in your configured design artifacts folder) + +--- + +## What This Phase Does + +UX Scenarios transforms your Trigger Map into concrete user journeys. Through the **8-question scenario dialog**, you define each meaningful transaction a user performs on your site — starting with the most important one. + +By the end, you'll have scenario outlines that ground every design decision in real user psychology and business goals. + +--- + +## The 8-Question Scenario Dialog + +This is the core of Phase 3. For each scenario, you walk through 8 strategic questions — one at a time, as a natural conversation: + +| # | Question | What it establishes | +|---|----------|-------------------| +| Q1 | "What transaction do we need to get really right?" | The key user journey | +| Q2 | "Which business goal does it serve?" | Trigger Map connection | +| Q3 | "Which user, and in what real-life situation?" | Persona + context | +| Q4 | "What do they want and fear going into this?" | Driving forces | +| Q5 | "What device are they on?" | Platform | +| Q6 | "What's the natural starting point?" | Entry point + discovery | +| Q7 | "What's the best possible outcome — for both sides?" | Mutual success | +| Q8 | "What's the shortest path through the site?" | Linear sunshine path | + +**What counts as a transaction:** Not just purchases or bookings. Clicking through a menu item by item to research site content is a transaction. Comparing options is a transaction. Any meaningful journey where the user moves through the site with intent. + +### Two Modes + +- **Conversation mode** (default): Saga asks, you answer. One question at a time. Each answer shapes the next question naturally. +- **Suggest mode**: Saga answers all 8 questions based on the Trigger Map and Product Brief. You review and adjust. + +--- + +## The Scenario → Page Flow + +After the 8 questions define a scenario, the process continues with page outlining and design: + +```mermaid +flowchart TD + A["8-Question Scenario Dialog\nQ1-Q8 → Name → Quality Gates → Save"] --> B{"Post-Scenario Menu"} + + B -->|"[N] Next scenario"| A + B -->|"[O] Outline pages"| C["Page Outline Dialog"] + B -->|"[D] Design first page"| D["Create First Page Folder"] + B -->|"[C] Overview"| Z["Generate Scenario Overview"] + + C --> E{"For each page:"} + E --> F["1. What's the point of this page?\n2. What does the user do to move forward?"] + F --> G{"Interaction type?"} + G -->|"Leaves page"| H["New scenario step\n→ Create page folder"] + G -->|"Stays on page"| I["Storyboard item\n→ Document in page spec"] + I --> F + H --> J{"Continue?"} + J -->|"Next page"| E + J -->|"Stop"| B + + D --> K["Phase 4: Design Page\nSteps 08-15"] + + K --> L{"Page Complete Menu"} + L -->|"[N] Next page"| M["Outline → Design Loop"] + L -->|"[R] Dashboard"| N["Phase 4 Scenario Dashboard"] + L -->|"[V] Validate"| O["Audit Page Spec"] + O --> L + + M --> P["Outline next page\nPurpose + Exit Action"] + P --> Q["Create page folder"] + Q --> K +``` + +### The Page Outline Dialog + +For each page in the scenario, ask two questions: + +**1. "What's the point of this page?"** +What does the user need to accomplish here? +- e.g., "See a list of news articles" or "Find the phone number and opening hours" + +**2. "What does the user do to move forward?"** +What interaction takes them to the next step? +- e.g., "Selects 'News' in the menu" → next page is the News listing + +**Two types of interactions:** +- **Leaves the page** → new scenario step (new page folder) +- **Stays on the page** → storyboard item (documented within the page spec) + +### The Outline → Design Loop + +After designing a page in Phase 4, the user can choose [N] to outline and design the next page. This creates a continuous loop: + +1. **Outline** the next page (purpose + exit action) +2. **Create** the page folder with boilerplate spec +3. **Design** the page (Phase 4 steps 08-15) +4. **Repeat** until all pages are done + +--- + +## Page Folder Structure + +Each page gets its own folder with a spec and a Sketches subfolder: + +``` +C-UX-Scenarios/01-hasses-emergency-search/ +├── 01-hasses-emergency-search.md # Scenario outline +└── pages/ + ├── 01.1-start-page/ + │ ├── 01.1-start-page.md # Full boilerplate + │ └── Sketches/ + ├── 01.2-services/ + │ ├── 01.2-services.md # Minimal boilerplate + │ └── Sketches/ + └── 01.3-contact/ + ├── 01.3-contact.md # Minimal boilerplate + └── Sketches/ +``` + +**Naming convention:** `{scenario-number}.{step-number}-{page-slug}` + +The **first page** gets rich context from the 8-question dialog (device, arrival method, mental state, user situation). Remaining pages get minimal boilerplate with page purpose. + +--- + +## What You'll Create + +- **Scenario outlines** — one per transaction, grounded in Trigger Map personas and business goals +- **Page folders** — structured boilerplate specs ready for Phase 4 design +- **Scenario overview** — summary of all scenarios with page assignments + +--- + +## Post-Scenario Options + +After each scenario, you choose: + +| Option | What happens | +|--------|-------------| +| **[N] Next scenario** | Define the next transaction for the next target group | +| **[O] Outline pages** | Walk through pages one at a time, creating folders | +| **[D] Design first page** | Create first page folder and jump to Phase 4 | +| **[C] Continue** | Generate scenario overview (when all are done) | + +--- + +## Quality Gates + +Before moving on from a scenario, Saga verifies: + +- All 8 questions answered with specific, concrete responses +- Mental state is visceral and specific (not generic "interested") +- Entry point is realistic with device + context + discovery method +- Path is truly linear (zero "if" statements, zero branches) +- Both successes are specific and measurable +- Scenario name includes persona name +- Trigger Map connection is explicit + +--- + +## When to Use This Phase + +**Always use this phase** — it's the bridge between strategy (Phases 1-2) and design (Phase 4). Without scenarios, page design lacks context and purpose. + +**Process scenarios in priority order:** +1. Primary transaction for primary target group +2. Secondary transactions +3. Tertiary/edge case transactions + +--- + +## What to Prepare + +Bring: +- **Product Brief** (Phase 1) — strategic context +- **Trigger Map** (Phase 2) — personas, driving forces, business goals +- **Page inventory** — known pages from the Trigger Map's feature analysis + +--- + +## Connection to Phase 4 + +Phase 3 scenarios feed directly into Phase 4 design: + +- **Scenario gate**: Phase 4 checks for existing scenarios before page design. No scenario? It redirects you back to Phase 3. +- **Page handover**: The first page spec includes device, mental state, and entry context — everything Freya needs to start designing. +- **Outline → Design loop**: After designing a page, you can outline the next one and continue designing without leaving Phase 4. + +--- + +_Phase 3 of the Whiteport Design Studio method_ diff --git a/docs/method/phase-4-ux-design-guide.md b/docs/method/phase-4-ux-design-guide.md index d298e6994..ee41e0307 100644 --- a/docs/method/phase-4-ux-design-guide.md +++ b/docs/method/phase-4-ux-design-guide.md @@ -1,186 +1,165 @@ -# Phase 4: UX Design (UX-Sketches & Usage Scenarios) +# Phase 4: UX Design (Page Specifications) -**Agent:** Freya the WDS Designer -**Output:** `C-Scenarios/` (or your configured prefix) +**Agent:** Freya the Designer +**Output:** `D-UX-Design/` (or your configured prefix) --- ## What This Phase Does -UX Design transforms ideas into detailed visual specifications. Working with Freya, you conceptualize, sketch, and specify every interaction until your design can be logically explained without gaps. +UX Design transforms scenarios into detailed visual specifications. Working with Freya, 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 gaps in your thinking early - when they're easy to address. --- +## Scenario Gate + +Phase 4 requires a Phase 3 scenario before page design can begin. When you start, Freya checks for existing scenarios in `C-UX-Scenarios/`. + +- **If a scenario exists** — Freya loads the scenario context (8-question answers, shortest path, first page spec) and proceeds to design. +- **If no scenario exists** — Freya redirects you to Phase 3 to outline the scenario first. The 8-question dialog produces richer, more grounded scenarios than trying to shortcut the process. + +This ensures every page is designed with purpose — grounded in a real user journey, connected to business goals. + +--- + ## 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 Prototypes** - Interactive prototypes for validation --- -## How Freya the WDS Designer helps you design software +## Activities -### 4A: Scenario Initialization & Exploration +Phase 4 is **menu-driven**, not linear. You pick scenarios and activities from a dashboard: -**When:** Starting a new scenario - before sketching begins +``` +What would you like to do? -**The Scenario Init Process** (6 steps): +[C] Conceptualize — Explore what the design needs +[K] Analyse Sketches — I'll interpret your sketch +[S] Suggest Interface — I'll propose a design, checking each step +[D] Dream Up Interface — I'll create it all, you review +[P] Write Specifications — Detail a page specification +[W] Visual Design — Work with visual tools, integrate results +[M] Manage Design System — Define/update design system components +[V] Validate Specifications — Audit a finished spec +[H] Design Delivery — Package and hand off for development +``` -1. Feature selection - Which feature delivers value? -2. Entry point - Where does user encounter it? -3. Mental state - How are they feeling? -4. Mutual success - What's winning for both sides? -5. Shortest path - Minimum steps to success -6. **Create VTC** - Crystallize scenario strategy +### [C] Conceptualize -See: [Scenario Initialization Guide](../workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md) +**When:** Starting a new page — before sketching begins -**Value Trigger Chain for Each Scenario:** +Freya helps you think through the user's journey, explore content and feature options, consider psychological triggers from your Trigger Map, and arrive at a clear solution ready for sketching. -Each scenario gets its own [VTC](./value-trigger-chain-guide.md) that serves as strategic guidance: -- Extracted from Trigger Map (if Selection Workshop - 10-15 mins) -- Created from scratch (if Creation Workshop - 20-30 mins) +### [K] Analyse Sketches -The VTC guides every page, every interaction, every word in the scenario. +**When:** You have a sketch and need feedback -**Then Exploration:** +Freya analyzes what the sketch shows, asks clarifying questions, and identifies all components and states. -Freya helps you: -- Think through the user's journey -- Explore content and feature options -- Consider psychological triggers from your Trigger Map -- Reference the scenario's VTC for driving forces -- Arrive at a clear solution ready for sketching +### [S] Suggest Interface -### 4B: UI Sketch Analysis +**When:** You want collaborative step-by-step design -**When:** You have a sketch and you need feedback on it +Freya proposes each design decision, you confirm or adjust before moving on. Uses steps 08-15 to build the page specification incrementally. -Freya helps you: +### [D] Dream Up Interface -- Analyze what the sketch shows -- Ask clarifying questions -- Identify all components and states +**When:** You trust Freya to make good decisions -### 4C: Conceptual Specification +Freya creates a complete page specification autonomously, then presents the result for your review. Uses the same steps as Suggest but with autonomous execution. + +### [P] Write Specifications **When:** Design is clear, need development-ready specs -Freya helps you: +Document every detail systematically — Object IDs, interactions, states, content. -- Document every detail systematically -- Assign Object IDs for testing -- Define all interactions and states -- Prepare multilingual content, error codes, instructions and any other content needed for the developers +### [W] Visual Design -### 4D: HTML Prototype +**When:** Working with visual tools (Figma, design files) -**When:** Specifications complete, and we make the sketch come alive to test the concept +Work with visual design tools and integrate results back into specifications. -Freya helps you: +### [M] Manage Design System -- Create interactive prototypes -- Test the design in browser -- Discover gaps and issues -- Refine specifications -- Visualize the concept before development +**When:** Extracting or updating reusable components -**Visual Refinement (Optional):** +Define, update, or browse design system components as you design pages. -If the prototype looks functional but not visually appealing (design system incomplete): +### [V] Validate Specifications -- Freya automatically identifies components needing refinement -- Injects components to Figma via MCP server for visual polish -- Designer refines in Figma (colors, spacing, typography, states) -- Freya reads refined components back automatically -- Updates design system with new tokens and components -- Re-renders prototype with enhanced design system +**When:** Auditing a finished spec for completeness -This iterative refinement enables you to build the design system organically as you create prototypes, rather than requiring a complete design system upfront. +Check that specifications are complete, consistent, and development-ready. -**Figma Export Methods:** -- **MCP Server (Automated):** Single viewport, fully automated, no file modifications -- **Browser Extension (Manual):** Multiple viewports (mobile/tablet/desktop), requires temporary aria-label injection +### [H] Design Delivery -See: [Prepare for Figma Export](../tools/prepare-for-figma-export.md) for aria-label workflow details +**When:** Ready to hand off for development -### 4E: PRD Update +Package specifications for development handoff. -**When:** Page design is complete, before moving to the next scenario +--- -Freya helps you: +## The Outline → Design Loop -- Identify what features this page requires -- Add functional requirements to the PRD -- Reference the page (e.g., "Required by: 2.1-Dog-Calendar") -- Note any API endpoints, validations, or data needs discovered +After designing a page (via [S] Suggest or [D] Dream Up), you choose what to do next: -**Why this step matters:** - -Each page reveals concrete requirements: - -- "This form needs email validation" -- "We need a GET endpoint for availability" -- "Users need to upload images here" - -Capturing these while the page is fresh ensures nothing is forgotten. The PRD becomes a complete feature inventory with traceability to the pages that need each feature. - -**PRD grows like this:** - -```markdown -## Functional Requirements - -### Email Validation - -**Required by:** 1.2-Sign-Up, 2.3-Profile-Edit - -- Validate format on input -- Check domain exists -- Prevent duplicates - -### Availability Calendar API - -**Required by:** 2.1-Dog-Calendar, 3.1-Booking-Flow - -- GET /api/walkers/{id}/availability -- Returns 2-week window -- Updates via WebSocket ``` +Page complete! What would you like to do? + +[N] Next page — outline and design the next step in this scenario +[R] Return to Scenario Dashboard — pick a different scenario or activity +[V] Validate — audit this page specification +``` + +When you choose **[N] Next page**, the flow is: + +1. **Outline the next page** — "What's the point of this page?" and "What does the user do to move forward?" +2. **Create the page folder** with boilerplate spec and Sketches/ subfolder +3. **Design the page** — run steps 08-15 +4. **After completion** — present this menu again + +This loop continues until all pages in the scenario are designed or you choose to stop. --- ## The Scenario Structure -Scenarios organize your design work into a clear hierarchy: +Scenarios from Phase 3 organize your design work into a clear hierarchy: ``` -C-Scenarios/ -├── 00-Scenario-Overview.md -├── 01-User-Onboarding/ -│ ├── 1.1-Start-Page/ -│ │ ├── 1.1-Start-Page.md -│ │ ├── Sketches/ -│ │ └── Prototype/ -│ └── 1.2-Sign-Up/ -│ ├── 1.2-Sign-Up.md -│ └── ... -├── 02-Core-Feature/ +C-UX-Scenarios/ +├── 01-hasses-emergency-search/ +│ ├── 01-hasses-emergency-search.md # Scenario outline +│ └── pages/ +│ ├── 01.1-start-page/ +│ │ ├── 01.1-start-page.md # Page spec (full context) +│ │ └── Sketches/ +│ ├── 01.2-services/ +│ │ ├── 01.2-services.md # Page spec +│ │ └── Sketches/ +│ └── 01.3-contact/ +│ ├── 01.3-contact.md # Page spec +│ └── Sketches/ +├── 02-lisas-summer-booking/ │ └── ... ``` **Numbering Convention:** - Scenarios: 01, 02, 03... -- Pages within scenarios: 1.1, 1.2, 2.1, 2.2... +- Pages within scenarios: 01.1, 01.2, 02.1, 02.2... +- First page gets full entry context (device, mental state, arrival method) --- @@ -205,32 +184,19 @@ signin-form-error-email ### Design System Integration -**When Design System is enabled** (Phase 5), each object in your specification includes component library references: - -**Example specification entry:** +**When Design System is enabled** (Phase 7), each object in your specification includes component library references: ```markdown ### Submit Button **Object ID:** `signin-form-submit-button` **Component:** primary-button (from Design System) -**Figma Component:** Primary Button **Variant:** size=large, type=primary **State:** default Triggers form validation and submission... ``` -**Benefits:** - -- Designers know which Figma component to use -- Developers know which code component to implement -- Design System ensures consistency -- Object IDs connect spec → design → code - -**Without Design System:** -Just describe the element directly in the specification without component references. - --- ## The Pressure-Testing Process @@ -257,29 +223,14 @@ Interactive prototypes that validate your design: - 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-Start-Page/ -├── 1.1-Start-Page.md (specification) -├── Sketches/ -│ └── concept-sketch.jpg -└── Prototype/ - ├── 1.1-Start-Page-Prototype.html - ├── 1.1-Start-Page-Prototype.css - └── 1.1-Start-Page-Prototype.js -``` - --- ## When to Use This Phase @@ -287,25 +238,24 @@ Interactive prototypes that validate your design: **Use this phase when:** - Ready to design specific screens/pages -- Have strategic clarity from Phase 1-2 +- Have scenario outlines from Phase 3 - Want to validate designs before development -**Start with exploration (4A) if:** +**Start with [C] Conceptualize if:** - No existing sketches - Unsure how to approach a feature - Need to think through the user journey -**Start with analysis (4B) if:** +**Start with [K] Analyse Sketches if:** - Have sketches ready to specify - Know what you want, need to document it -**Use HTML prototypes (4D) if:** +**Start with [S] Suggest or [D] Dream Up if:** -- Specifications feel complete -- Want to validate before development -- Need stakeholder sign-off +- Have a Phase 3 scenario with page outlines +- Want Freya to help build the page specification step by step --- @@ -313,10 +263,9 @@ Interactive prototypes that validate your design: Bring: -- Trigger Map (Phase 2) - for user psychology reference +- **UX Scenarios** (Phase 3) - scenario outlines with page folders +- **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) --- @@ -324,8 +273,8 @@ Bring: Your specifications enable: -- **Phase 5: Design System** - Components extracted and documented -- **Phase 6: Dev Integration** - Complete handoff package +- **Phase 5: Agentic Development** - AI-assisted implementation +- **Phase 7: Design System** - Components extracted and documented - **Development** - Specs so clear they eliminate guesswork --- @@ -360,29 +309,18 @@ Your specifications enable: --- -## Example Output - -See: `examples/dog-week-patterns/C-Scenarios/` for complete scenario specifications from a real project. - ---- - ## Related Resources **Method Guides:** -- [Value Trigger Chain Guide](./value-trigger-chain-guide.md) - Creating VTCs for each scenario -- [Phase 2: Trigger Mapping Guide](./phase-2-trigger-mapping-guide.md) - Source for VTC extraction -- [Phase 3: PRD Platform Guide](./phase-3-prd-platform-guide.md) - Technical constraints -- [Phase 5: Design System Guide](./phase-5-design-system-guide.md) - Component extraction (parallel) +- [Phase 3: UX Scenarios Guide](./phase-3-ux-scenarios-guide.md) - Scenario outlines that drive page design +- [Phase 2: Trigger Mapping Guide](./phase-2-trigger-mapping-guide.md) - Source for user psychology +- [Value Trigger Chain Guide](./value-trigger-chain-guide.md) - VTCs for each scenario **Strategic Models:** -- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - User awareness positioning (used in VTC) +- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - User awareness positioning - [Action Mapping](../models/action-mapping.md) - User actions in scenario steps - [Kathy Sierra: Badass Users](../models/kathy-sierra-badass-users.md) - Making users feel capable -**Workflows:** -- Scenario Initialization: `workflows/4-ux-design/scenario-init/scenario-init/00-SCENARIO-INIT-GUIDE.md` -- VTC Workshop: `workflows/shared/vtc-workshop/vtc-workshop-guide.md` - --- _Phase 4 of the Whiteport Design Studio method_ diff --git a/docs/method/wds-method-guide.md b/docs/method/wds-method-guide.md index b49ea2ec3..df938ccc7 100644 --- a/docs/method/wds-method-guide.md +++ b/docs/method/wds-method-guide.md @@ -19,17 +19,16 @@ WDS creates the **design artifacts** that development teams need to build except ### The Core Idea ``` -Vision → Clarity → UX Design → Design System → PRD Complete - │ │ │ │ │ - │ │ │ │ └── Development - │ │ │ │ gets everything - │ │ │ │ - │ │ │ └── Components, - │ │ │ tokens, patterns - │ │ │ (optional, parallel) - │ │ │ - │ │ └── Sketching, specifying, - │ │ prototyping, PRD grows +Vision → Clarity → Scenarios → UX Design → Development Ready + │ │ │ │ │ + │ │ │ │ └── AI or human + │ │ │ │ development + │ │ │ │ + │ │ │ └── Sketching, specifying, + │ │ │ prototyping, specs grow + │ │ │ + │ │ └── 8-question scenario dialog, + │ │ user journeys, page outlines │ │ │ └── Trigger mapping, │ Feature Impact Analysis @@ -40,13 +39,22 @@ Vision → Clarity → UX Design → Design System → PRD Complete --- -## The Six Phases +## The Nine Phases -WDS follows six phases, each producing artifacts in your project's `docs/` folder: +WDS follows nine phases (0-8), each producing artifacts in your project's design artifacts folder: + +### Phase 0: Alignment & Signoff + +**Output:** `_alignment/` +**Agent:** Saga the Analyst + +Generate alignment presentations and signoff documents. Used when you need stakeholder buy-in before proceeding. + +--- ### Phase 1: Product Exploration (Product Brief) -**Output:** `A-Product-Brief/` +**Output:** `A-Product-Brief/` **Agent:** Saga the Analyst Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically. @@ -62,7 +70,7 @@ Establish your strategic foundation through conversational discovery. Instead of ### Phase 2: Trigger Mapping (Trigger Map) -**Output:** `B-Trigger-Map/` +**Output:** `B-Trigger-Map/` **Agent:** Saga the Analyst Connect business goals to user psychology through Trigger Mapping. Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions. @@ -78,50 +86,87 @@ Connect business goals to user psychology through Trigger Mapping. Discover not --- -### Phase 3: PRD Platform (Technical Foundation) +### Phase 3: UX Scenarios (Scenario Outlines) -**Output:** `C-Requirements/` -**Agent:** Freya the PM +**Output:** `C-UX-Scenarios/` +**Agent:** Saga the Analyst -Prove your concept works technically - in parallel with design work. Validate platform decisions, create proofs of concept, and set up experimental endpoints. +Transform your Trigger Map into concrete user journeys through the **8-question scenario dialog**. Define each meaningful transaction a user performs on your site — starting with the most important one. **What you create:** -- Platform architecture decisions -- Data model and integrations -- Technical proofs of concept -- Experimental endpoints -- Security and performance framework -- Technical constraints document (for UX Design) +- Scenario outlines grounded in Trigger Map personas and business goals +- Page folders with boilerplate specs ready for Phase 4 design +- Scenario overview summarizing all scenarios with page assignments + +**The 8-Question Dialog:** + +| # | Question | What it establishes | +|---|----------|-------------------| +| Q1 | "What transaction do we need to get really right?" | The key user journey | +| Q2 | "Which business goal does it serve?" | Trigger Map connection | +| Q3 | "Which user, and in what real-life situation?" | Persona + context | +| Q4 | "What do they want and fear going into this?" | Driving forces | +| Q5 | "What device are they on?" | Platform | +| Q6 | "What's the natural starting point?" | Entry point + discovery | +| Q7 | "What's the best possible outcome — for both sides?" | Mutual success | +| Q8 | "What's the shortest path through the site?" | Linear sunshine path | + +See: [Phase 3: UX Scenarios Guide](./phase-3-ux-scenarios-guide.md) --- -### Phase 4: UX Design (UX-Sketches & Usage Scenarios) +### Phase 4: UX Design (Page Specifications) -**Output:** `C-Scenarios/` -**Agent:** Baldr the UX Expert +**Output:** `D-UX-Design/` +**Agent:** Freya the Designer -Transform ideas into detailed visual specifications. Your agent helps you think out the design, assists in sketching, creates specifications, and builds HTML prototypes. Each page adds functional requirements to the PRD. - -**The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address. +Transform scenarios into detailed visual specifications. Freya helps you conceptualize, sketch, specify, and prototype every interaction until your design can be logically explained without gaps. **What you create:** -- Scenario folder structure (numbered hierarchy) - Page specifications with full detail - Component definitions with Object IDs - Interaction behaviors and states - HTML prototypes for validation -- Functional requirements added to PRD (via step 4E) + +**Activities:** Conceptualize, Analyse Sketches, Suggest Interface, Dream Up Interface, Write Specifications, Visual Design, Manage Design System, Validate, Design Delivery + +See: [Phase 4: UX Design Guide](./phase-4-ux-design-guide.md) --- -### Phase 5: Design System (Component Library) +### Phase 5: Agentic Development -**Output:** `D-Design-System/` -**Agent:** Baldr the UX Expert +**Output:** Development artifacts +**Agent:** Idunn the PM -Build your component library following atomic design principles. This phase is **optional** and runs **in parallel** with Phase 4 - as you design pages, you extract reusable components. +Bridge from design to development. Manage the development process with AI-assisted implementation, testing, and deployment. + +**What you create:** + +- Development tasks from design specifications +- Implementation with AI assistance +- Testing and validation +- Deployment packages + +--- + +### Phase 6: Asset Generation + +**Output:** Generated assets +**Agent:** Freya the Designer + +Generate visual assets, icons, illustrations, and other design deliverables needed for the project. + +--- + +### Phase 7: Design System (Component Library) + +**Output:** `D-Design-System/` +**Agent:** Freya the Designer + +Build your component library following atomic design principles. This phase runs **in parallel** with Phase 4 — as you design pages, you extract reusable components. **What you create:** @@ -130,30 +175,21 @@ Build your component library following atomic design principles. This phase is * - Molecular components (form groups, cards) - Organism components (headers, complex sections) - Interactive HTML component showcase -- Figma/design tool integration with unified naming --- -### Phase 6: PRD Finalization (Complete PRD) +### Phase 8: Product Evolution -**Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/` -**Agent:** Freya the PM +**Output:** Evolution artifacts +**Agent:** Idunn the PM -Compile all functional requirements discovered during Phase 4 into a complete, development-ready PRD. This phase runs **continuously** - hand off as soon as you have MVP scope, then update as design progresses. - -**What you create:** - -- Complete PRD (Platform + Functional requirements) -- Feature organization by epic/area -- Development sequence with priorities -- Handoff package in `E-UI-Roadmap/` -- Scenario-to-epic mapping +Iterate on existing products. Analyze usage, scope changes, design updates, implement, test, and deploy improvements. --- ## Folder Structure -WDS creates an organized folder structure in your project's `docs/` folder. During setup, you make two choices: +WDS creates an organized folder structure in your project's design artifacts folder. During setup, you make two choices: ### Your 4 Options @@ -167,25 +203,21 @@ WDS creates an organized folder structure in your project's `docs/` folder. Duri **Letters + Title-Case** (default): ``` -docs/ +design-artifacts/ ├── A-Product-Brief/ ├── B-Trigger-Map/ -├── C-Platform-Requirements/ -├── C-Scenarios/ -├── D-Design-System/ -└── E-PRD-Finalization/ -``` - -**Numbers + Title-Case**: - -``` -docs/ -├── 01-Product-Brief/ -├── 02-Trigger-Map/ -├── 03-Platform-Requirements/ -├── 03-Scenarios/ -├── 04-Design-System/ -└── 05-PRD-Finalization/ +├── C-UX-Scenarios/ +│ └── 01-hasses-emergency-search/ +│ ├── 01-hasses-emergency-search.md +│ └── pages/ +│ ├── 01.1-start-page/ +│ │ ├── 01.1-start-page.md +│ │ └── Sketches/ +│ └── 01.2-services/ +│ ├── 01.2-services.md +│ └── Sketches/ +├── D-UX-Design/ +└── D-Design-System/ ``` **Default (Letters + Title-Case) is recommended because:** @@ -198,16 +230,16 @@ docs/ ## Phase-Selectable Workflow -Not every project needs all six phases. Select what you need based on your situation: +Not every project needs all nine phases. Select what you need based on your situation: | Project Type | Recommended Phases | | ----------------------------- | ------------------ | -| **Landing page** | 1, 4 | -| **Full product (greenfield)** | All six | -| **Feature enhancement** | 2, 4, 6 | -| **Design system only** | 4, 5 | +| **Landing page** | 1, 3, 4 | +| **Full product (greenfield)** | All phases | +| **Feature enhancement** | 2, 3, 4 | +| **Design system only** | 4, 7 | | **Strategic planning** | 1, 2 | -| **Quick prototype** | 4 only | +| **Quick prototype** | 3, 4 | Your agents will help you identify which phases fit your project. @@ -217,38 +249,41 @@ Your agents will help you identify which phases fit your project. Three specialized agents guide you through WDS: -### Saga the 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. +Saga guides you through discovery, research, and scenario creation. She's curious, patient, and helps you uncover insights you might not have seen yourself. **Works with you on:** +- Phase 0: Alignment & Signoff - Phase 1: Product Exploration - Phase 2: Trigger Mapping +- Phase 3: UX Scenarios -### Freya the PM ⚔️ - -_"The strategic leader who sees what must be done"_ - -Freya helps you define technical requirements and finalize the PRD for development. She balances passion with strategy, knowing when to be fierce and when to be patient. - -**Works with you on:** - -- Phase 3: PRD Platform -- Phase 6: PRD Finalization - -### Baldr the UX Expert ✨ +### Freya the Designer _"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. +Freya transforms your scenarios into beautiful, detailed specifications. She cares deeply about craft and ensures every detail serves the user experience. **Works with you on:** - Phase 4: UX Design -- Phase 5: Design System +- Phase 6: Asset Generation +- Phase 7: Design System + +### Idunn the PM + +_"The keeper of what endures"_ + +Idunn manages the bridge from design to development and guides product evolution. She ensures nothing is lost in translation and that products continue to improve. + +**Works with you on:** + +- Phase 5: Agentic Development +- Phase 8: Product Evolution --- @@ -286,31 +321,23 @@ It never feels like filling out a form. ## Getting Started -### Prerequisites - -1. BMad Method installed with WDS module -2. Project workspace ready -3. Stakeholders available for workshop phases - ### Quick Start ``` -# Install BMad with WDS -npx bmad-method@alpha install +# Install WDS +npx whiteport-design-studio install -# Activate any WDS agent -# They'll guide you from there - -# Or run workflow-init for phase selection -*workflow-init +# Start a conversation with Saga +# She'll guide you from there ``` ### First Steps 1. **Start with Phase 1** if you're building something new 2. **Start with Phase 2** if you have existing vision but need user clarity -3. **Start with Phase 4** if you have sketches ready to specify -4. **Ask your agent** if you're not sure where to begin +3. **Start with Phase 3** if you have a Trigger Map and need scenario outlines +4. **Start with Phase 4** if you have scenarios ready to design +5. **Ask your agent** if you're not sure where to begin --- @@ -328,51 +355,34 @@ npx bmad-method@alpha install - Conversations that build understanding - Personas with psychological depth connected to business goals +- 8-question scenario dialog grounding every design in real user psychology - Collaborative workshops building shared understanding - Specifications so clear they eliminate guesswork - Everyone aligned because they built it together --- -## Integration with Development +## The Scenario → Design Flow -WDS focuses on **design** - creating the artifacts that guide development. The actual development process is handled by BMad Method (BMM) or your preferred development workflow. +The heart of WDS is the connection between Phase 3 (Scenarios) and Phase 4 (Design): -### The PRD Journey +1. **Phase 3** defines the scenario through 8 strategic questions +2. After completing a scenario, you choose to outline pages or jump to design +3. **Page Outline Dialog** defines each page's purpose and exit action +4. **Phase 4** designs each page with full context from the scenario +5. The **Outline → Design loop** lets you outline and design pages continuously -``` -Phase 3: PRD starts Phase 4: PRD grows Phase 6: PRD completes -(Technical Foundation) (Each page adds features) (Organized for dev) - │ │ │ - ▼ ▼ ▼ -C-Requirements/ ────► C-Requirements/ ────► E-UI-Roadmap/ -├── Platform arch ├── Platform arch ├── Priority sequence -├── Data model ├── Data model ├── Epic mapping -├── Integrations ├── Integrations ├── Component inventory -└── Security └── Functional reqs ◄──┐ └── Handoff checklist - (from each page) │ - │ - C-Scenarios/ ─────────┘ - (Page specs add features via 4E) -``` - -### Parallel Streams - -Design and development can work in parallel: - -- Phase 3 complete → Backend/platform development can start -- Phase 4 MVP scenarios complete → Phase 6 first handoff → Sprint 1 begins -- Design continues → Regular Phase 6 updates → More sprints +This ensures every page is designed with purpose — grounded in real user psychology, connected to business goals, and part of a coherent user journey. --- ## Learn More - **Phase guides:** Detailed documentation for each phase -- **Examples:** Dog Week patterns showing real artifacts +- **Examples:** Real project patterns showing complete artifacts - **Templates:** Ready-to-use templates for all deliverables - **Conversation examples:** See how agent sessions flow --- -_Whiteport Design Studio - Part of the BMad ecosystem_ +_Whiteport Design Studio_