whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-17-usability-testing/lesson-03-acting-on-findings.md

@@ -0,0 +1,253 @@
+# Module 17: Usability Testing
+
+## Lesson 3: Acting on Findings
+
+**Turning observations into design improvements**
+
+---
+
+## Review the Recordings
+
+Don't process findings from memory. Watch the recordings.
+
+On the second viewing, you see what you missed. The hesitation you didn't notice. The comment you brushed past. The pattern across multiple users that wasn't visible during any single session.
+
+### What to Look For
+
+**Patterns** — Did multiple users struggle at the same point? That's a design problem, not a user problem.
+
+**Surprises** — Did users do something you didn't expect? They found a path you didn't design for, or ignored the path you did.
+
+**Quotes** — Exact words users said. "I don't know what this means" is more powerful than "users found the label confusing."
+
+**Completion** — Did they finish the task? How long did it take? Did they need to backtrack?
+
+### Timestamp Key Moments
+
+As you review, note timestamps for:
+
+- First confusion point
+- Misclicks or wrong paths
+- Moments of hesitation (3+ seconds)
+- Verbal reactions ("Oh!", "Hmm...", "Wait...")
+- Task abandonment
+- Successful completion
+
+These timestamps become your evidence when presenting findings.
+
+---
+
+## Document the Findings
+
+For each usability issue, document:
+
+```markdown
+## Finding: [Short description]
+
+**Severity:** Critical | Major | Minor
+**Observed in:** [# of # participants]
+**Task:** [Which task triggered this]
+**Timestamp:** [Recording reference]
+
+### What happened
+[Describe the behavior — what the user did, not what they should have done]
+
+### Why it matters
+[Connect to persona, driving force, or business goal]
+
+### Root cause
+[What in the design caused this? Be specific — page, element, interaction]
+
+### Recommendation
+[What to change in the specification]
+```
+
+### Example
+
+```markdown
+## Finding: Users don't see the registration CTA
+
+**Severity:** Critical
+**Observed in:** 4 of 5 participants
+**Task:** "You want to create an account. Go ahead."
+**Timestamp:** P1 0:23, P2 0:31, P3 0:18, P4 0:45
+
+### What happened
+Users scrolled past the registration button. Three looked at the
+navigation menu first. One tried clicking the logo. Only after
+20-40 seconds did they find the CTA below the fold.
+
+### Why it matters
+Felix needs simple paths with no hunting (driving force: efficiency).
+If the primary action is hidden, first-time users will bounce.
+
+### Root cause
+Page P01 (landing): The CTA "Create Free Account" sits below a
+large hero image. Visual hierarchy prioritizes the image over
+the action.
+
+### Recommendation
+Move CTA above the fold. Increase visual weight — larger button,
+contrasting color, or positioned within the hero section instead
+of below it. Update spec P01 section 3.
+```
+
+---
+
+## Connect to Your Design System
+
+Usability findings don't exist in isolation. They connect back to everything you've built:
+
+### Trace to Specifications
+
+Every finding should point to a specific page, element, or interaction in your specs. If you can't point to the spec, the finding is too vague.
+
+> "Users were confused" → **Too vague**
+> "Users didn't see the CTA on P01 because it's below the fold" → **Actionable**
+
+### Trace to Trigger Maps
+
+Your trigger maps describe the driving forces behind user actions. When testing reveals problems, check if the driving force was addressed:
+
+> Finding: Users abandon at step 2 of registration.
+> Trigger map says: Felix is motivated by speed — "I want this done fast."
+> Connection: Step 2 feels unnecessary. Can we combine steps 1 and 2?
+
+### Trace to Personas
+
+Does the finding affect all users, or is it persona-specific?
+
+> Finding works for tech-savvy users but fails for the less technical persona → Different fix needed than a universal change.
+
+---
+
+## Prioritize What to Fix
+
+Not every finding needs immediate action.
+
+### Critical
+
+Users **cannot complete the task.** The flow is broken.
+
+- Fix before next test round
+- Update spec immediately
+- Rebuild in next agentic session
+
+### Major
+
+Users **complete the task but with significant difficulty.** Hesitation, confusion, wrong paths.
+
+- Fix in current iteration
+- Update spec
+- May need design rethinking, not just tweaks
+
+### Minor
+
+Users **notice something but it doesn't block them.** Small friction, slightly confusing labels.
+
+- Fix when convenient
+- Log for future reference
+- Sometimes resolves itself when major issues are fixed
+
+### Not a Problem
+
+Users did something unexpected but it **worked fine.** Their path was different from what you designed, but the outcome was correct.
+
+- Document it — you learned something about user behavior
+- Consider if the "designed" path is actually needed
+- Don't fix what isn't broken
+
+---
+
+## Update Your Specifications
+
+This is where the cycle closes. Findings become spec changes.
+
+```markdown
+## Spec Update Log: Usability Round 1
+
+### P01 Landing Page
+- **Changed:** CTA moved from below hero to within hero section
+  - Reason: 4/5 users missed it below the fold
+  - Finding: "Users don't see the registration CTA"
+
+### P02 Signup Form
+- **Changed:** Combined steps 1 and 2 into single form
+  - Reason: 3/5 users hesitated at step transition
+  - Finding: "Step 2 feels unnecessary"
+
+### P03 Welcome Screen
+- **No changes.** All users navigated successfully.
+```
+
+Update the spec. Then rebuild. Then test again.
+
+---
+
+## The Iterate Cycle
+
+```
+Round 1: Test prototype
+  → 3 critical, 2 major findings
+  → Update specs → Rebuild
+
+Round 2: Test updated prototype
+  → 0 critical, 1 major, 2 minor findings
+  → Update specs → Rebuild
+
+Round 3: Test refined prototype
+  → 0 critical, 0 major, 1 minor finding
+  → Ship it
+```
+
+Each round should have fewer and less severe findings. If severity increases between rounds, something went wrong in the redesign.
+
+**Two to three rounds** is typical for a critical flow. One round is enough for simpler features.
+
+---
+
+## Presenting Findings
+
+Sometimes you need to convince stakeholders that changes are necessary.
+
+### Use Evidence, Not Opinion
+
+- **Weak:** "I think the CTA should be bigger"
+- **Strong:** "4 of 5 test participants couldn't find the CTA within 30 seconds. Here are the recordings."
+
+### Show, Don't Tell
+
+Play the relevant 30 seconds of recording. Seeing a real user struggle is more persuasive than any report.
+
+### Connect to Business Impact
+
+- "Users can't find the registration button → fewer signups → less revenue"
+- "Users abandon at step 2 → 60% drop-off in the funnel"
+
+---
+
+## The Freya Method
+
+Freya helps structure your findings:
+
+> "You found 5 issues. Let me help prioritize. Finding #1 blocks the primary task for 4 of 5 users — that's critical. Findings #3 and #4 might resolve themselves once #1 is fixed."
+
+> "This finding connects to the trigger map: Felix's driving force is efficiency. The three-step process contradicts that. Recommend consolidating."
+
+> "Update spec P01 section 3 based on finding #1. I'll note the change in the spec update log."
+
+---
+
+## What's Next
+
+In the tutorial, you'll plan a usability test for one of your flows and walk through the complete process.
+
+---
+
+**[Continue to Tutorial: Plan Your Usability Test →](tutorial-17.md)**
+
+---
+
+[← Back to Lesson 2](lesson-02-test-results.md) | [Back to Module Overview](module-17-usability-testing-overview.md)
+
+*Part of Module 17: Usability Testing*

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

