whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-18-product-evolution/tutorial-18.md

@@ -0,0 +1,293 @@
+# Tutorial 18: Evolve Your Product
+
+**Hands-on guide to running a complete evolution cycle**
+
+---
+
+## Overview
+
+This tutorial walks you through a product evolution cycle — from receiving user feedback to closing the Design Log with a verified change.
+
+**Time:** 20-30 minutes
+**Prerequisites:** Understanding of WDS workflow (Modules 4-17)
+**Agent:** Freya
+**What you'll practice:** The complete evolution cycle using the Product Evolution Design Log
+
+---
+
+## The Change Request
+
+You've received this feedback from usability testing (Module 17):
+
+> "3 of 5 users hesitated at the password field. They didn't know the full requirements until they submitted and got an error. One user tried three times before getting it right."
+
+Your task: fix this using the evolution cycle.
+
+---
+
+## Step 1: Connect to Strategy (3 min)
+
+### Trace the feedback
+
+**You say to the agent:**
+> "We have usability feedback about password requirements. Help me connect this to our Trigger Map."
+
+**The agent analyzes:**
+> "Looking at your Trigger Map...
+>
+> Persona: Felix — values speed and efficiency
+> Driving force: 'Don't waste my time with unclear processes'
+> Business goal: Reduce signup abandonment (currently 15% drop-off at password step)
+>
+> This directly opposes Felix's core driving force. Proceed."
+
+### Apply the Whiteport Rule
+
+Is this worth showing to 5 users and 1 domain expert? Yes — the problem was found by testing with users. The fix should be verified the same way.
+
+---
+
+## Step 2: Create the Evolution Design Log (5 min)
+
+**You say:**
+> "Create a Design Log for this evolution. Type: feature modification. Context: password field requirements are hidden until error."
+
+**The agent creates:**
+
+```markdown
+# Design Log: Password Requirements Clarity
+
+## Meta
+- Date: 2026-03-15
+- Type: Feature modification
+- Input: Usability test findings (Round 1)
+- Agent: Freya
+- Branch: fix/password-requirements
+- Status: In Progress
+
+## Context
+Current: Password field shows "At least 8 characters" as helper text.
+Full requirements (8+ chars, 1 number, 1 letter) only appear as error
+messages after submission.
+
+Problem: Users don't know requirements until they fail. 3/5 users
+hesitated. 1 user needed 3 attempts.
+
+Trigger Map: Felix — efficiency driving force.
+Business: 15% drop-off at password step.
+
+## Scope
+Change: Show full requirements upfront before user types.
+Keep: Strength indicator, blur validation, error styling.
+Don't touch: Email field, form layout, submission flow.
+
+## Tasks
+1. [ ] Review current spec P02-signup-form.md
+2. [ ] Update spec with new requirements display
+3. [ ] Implement the change
+4. [ ] Verify with Puppeteer
+5. [ ] Verify unchanged functionality
+6. [ ] Quick guerrilla test
+7. [ ] Close dialog
+
+## Requirements
+- Must not change form layout or other fields
+- Requirements text must be clear without jargon
+- Must maintain WCAG AA compliance
+- Spec updated before implementation
+
+## Test Protocol
+- [ ] Helper text shows full requirements
+- [ ] Requirements visible before user types
+- [ ] Blur validation still triggers correctly
+- [ ] Error messages still appear on invalid input
+- [ ] Strength indicator still works
+- [ ] Email field unchanged
+- [ ] Touch targets maintained
+```
+
+**Review the dialog.** Does it cover everything? Adjust before proceeding.
+
+---
+
+## Step 3: Review and Update Spec (5 min)
+
+### Read current specification
+
+**The agent reads P02-signup-form.md:**
+> "Current password field spec:
+> - Label: 'Password'
+> - Helper text: 'At least 8 characters'
+> - Validation: On blur — 8+ chars, 1 number, 1 letter
+> - Error: 'Password must be at least 8 characters with a number and letter'
+> - Strength indicator: Appears on typing"
+
+### Update the specification
+
+**You say:**
+> "Update the spec: helper text should read '8+ characters, including a number and letter'. Requirements visible at all times, not just on error. Add changelog entry."
+
+**The agent updates P02-signup-form.md:**
+
+```markdown
+#### Password Field (v1.2)
+- Label: "Password"
+- Helper text: "8+ characters, including a number and letter"
+- Requirements: Shown below field at all times
+- Validation: On blur — check 8+ chars, 1 number, 1 letter
+- Error: Red border + "Password must be at least 8 characters
+  with a number and letter"
+- Strength indicator: Appears on typing
+```
+
+```markdown
+### Changelog
+#### v1.2 (2026-03-15)
+- Changed: Password helper text shows full requirements upfront
+- Reason: Usability testing — 3/5 users confused by hidden requirements
+- Connection: Felix — efficiency driving force
+```
+
+**The agent logs:**
+> "Tasks 1 and 2 complete. Spec updated to v1.2."
+
+---
+
+## Step 4: Implement and Verify (5 min)
+
+### Build the change
+
+**You say:**
+> "Implement the spec change. Then verify with Puppeteer."
+
+**The agent builds:**
+> "Updating password field component..."
+> "Helper text changed from 'At least 8 characters' to '8+ characters, including a number and letter'..."
+> "Requirements now render on page load instead of on error..."
+
+### Agent verifies with Puppeteer
+
+> "Opening signup form at localhost:3000/signup..."
+> "Helper text: '8+ characters, including a number and letter' — matches spec v1.2. ✓"
+> "Requirements visible before typing — confirmed. ✓"
+> "Entering 'short', blurring... error message appears. ✓"
+> "Entering valid password... strength indicator appears. ✓"
+> "Checking email field... unchanged. ✓"
+> "Touch target on submit button: 48px. ✓"
+> "6 of 6 criteria pass."
+
+**You evaluate:** Does it look right? Does the helper text feel clear? Is the visual hierarchy maintained?
+
+---
+
+## Step 5: Quick Usability Check (5 min)
+
+### Guerrilla test
+
+Grab someone nearby. Don't explain anything. Just say:
+
+> "Can you create an account on this?"
+
+Watch what happens at the password field. Do they hesitate? Do they read the requirements? Do they get it right the first time?
+
+**Result:**
+> User entered password on first attempt without hesitation. Read the requirements text, typed a valid password. Done.
+
+Compare to the original finding: 3 of 5 hesitated, 1 needed 3 attempts.
+
+One guerrilla test isn't statistically significant — but combined with the original finding, it confirms the direction is right.
+
+---
+
+## Step 6: Close the Dialog (3 min)
+
+### Commit and document
+
+**The agent commits:**
+> "Show password requirements upfront per spec v1.2"
+
+**Close the Design Log:**
+
+```markdown
+## Meta
+- Status: Complete
+
+## Summary
+Updated password field to show requirements upfront.
+Spec updated to v1.2. Puppeteer verified 6/6 criteria.
+Guerrilla test confirmed improvement.
+
+## Log
+### Step 1: Review spec (completed)
+- Read P02-signup-form.md v1.1
+- Identified: requirements hidden until error
+
+### Step 2: Update spec (completed)
+- Helper text: "8+ characters, including a number and letter"
+- Requirements visible at all times
+- Changelog entry added with reason and connection
+
+### Step 3: Implement (completed)
+- Updated helper text component
+- Requirements render on page load
+- Commit: "Show password requirements upfront per spec v1.2"
+
+### Step 4: Verify (completed)
+- Puppeteer: 6/6 criteria pass
+- Helper text matches, requirements visible, validation works,
+  strength indicator works, email field unchanged
+
+### Step 5: Test (completed)
+- Guerrilla test: user completed password on first attempt
+- Original problem: 3/5 hesitated, 1 needed 3 attempts
+```
+
+---
+
+## What You've Practiced
+
+The complete evolution cycle:
+
+1. **Connected** feedback to Trigger Map and business goal
+2. **Created** an Evolution Design Log with context
+3. **Updated** the specification before touching code
+4. **Built** from the updated spec
+5. **Verified** with Puppeteer during development
+6. **Tested** with a quick guerrilla session
+7. **Documented** everything in the Design Log
+
+Same WDS process. Smaller scope. Full discipline.
+
+---
+
+## You've Completed the WDS Course!
+
+**Congratulations.** You've learned the full methodology:
+
+1. **Strategy** — Product Brief, Trigger Map, Platform Requirements
+2. **Design** — Scenarios, Sketches, Storyboards, Specifications, Components, Design System
+3. **Build** — Agentic Development, Visual Design, Design Delivery
+4. **Validate** — Usability Testing
+5. **Evolve** — Product Evolution
+
+Whether you're starting from a blank page or improving a live product, the process is the same. The scope changes. The discipline doesn't.
+
+**You are the linchpin.**
+
+---
+
+## What's Next?
+
+- **Apply to a real project** — The only way to truly learn is to do
+- **Join the community** — [Discord](https://discord.gg/whiteport)
+- **Contribute** — WDS is open source
+- **Teach others** — Spread creative discipline
+
+---
+
+**[← Back to Lesson 2](lesson-02-update-spec-project-code.md)** | **[← Back to Module Overview](module-18-product-evolution-overview.md)** | **[Back to Course Overview](../00-course-overview/00-course-overview.md)**
+
+---
+
+*Created by Mårten Angner and the Whiteport team*
+*Part of Module 18: Product Evolution*

package/docs/learn/widgets/W01-task-list.md

@@ -0,0 +1,31 @@
+# Widget W01: Task List
+
+**Example widget specification for the WDS course**
+
+---
+
+## Coming Soon
+
+This is an example widget specification referenced from [Module 11: Conceptual Specifications](../module-11-conceptual-specifications/lesson-02-section-widget-specifications.md). It will demonstrate a complete widget specification for a task list component.
+
+---
+
+## Widget Overview
+
+| Property | Value |
+|----------|-------|
+| **ID** | W01 |
+| **Name** | Task List Widget |
+| **Type** | Interactive List |
+| **Context** | Dashboard Section |
+
+## Functionality
+
+- Displays user's assigned tasks
+- Allows status updates (tap to toggle)
+- Supports filtering by status and date
+- Infinite scroll with loading indicator
+
+---
+
+*This is a teaching example for the WDS course.*

package/docs/learn/widgets/W02-calendar.md

@@ -0,0 +1,31 @@
+# Widget W02: Calendar
+
+**Example widget specification for the WDS course**
+
+---
+
+## Coming Soon
+
+This is an example widget specification referenced from [Module 11: Conceptual Specifications](../module-11-conceptual-specifications/lesson-02-section-widget-specifications.md). It will demonstrate a complete widget specification for a calendar component.
+
+---
+
+## Widget Overview
+
+| Property | Value |
+|----------|-------|
+| **ID** | W02 |
+| **Name** | Calendar Widget |
+| **Type** | Interactive Calendar |
+| **Context** | Dashboard Section |
+
+## Functionality
+
+- Shows weekly view by default
+- Displays scheduled tasks and events
+- Allows drag-to-reschedule interactions
+- Supports day, week, and month views
+
+---
+
+*This is a teaching example for the WDS course.*

package/docs/learn/widgets/W02-product-card.md

@@ -0,0 +1,31 @@
+# Widget W02: Product Card
+
+**Example widget specification for the WDS course**
+
+---
+
+## Coming Soon
+
+This is an example widget specification referenced from [Module 11: Conceptual Specifications](../module-11-conceptual-specifications/lesson-02-section-widget-specifications.md). It will demonstrate a complete widget specification for a product card component.
+
+---
+
+## Widget Overview
+
+| Property | Value |
+|----------|-------|
+| **ID** | W03 |
+| **Name** | Product Card Widget |
+| **Type** | Template Card |
+| **Context** | Product Grid Section |
+
+## Functionality
+
+- Template rendered N times from product data
+- Adapts to container width (responsive)
+- Shows product image, title, price, and action button
+- Hover state reveals additional details
+
+---
+
+*This is a teaching example for the WDS course.*

package/docs/learn/widgets/W03-quick-add.md

@@ -0,0 +1,31 @@
+# Widget W03: Quick Add
+
+**Example widget specification for the WDS course**
+
+---
+
+## Coming Soon
+
+This is an example widget specification referenced from [Module 11: Conceptual Specifications](../module-11-conceptual-specifications/lesson-02-section-widget-specifications.md). It will demonstrate a complete widget specification for a quick-add component.
+
+---
+
+## Widget Overview
+
+| Property | Value |
+|----------|-------|
+| **ID** | W04 |
+| **Name** | Quick Add Widget |
+| **Type** | Floating Action |
+| **Context** | Global Overlay |
+
+## Functionality
+
+- Floating action button (bottom-right)
+- Opens task creation modal on tap
+- Persists across page scroll
+- Accessible via keyboard shortcut
+
+---
+
+*This is a teaching example for the WDS course.*

package/docs/method/content-creation-philosophy.md

@@ -81,7 +81,7 @@ Strategic content considers:
 - **Action Mapping:** What action must this enable?
 - **Badass Users:** How does this make them feel capable?
 - **Golden Circle:** What's the persuasive sequence (WHY-HOW-WHAT)?
-- **VTC:** What business goal and user psychology does this serve?
+- **Trigger Map:** What business goal and user psychology does this serve?
 
 Quick generation misses these dimensions.
 
@@ -104,7 +104,7 @@ The workshop codifies strategic thinking:
 
 **What it does:**
 1. Defines content purpose (what job must this do?)
-2. Loads strategic context (VTC, awareness, users)
+2. Loads strategic context (Trigger Map, awareness, users)
 3. Applies relevant models (CAC, Action Mapping, Badass Users, Golden Circle)
 4. Generates options with reasoning
 5. Enables informed selection
@@ -294,7 +294,7 @@ Which resonates with your brand voice?"
 **WDS Method Guides:**
 - [Content Purpose Guide](content-purpose-guide.md) - How to define what content must do
 - [Tone of Voice Guide](tone-of-voice-guide.md) - For UI microcopy consistency
-- [Value Trigger Chain Guide](value-trigger-chain-guide.md) - Strategic context for content
+- [Trigger Mapping Guide](phase-2-trigger-mapping-guide.md) - Strategic context for content
 
 **Strategic Models:**
 - [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - What language users understand

package/docs/method/content-purpose-guide.md

@@ -178,7 +178,7 @@ Different purposes emphasize different strategic models:
 ### Purpose: "Inspire users with our mission"
 **Model Priorities:**
 - Golden Circle ⭐⭐⭐ (WHY story)
-- VTC ⭐⭐ (Who we serve)
+- Trigger Map ⭐⭐ (Who we serve)
 - Customer Awareness ⭐ (Meet their level)
 - Action Mapping ⭐ (Soft)
 
@@ -196,7 +196,7 @@ Different purposes emphasize different strategic models:
 - Golden Circle (WHY)
 - Badass Users (Transform)
 - Action Mapping (Enable)
-- VTC (Context)
+- Trigger Map (Context)
 
 ---
 
@@ -238,7 +238,7 @@ Different purposes emphasize different strategic models:
 
 **Purpose:** "Convince value-conscious users that longer shelf life saves them money"
 
-**Model Priorities:** VTC ⭐⭐⭐ (fear of waste), Badass Users ⭐⭐
+**Model Priorities:** Trigger Map ⭐⭐⭐ (fear of waste), Badass Users ⭐⭐
 
 **Content:** "Stop throwing away spoiled product. Our 90-day shelf life (3x longer than competitors) means you'll use what you buy. No more waste. No more emergency reorders."
 
@@ -425,7 +425,7 @@ When reviewing content, ask:
 - [Kathy Sierra Badass Users](../models/kathy-sierra-badass-users.md) - Empowerment framing
 
 **Whiteport Methods:**
-- [Value Trigger Chain](value-trigger-chain-guide.md) - Strategic context for content
+- [Trigger Mapping Guide](phase-2-trigger-mapping-guide.md) - Strategic context for content
 
 **Workflows:**
 - [Content Creation Workshop](../src/workflows/shared/content-creation-workshop/content-creation-workshop-guide.md) - Using purpose in content generation

package/docs/method/phase-1-product-exploration-guide.md

@@ -23,15 +23,42 @@ Your Product Brief includes:
 - **Solution Approach** - The "how" that enables development
 - **Success Criteria** - The "what" that measures progress
 - **Market Positioning** - How you're different (optional: ICP framework)
-- **Value Trigger Chain (VTC)** - Strategic benchmark created after vision and positioning
 
-**The VTC (Step 4):**
+Phase 1 captures a casual, conversational understanding of the business — who the users are, what the goals are, what the product should do. The deep strategic analysis (personas, driving forces, prioritization) happens in Phase 2: Trigger Mapping.
 
-After capturing your vision and positioning, you'll create a [Value Trigger Chain](./value-trigger-chain-guide.md) - a strategic summary that serves as a benchmark for all subsequent discovery work. It captures:
+---
+
+## Workflow Structure
+
+Phase 1 follows a linear path through four document modules, with an optional simplified mode:
+
+```mermaid
+flowchart TD
+    START(["Phase 1: Product Exploration"]) --> MODE{Brief level?}
+
+    MODE -->|Simplified| SIMPLE["Simplified Brief\nSingle-step quick capture"]
+    MODE -->|Complete| VISION["Vision & Positioning\nSteps 01-03"]
+
+    SIMPLE --> DONE([Phase complete])
+
+    VISION --> BRIEF["Product Brief\nBusiness model, users,\nsuccess criteria, constraints\nSteps 05-12"]
+    BRIEF --> CONTENT["Content & Language\nPersonality, tone, SEO,\ncontent structure\nSteps 13-18"]
+    CONTENT --> VISUAL["Visual Direction\nInspiration, brand, style,\nlayout, imagery\nSteps 19-26"]
+    VISUAL --> PLATFORM["Platform Requirements\nTech stack, integrations,\ncontact strategy, multilingual\nSteps 27-32"]
+    PLATFORM --> SUMMARY["Summary & Activation\nAnalyze, summarize,\nupdate design log\nSteps 33-36"]
+    SUMMARY --> PHASE2(["→ Phase 2: Trigger Mapping"])
+
+    START -.->|"validate / -v"| VALIDATE["Validation Mode\nBrief completeness\n→ SEO → Content → Visual → Platform"]
+    VALIDATE -.-> REPORT["Validation Report"]
+```
 
-- Business Goal → Solution → User → Driving Forces → Customer Awareness
+**Four document modules** — each produces its own output file:
+1. **Product Brief** — vision, business model, users, success criteria
+2. **Content & Language** — personality, tone, SEO keywords, structure
+3. **Visual Direction** — brand, style references, layout, imagery
+4. **Platform Requirements** — tech stack, integrations, multilingual
 
-This early VTC ensures all remaining discovery (business model, success criteria, etc.) aligns with your core strategy. If anything contradicts the VTC during discovery, either the VTC needs refinement or the discovery finding doesn't serve your strategy.
+Phase 1 captures casual business context. Deep strategic analysis (personas, driving forces) is done in Phase 2: Trigger Mapping.
 
 ---
 
@@ -121,8 +148,8 @@ You don't need polished answers. The conversation will help clarify everything.
 
 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 2: Trigger Mapping** - Deep user psychology (personas, driving forces, prioritization)
+- **Phase 3: UX Scenarios** - User journeys grounded in your vision
 - **Phase 4: UX Design** - Design work grounded in strategic purpose
 
 The brief becomes the reference point everyone shares.
@@ -162,11 +189,11 @@ See: `examples/dog-week-patterns/A-Product-Brief/` for a complete Product Brief
 ## Related Resources
 
 **Method Guides:**
-- [Value Trigger Chain Guide](./value-trigger-chain-guide.md) - Creating your strategic benchmark (Step 4)
 - [Phase 2: Trigger Mapping Guide](./phase-2-trigger-mapping-guide.md) - Deep user psychology (next phase)
+- [Phase 3: UX Scenarios Guide](./phase-3-ux-scenarios-guide.md) - User journeys from Trigger Map
 
 **Strategic Models:**
-- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - Understanding user awareness stages (used in VTC)
+- [Customer Awareness Cycle](../models/customer-awareness-cycle.md) - Understanding user awareness stages
 - [Golden Circle](../models/golden-circle.md) - WHY, HOW, WHAT framework (useful for vision)
 
 **Workflows:**

package/docs/method/phase-2-trigger-mapping-guide.md

@@ -120,6 +120,48 @@ When all levels are prioritized, you have perfect guidance for design:
 
 ---
 
+## Workflow Structure
+
+Phase 2 has two entry routes — from scratch or from existing documentation — that merge into the same main flow:
+
+```mermaid
+flowchart TD
+    START(["Phase 2: Trigger Mapping"]) --> ENTRY{Entry route?}
+
+    ENTRY -->|"From scratch"| OVERVIEW["Overview & Setup\nStep 01"]
+    ENTRY -->|"From existing docs"| SYNTH["Documentation Synthesis\nExtract goals, groups,\ndriving forces, priorities\nSteps 00a-00f"]
+    SYNTH --> OVERVIEW
+
+    OVERVIEW --> GOALS["Business Goals\nVision + SMART objectives\nStep 02"]
+    GOALS --> GROUPS["Target Groups\nWho needs to succeed?\nStep 03"]
+    GROUPS --> FORCES["Driving Forces\nPositive + negative triggers\nStep 04"]
+    FORCES --> PRIORITY["Prioritization\nRank goals, groups, forces\nStep 05"]
+
+    PRIORITY --> FIA["Feature Impact Analysis\nExtract features → assess impact\n→ score → generate document\nSteps 06a-06e"]
+
+    FIA --> GENERATE["Generate Trigger Map\nHub document + personas\n+ key insights + quality check\nSteps 07a-07g"]
+
+    GENERATE --> MERMAID["Mermaid Diagram\nBuild visual map incrementally\nGoals → platform → groups\n→ forces → connections → styling\nSteps 08a-08h"]
+
+    MERMAID --> FINALIZE["Finalize & Deliver\nHub doc + cross-references\n+ quality check + handover\nSteps 09a-09f"]
+
+    FINALIZE --> PHASE3(["→ Phase 3: UX Scenarios"])
+
+    START -.->|"validate / -v"| VALIDATE["Validation Mode\nTarget groups → prioritization\n→ personas → feature alignment\n→ cross-document coherence"]
+    VALIDATE -.-> REPORT["Validation Report"]
+```
+
+**Two entry routes:**
+- **From scratch** — full conversational discovery through all stages
+- **From existing documentation** — synthesize existing docs first, then fill gaps through the same stages
+
+**Key outputs:**
+- `trigger-map.md` — hub document with Mermaid diagram
+- Persona files for each target group
+- `feature-impact-analysis.md` — scored feature list
+
+---
+
 ## How It Works
 
 ### Stage 1: Business Goals (15-20 minutes)
@@ -345,7 +387,7 @@ Bring:
 
 Your Trigger Map enables:
 
-- **Phase 3: Requirements** - Technical decisions aligned with user priorities
+- **Phase 3: UX Scenarios** - User journeys grounded in personas and driving forces
 - **Phase 4: UX Design** - Design work grounded in user psychology
 - **Development priorities** - Clear guidance on what to build first
 
@@ -383,8 +425,8 @@ See: `examples/dog-week-patterns/B-Trigger-Map/` for a complete Trigger Map with
 ## Related Resources
 
 **Method Guides:**
-- [Value Trigger Chain Guide](./value-trigger-chain-guide.md) - Extracting VTCs from Trigger Map
 - [Phase 1: Product Exploration](./phase-1-product-exploration-guide.md) - Strategic foundation (prerequisite)
+- [Phase 3: UX Scenarios Guide](./phase-3-ux-scenarios-guide.md) - User journeys from Trigger Map
 - [Phase 4: UX Design Guide](./phase-4-ux-design-guide.md) - Using Trigger Map in scenarios
 
 **Foundational Models:**