whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-15-visual-design/tutorial-15.md

@@ -0,0 +1,377 @@
+# Tutorial 15: Create Your Visuals
+
+**Hands-on guide to generating and refining visual designs**
+
+---
+
+## Overview
+
+This tutorial walks you through generating visual prototypes from your specifications.
+
+**Time:** 40-50 minutes
+**Prerequisites:** Working prototypes (Module 14), Components documented (Module 12)
+**Agent:** Freya
+**What you'll create:** Visual prototypes for your key pages
+
+---
+
+## Before You Start
+
+**You'll need:**
+
+- Your page specifications
+- Your component documentation
+- Design tokens (if using Design System Mode 2-4)
+- Access to Figma or browser preview
+
+**Freya will help you:**
+
+- Generate initial visuals
+- Review against specifications
+- Identify refinements needed
+- Ensure accessibility compliance
+
+---
+
+## Step 1: Choose Your First Page (2 min)
+
+### Start with a key page:
+
+**You say:**
+> "Let's create visuals for the signup form (P02) from S01-User-Registration. Here's my specification."
+
+**Share your specification with Freya.**
+
+**Freya acknowledges:**
+> "I have your signup form specification. Let's generate a visual prototype and refine it."
+
+---
+
+## Step 2: Define Visual Requirements (3 min)
+
+### Establish design tokens:
+
+**Freya asks:**
+> "What are your visual requirements? Font family, primary color, and base sizing?"
+
+**You respond:**
+> "Inter font, primary color #0066FF, 16px base, white background with light gray accents (#F9FAFB)."
+
+**Freya notes:**
+```
+Visual tokens:
+- Font: Inter
+- Primary: #0066FF
+- Background: #FFFFFF
+- Accent/muted: #F9FAFB
+- Text: #111827
+- Error: #DC2626
+- Base size: 16px
+- Spacing scale: 8px increments
+```
+
+---
+
+## Step 3: Generate Initial Visual (5 min)
+
+### Freya generates prototype:
+
+> "Generating signup form prototype based on your specification..."
+
+**Freya produces:**
+```html
+<!-- Signup Form Prototype -->
+<div style="max-width: 400px; margin: 0 auto; padding: 24px; font-family: Inter, sans-serif;">
+  <h1 style="font-size: 24px; font-weight: 600; margin-bottom: 8px;">
+    Start in 2 minutes
+  </h1>
+  <p style="color: #6B7280; margin-bottom: 24px;">
+    No credit card required. Cancel anytime.
+  </p>
+
+  <form>
+    <div style="margin-bottom: 16px;">
+      <label style="display: block; margin-bottom: 4px;">Email</label>
+      <input type="email" placeholder="you@example.com"
+             style="width: 100%; padding: 12px; border: 1px solid #D1D5DB; border-radius: 6px;">
+    </div>
+
+    <div style="margin-bottom: 24px;">
+      <label style="display: block; margin-bottom: 4px;">Password</label>
+      <input type="password"
+             style="width: 100%; padding: 12px; border: 1px solid #D1D5DB; border-radius: 6px;">
+      <span style="color: #6B7280; font-size: 14px;">At least 8 characters</span>
+    </div>
+
+    <button style="width: 100%; padding: 14px; background: #0066FF; color: white; border: none; border-radius: 6px; font-size: 16px; font-weight: 500; cursor: pointer;">
+      Create Free Account
+    </button>
+  </form>
+
+  <p style="margin-top: 16px; font-size: 14px; color: #6B7280; text-align: center;">
+    By continuing, you agree to our <a href="#">Terms</a> and <a href="#">Privacy Policy</a>
+  </p>
+
+  <p style="margin-top: 24px; text-align: center;">
+    Already have an account? <a href="#">Log in</a>
+  </p>
+</div>
+```
+
+> "Preview this in your browser and let me know what needs adjustment."
+
+---
+
+## Step 4: Review Against Specification (5 min)
+
+### Compare visual to spec:
+
+**Freya:**
+> "Let's verify the visual matches your specification. Checking each element..."
+
+**Checklist:**
+
+| Element | Spec | Visual | Status |
+|---------|------|--------|--------|
+| Headline | "Start in 2 minutes" | ✓ | Match |
+| Subheadline | "No credit card required" | ✓ | Match |
+| Email field | Required, placeholder | ✓ | Match |
+| Password field | 8+ chars, helper text | ✓ | Match |
+| Submit button | "Create Free Account" | ✓ | Match |
+| Terms link | Present | ✓ | Match |
+| Login link | Present | ✓ | Match |
+
+### Identify gaps:
+
+**Freya:**
+> "I notice a few things:
+> 1. Password show/hide toggle is missing from the visual
+> 2. Strength indicator not shown
+> 3. Error states not visualized yet
+>
+> Should we add these?"
+
+**You respond:**
+> "Yes, add the show/hide toggle. Skip strength indicator for MVP. We need error states too."
+
+---
+
+## Step 5: Refine the Visual (10 min)
+
+### Add missing elements:
+
+**Freya updates:**
+> "Adding password toggle and generating error states..."
+
+**Password field with toggle:**
+```html
+<div style="position: relative;">
+  <input type="password" style="...">
+  <button type="button" style="position: absolute; right: 12px; top: 50%; transform: translateY(-50%); background: none; border: none; cursor: pointer;">
+    👁️ <!-- Eye icon -->
+  </button>
+</div>
+```
+
+**Error state:**
+```html
+<div style="margin-bottom: 16px;">
+  <label style="display: block; margin-bottom: 4px;">Email</label>
+  <input type="email"
+         style="... border-color: #DC2626;">
+  <span style="color: #DC2626; font-size: 14px;">
+    Please enter a valid email
+  </span>
+</div>
+```
+
+### Design all states:
+
+- Default (empty form)
+- Filling (content entered)
+- Error (validation failed)
+- Submitting (loading state)
+- Success (before redirect)
+
+---
+
+## Step 6: Check Accessibility (5 min)
+
+### Verify contrast and sizing:
+
+**Freya:**
+> "Running accessibility checks..."
+
+**Results:**
+| Check | Result |
+|-------|--------|
+| Button text contrast | 8.6:1 ✓ Pass |
+| Input text contrast | 13.4:1 ✓ Pass |
+| Helper text contrast | 4.8:1 ✓ Pass |
+| Error text contrast | 5.3:1 ✓ Pass |
+| Focus visible | ⚠️ Need to add |
+| Touch targets | ✓ 44px+ |
+
+### Add focus states:
+
+**Freya:**
+> "Adding focus styles for keyboard navigation..."
+
+```css
+input:focus {
+  outline: 2px solid #0066FF;
+  outline-offset: 2px;
+}
+
+button:focus {
+  outline: 2px solid #0066FF;
+  outline-offset: 2px;
+}
+```
+
+---
+
+## Step 7: Generate Responsive Variations (5 min)
+
+### Create tablet/desktop versions:
+
+**Freya:**
+> "Your base is mobile-first. For larger screens, do you want any layout changes?"
+
+**You respond:**
+> "Center the form on desktop with max-width 400px. Add some padding around it."
+
+**Freya generates:**
+```css
+@media (min-width: 768px) {
+  .signup-container {
+    max-width: 400px;
+    margin: 64px auto;
+    padding: 32px;
+    background: white;
+    border-radius: 8px;
+    box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+  }
+}
+```
+
+---
+
+## Step 8: Save and Document (5 min)
+
+### Save the visual prototype:
+
+**Options:**
+1. **HTML file** — Save in scenario folder
+2. **Figma import** — Use html.to.design
+3. **Screenshots** — Capture each state
+
+```
+C-UX-Scenarios/
+└── S01-User-Registration/
+    ├── P02-signup-form/
+    │   ├── specification.md
+    │   ├── visual-prototype.html
+    │   └── states/
+    │       ├── default.png
+    │       ├── error.png
+    │       ├── loading.png
+    │       └── success.png
+```
+
+### Document visual decisions:
+
+```markdown
+## Visual Notes
+
+### Design Tokens Applied
+- Primary button: #0066FF
+- Error: #DC2626
+- Text: #111827
+- Muted text: #6B7280
+
+### Deviations from Spec
+- Strength indicator removed (MVP scope)
+- Added subtle shadow on desktop
+
+### Accessibility
+- All contrast ratios pass WCAG AA
+- Focus states visible
+- Touch targets 44px+
+```
+
+---
+
+## Step 9: Move to Next Page (Optional)
+
+### Repeat for remaining pages:
+
+**Freya:**
+> "Signup form visual is complete. The next pages in S01 are:
+> - P01-landing-page
+> - P03-welcome-screen
+>
+> Which would you like to visualize next?"
+
+Continue the process for each page in your scenarios.
+
+---
+
+## What You've Created
+
+### For each page:
+
+- **Visual prototype** — Working HTML/CSS
+- **State screenshots** — All states visualized
+- **Responsive variations** — Mobile + desktop
+- **Accessibility verified** — Contrast, focus, targets
+
+### Ready for:
+
+- Stakeholder review
+- Usability testing
+- Developer handoff
+- Design delivery
+
+---
+
+## Tips for Success
+
+**DO:**
+
+- Start with specification, not visuals
+- Check against spec after every generation
+- Design all states, not just default
+- Verify accessibility before approving
+- Document deviations
+
+**DON'T:**
+
+- Skip error states
+- Ignore responsive behavior
+- Approve without contrast check
+- Leave spec-visual mismatches
+
+---
+
+## You've Completed Module 15!
+
+**Your specifications are now visible.** You have:
+- Working prototypes
+- All states designed
+- Accessibility verified
+- Responsive behavior defined
+
+---
+
+## Next Module
+
+**[Module 16: Design Delivery →](../module-16-design-delivery/module-16-design-delivery-overview.md)**
+
+Package and deliver your design.
+
+---
+
+[← Back to Lesson 2](lesson-02-visual-techniques.md) | [Back to Module Overview](module-15-visual-design-overview.md)
+
+*Part of Module 15: Visual Design*

