whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-13-design-system/module-13-design-system-overview.md

@@ -0,0 +1,157 @@
+# Module 13: Design System
+
+**Time: 30 min | Agent: Freya | Phase: Design | Focus: Systems**
+
+---
+
+## What Is a Design System?
+
+A design system is a collection of reusable components — buttons, input fields, cards, navigation elements — that share consistent styling and behavior across your product.
+
+Large organizations spend months building comprehensive design systems with hundreds of components before writing a single line of product code. That works when you have a dedicated team and a long timeline.
+
+Most projects don't.
+
+---
+
+## The WDS Approach: Build As You Go
+
+In WDS, the design system grows naturally from your work.
+
+As you sketch scenarios, write specifications, and define storyboards, you encounter the same elements over and over — a text field here, a button there, a card layout that keeps appearing. Instead of designing each one from scratch every time, you extract it into a shared component.
+
+```
+Scenario P01: Homepage
+  → You specify a search widget
+  → It goes into your component library
+
+Scenario P04: Dashboard
+  → You need a search widget again
+  → It's already there. Reuse it.
+
+Scenario P07: Settings
+  → You need search again, slightly different
+  → Add a variant to the existing component
+```
+
+Each component you extract becomes a puzzle piece. Over time, your collection grows into a treasure chest of ready-made building blocks. Every new page starts a little better because half the pieces already exist.
+
+---
+
+## Design Stays With the Component
+
+This is the key insight: **as soon as you add visual design to a component, it's saved**.
+
+The next time that component appears on a new page, it already looks right. No re-styling. No guessing. The page looks better out of the box because the pieces are already designed.
+
+---
+
+## All Design Is Code
+
+In WDS, your design system lives as code — not as Figma files collecting dust.
+
+You don't need a separate component library in Figma if you don't want one. Every component is stored as a specification in your project, and the styling is saved alongside it.
+
+When you want to edit a component visually:
+
+```
+1. Open the component in Figma
+   → Use the html.to.design plugin to import it
+
+2. Make your changes in Figma
+   → Adjust colors, spacing, typography
+
+3. Sync back to code
+   → Use the Figma MCP to push changes back
+
+4. The WDS agent handles naming
+   → Keeps everything connected automatically
+```
+
+This means your design system is always in sync with your code. No handoff gaps. No "the Figma file says one thing but the code says another."
+
+---
+
+## Design System Paths
+
+Not every project starts from zero. WDS supports three paths:
+
+### Dynamic (Default)
+
+The default WDS approach. Your design system grows one component at a time as you design. Where the components come from depends on your project:
+
+**A: Build on a raw component library**
+
+You start from an external library like shadcn, Radix, or MUI. When you need a button, you pick one from the library, apply your branding, and it becomes part of your design system. Next page needs a card? Pick one, brand it, done.
+
+**B: Make them as you go**
+
+No library — you design each component from scratch as patterns emerge. When something appears twice, you extract it into a shared component.
+
+Most projects use a mix of both. The source doesn't matter. What matters is that each component is picked up **when you need it**, branded to your project, and stored for reuse.
+
+Freya helps by noticing patterns:
+
+> "This button appears in three specifications. Should we extract it as a component?"
+
+You say yes → it goes into `C-UX-Scenarios/Functional-Components/`
+
+Over time, your components accumulate. And on your next project for the same client? The design system already exists. You import it, reuse it, extend it.
+
+```
+Project 1: Dynamic — you pick and build components as you go
+    ↓
+Project 2: You reuse what you built + add new components
+    ↓
+Project 3: Your library keeps growing
+```
+
+Your work compounds. Each project builds on the last.
+
+### None
+
+No design system at all. Each page is self-contained with inline styling. Best for landing pages, quick prototypes, and tight deadlines.
+
+**Trade-off:** Consistency is manual. Reuse requires copy-paste.
+
+---
+
+## The 5-Activity Workflow
+
+In the WDS workflow (Phase 7), the design system is managed through a menu-driven approach:
+
+```
+[C] Create Design System    — Build from scratch or from component library
+[I] Import Design System    — Capture an existing system from a live product
+[V] View Components         — Preview components in a disposable localhost app
+[E] Edit Components         — Open components in Figma for visual refinement
+[B] Browse Design System    — Explore tokens, relationships, and components
+```
+
+The [B] Browse activity generates a disposable localhost application that lets you search tokens by intent ("I need a calm background color"), view relationships between design tokens, and browse the component catalog — like an Airtable-like interface for your design system.
+
+---
+
+## Lessons
+
+### [Lesson 1: Understanding the Four Modes](lesson-01-understanding-modes.md)
+How component management affects your workflow
+
+---
+
+## Tutorial
+
+### [Tutorial 13: Apply Your Mode](tutorial-13.md)
+Hands-on guide to working effectively in your design system mode
+
+---
+
+## Next Module
+
+**[Module 14: Agentic Development →](../module-14-agentic-development/module-14-agentic-development-overview.md)**
+
+Generate working prototypes from your specifications.
+
+---
+
+*Part of the WDS Course: From Designer to Linchpin*