@@ -0,0 +1,231 @@
+# Module 17: Usability Testing
+
+**Time: 45 min | Agent: Freya | Phase: Validation**
+
+---
+
+## The New Economics of Testing
+
+Usability testing hasn't changed. But everything around it has.
+
+When every phase of design took weeks, a couple of days of testing and a couple of days processing results didn't feel like much. Now, when a complete product can be built in an afternoon, spending two days testing on humans suddenly feels relatively very expensive.
+
+This doesn't make usability testing less valuable. It makes planning more important.
+
+The answer isn't to skip testing. It's to **test early** and **plan ahead**. Line up your test group before you start building. When the prototype is ready, they're ready. No waiting. No scheduling back and forth.
+
+---
+
+## The Whiteport Rule
+
+**If a feature or change isn't worth showing to 5 users and 1 domain expert for feedback, then it's not worth building in the first place.**
+
+This is the simplest filter for what deserves your time. If you can't justify 20 minutes of testing for a feature, ask yourself why you're spending hours building it.
+
+Every feature you ship will be used by real people. If you're not willing to watch 5 of them try it, you're shipping blind.
+
+---
+
+## Spec Conformity Is Not Usability
+
+In Module 14, the agent verifies that the implementation matches the specification — using Puppeteer to check every element, state, and interaction. That's functional testing. It answers: **did we build what we designed?**
+
+Usability testing answers a different question: **did we design the right thing?**
+
+A form can match the spec perfectly and still confuse users. A flow can implement every acceptance criterion and still feel wrong. Numbers pass. Humans struggle.
+
+| What you assumed | What testing reveals |
+|------------------|---------------------|
+| Users will see the CTA first | Users look at the image, miss the CTA |
+| The error message is clear | Users don't understand "invalid format" |
+| The flow is intuitive | Users expect "Back" to go to the previous page, not the dashboard |
+| Three steps is simple enough | Users abandon at step 2 |
+
+These are things no specification can predict. You have to watch real people use the product.
+
+---
+
+## Test on Their Turf
+
+The gold standard for usability testing is **contextual testing** — testing the product on the user's own devices, in their own environment. At their home. In their office. On their phone, their laptop, their browser.
+
+This gives the most reliable results because the user isn't distracted by being in a test session. They're using a product in context, the way they actually would.
+
+Compared to a lab setting or a video call with screen sharing, contextual testing reveals:
+
+- How the product fits into their real workflow
+- What distracts them in their actual environment
+- Whether the design works on their specific device and screen size
+- Their natural behavior — not their "I'm being tested" behavior
+
+---
+
+## Think-Aloud: The Core Method
+
+### Contextual Think-Aloud
+
+The user talks through what they're doing as they do it:
+
+> "I'm looking for where to sign up... I see this button but I'm not sure if that's it... OK I'll click it... Now it wants my email..."
+
+You observe and take notes. You don't help. You don't guide. You listen.
+
+### Retrospective Think-Aloud
+
+The session is recorded. Afterward, you watch the recording together with the user:
+
+> "Here I was confused because I didn't know if my password was saved. I waited for a confirmation but nothing happened."
+
+Retrospective think-aloud is powerful because the user isn't splitting attention between doing and explaining. They perform naturally first, then reflect.
+
+### Which to Use
+
+| Method | When | Trade-off |
+|--------|------|-----------|
+| Contextual think-aloud | Quick tests, guerrilla testing | User splits attention between doing and explaining |
+| Retrospective think-aloud | Formal sessions, critical flows | Takes longer but gives richer insight |
+| Both combined | When you have time | Best results |
+
+---
+
+## Record Everything
+
+Always record the session. Always.
+
+When you're running the test, you're focused on the user — their body language, their hesitation, what they say. You miss things. Recording lets you review the tape and spot what you didn't catch the first time.
+
+A recorded session gives you:
+
+- Exact moments of confusion (timestamp them)
+- Quotes you can use to justify design changes
+- Evidence for stakeholders who weren't there
+- Details you missed because you were watching the user's face, not the screen
+
+---
+
+## Plan Ahead
+
+The biggest usability testing failure is not having testers ready when the prototype is.
+
+**Before you start building:**
+
+1. Identify 3-5 people who match your personas
+2. Ask them if they're available for a 20-minute session this week (or next)
+3. Get their confirmation
+
+**When the prototype is ready:**
+
+4. Send them the link or visit them
+5. Run the test
+6. Process results the same day while it's fresh
+
+Total overhead: one message before, one session after. Testing doesn't slow you down — because you planned for it.
+
+---
+
+## When to Test
+
+```
+  WDS Stage                     What to Test
+  ─────────                     ────────────
+
+  Storyboards ─────────────── Does the flow make sense?
+       │                       Are we solving the right problem?
+       ▼
+  Prototypes ──────────────── Can users complete the task?
+       │                       Where do they hesitate?
+       ▼
+  Production ──────────────── Does it work in the real context?
+                               How does it perform with real data?
+```
+
+**Prototypes are the sweet spot.** The design is real enough to test, cheap enough to change.
+
+---
+
+## The Freya Method
+
+Freya connects usability findings to your design strategy:
+
+> "Three of five users struggled to find the registration link. This connects to Felix's driving force — he needs simple paths with no hunting."
+
+> "Users understood the error messages but didn't know how to fix the problem. The spec tells them what's wrong but not what to do."
+
+> "The flow works technically, but users feel uncertain at step 2. They need a progress indicator or reassurance."
+
+She maps observations to personas, driving forces, and business goals — turning individual findings into design decisions.
+
+---
+
+## What You'll Learn
+
+### Lesson 1: The Test Scenario
+
+How to prepare for a usability test — picking the flow, writing tasks that reveal real behavior, selecting participants, preparing materials, and creating the test scenario document.
+
+### Lesson 2: Conducting the Test
+
+How to run the session — presenting the same information to every participant, observing in silence, deflecting questions, recording everything, and using the retrospective replay to unlock deeper insights.
+
+### Lesson 3: Acting on Findings
+
+How to review recordings, document usability issues, connect them back to specifications and trigger maps, prioritize what to fix, and feed learning into the next iteration.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| No testers lined up when prototype is ready | Plan ahead — recruit before you start building |
+| Testing in a lab or conference room | Go to their environment, their devices |
+| Helping users when they struggle | Observe silently — the struggle is the data |
+| Not recording | Always record, you'll miss things live |
+| Asking "do you like it?" | Watch behavior, don't ask for opinions |
+| Fixing symptoms | Trace issues to root causes in specifications |
+| Testing too much at once | One flow per session, 3-5 tasks maximum |
+
+---
+
+## Practice
+
+Pick one flow from your project:
+
+1. Define 3 tasks a user should be able to complete
+2. Find one person who matches your persona
+3. Give them the prototype on their own device
+4. Watch them attempt the tasks — don't help
+5. Record the session
+6. Review the recording — what did you miss the first time?
+
+---
+
+## Lessons
+
+### [Lesson 1: The Test Scenario](lesson-01-spec-verification.md)
+Preparing everything before the user arrives
+
+### [Lesson 2: Conducting the Test](lesson-02-test-results.md)
+The session, the silence, and the replay
+
+### [Lesson 3: Acting on Findings](lesson-03-acting-on-findings.md)
+Turning observations into design improvements
+
+---
+
+## Tutorial
+
+### [Tutorial 17: Plan Your Usability Test](tutorial-17.md)
+Hands-on guide to preparing and running a usability test session
+
+---
+
+## Next Module
+
+**[Module 18: Product Evolution →](../module-18-product-evolution/module-18-product-evolution-overview.md)**
+
+Products don't end at launch.
+
+---
+
+*Part of the WDS Course: From Designer to Linchpin*