whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-15-visual-design/lesson-02-visual-techniques.md

@@ -0,0 +1,334 @@
+# Module 15: Visual Design
+
+## Lesson 2: Visual Design Techniques
+
+**Practical methods for generating and refining visuals**
+
+---
+
+## Three Methods
+
+In WDS, visual design happens through three categories of tools. You'll likely use a combination depending on the task.
+
+### 1. Figma — Precision Design
+
+Figma is where you go for pixel-level control. In WDS, you don't live in Figma — but you visit it when the agent can't get the details right.
+
+**How you get code into Figma:**
+
+**code.to.design** — a plugin that imports your HTML prototypes directly into Figma as editable layers. Your working prototype becomes a Figma file you can manipulate with all the precision Figma offers. When you're done, export back to code.
+
+**How Figma talks to your agent:**
+
+**Figma MCP** — connects your AI coding agent directly to Figma. The agent can read your Figma designs, extract styles, colors, spacing, and typography, and apply them to code — without you manually exporting or copying values.
+
+**Best for:**
+- Fine-tuning visual details the agent can't get right
+- Establishing the visual language for a project
+- Working with brand elements that need a designer's eye
+- Exploring visual directions before committing to code
+- Handing off precise specifications to developers
+
+---
+
+### 2. Image Generators — Visual Assets and Inspiration
+
+AI image generation creates visual assets — hero photos, card images, persona illustrations, mood boards — that feed into your designs. These aren't working code or editable layouts. They're image assets.
+
+**Nanobanana MCP (Gemini 2.5 Flash / Gemini 3 Pro)** — generates images directly from your AI coding agent and saves them to your repository. We've tested this extensively and learned what it does well and what it doesn't.
+
+**What NB does well:**
+- **Image assets** — Hero photos, card images, seasonal photos, persona illustrations
+- **Mood visualization** — Captures atmosphere and visual direction
+- **Style transfer** — Reference images influence the generated style
+- **Quick exploration** — Fast to generate multiple visual directions
+
+**What NB does NOT do well (critical limitations):**
+- **All text is garbled** — AI-rendered text is never readable. Never trust it.
+- **Logos cannot be reproduced** — Generates "inspired by" versions, not the real logo
+- **Cannot edit results** — If something is wrong, you regenerate entirely. You cannot move, resize, or adjust elements.
+- **Wireframe labels leak into mockups** — Annotation text bleeds through in edit mode
+- **2x2 grids flatten** — Multi-row layouts are a consistent weak point
+- **Broad edits cause section loss** — Unfocused instructions drop entire sections
+
+**NB is an asset production tool, not a design tool.** The images are excellent as placeholders and visual references, but you cannot iterate on them the way you can with code or Figma. For wireframing, use Excalidraw. For production mockups, use Stitch or code generation.
+
+**Best for:**
+- Hero photos, card images, seasonal visuals, background images
+- Persona illustrations for Trigger Map documents
+- Mood boards and visual direction exploration
+- Placeholder imagery during prototyping
+
+For detailed guidance on AI wireframe generation (and why we recommend against it for iterative design), see [Module 09, Lesson 6: AI Wireframe Generation](../module-09-conceptual-sketching/lesson-06-ai-wireframe-generation.md).
+
+---
+
+### 3. UI Generators — Working Interfaces from Prompts
+
+UI generators produce working interfaces — real HTML/CSS/React that you can interact with in the browser. This is the core WDS workflow.
+
+**AI code generation (Claude, GPT, etc.)** — the agent generates working code directly from your specifications. You give it a spec, it builds a prototype. You click buttons, fill in forms, see hover states. This is real code, not a picture.
+
+```
+You: "Build the signup form from spec P02. Use our design tokens.
+      Primary #0066FF, Inter font, 8px spacing scale."
+
+Agent: Creates working HTML/CSS with all elements,
+       states, and interactions from the spec.
+
+You: Open in browser. Review. Give feedback.
+```
+
+**Google Stitch** — Google's AI UI design tool that generates real HTML/CSS code from text prompts or wireframe images. Available as an API with MCP server integration. Produces production-quality layouts with readable text, proper structure, and Figma export. 350 standard + 50 experimental generations per month.
+
+**Best for:**
+- Building working prototypes from specifications
+- Iterating on layout, structure, and behavior
+- Creating the production foundation
+- Testing interactions and responsive behavior
+
+---
+
+## This Is Evolving
+
+We are actively exploring these techniques as tools and capabilities develop rapidly. New image generation models, UI-specific generators, and Figma integrations appear regularly.
+
+**What we've tested:**
+- **Nanobanana MCP** for image generation — excellent for image assets (hero photos, card images, persona illustrations). Not suitable for wireframes or mockups due to garbled text, non-editable output, and layout limitations. See [Module 09, Lesson 6](../module-09-conceptual-sketching/lesson-06-ai-wireframe-generation.md) for detailed findings.
+- **code.to.design** for Figma round-trips — established workflow
+- **Figma MCP** for reading designs into code — works
+- **AI code generation** (Claude, GPT) for UI building — core WDS workflow
+- **Google Stitch** for UI generation — API and MCP available, generates real HTML/CSS
+
+**Recommended tool roles (as of February 2026):**
+
+| Tool | Role | Why |
+|------|------|-----|
+| **Excalidraw** | Wireframes | Editable, fast iteration, user can drag and resize |
+| **Nano Banana** | Image assets | Hero photos, card images, illustrations, mood visuals |
+| **Google Stitch** | Production mockups | Real HTML/CSS output, readable text, Figma export |
+| **Figma** | Final polish | Pixel-level refinement, design system management |
+| **AI code gen** | Prototypes | Working interactive prototypes from specs |
+
+**Share your experience:** If you discover techniques that work well, or tools we haven't covered, share them in the Discord forum **#UX-design-channel**. This course evolves based on what the community learns together.
+
+---
+
+## Prompting for Visual Output
+
+Whether you're generating code, images, or Figma designs, the quality of your output depends on the quality of your input.
+
+### Prompt Structure for Code Generation
+
+```
+Generate [element type] based on this specification:
+
+[Paste your specification]
+
+Visual requirements:
+- Font: [font family]
+- Primary color: [hex code]
+- Background: [color/style]
+- Size: [dimensions or responsive]
+
+Focus on: [what's most important]
+```
+
+### Example
+
+```
+Generate a signup form based on this specification:
+
+## Signup Form
+- Email field (required, validates email format)
+- Password field (required, 8+ chars, show/hide toggle)
+- Submit button: "Create Free Account"
+- Terms link below
+- Login link for existing users
+
+Visual requirements:
+- Font: Inter
+- Primary color: #0066FF
+- Background: White with subtle gray (#F9FAFB)
+- Size: Mobile-first (max-width 400px)
+
+Focus on: Clean, minimal, low friction
+```
+
+### Prompt Tips for Image Generation
+
+When generating visual concepts or mood boards:
+
+- Describe the feeling, not just the elements ("warm, inviting, professional" not just "signup form")
+- Reference styles ("in the style of Stripe's marketing pages")
+- Specify what you'll use the image for ("mood board for the onboarding flow")
+- Include constraints ("mobile-first, accessible, brand colors #0066FF and #1A1A2E")
+
+---
+
+## Refining Generated Output
+
+AI output is a starting point, not a final product. Regardless of which method you used, here's what to check and refine.
+
+### Spacing
+
+- AI often under- or over-spaces
+- Adjust for visual rhythm
+- Ensure breathing room around elements
+
+### Typography
+
+- Check font weights
+- Verify line heights
+- Adjust size hierarchy
+
+### Colors
+
+- Verify contrast ratios
+- Check hover states
+- Ensure consistency with tokens
+
+### Touch Targets
+
+- Buttons 44px minimum
+- Adequate spacing between tap targets
+- Test on actual devices
+
+---
+
+## Designing States
+
+Each interactive element needs its states designed:
+
+### Default
+
+The initial appearance. What users see on load.
+
+### Hover
+
+Feedback on mouseover:
+- Slight color change (10% darker)
+- Subtle shadow or elevation
+- Cursor change
+
+### Active/Pressed
+
+Feedback on click:
+- Darker than hover
+- Slight scale down (98%)
+- Pressed appearance
+
+### Focus
+
+For keyboard navigation — must be visible:
+- Outline (2px solid)
+- Offset from element
+- Sufficient contrast
+
+### Disabled
+
+When interaction is blocked:
+- Reduced opacity (50-60%)
+- No hover effects
+- Cursor: not-allowed
+
+### Loading
+
+During async operations:
+- Spinner or skeleton
+- Reduced interactivity
+- Progress indication
+
+### Error
+
+When something fails:
+- Error color (usually red)
+- Clear message
+- Recovery path visible
+
+---
+
+## Accessibility in Visual Design
+
+### Color Contrast
+
+- Text on background: 4.5:1 minimum (WCAG AA)
+- Large text (18px+): 3:1 minimum
+- UI components: 3:1 minimum
+
+**Tools:** Contrast checkers in Figma, browser extensions
+
+### Focus Visibility
+
+- Focus rings must be visible
+- 3:1 contrast against background
+- Don't hide on mouse use
+
+### Touch Targets
+
+- Minimum 44x44px for touch
+- 24x24px for precise mouse input
+- Adequate spacing between targets
+
+---
+
+## Consistency Patterns
+
+### Token Application
+
+Apply tokens consistently:
+
+```css
+/* All primary buttons use same color */
+.btn-primary {
+  background: var(--color-primary);
+  color: var(--color-text-on-primary);
+}
+
+/* All headings use same scale */
+h1 { font: var(--type-heading-1); }
+h2 { font: var(--type-heading-2); }
+
+/* All spacing uses same scale */
+.card { padding: var(--space-lg); }
+.stack > * + * { margin-top: var(--space-md); }
+```
+
+### Component Reuse
+
+Same component, same styling:
+- Buttons look identical across pages
+- Inputs behave the same everywhere
+- Cards have consistent structure
+
+---
+
+## Visual Design Checklist
+
+For each page:
+
+- [ ] Layout matches specification
+- [ ] Visual hierarchy correct (primary element dominates)
+- [ ] Typography applied from tokens
+- [ ] Colors from palette/brand
+- [ ] Spacing consistent (uses token scale)
+- [ ] All states designed (default, hover, loading, error, etc.)
+- [ ] Contrast ratios pass WCAG
+- [ ] Touch targets adequate
+- [ ] Responsive behavior defined
+
+---
+
+## What's Next
+
+In the tutorial, you'll generate and refine visuals for your own specifications, working through the design loop until you have polished, validated prototypes.
+
+---
+
+**[Continue to Tutorial: Create Your Visuals →](tutorial-15.md)**
+
+---
+
+[← Back to Lesson 1](lesson-01-making-it-visible.md) | [Back to Module Overview](module-15-visual-design-overview.md)
+
+*Part of Module 15: Visual Design*

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