package/docs/learn/module-13-design-system/tutorial-13.md

@@ -0,0 +1,344 @@
+# Tutorial 13: Apply Your Mode
+
+**Hands-on guide to working effectively in your design system mode**
+
+---
+
+## Overview
+
+This tutorial helps you verify your mode choice and work effectively within it.
+
+**Time:** 15-20 minutes
+**Prerequisites:** Visual designs completed (Module 13)
+**Agent:** Freya
+**What you'll do:** Review and optimize your design system approach
+
+---
+
+## Before You Start
+
+**Know your mode:**
+
+- Mode 1: None (inline styling)
+- Mode 2: Building (extracting components)
+- Mode 3: Library (using external library)
+- Mode 4: Existing (importing previous system)
+
+**If unsure, ask Freya:**
+> "What design system mode are we using for this project?"
+
+---
+
+## Mode 1: None — Tutorial
+
+### Verify inline specifications are complete:
+
+**Check each page spec:**
+
+```markdown
+### Submit Button
+- Style: bg #0066FF, text white, 16px, rounded 6px
+- Padding: 14px vertical, 24px horizontal
+- States: hover (darken 10%), active (scale 98%), loading (spinner), disabled (opacity 50%)
+- Label: "Create Free Account"
+```
+
+### Consistency check:
+
+**Freya asks:**
+> "I notice you have similar buttons on 3 pages. Their styling is slightly different:
+> - P01: rounded 6px
+> - P02: rounded 8px
+> - P03: rounded 6px
+>
+> Should these be consistent?"
+
+**Resolve inconsistencies manually** since there's no central component.
+
+### When to upgrade:
+
+If you find yourself fixing the same inconsistency repeatedly, consider upgrading to Mode 2.
+
+---
+
+## Mode 2: Building — Tutorial
+
+### Review extracted components:
+
+**Freya summarizes:**
+> "Your design system has grown to include:
+>
+> **Components:**
+> - Button (3 variants, 5 states)
+> - Input (3 types, 4 states)
+> - Card (2 variants)
+>
+> **Tokens:**
+> - 6 colors defined
+> - Typography scale
+> - Spacing scale
+>
+> All page specs reference these components."
+
+### Check for missing patterns:
+
+**Freya:**
+> "Looking at your specs, I see a repeated pattern that isn't extracted yet:
+>
+> Form Field Group (label + input + error message) appears 8 times.
+>
+> Should we extract this as a component?"
+
+**You decide:**
+> "Yes, let's extract it."
+
+**Freya creates:**
+```markdown
+# FormField Component
+
+## Description
+Container for label, input, helper text, and error message.
+Provides consistent spacing and error handling.
+
+## Props
+| Prop | Type | Description |
+|------|------|-------------|
+| label | string | Field label |
+| input | Input | The input component |
+| helper | string | Helper text (optional) |
+| error | string | Error message (optional) |
+
+## States
+- Default: Label + input visible
+- With helper: Helper text below input
+- Error: Error message replaces helper, input bordered red
+```
+
+### Update specs to use new component:
+
+**Before:**
+```markdown
+### Email Section
+- Label: "Email" (above, 14px, #374151)
+- Input: email type, placeholder "you@example.com"
+- Helper: none
+- Error: "Please enter a valid email" (when invalid)
+```
+
+**After:**
+```markdown
+### Email Section
+- Component: FormField
+- Label: "Email"
+- Input: Input (email)
+- Placeholder: "you@example.com"
+- Error: "Please enter a valid email"
+```
+
+---
+
+## Mode 3: Library — Tutorial
+
+### Verify library component usage:
+
+**Freya checks:**
+> "You're using shadcn components. Let me verify your usage:
+>
+> **Correctly used:**
+> - Button (default, destructive, outline variants)
+> - Input (with FormField wrapper)
+> - Card (default)
+>
+> **Token overrides:**
+> - Primary color: #0066FF (applied)
+> - Border radius: 6px (applied)
+> - Font: Inter (applied)
+>
+> **Custom additions:**
+> - TaskCard (extends shadcn/Card) — documented
+> - StrengthIndicator — custom component
+>
+> Everything looks aligned."
+
+### Check token application:
+
+```yaml
+# D-Design-System/tokens/colors.yaml
+colors:
+  background: "#FFFFFF"
+  foreground: "#111827"
+  primary: "#0066FF"
+  primary-foreground: "#FFFFFF"
+  secondary: "#F3F4F6"
+  secondary-foreground: "#374151"
+  destructive: "#DC2626"
+  destructive-foreground: "#FFFFFF"
+  muted: "#F9FAFB"
+  muted-foreground: "#6B7280"
+```
+
+### Document custom components:
+
+If you created components beyond the library, document them:
+
+```markdown
+# StrengthIndicator (Custom)
+
+## Description
+Password strength feedback component.
+Not from shadcn — custom for this project.
+
+## Props
+| Prop | Type | Description |
+|------|------|-------------|
+| strength | number | 0-4 strength level |
+
+## Visual
+- 4 bars, filling based on strength
+- Colors: red (1), orange (2), yellow (3), green (4)
+```
+
+---
+
+## Mode 4: Existing — Tutorial
+
+### Review imported components:
+
+**Freya:**
+> "Importing design system from Acme Project v2...
+>
+> **Available components:**
+> - Button (4 variants)
+> - Input (5 types)
+> - Card, Modal, Toast
+> - Form patterns
+>
+> **Token values:**
+> - Brand colors (Acme palette)
+> - Typography (Inter scale)
+> - Spacing (8px base)
+>
+> Ready to use. Any extensions needed?"
+
+### Extend for new project:
+
+**You say:**
+> "This project needs a new Button variant: 'outline-primary' — blue border, transparent background."
+
+**Freya extends:**
+```markdown
+# Button Component (Extended)
+
+## New Variant: outline-primary
+- Border: 1px solid #0066FF
+- Background: transparent
+- Text: #0066FF
+- Hover: Background #0066FF/10%
+
+Added for: New Project
+Reason: Secondary CTAs need brand color visibility
+```
+
+### Track extensions:
+
+```markdown
+# Design System Extensions — New Project
+
+## New Variants
+- Button: outline-primary
+
+## New Components
+- None yet
+
+## Token Overrides
+- None (using Acme palette)
+```
+
+---
+
+## All Modes: Final Check
+
+### Verify alignment:
+
+| Check | Action |
+|-------|--------|
+| All page specs use correct component references | Review each spec |
+| No orphan inline styles (Mode 2-4) | Search for inline definitions |
+| Tokens applied consistently | Check visual prototypes |
+| New patterns documented | Add to design system |
+
+### Document your mode:
+
+Add to project README or design system index:
+
+```markdown
+# Design System
+
+## Mode: Building (Mode 2)
+
+## Components
+See: C-UX-Scenarios/Functional-Components/
+
+## Tokens
+See: D-Design-System/tokens/
+
+## Usage
+All page specifications reference components from this system.
+Do not use inline styles for elements that have component definitions.
+```
+
+---
+
+## What You've Accomplished
+
+### By mode:
+
+**Mode 1:** Verified all inline specs are complete and consistent
+
+**Mode 2:** Components extracted, patterns identified, specs updated
+
+**Mode 3:** Library components correctly used, tokens applied, customs documented
+
+**Mode 4:** System imported, extensions added, tracking in place
+
+---
+
+## Tips for Success
+
+**DO:**
+
+- Review mode choice periodically
+- Extract patterns when they repeat 3+ times
+- Document deviations and extensions
+- Keep tokens in sync with visuals
+
+**DON'T:**
+
+- Mix approaches (inline + components randomly)
+- Forget to update specs when extracting
+- Over-engineer for small projects
+- Ignore library conventions in Mode 3
+
+---
+
+## You've Completed Module 13!
+
+**Your design system mode is optimized.** You understand:
+- How your mode works
+- Where components live
+- How to extend the system
+- How to maintain consistency
+
+---
+
+## Next Module
+
+**[Module 14: Agentic Development →](../module-14-agentic-development/module-14-agentic-development-overview.md)**
+
+Generate working prototypes from your specifications.
+
+---
+
+[← Back to Lesson 1](lesson-01-understanding-modes.md) | [Back to Module Overview](module-13-design-system-overview.md)
+
+*Part of Module 13: Design System*

