whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-17-usability-testing/tutorial-17.md

@@ -0,0 +1,301 @@
+# Tutorial 17: Plan Your Usability Test
+
+**Hands-on guide to preparing and running a usability test session**
+
+---
+
+## Overview
+
+This tutorial walks you through planning a usability test for one of your flows. You'll define tasks, recruit participants, run a session, and document findings.
+
+**Time:** 30 minutes for planning, 20 minutes per test session
+**Prerequisites:** A working prototype (Module 14) or delivered implementation (Module 16)
+**Agent:** Freya
+**What you'll create:** Test plan, observation notes, and findings document
+
+---
+
+## Before You Start
+
+**You'll need:**
+
+- A working prototype or implementation of one flow
+- Access to 1-3 people who roughly match your personas
+- A way to record (phone camera, screen recording, or video call)
+
+**Freya will help you:**
+
+- Define good test tasks
+- Prepare the session structure
+- Analyze findings afterward
+- Connect findings to specs and trigger maps
+
+---
+
+## Step 1: Choose the Flow (5 min)
+
+Pick one flow to test. Not the whole product — one flow.
+
+**Good choices:**
+- The primary user journey (signup, onboarding, first action)
+- A flow you're uncertain about
+- A flow with many interaction steps
+
+**You say to Freya:**
+> "I want to plan a usability test for the user registration flow. Help me define test tasks."
+
+**Freya responds:**
+> "Good choice — registration is the first impression. Let's define tasks that test the complete journey without leading the participant."
+
+---
+
+## Step 2: Define Tasks (5 min)
+
+Write 3-5 tasks. Each task should:
+- Describe a goal, not a path
+- Be something a real user would actually need to do
+- Be completable in 2-5 minutes
+
+**Freya suggests:**
+
+```markdown
+## Test Tasks: User Registration Flow
+
+### Task 1: Create an account
+"You've heard about [product name] and want to try it.
+Go ahead and create an account."
+
+### Task 2: Understand what you signed up for
+"You just created your account. What can you do now?
+Take a look around."
+
+### Task 3: Find your account settings
+"You want to change your email notification preferences.
+See if you can find where to do that."
+```
+
+**Review the tasks.** Are they realistic? Do they avoid leading the user? Adjust if needed.
+
+---
+
+## Step 3: Prepare the Session (5 min)
+
+### Create a session template:
+
+```markdown
+# Usability Test Session
+
+## Flow: User Registration
+## Date: [Date]
+## Participant: [Name or P1, P2, etc.]
+## Location: [Their home / office / remote]
+## Recording: [Yes/No, method]
+
+## Introduction Script
+"Thanks for helping me test this. I'm testing the design,
+not you — there are no wrong answers. Please think out loud
+as you go. I won't be able to help during the tasks."
+
+## Tasks
+1. Create an account
+2. Understand what you signed up for
+3. Find account settings
+
+## Observation Notes
+[To be filled during session]
+
+## Post-Session Questions
+- What stood out to you?
+- Was anything confusing or unexpected?
+- If you could change one thing, what would it be?
+```
+
+### Recruit participants:
+
+Send a message to 3-5 people:
+
+> "Hi! I'm working on a product and would love 20 minutes of your time to try it out. No preparation needed — just use it and tell me what you think. Available this week?"
+
+---
+
+## Step 4: Run the Session (20 min per participant)
+
+### Start recording.
+
+### Read the introduction script.
+
+### Give Task 1. Observe silently.
+
+Take notes:
+
+```markdown
+## Observation Notes — P1
+
+### Task 1: Create an account
+- 0:00 — Looks at the page, scrolls down
+- 0:12 — Scrolls back up, looking for something
+- 0:18 — "Where do I sign up?"
+- 0:23 — Finds button, clicks it
+- 0:35 — Fills in email quickly
+- 0:42 — Pauses at password field, reads helper text
+- 0:55 — Submits form
+- 1:02 — "Oh, it worked. That was easy."
+- Completed: Yes
+- Time: 1:02
+- Issues: Didn't see CTA immediately (18 seconds searching)
+```
+
+### Give Task 2. Observe.
+
+### Give Task 3. Observe.
+
+### Ask post-session questions. Note answers.
+
+### Stop recording. Thank them.
+
+---
+
+## Step 5: Review and Analyze (15 min)
+
+### Watch the recording
+
+After all sessions are done, review the recordings. Look for patterns.
+
+**You say to Freya:**
+> "I tested the registration flow with 3 participants. Here are my observation notes. Help me identify patterns and create findings."
+
+### Freya analyzes:
+
+> "Pattern 1: All three participants took 15-20 seconds to find the registration button. This is a critical visibility issue — the CTA is below the fold."
+
+> "Pattern 2: Two participants hesitated at the password field. They weren't sure about the requirements. The helper text says '8+ characters' but they expected to see the full requirements before typing."
+
+> "Participant 3 completed everything smoothly — they match the tech-savvy persona. The issues appear persona-specific: less tech-comfortable users struggled more."
+
+---
+
+## Step 6: Document Findings (10 min)
+
+### Create the findings document:
+
+```markdown
+# Usability Findings: User Registration Flow
+## Test Date: 2026-02-15
+## Participants: 3
+## Method: Contextual think-aloud
+
+## Finding 1: Registration CTA not visible
+**Severity:** Critical
+**Observed in:** 3 of 3 participants
+**Task:** Create an account
+**Timestamps:** P1 0:18, P2 0:22, P3 0:08
+
+### What happened
+All participants scrolled or searched before finding the
+registration button. Average time to find: 16 seconds.
+
+### Root cause
+P01 landing page: CTA is below the hero image.
+Visual hierarchy prioritizes imagery over action.
+
+### Recommendation
+Move CTA into hero section. Update spec P01 section 3.
+
+---
+
+## Finding 2: Password requirements unclear
+**Severity:** Major
+**Observed in:** 2 of 3 participants
+**Task:** Create an account
+**Timestamps:** P1 0:42, P2 0:38
+
+### What happened
+Users paused at password field. Helper text says "8+ characters"
+but users expected to see full requirements (uppercase, number, etc.)
+before typing.
+
+### Root cause
+P02 signup form: Helper text is minimal. Requirements only
+appear as error messages after the user types a password
+that doesn't meet them.
+
+### Recommendation
+Show full password requirements below the field from the start.
+Update spec P02 section 4.
+
+---
+
+## Summary
+- 1 critical finding (CTA visibility)
+- 1 major finding (password clarity)
+- 0 minor findings
+- Next step: Update specs, rebuild, test again
+```
+
+---
+
+## Step 7: Update Specs and Plan Next Round (5 min)
+
+### Update specifications:
+
+Based on findings, update the relevant page specs. Document what changed and why.
+
+### Plan the next test:
+
+> "After rebuilding with these changes, I'll test again with 3 new participants to verify the fixes work."
+
+---
+
+## What You've Created
+
+- **Test plan** with defined tasks and session structure
+- **Observation notes** from real user sessions
+- **Findings document** with severity, evidence, and recommendations
+- **Spec updates** based on evidence, not opinion
+- **Plan for next round** of testing
+
+---
+
+## Tips for Success
+
+**DO:**
+
+- Test on the user's own device in their own environment
+- Record every session
+- Observe silently during tasks
+- Process findings the same day
+- Connect findings to specs and personas
+
+**DON'T:**
+
+- Help the user when they struggle
+- Test with people who've seen the design before
+- Skip the recording
+- Wait a week to process findings (you'll forget details)
+- Change the design based on one user's opinion
+
+---
+
+## You've Completed Module 17!
+
+**You can now plan and run usability tests.** You've learned to:
+- Define tasks that reveal real usability issues
+- Observe without guiding
+- Record and review sessions
+- Document findings with evidence
+- Connect findings back to specifications
+- Plan iterative test rounds
+
+---
+
+## Next Module
+
+**[Module 18: Product Evolution →](../module-18-product-evolution/module-18-product-evolution-overview.md)**
+
+Products don't end at launch. Learn how to evolve them.
+
+---
+
+[← Back to Lesson 3](lesson-03-acting-on-findings.md) | [Back to Module Overview](module-17-usability-testing-overview.md)
+
+*Part of Module 17: Usability Testing*

package/docs/learn/module-18-product-evolution/lesson-01-continuous-improvement.md

@@ -0,0 +1,255 @@
+# Module 18: Product Evolution
+
+## Lesson 1: The Evolution Cycle
+
+**Running WDS in miniature for every change**
+
+---
+
+## One Change, Full Discipline
+
+A product evolution change — whether it's a new feature, a modification, a fix, or an optimization — follows the same WDS process you've learned throughout this course. The difference is scope. Instead of building a whole product, you're improving one part of it.
+
+The Product Evolution Design Log organizes this cycle. It's the same Design Log from Module 14, with one addition: **context** — what exists today and why it needs to change.
+
+---
+
+## Step 1: Receive and Connect
+
+### Something triggers the change
+
+Changes come from:
+- **User feedback** — "The password requirements aren't clear"
+- **Usability testing** — "3 of 5 users couldn't find the settings page"
+- **Analytics** — "40% drop-off at step 2 of checkout"
+- **Business need** — "We need to support a new payment method"
+- **Bug report** — "Error message shows wrong text on mobile"
+
+### Connect to the Trigger Map
+
+Before doing anything else, trace the change to your strategy:
+
+- **Which persona** does this serve?
+- **Which driving force** does it address?
+- **Which business goal** does it advance?
+
+If it doesn't connect, apply the Whiteport Rule: if it's not worth showing to 5 users and 1 domain expert, it shouldn't be built.
+
+> Change: "Users report password requirements unclear"
+> Persona: Felix — wants quick, frictionless onboarding
+> Driving force: Efficiency — don't waste my time
+> Business goal: Reduce signup abandonment
+
+Connected. Proceed.
+
+---
+
+## Step 2: Start the Design Log
+
+Create the dialog with context about what exists and what needs to change:
+
+```markdown
+# Design Log: Password Requirements Clarity
+
+## Meta
+- Date: 2026-03-15
+- Type: Feature modification
+- Input: User feedback + usability test findings
+- Agent: Freya
+- Branch: fix/password-requirements
+- Status: In Progress
+
+## Context
+Current state: Password field shows "At least 8 characters" as helper
+text. Full requirements only appear as error messages after the user
+submits a password that doesn't meet them.
+
+Problem: Users don't know the requirements until they fail.
+3 of 5 usability test participants hesitated at the password field.
+
+Trigger Map: Felix — efficiency driving force.
+Business: Signup funnel shows 15% drop-off at password step.
+
+## Scope
+Change: Show password requirements upfront, before the user types.
+Keep: Password strength indicator, validation behavior.
+Don't touch: Other form fields, submission flow.
+```
+
+The context section is what makes evolution dialogs different from greenfield. You're not starting from nothing — you're describing what's there and what needs to be different.
+
+---
+
+## Step 3: Review and Update the Specification
+
+### Read the current spec
+
+Before changing anything, read the existing specification for the affected page or flow. Understand what was designed and why.
+
+> "Current spec P02-signup-form.md says:
+> Password field helper text: 'At least 8 characters'
+> Validation: On blur, check 8+ chars, 1 number, 1 letter
+> Error: 'Password must be at least 8 characters with a number and letter'"
+
+### Update the specification
+
+Make the change in the spec first. The spec is the source of truth.
+
+```markdown
+#### Password Field (updated v1.2)
+- Helper text: "8+ characters, including a number and letter"
+- Requirements: Shown below field at all times (not just on error)
+- Validation: On blur (unchanged)
+- Strength indicator: Appears on typing (unchanged)
+```
+
+### Add to the changelog
+
+```markdown
+### v1.2 (2026-03-15)
+- Changed: Password helper text shows full requirements upfront
+- Reason: User feedback — 3/5 users confused by hidden requirements
+- Connection: Felix — efficiency driving force
+```
+
+---
+
+## Step 4: Build the Change
+
+The agent implements from the updated spec — exactly as in Module 14.
+
+### Tasks in the Design Log:
+
+```markdown
+## Tasks
+1. [x] Review current specification
+2. [x] Update specification with change
+3. [ ] Implement helper text update
+4. [ ] Agent verifies against updated spec (Puppeteer)
+5. [ ] Verify unchanged functionality still works
+6. [ ] Update design system if needed
+```
+
+### The agent builds and verifies:
+
+> "Updating password field helper text..."
+> "Opening signup form at localhost:3000/signup..."
+> "Helper text reads '8+ characters, including a number and letter' — matches updated spec. ✓"
+> "Requirements visible before typing — confirmed. ✓"
+> "Entering short password, blurring... error message appears correctly. ✓"
+> "Strength indicator still functions on typing. ✓"
+> "Email field unchanged — verified. ✓"
+
+Build, verify, evaluate — same loop, smaller scope.
+
+---
+
+## Step 5: Test
+
+### Functional testing
+
+The agent verifies with Puppeteer during development (Module 14). By the time you finish building, functional testing is already done.
+
+### Usability testing
+
+Apply the Whiteport Rule. Is this change worth showing to 5 users?
+
+For a password requirements update — probably yes, because the original problem came from usability testing. You want to verify the fix actually works. But you might run a quick guerrilla test instead of a full session.
+
+For a color fix or typo correction — probably no. Functional verification is enough.
+
+---
+
+## Step 6: Deliver and Document
+
+### Create the delivery
+
+For changes that go through development review, create a DD (Module 16). For small changes you implement yourself, document in the Design Log.
+
+### Close the dialog
+
+```markdown
+## Meta
+- Status: Complete
+
+## Summary
+Updated password field to show requirements upfront.
+Spec updated to v1.2. All tests passing.
+One guerrilla test confirmed improvement.
+
+## Log
+### Step 1: Review spec (completed)
+- Current spec clear but requirements hidden until error
+- Identified gap between spec intent and user experience
+
+### Step 2: Update spec (completed)
+- Helper text now includes full requirements
+- Changelog updated with reason and connection
+
+### Step 3: Implement (completed)
+- Updated helper text component
+- Requirements now render on page load
+- Commit: "Show password requirements upfront per spec v1.2"
+
+### Step 4: Verify (completed)
+- Puppeteer confirmed: text matches, requirements visible,
+  validation still works, other fields unchanged
+
+### Step 5: Test (completed)
+- Guerrilla test: 1 user completed signup without hesitation
+  at password field (previously 3/5 hesitated)
+```
+
+---
+
+## The Cycle Scales
+
+The same cycle works for everything:
+
+| Change Size | What You Do |
+|-------------|-------------|
+| **Typo fix** | Check spec → Fix → Verify → Commit |
+| **Small modification** | Connect → Update spec → Build → Verify → Document |
+| **New feature** | Full WDS cycle: Trigger map → Scenario → Spec → Build → Test → Deliver |
+| **Major redesign** | Full WDS cycle with sketching, storyboarding, and formal usability testing |
+
+Small changes skip steps. Large changes use every step. The discipline is the same — you just apply as much process as the change requires.
+
+---
+
+## Avoiding Spec Drift
+
+Over time, specs and reality can diverge. This is the biggest risk in brownfield development.
+
+### Prevention
+
+- **Update specs with every change.** No exceptions.
+- **Version your specs.** Changelogs show what changed and why.
+- **Let the agent verify.** Puppeteer catches drift automatically.
+
+### Recovery
+
+If specs are already out of date:
+
+1. Audit the current implementation
+2. Update specs to match reality
+3. Document intentional differences
+4. Resume the evolution cycle from there
+
+This is normal in brownfield. Don't feel guilty — just fix it and move forward.
+
+---
+
+## What's Next
+
+In the next lesson, you'll learn the discipline of updating specifications before touching code — and how the agent projects those changes into the codebase.
+
+---
+
+**[Continue to Lesson 2: Update the Spec — Project the Code →](lesson-02-update-spec-project-code.md)**
+
+---
+
+[← Back to Module Overview](module-18-product-evolution-overview.md)
+
+*Part of Module 18: Product Evolution*