package/docs/learn/module-16-design-delivery/lesson-01-validation-packaging.md

@@ -0,0 +1,340 @@
+# Module 16: Design Delivery
+
+## Lesson 1: Validation and Packaging
+
+**Ensuring everything is complete and packaging for handoff**
+
+---
+
+## Two Steps Before Handoff
+
+Before any design work leaves your hands, it goes through two steps:
+
+1. **Validate** — Is everything complete? Are there gaps?
+2. **Package** — Create the DD file and test scenario
+
+Gaps found during development are expensive. Gaps found during validation are cheap.
+
+---
+
+## Step 1: Validate
+
+### The Completeness Check
+
+Before creating a Design Delivery, verify the flow is truly complete. Freya helps run this audit.
+
+**Is it a complete flow?**
+
+- [ ] Entry point is clear (where does the user start?)
+- [ ] Exit point is clear (where does the user end up?)
+- [ ] Every screen in between is fully specified
+- [ ] The flow delivers real user value on its own
+
+**Are all pages specified?**
+
+- [ ] All elements documented with Object IDs
+- [ ] All states defined (default, hover, loading, error, empty)
+- [ ] All content written — no placeholder text, no "lorem ipsum"
+- [ ] All interactions described (what happens when user clicks, types, scrolls)
+- [ ] Error states handled with specific error messages
+- [ ] Loading states defined
+- [ ] Empty states defined
+
+**Is it traceable?**
+
+- [ ] Every element connects to the Trigger Map
+- [ ] Personas referenced
+- [ ] Driving forces addressed
+- [ ] Features linked
+- [ ] Business goals traceable
+
+**Is it unambiguous?**
+
+- [ ] Consistent terminology throughout
+- [ ] No vague descriptions ("appropriate", "suitable", "nice")
+- [ ] Accessibility considered (contrast, touch targets, focus order)
+- [ ] Visual design matches specification
+
+**Is it testable?**
+
+- [ ] Acceptance criteria defined for every interaction
+- [ ] Success states clear
+- [ ] Error conditions specified with exact messages
+- [ ] Expected behaviors documented
+
+---
+
+### The Freya Audit
+
+Ask Freya to audit your specifications. She reads through every page in the flow and flags issues:
+
+> "Auditing S01-User-Registration..."
+
+> "Page P02 is missing the error state for network timeout."
+
+> "Element signup-button has no Object ID — should be 'signup-submit-btn'."
+
+> "This spec says 'appropriate error message' — what's the actual text?"
+
+> "Page P03 references a 'Continue' button but the specification doesn't describe what happens when it's clicked."
+
+She finds gaps before developers do.
+
+### Common Gaps
+
+| Gap Type | Example | Fix |
+|----------|---------|-----|
+| Missing state | No loading state for form submission | Add loading specification |
+| Vague content | "Show error message" | Write exact error text |
+| No Object ID | Button without identifier | Add consistent ID |
+| Disconnected | Feature not linked to Trigger Map | Add connection |
+| Missing edge case | What if network fails? | Document recovery path |
+| Incomplete flow | Signup works but no email verification | Add verification screens |
+
+---
+
+## Step 2: Create the Design Delivery
+
+Once validation passes, create the DD file. This is the contract that tells development exactly what to build.
+
+### The DD-XXX.yaml File
+
+Each delivery follows the standard template. Here's what goes into each section:
+
+```yaml
+delivery:
+  id: "DD-001"
+  name: "User Registration"
+  type: "user_flow"           # user_flow | feature | component
+  status: "ready"             # ready | in_progress | blocked
+  priority: "high"            # high | medium | low
+```
+
+**Delivery metadata.** The ID follows the format DD-001, DD-002, etc. Status should be "ready" when you're done validating.
+
+---
+
+```yaml
+description: |
+  First-time user signup flow from landing page
+  through registration to welcome dashboard.
+  Includes email/password signup, real-time validation,
+  and immediate access to the product.
+```
+
+**What this delivery contains.** One paragraph that gives development the full picture.
+
+---
+
+```yaml
+user_value:
+  problem: "Users need to create an account to access the product"
+  solution: "Simple email + password signup with immediate access"
+  success_criteria:
+    - "User can register in under 2 minutes"
+    - "Zero confusion on required fields"
+    - "Immediate access after registration"
+```
+
+**Why this matters.** Developers build better when they understand the user problem they're solving.
+
+---
+
+```yaml
+design_artifacts:
+  scenarios:
+    - id: "01-user-registration"
+      path: "C-UX-Scenarios/01-user-registration/"
+      screens: ["landing", "signup-form", "email-verification", "welcome"]
+
+  user_flows:
+    - name: "Registration Flow"
+      path: "C-UX-Scenarios/flows/registration.excalidraw"
+      entry: "landing"
+      exit: "welcome"
+
+  design_system:
+    components:
+      - "Button (primary, secondary, loading)"
+      - "Input (text, email, password with toggle)"
+      - "FormField (label, input, helper, error)"
+    path: "D-Design-System/"
+```
+
+**What's included.** References to your scenarios, user flows, and components. These are paths to the actual files — not copies of the content.
+
+---
+
+```yaml
+technical_requirements:
+  platform:
+    frontend: "next.js"
+    backend: "supabase"
+
+  integrations:
+    - name: "authentication-api"
+      purpose: "User registration and session management"
+      required: true
+    - name: "email-service"
+      purpose: "Verification emails"
+      required: true
+
+  data_models:
+    - name: "User"
+      fields: ["email", "password_hash", "created_at", "verified"]
+```
+
+**What development needs.** Platform info comes from the PRD's technical foundation (Phase 3). If no PRD exists yet, describe what you know.
+
+---
+
+```yaml
+acceptance_criteria:
+  functional:
+    - "User can enter email and password"
+    - "Real-time validation shows errors on blur"
+    - "Submit button disabled when form is invalid"
+    - "Loading state shown during submission"
+    - "Redirect to welcome screen on success"
+    - "Welcome screen shows user's email"
+
+  non_functional:
+    - "Form submission completes under 2 seconds"
+    - "WCAG AA contrast compliance on all elements"
+    - "Touch targets minimum 44px"
+    - "Works on mobile viewports (320px+)"
+
+  edge_cases:
+    - "Duplicate email → 'This email is already registered'"
+    - "Network error → 'Check your connection' with retry button"
+    - "Server error → 'Something went wrong. Please try again.'"
+    - "Refresh during submission → no duplicate account created"
+    - "Back button from welcome → clean signup form"
+```
+
+**How to verify.** Every criterion must be testable — a tester can read this list and check each item without asking you.
+
+---
+
+```yaml
+testing_guidance:
+  user_testing:
+    - "Can a new user complete registration without help?"
+    - "Does the validation feel helpful or annoying?"
+
+  qa_testing:
+    - "Test all error states trigger correctly"
+    - "Verify email verification flow end-to-end"
+    - "Test on mobile (iOS Safari, Android Chrome)"
+
+estimated_complexity:
+  size: "small"
+  effort: "1-2 weeks"
+  risk: "low"
+  dependencies: []
+```
+
+**Testing approach and effort estimate.** Helps development plan their work.
+
+---
+
+## Create the Test Scenario
+
+Alongside the DD file, create a test scenario file (TS-XXX.yaml) that defines:
+
+- Happy path tests (the normal user journey)
+- Error state tests (what goes wrong and how to verify handling)
+- Edge case tests (unusual but important situations)
+- Design system validation (components render correctly)
+- Accessibility tests (keyboard, screen reader, contrast)
+
+This file is used by testers in Module 17 to verify the implementation matches your design.
+
+---
+
+## The Handoff Dialog
+
+Before marking a delivery as handed off, sit down with the development team (or the BMad architect agent) for a 20-30 minute handoff dialog.
+
+**What you cover:**
+
+- Walk through the user flow
+- Highlight key interactions and states
+- Discuss technical requirements
+- Agree on epic breakdown (how to split the work)
+- Answer questions
+- Identify risks or unknowns
+
+**Document the dialog** in a handoff log (`DD-XXX-handoff-log.md`):
+
+```markdown
+# Handoff Log: DD-001 User Registration
+
+## Date: 2026-02-15
+## Duration: 25 minutes
+## Participants: Mårten (designer), Marcus (developer)
+
+## Key Discussion Points
+- Agreed on email-first registration (no social login in v1)
+- Password strength indicator: nice-to-have, not blocking
+- Mobile: must work on 320px viewport
+
+## Epic Breakdown
+1. Form UI + validation (3 days)
+2. Auth API integration (2 days)
+3. Email verification flow (2 days)
+4. Welcome screen + redirect (1 day)
+
+## Questions Resolved
+- Q: Real-time validation on every keystroke?
+  A: No, on blur. Spec updated.
+
+## Action Items
+- [ ] Marcus: Set up auth API endpoint
+- [ ] Mårten: Add 320px viewport to test scenario
+```
+
+---
+
+## Reference, Don't Duplicate
+
+The DD file **references** your design artifacts. It doesn't copy them.
+
+```yaml
+design_artifacts:
+  scenarios:
+    - id: "01-user-registration"
+      path: "C-UX-Scenarios/01-user-registration/"    # ← reference
+```
+
+This means:
+- When specs update, the delivery stays current
+- Single source of truth maintained
+- No sync issues between documents
+
+---
+
+## After Handoff
+
+Once delivered:
+
+- Mark the DD status as `in_development`
+- The development team (or BMad agents) builds from the DD and referenced artifacts
+- You continue designing the next flow
+- When development is complete, you test the implementation (Module 17)
+
+---
+
+## What's Next
+
+In the tutorial, you'll run the validation checklist on your own specifications and create your delivery package.
+
+---
+
+**[Continue to Tutorial: Create Your Delivery →](tutorial-16.md)**
+
+---
+
+[← Back to Module Overview](module-16-design-delivery-overview.md)
+
+*Part of Module 16: Design Delivery*