package/docs/learn/module-14-agentic-development/lesson-01-iterative-building.md

@@ -0,0 +1,182 @@
+# Module 14: Agentic Development
+
+## Lesson 1: The Development Design Log
+
+**How the process is organized**
+
+---
+
+## Every Session Starts with a Plan
+
+When you ask Freya to develop something, the first thing the agent does is create a **Design Log**.
+
+This isn't documentation after the fact. It's the plan *before* anything is built.
+
+The agent reads your input — a specification, a concept, an inspiration image, a rough idea — and creates:
+
+1. **Scope** — What are we building? What's the boundary?
+2. **Tasks** — Ordered steps to get there
+3. **Requirements** — Constraints we must respect (brand, accessibility, technical)
+4. **Test protocol** — How we'll verify each step is done right
+
+Then the agent starts executing. One step at a time.
+
+---
+
+## The Design Log Document
+
+```markdown
+# Design Log: Signup Form
+
+## Meta
+- Date: 2026-02-10
+- Input: P02-signup-form.md (specification)
+- Agent: Freya
+- Status: In Progress
+
+## Scope
+Build the signup form as a working prototype from the specification.
+Includes: form layout, validation, error states, loading states.
+Excludes: backend integration, email verification flow.
+
+## Tasks
+1. [x] Create form layout with all fields
+2. [x] Add real-time validation
+3. [ ] Implement error states
+4. [ ] Add loading and success states
+5. [ ] Responsive adjustments
+6. [ ] Accessibility pass
+
+## Requirements
+- Must match specification P02 exactly
+- Inter font, #0066FF primary
+- Mobile-first, max-width 400px
+- WCAG AA contrast compliance
+
+## Test Protocol
+- [ ] All text matches spec
+- [ ] All states render correctly
+- [ ] Tab navigation works
+- [ ] Touch targets 44px+
+- [ ] Contrast ratios pass
+
+## Log
+### Step 1: Form layout (completed)
+- Created form with email, password, submit
+- Matches spec layout
+- Decision: Used flexbox for vertical stacking
+
+### Step 2: Validation (completed)
+- Added blur-based validation
+- Decision: Blur instead of keypress (less jarring)
+- Spec impact: Updated storyboard to clarify trigger
+
+### Step 3: Error states (in progress)
+- ...
+```
+
+---
+
+## Why Start with the Dialog?
+
+### It forces clarity
+
+Before building, you know exactly what you're building and how you'll know it's done.
+
+### It enables restart
+
+AI conversations are ephemeral. The dialog is permanent. If you lose context, start a new session, or come back next week — load the dialog. Everything is there.
+
+### It tracks decisions
+
+"Why did we use blur validation?" The answer is in the log, not in someone's memory.
+
+### It shows progress
+
+At any point you can see: what's done, what's next, what changed.
+
+---
+
+## The Log Is the Heartbeat
+
+As you execute each step, the agent logs:
+
+- **What was built** — the output
+- **Decisions made** — and the reasoning
+- **Spec impacts** — did anything in the spec change?
+- **Issues found** — unexpected problems
+
+This log is what makes the dialog a living document, not a static plan.
+
+---
+
+## Plans Change
+
+After completing a step, you and the agent re-evaluate:
+
+- Did this step reveal something new?
+- Should priorities change?
+- Do we need to add tasks?
+- Should we remove tasks that are no longer relevant?
+- Did the scope shift?
+
+**Example:** You planned to build the password strength indicator. But after implementing the form, you realize the field is too small to show it on mobile. New task: rethink the indicator placement. Old task: build indicator as-is → removed.
+
+The plan is not a contract. It's a compass.
+
+---
+
+## Types of Agentic Sessions
+
+The same Design Log structure works for all types:
+
+| Type | Example | Agent |
+|------|---------|-------|
+| **Concept exploration** | "Dream up a dashboard layout for dog trainers" | Freya |
+| **Proof of concept** | "Can we do infinite scroll with this data model?" | Freya |
+| **Prototype** | "Build a working signup form from this spec" | Freya |
+| **Design inspiration** | "Generate 3 visual directions for the landing page" | Freya |
+| **Production code** | "Implement the complete registration scenario" | Freya |
+
+The scope and depth change. The process doesn't.
+
+---
+
+## Session Continuity
+
+### Starting a new session
+
+Load the Design Log into your new conversation:
+
+```
+"I'm continuing the signup form implementation.
+Here's the current Design Log with plan and log:
+
+[Paste dialog.md content]
+
+We completed steps 1-3. Next is step 4: loading states."
+```
+
+The agent picks up from the log, not from memory.
+
+### Handing off between agents
+
+You dreamed up a component in a design session. Now you need to build it.
+
+The Design Log travels with the work. The agent reads the previous design log and continues where it left off.
+
+---
+
+## What's Next
+
+In the next lesson, you'll learn how to evaluate results effectively and give feedback that keeps the work on track.
+
+---
+
+**[Continue to Lesson 2: Evaluation and Feedback →](lesson-02-documenting-decisions.md)**
+
+---
+
+[← Back to Module Overview](module-14-agentic-development-overview.md)
+
+*Part of Module 14: Agentic Development*