@@ -0,0 +1,338 @@
+# Module 15: Visual Design
+
+**Time: 60 min | Agent: Freya | Phase: Design | Focus: Visual**
+
+---
+
+## The Big Shift
+
+In WDS, visual design lives in the codebase.
+
+There is no ambitious Figma structure or Photoshop file to maintain. WDS is specifications and code centric. Your design artifacts are working prototypes, not static mockups.
+
+This doesn't mean you never open Figma. It means Figma is a tool you reach for when you need it — not where your design lives.
+
+---
+
+## Designing with Soul
+
+LLMs are remarkably good at generating functional, clean, well-structured interfaces. They are remarkably weak at creative, visionary, and emotionally resonant design.
+
+An AI agent can build a signup form that follows every best practice. But it won't dream up the visual language that makes your product feel like *yours*. It won't make the bold typographic choice, the unexpected color palette, the playful micro-interaction that gives a product its soul.
+
+**As of February 2026, we recommend having a visual designer set the visual language as you develop the product.** This doesn't mean you need a designer on every screen. It means someone with a design eye should establish:
+
+- The overall aesthetic direction
+- Brand expression in the UI
+- Typographic personality
+- Color relationships beyond "primary, secondary, error"
+- The small details that make good design feel great
+
+Once the visual language is set, the agent can apply it consistently. But the language itself needs a human author.
+
+---
+
+## Visual Design Is Not a Step — It's a Layer
+
+In traditional workflows, visual design is a phase you reach after wireframing. In WDS, visual design can enter the project at any point where it adds value.
+
+Here is the full WDS process. At each step, you can choose to introduce visual design — or not.
+
+```
+  WDS Process                        Visual Design Can Enter As...
+  ───────────                        ────────────────────────────
+
+  Project Setup ──────────────────── Brand references, mood boards,
+       │                             design system inspiration,
+       │                             existing visual identity
+       ▼
+  Outline Scenarios
+       │
+       ▼
+  Conceptual Sketching ──────────── Visual concepts instead of
+       │                             wireframe-level sketches,
+       │                             AI-generated inspiration
+       ▼
+  Storyboarding ─────────────────── Designed visualizations with
+       │                             visual fidelity from the start,
+       │                             styled storyboard frames
+       ▼
+  Specifications ────────────────── Visual references and inspiration
+       │                             images embedded directly in specs,
+       │                             color and typography decisions
+       ▼
+  Components + Design System ────── Component-level visual design,
+       │                             design tokens, patterns,
+       │                             branded component library
+       ▼
+  Prototyping ───────────────────── Visual polish applied directly
+       │                             to working code, styled
+       │                             prototypes from the start
+       ▼
+  ★ Visual Design Phase ★ ──────── Prototypes opened in Figma or
+       │                             refined with design tools,
+       │                             soul added to working code,
+       │                             final visual refinement
+       ▼
+  Delivery
+```
+
+The more visual design you introduce early, the less you need to do in this phase. Some projects arrive here with prototypes that already look finished. Others arrive with functional wireframes that need a full visual pass. Both are valid.
+
+---
+
+## How Visual Design Works at Each Step
+
+### At project setup
+
+You establish the visual direction before any design work begins. Mood boards, brand guidelines, reference sites, inspiration collections. These inform every decision downstream.
+
+> "Here's our brand. Here's the feeling we want. Here are three sites that nail the aesthetic."
+
+### At conceptual sketching
+
+Instead of rough wireframes, you create visual concepts. AI can generate styled layouts from a description. You use these to explore direction — not as final designs, but as visual thinking.
+
+> "Generate three visual directions for the landing page based on this brief."
+
+### At storyboarding
+
+Your storyboard frames can carry visual fidelity. Instead of gray boxes, the frames show colors, typography, and imagery. This helps stakeholders react to the experience, not just the structure.
+
+### At specifications
+
+You embed visual references directly in your specs. A color note here, a typography decision there, an inspiration screenshot attached. The spec carries visual intent alongside functional requirements.
+
+### At component + design system level
+
+Your design tokens (colors, fonts, spacing) are defined. Your component library carries the visual identity. Everything built from this point inherits the design automatically.
+
+### At prototyping
+
+When the agent builds a prototype using your design system, it already looks designed. You review and refine — adjusting what the agent didn't get right, adding details that need a human eye.
+
+### At the visual design phase (this module)
+
+This is the dedicated pass where you ensure everything has the right soul. Open prototypes in Figma, refine details the agent missed, adjust visual hierarchy, add polish. Then bring it back to code.
+
+---
+
+## Your Level of Control
+
+**You maintain 100% control over the final design.**
+
+AI generates. You direct. The degree to which you intervene is up to you:
+
+| Comfort Level | Approach |
+|---------------|----------|
+| Full control | Generate → Open in Figma → Refine every detail → Export back to code |
+| Collaborative | Generate → Adjust in code → Open specific elements in Figma → Return to code |
+| AI-forward | Generate → Review → Refine with AI prompts → Final polish in code |
+
+There is no wrong approach. Use whatever gives you confidence in the result.
+
+---
+
+## Tools
+
+### AI Code Generation
+
+The agent generates HTML/CSS from your specifications. You review the output in your browser and refine through the Design Log process (Module 14).
+
+### Figma
+
+Reach for Figma when you need to:
+
+- Add soul that AI didn't capture
+- Fine-tune visual details pixel by pixel
+- Work with brand elements that need a designer's eye
+- Explore visual directions before committing to code
+
+You interact with Figma through two tools:
+
+**code.to.design** — imports your HTML prototypes directly into Figma as editable layers. Refine in Figma, then export back to code. Round-trip as many times as you need.
+
+**Figma MCP** — connects your AI coding agent directly to Figma. The agent can read your Figma designs, extract styles, and apply them to code — without you manually exporting or copying values.
+
+### AI Visual Tools — What We've Learned
+
+Different AI tools serve different purposes in visual design. Here's what works based on real project testing:
+
+| Tool | Best For | Limitation |
+|------|----------|------------|
+| **Excalidraw** | Wireframes, layout iteration | Manual, no AI generation |
+| **Nano Banana** | Image assets (hero photos, card images, personas) | Cannot render text, output is non-editable |
+| **Google Stitch** | Production HTML/CSS mockups | Requires Google Cloud setup |
+| **Figma** | Final visual polish, pixel-level refinement | Manual, slower |
+| **AI code gen** | Interactive prototypes | May need visual refinement |
+
+**Nano Banana is an asset production tool, not a design tool.** It generates excellent placeholder images but cannot produce wireframes or mockups suitable for iterative design. All text is garbled, output cannot be edited. For the full analysis, see [Module 09, Lesson 6: AI Wireframe Generation](../module-09-conceptual-sketching/lesson-06-ai-wireframe-generation.md).
+
+**Recommended workflow for page design:**
+1. **Excalidraw** — Sketch and iterate on layout (editable, user controls)
+2. **Nano Banana** — Generate image assets (hero photos, card images, seasonal visuals)
+3. **Stitch or code gen** — Generate production HTML/CSS from approved wireframe
+
+### AI Asset Generation (Phase 6 Pipeline)
+
+WDS Phase 6 provides a full **creative production pipeline** for generating visual assets with AI:
+
+```
+[W] Wireframes       — Structural layouts from page specs
+[P] Page Designs     — Full page compositions
+[U] UI Elements      — Buttons, cards, forms, components
+[I] Icons            — Icon sets matching your design system
+[M] Images           — Photos, illustrations, backgrounds
+[V] Videos           — Motion content and animations
+[C] Content          — Strategic text (5-model framework)
+[E] Export to Figma  — Push assets to Figma
+```
+
+Each activity uses **style libraries** — predefined design styles (minimal, corporate, brutalist, organic, playful, editorial) and content styles (photorealistic, illustration, watercolor, isometric, flat design, etc.) with prompt keywords for consistent AI generation.
+
+**Batch mode** generates all assets of a type in one session, using earlier results as reference images for visual consistency across the set.
+
+---
+
+## The Freya Method
+
+Freya connects visuals to strategy:
+
+> "This visual is beautiful, but does it match Felix's need for simplicity?"
+> "The color contrast here might cause accessibility issues."
+> "Your spec says primary CTA — but visually the secondary button draws more attention."
+
+She keeps visuals aligned with intent — whether you're working in code or Figma.
+
+---
+
+## What to Design
+
+### For Each Page
+
+1. **Layout** — Position of elements
+2. **Visual hierarchy** — What draws attention first
+3. **Typography** — Font choices, sizes, weights
+4. **Colors** — From your palette or brand
+5. **Spacing** — Rhythm and breathing room
+6. **States** — Hover, active, error, etc.
+
+### Don't Forget
+
+- Empty states
+- Loading states
+- Error states
+- Mobile responsive (if applicable)
+
+---
+
+## Design Tokens
+
+If using Design System (Modes 2-4), extract tokens:
+
+```yaml
+colors:
+  primary: "#0066FF"
+  secondary: "#6B7280"
+  error: "#DC2626"
+
+typography:
+  heading: "Inter, 24px, 700"
+  body: "Inter, 16px, 400"
+
+spacing:
+  sm: "8px"
+  md: "16px"
+  lg: "24px"
+```
+
+Tokens ensure consistency across all visuals — in code and in Figma.
+
+---
+
+## Output
+
+Visual prototypes for each page, living in the codebase:
+
+```
+C-UX-Scenarios/
+└── S01-User-Registration/
+    ├── scenario-overview.md
+    ├── P01-signup-form.md
+    ├── P01-signup-form.html    ← Visual prototype
+    └── P02-welcome-screen.md
+```
+
+---
+
+## What You'll Learn
+
+### Lesson 1: Making It Visible
+
+From specification to visual reality. The visual design loop — generate, review, refine. Working with design tokens, applying visual direction to prototypes, and choosing when to work in code versus Figma.
+
+### Lesson 2: Visual Design Techniques
+
+Three methods for creating visual output: Figma round-trips with code.to.design, AI image generation for concepts and inspiration, and AI UI generation for styled prototypes. How to prompt for visual output, refine generated results, design all states, and maintain consistency.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Design before spec | Spec first, always |
+| Living in Figma | Code is home, Figma is a visit |
+| Ignoring states | Design all states |
+| Inconsistent styling | Use design tokens |
+| Forgetting accessibility | Check contrast, sizes |
+| Over-designing | Keep it simple |
+
+---
+
+## The Test
+
+Does your visual match your specification exactly?
+
+If there's a difference, update either the spec or the visual. Never leave mismatches.
+
+---
+
+## Practice
+
+Take one specification from Module 11:
+
+1. Generate visual prototype with AI
+2. Review against spec
+3. Refine — in code or via Figma round-trip
+4. Verify all states are designed
+5. Confirm: does it match the spec?
+
+---
+
+## Lessons
+
+### [Lesson 1: Making It Visible](lesson-01-making-it-visible.md)
+From specification to visual reality
+
+### [Lesson 2: Visual Design Techniques](lesson-02-visual-techniques.md)
+Practical methods for generating and refining visuals
+
+---
+
+## Tutorial
+
+### [Tutorial 15: Create Your Visuals](tutorial-15.md)
+Hands-on guide to generating and refining visual designs
+
+---
+
+## Next Module
+
+**[Module 16: Design Delivery →](../module-16-design-delivery/module-16-design-delivery-overview.md)**
+
+Package and deliver your design.
+
+---
+
+*Part of the WDS Course: From Designer to Linchpin*