picasso-skill 2.2.0 → 2.3.0

package/agents/picasso.md

@@ -61,21 +61,38 @@ Based on the answer, determine the **engagement type**:
 
 If the user says "just fix X" -- skip the rest of the interview and go directly to the fix. Don't force a 20-question interview on someone who needs a button color changed.
 
-### Section 2: Aesthetic Direction
+### Section 2: Aesthetic Direction (VISUAL)
 
 Only ask if engagement type is Full Design or Overhaul.
 
-- "What vibe are you going for? Pick one or combine:"
-  - Minimal / clean (Linear, Notion)
-  - Bold / editorial (Stripe, Vercel)
-  - Warm / friendly (Slack, Mailchimp)
-  - Dark / technical (Raycast, Warp)
-  - Luxury / premium (Apple, Rolls-Royce)
-  - Playful / fun (Figma, Discord)
-  - Brutalist / raw (Craigslist-but-intentional)
-  - Or: "I'll know it when I see it" (you pick, I'll react)
-- "Any colors you already have? (brand colors, hex values, 'I like blue', anything)"
-- "Any fonts you're attached to, or should I pick?"
+First ask: "Any colors or fonts you already have? Any site you love the look of?"
+
+Then, instead of listing vibes as text, **show them visually**:
+
+1. Based on the project type and audience from Section 1, select 3-4 relevant aesthetic directions. Not all 7 -- only the ones that make sense for THIS project. A legal SaaS gets "Minimal/clean", "Dark/technical", "Luxury/premium". A kids' app gets "Playful/fun", "Warm/friendly", "Bold/editorial".
+
+2. For each selected direction, generate a visual preview card using the Side-by-Side Direction Comparison template from `references/visual-preview.md`. Each card shows:
+   - The direction name and a one-line vibe description
+   - A color palette strip (5 swatches)
+   - A nav bar, heading, body text, card, and buttons -- all rendered in that direction's actual fonts and colors
+
+3. Write the comparison to `/tmp/picasso-interview-vibes.html`. Open with Playwright MCP, screenshot, view with Read.
+
+4. Present to user: "Here are the directions that fit your project. Which speaks to you? Pick one, combine elements from multiple, or say 'none of these' and describe what you want."
+
+The direction options and their representative tokens:
+
+| Direction | Heading Font | Body Font | Primary | Surface | Radius |
+|-----------|-------------|-----------|---------|---------|--------|
+| Minimal/clean | Satoshi | DM Sans | slate-700 | white | 4px |
+| Bold/editorial | Clash Display | Work Sans | near-black | white | 0px |
+| Warm/friendly | Plus Jakarta Sans | DM Sans | amber-600 | warm-white | 12px |
+| Dark/technical | Geist Mono | Inter | cyan-400 | gray-950 | 2px |
+| Luxury/premium | Cormorant | IBM Plex Sans | gold | near-black | 2px |
+| Playful/fun | Outfit | DM Sans | violet-500 | pastel-bg | 16px |
+| Brutalist/raw | Space Mono | Space Mono | black | white | 0px |
+
+**Use these as starting points.** Customize based on the project context. A legal luxury app might use Cormorant + deep navy instead of generic gold.
 
 ### Section 3: Context-Driven Recommendations
 
@@ -157,9 +174,16 @@ Do NOT jump to code. Present a **Design Brief** -- a short, opinionated creative
    - What you're recommending and what you're explicitly NOT doing (and why)
    - The execution plan in priority order
 
-3. **Generate `.picasso.md`** from the answers and save to project root.
+3. **Generate a Visual Brief Preview (MANDATORY).** Before asking for confirmation:
+   - Generate a self-contained HTML page showing a representative layout in the committed design tokens (nav + hero + card + buttons + input)
+   - Use the Full Page Mood Preview structure from `references/visual-preview.md`
+   - Write to `/tmp/picasso-brief-preview.html`
+   - Open with Playwright MCP, screenshot, view with Read
+   - Present alongside the text brief: "Here's what I'm proposing -- the reasoning and a visual preview."
+
+4. **Generate `.picasso.md`** from the answers and save to project root.
 
-4. **Wait for confirmation**: "Does this direction feel right? I won't write code until you say go."
+5. **Wait for confirmation**: "Does this direction feel right? I won't write code until you say go."
 
 ### CRITICAL: The Reference Loading Rule
 
@@ -662,6 +686,7 @@ When the user invokes these commands, execute the corresponding workflow:
 | `/mood-board` | Generate visual inspiration HTML from adjectives |
 | `/design-system-sync` | Detect and fix drift between DESIGN.md and code |
 | `/preset <name>` | Apply a curated community design preset |
+| `/preview` | Visual preview of design tokens, presets, or side-by-side direction comparison |
 | `/godmode` | The ultimate command: interview + audit + score + roast + fix everything + before/after report |
 | `/quick-audit` | 5-minute fast audit: font, color, spacing, a11y, anti-slop — skip the deep dive |
 | `/autorefine` | Binary evaluation loop: define 6 criteria, mutate one thing at a time, iterate to 6/6 pass |
@@ -892,29 +917,30 @@ Compare the current project against a competitor:
 
 ### /evolve -- Iterative Design Refinement Loop
 
-Multi-round design refinement:
-1. **Round 1: Directions** -- Generate 3 distinct aesthetic directions for the page/component. Describe each in 2-3 sentences with the key differentiator. Ask user to pick one (or combine elements).
-2. **Round 2: Refinement** -- Implement the chosen direction. Screenshot it. Ask "What do you love? What's not right?"
-3. **Round 3: Polish** -- Apply feedback. Screenshot again. Ask "Are we there? Or one more round?"
-4. **Round 4+: Iterate** -- Continue until user says "ship it"
+Multi-round design refinement with visual previews at every step:
+1. **Round 1: Directions** -- Generate 3 distinct aesthetic directions. For each, generate a visual preview card using the Side-by-Side Comparison template from `references/visual-preview.md`. Write to `/tmp/picasso-evolve-round1.html`, screenshot, view, present. Ask user to pick one (or combine elements).
+2. **Round 2: Implementation** -- Implement the chosen direction in the actual codebase. Screenshot the running app. Ask "What do you love? What's not right?"
+3. **Round 3+: Refinement** -- Apply feedback. Screenshot again. Ask "Are we there? Or one more round?"
+4. Continue until user says "ship it"
 
 Rules:
-- Never generate just one option in Round 1
+- Round 1 MUST show visual previews, not just text descriptions
 - Each direction must be genuinely different (not three variations of the same thing)
 - Always screenshot between rounds so the user can SEE the change
 - Max 5 rounds before suggesting we ship (diminishing returns)
 
 ### /mood-board -- Generate Visual Inspiration
 
-When the user isn't sure what they want, generate a mood board:
+When the user isn't sure what they want, generate a visual mood board:
 1. Ask for 3-5 adjectives or reference points
-2. Search the style-presets.md for matching presets
-3. Generate a single HTML file at `/tmp/picasso-moodboard.html` that shows:
-   - Color swatches with OKLCH values
-   - Font samples at different sizes
-   - Example component (a card, a button, a hero) in that style
-   - Spacing rhythm visualization
-4. Open in browser for the user to react to
+2. Search `references/style-presets.md` for matching presets (2-4 best matches)
+3. Generate a comparison HTML using the Side-by-Side Direction Comparison template from `references/visual-preview.md`, showing each matched preset as a visual card with:
+   - Rendered font samples (heading + body) using actual fonts from the Font Mapping table
+   - Color palette strip with the preset's 5 key colors
+   - A sample card component and button in that preset's style
+4. Write to `/tmp/picasso-moodboard.html`
+5. Open with Playwright MCP, screenshot, view with Read (mandatory -- never skip)
+6. Present to user: "Based on your adjectives, these presets match. Which elements resonate?"
 
 ### /design-system-sync -- Auto-sync Code to DESIGN.md
 
@@ -928,14 +954,27 @@ Detect drift between DESIGN.md and actual code:
 
 ### /preset <name> -- Apply Community Preset
 
-Apply a curated design preset by name:
-1. Load from style-presets.md or a presets directory
-2. Generate `.picasso.md` + `DESIGN.md` from the preset
-3. Apply to the codebase:
-   - Update CSS variables / Tailwind config
-   - Update font imports
-   - Adjust component styling
-4. Available presets: linear, stripe, vercel, notion, raycast, editorial, luxury, brutalist, dark-tech, warm-saas, cyberpunk, cottage, etc.
+Apply a curated design preset by name.
+
+**When no preset name is given** (`/preset` with no arguments):
+1. Load `references/style-presets.md` to get all 22 presets
+2. Generate a **visual preset browser** using the Preset Browser Grid template from `references/visual-preview.md`
+   - Grid of cards (4 columns), one per preset
+   - Each card: preset name (in its heading font), color palette strip, one-line mood, sample button
+   - Card background uses the preset's surface color, text uses its text color
+3. Write to `/tmp/picasso-preset-browser.html`
+4. Open with Playwright MCP, screenshot, view with Read
+5. Present: "Here are all 22 presets. Which one catches your eye?"
+6. Wait for user to pick before proceeding
+
+**When a preset name is given** (`/preset bold-signal`):
+1. Load the named preset from `references/style-presets.md`
+2. Generate a **visual preview** of the preset (Full Page Mood Preview from `references/visual-preview.md`)
+3. Write to `/tmp/picasso-preset-{name}.html`, screenshot, view
+4. Present: "Here's what {name} looks like. Apply it?"
+5. After confirmation:
+   - Generate `.picasso.md` + `DESIGN.md` from the preset
+   - Apply to the codebase (CSS variables, Tailwind config, font imports, component styling)
 
 ## Advanced Automation Commands
 

package/commands/mood.md

@@ -1,17 +1,51 @@
-Run the Picasso /mood command -- generate a design system from a word.
+---
+name: mood
+description: "Generate a complete design system from a mood word, with a visual preview before committing."
+---
 
-Use the Picasso agent to generate a complete design system from the mood word: $ARGUMENTS
+# /mood -- Design System from a Word
 
-Map the mood to design tokens:
-- Color palette (5-7 OKLCH values)
-- Font pairing (display + body + mono)
-- Border radius scale
-- Shadow style
-- Motion intensity
-- Spacing density
+Generate a complete design system from a mood word or phrase, and show a visual preview before writing any config files.
 
-Generate both .picasso.md and DESIGN.md from the mood.
+## Arguments
+
+The mood word: `$ARGUMENTS`
 
 Common moods: cyberpunk, cottage, brutalist, luxury, editorial, playful, corporate, dark-tech, warm-saas, minimal. Also accepts combinations like "brutalist-banking" or "warm-editorial".
 
 If no mood word is provided, ask the user for one.
+
+## Steps
+
+1. Parse the mood word(s) and map to design tokens:
+   - Color palette (5-7 values with hex)
+   - Font pairing (display + body + mono)
+   - Border radius scale
+   - Shadow style
+   - Motion intensity
+   - Spacing density
+
+2. **Generate a visual preview (MANDATORY -- before writing any config files):**
+   - Load `references/visual-preview.md` and use the Full Page Mood Preview structure
+   - Generate a self-contained HTML page showing a representative layout in the mood's tokens:
+     - Nav bar with logo text, links, and CTA button
+     - Hero section with large heading, subtitle, and primary button
+     - 2-3 sample cards in a grid
+     - A form input with button
+     - Footer with muted text
+   - Load fonts using the Font Mapping table from `references/visual-preview.md`
+   - Write to `/tmp/picasso-mood-{word}.html`
+   - Open via Playwright MCP, screenshot at 1440x900, view with Read tool
+   - Present to user: "This is what '{word}' looks like as a design system. Does this feel right, or should I adjust?"
+
+3. **Wait for confirmation.** Do not write `.picasso.md` or `DESIGN.md` until the user approves the visual direction.
+
+4. After confirmation, generate:
+   - `.picasso.md` with the mood's tokens and preferences
+   - `DESIGN.md` with the full design system specification
+
+## Rules
+
+- Never write config files before showing the visual preview
+- If the user says "adjust" or "not quite", iterate on the tokens and regenerate the preview
+- If Playwright MCP is unavailable, write the HTML and tell user the path to open manually

package/commands/preset.md

@@ -1,14 +1,44 @@
-Run the Picasso /preset command -- apply a curated design preset.
+---
+name: preset
+description: "Browse and apply curated design presets with visual previews."
+---
 
-Use the Picasso agent to apply the named preset: $ARGUMENTS
+# /preset -- Apply a Design Preset
 
-Available presets: linear, stripe, vercel, notion, raycast, editorial, luxury, brutalist, dark-tech, warm-saas, cyberpunk, cottage, minimal, playful.
+Browse or apply a curated design preset with a visual preview before committing.
 
-Steps:
-1. Load the preset from style-presets.md reference
-2. Generate .picasso.md + DESIGN.md from the preset
-3. Update CSS variables / Tailwind config to match
-4. Update font imports
-5. Show a summary of what was applied
+## Arguments
 
-If no preset name is provided, list all available presets and ask the user to pick.
+The preset name: `$ARGUMENTS`
+
+## Steps
+
+### No preset name given (`/preset`)
+
+1. Load all 22 presets from `references/style-presets.md`
+2. Generate a **visual preset browser** using the Preset Browser Grid template from `references/visual-preview.md`:
+   - 4-column grid of cards, one per preset
+   - Each card: preset name (in its heading font), 5-swatch color palette strip, one-line mood description, a sample button in the preset's primary color and radius
+   - Card backgrounds use the preset's surface color, text uses its text color
+3. Write to `/tmp/picasso-preset-browser.html`
+4. Open with Playwright MCP, screenshot at 1440x900, view with Read
+5. Present: "Here are all 22 presets. Which one catches your eye?"
+6. Wait for the user to pick
+
+### Preset name given (`/preset bold-signal`)
+
+1. Load the named preset from `references/style-presets.md`
+2. Generate a **visual preview** using the Full Page Mood Preview structure from `references/visual-preview.md`:
+   - Nav bar, hero, cards, form, footer -- all in the preset's tokens
+3. Write to `/tmp/picasso-preset-{name}.html`, screenshot, view with Read
+4. Present: "Here's what {name} looks like applied. Want to use it?"
+5. After confirmation:
+   - Generate `.picasso.md` + `DESIGN.md` from the preset
+   - Update CSS variables / Tailwind config to match
+   - Update font imports
+   - Show a summary of what was applied
+
+## Rules
+
+- Never apply a preset without showing a visual preview first
+- If Playwright MCP is unavailable, write the HTML and give the user the file path

package/commands/preview.md

@@ -0,0 +1,52 @@
+---
+name: preview
+description: "Generate visual previews of design directions, presets, or current tokens. Shows what options actually look like before committing."
+---
+
+# /preview -- Visual Design Preview
+
+Generate and display visual previews of design options.
+
+## Usage
+
+- `/preview` -- Preview current `.picasso.md` tokens as a rendered page
+- `/preview <preset-name>` -- Preview a specific style preset (e.g., `/preview bold-signal`)
+- `/preview compare <a> <b> [c]` -- Side-by-side comparison of 2-3 presets or directions
+
+## Steps
+
+### `/preview` (current tokens)
+
+1. Read `.picasso.md` from the project root. If not found, tell the user to run `/picasso` first.
+2. Extract design tokens: fonts, colors, radius, spacing density.
+3. Load `references/visual-preview.md` and use the Full Page Mood Preview template structure.
+4. Generate a self-contained HTML file showing a complete page in the current design tokens:
+   - Nav bar, hero section, card grid, form, footer
+   - All styled with the project's committed tokens
+5. Write to `/tmp/picasso-preview.html`
+6. Open via Playwright MCP (`mcp__playwright__browser_navigate` to `file:///tmp/picasso-preview.html`)
+7. Screenshot at 1440x900, view with Read tool
+8. Present to user: "Here's what your current design tokens look like rendered. Open `/tmp/picasso-preview.html` in your browser for full resolution."
+
+### `/preview <preset-name>`
+
+1. Load `references/style-presets.md` and find the named preset.
+2. Extract its tokens (colors, fonts, radius, signature element).
+3. Generate a Full Page Mood Preview HTML using those tokens.
+4. Write, screenshot, view, present (same as above).
+
+### `/preview compare <a> <b> [c]`
+
+1. Load `references/style-presets.md` and find each named preset.
+2. Load `references/visual-preview.md` and use the Side-by-Side Direction Comparison template.
+3. Generate a comparison HTML with 2-3 direction cards side by side.
+4. Write to `/tmp/picasso-preview-compare.html`
+5. Screenshot at 1440x900 (wide enough for side-by-side), view with Read.
+6. Present: "Here are the directions compared. Which speaks to you?"
+
+## Rules
+
+- Always load font URLs from the Font Mapping table in `references/visual-preview.md`
+- If Playwright MCP is unavailable, write the file and tell the user the path to open manually
+- Never describe what the preview looks like without viewing the screenshot first
+- The HTML must be fully self-contained (inline styles, external font imports only)

package/commands/variants.md

@@ -1,18 +1,37 @@
-Run the Picasso /variants command -- generate 2-3 distinct visual directions for A/B comparison.
+---
+name: variants
+description: "Generate 2-3 distinct visual directions with side-by-side visual previews for A/B comparison."
+---
 
-Steps:
-1. Read the current project's design context (.picasso.md, DESIGN.md, or infer from code)
-2. Generate 2-3 genuinely different aesthetic directions. NOT slight variations -- each must differ in at least 3 of: font, color palette, layout structure, border-radius philosophy, motion intensity
-3. For each direction:
+# /variants -- Visual Direction Comparison
+
+Generate 2-3 genuinely different aesthetic directions and show them as a side-by-side visual preview.
+
+## Steps
+
+1. Read the current project's design context (`.picasso.md`, `DESIGN.md`, or infer from code)
+2. Study the project type, audience, and competitive landscape to inform direction choices
+3. Generate 2-3 genuinely different aesthetic directions. NOT slight variations -- each must differ in at least 3 of: font, color palette, layout structure, border-radius philosophy, motion intensity
+4. For each direction:
    - Name it (e.g., "Editorial Minimalist", "Dark Terminal", "Warm Organic")
-   - List the 5 key design tokens (font, accent color, radius, shadow style, spacing density)
-   - Describe what makes it distinctive in 1-2 sentences
-   - Show a code snippet of one component (e.g., a card or button) in that style
-4. Present all directions to the user and ask which to pursue
-5. If Playwright is available, generate a quick HTML preview of each direction
+   - List the 5 key design tokens (heading font, body font, accent color, radius, shadow style)
+   - Describe what makes it distinctive in 1 sentence
+5. **Generate a visual preview (MANDATORY):**
+   - Load `references/visual-preview.md` and use the Side-by-Side Direction Comparison template
+   - For each direction, render a preview card showing: color palette strip, nav bar, heading, body text, sample card, primary/secondary buttons, input field -- all in that direction's tokens
+   - Load fonts using the Font Mapping table from `references/visual-preview.md`
+   - Write the comparison HTML to `/tmp/picasso-variants.html`
+   - Open via Playwright MCP: `mcp__playwright__browser_navigate` to `file:///tmp/picasso-variants.html`
+   - Screenshot at 1440x900 viewport
+   - View the screenshot with the Read tool
+6. Present the visual comparison to the user: "Here are the directions. Which speaks to you? Pick one, combine elements, or reject all."
+7. Also tell the user: "Open `/tmp/picasso-variants.html` in your browser for full resolution."
+
+## Rules
 
-Rules:
 - Each direction must pass the 3-second anti-slop test independently
-- No two directions can share the same font
+- No two directions can share the same heading font
 - At least one direction must be surprising or unconventional
 - Always include one "safe" option and one "bold" option
+- Visual preview is MANDATORY, not optional. If Playwright MCP is unavailable, write the HTML file and tell the user the path to open manually.
+- Never describe what the directions look like without viewing the screenshot first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picasso-skill",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
   "bin": {
     "picasso-skill": "./bin/install.mjs"

package/references/visual-preview.md

@@ -0,0 +1,359 @@
+# Visual Preview Reference
+
+Generate self-contained HTML previews to show users what design options look like before they commit. This replaces text-only descriptions with actual visual examples.
+
+---
+
+## 1. The Preview Protocol
+
+Every time Picasso presents 2+ aesthetic options for the user to choose from, generate a visual preview. Text-only option lists are banned for aesthetic decisions.
+
+### Standard Flow
+
+1. **Generate** a self-contained HTML file with inline styles and font imports
+2. **Write** to `/tmp/picasso-preview-{name}.html`
+3. **Open** via Playwright MCP: `mcp__playwright__browser_navigate` to `file:///tmp/picasso-preview-{name}.html`
+4. **Screenshot** via `mcp__playwright__browser_take_screenshot`
+5. **View** the screenshot with `Read` tool (mandatory -- never skip this)
+6. **Present** to the user with the file path so they can also open it in their browser
+
+### If Playwright MCP Is Unavailable
+
+1. Write the HTML file to `/tmp/`
+2. Tell the user: "I've generated a visual preview at `/tmp/picasso-preview-{name}.html` -- open it in your browser to see the options."
+3. Do NOT make visual claims about what the preview looks like without viewing it
+
+### File Naming
+
+- Interview aesthetics: `/tmp/picasso-interview-vibes.html`
+- Design brief preview: `/tmp/picasso-brief-preview.html`
+- Variants comparison: `/tmp/picasso-variants.html`
+- Mood preview: `/tmp/picasso-mood-{word}.html`
+- Preset browser: `/tmp/picasso-preset-browser.html`
+- Standalone preview: `/tmp/picasso-preview.html`
+
+---
+
+## 2. HTML Template: Side-by-Side Direction Comparison
+
+Use this when showing 2-4 aesthetic directions for the user to choose from (interview, /variants, /preview compare).
+
+Generate the full HTML dynamically. For each direction, substitute the actual font, colors, radius, and spacing values. The template below is a structural guide -- adapt the content to match each specific direction.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Picasso: Choose a Direction</title>
+<!-- Import fonts for all directions shown -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family={FONT_1}&family={FONT_2}&family={FONT_3}&display=swap" rel="stylesheet">
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: system-ui, sans-serif;
+    background: #f5f5f5;
+    padding: 32px;
+    color: #1a1a1a;
+  }
+  h1 {
+    text-align: center;
+    font-size: 20px;
+    font-weight: 600;
+    margin-bottom: 8px;
+    letter-spacing: -0.02em;
+  }
+  .subtitle {
+    text-align: center;
+    font-size: 13px;
+    color: #666;
+    margin-bottom: 32px;
+  }
+  .grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(340px, 1fr));
+    gap: 24px;
+    max-width: 1200px;
+    margin: 0 auto;
+  }
+  .direction {
+    border-radius: 12px;
+    overflow: hidden;
+    box-shadow: 0 2px 12px rgba(0,0,0,0.08);
+  }
+  .direction-label {
+    padding: 12px 16px;
+    font-size: 13px;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    background: #fff;
+    border-bottom: 1px solid #eee;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+  .direction-label span {
+    font-size: 11px;
+    font-weight: 400;
+    text-transform: none;
+    letter-spacing: 0;
+    color: #999;
+  }
+  /* Each .preview is a mini page rendered in the direction's style */
+  .preview {
+    padding: 24px;
+    min-height: 400px;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+  }
+  /* Palette strip */
+  .palette {
+    display: flex;
+    gap: 4px;
+    height: 24px;
+    border-radius: 4px;
+    overflow: hidden;
+  }
+  .palette .swatch {
+    flex: 1;
+    position: relative;
+  }
+  /* Sample nav */
+  .sample-nav {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 8px 0;
+  }
+  .sample-nav .logo {
+    font-weight: 700;
+    font-size: 15px;
+  }
+  .sample-nav .links {
+    display: flex;
+    gap: 16px;
+    font-size: 12px;
+    opacity: 0.6;
+  }
+  /* Sample card */
+  .sample-card {
+    padding: 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .sample-card h3 {
+    font-size: 16px;
+    font-weight: 600;
+  }
+  .sample-card p {
+    font-size: 12px;
+    line-height: 1.6;
+    opacity: 0.7;
+  }
+  /* Sample button */
+  .sample-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 8px 20px;
+    font-size: 12px;
+    font-weight: 600;
+    border: none;
+    cursor: pointer;
+    width: fit-content;
+  }
+  /* Sample input */
+  .sample-input {
+    padding: 8px 12px;
+    font-size: 12px;
+    border: 1px solid;
+    background: transparent;
+    width: 100%;
+  }
+  /* Font info footer */
+  .font-info {
+    font-size: 10px;
+    opacity: 0.4;
+    padding-top: 8px;
+    border-top: 1px solid;
+    border-color: inherit;
+  }
+</style>
+</head>
+<body>
+
+<h1>Choose a Direction</h1>
+<p class="subtitle">Pick one, combine elements, or describe something different.</p>
+
+<div class="grid">
+
+  <!-- Direction A -->
+  <div class="direction">
+    <div class="direction-label">
+      A: {DIRECTION_A_NAME}
+      <span>{DIRECTION_A_VIBE}</span>
+    </div>
+    <div class="preview" style="background: {A_BG}; color: {A_TEXT}; font-family: '{A_BODY_FONT}', sans-serif;">
+      <div class="palette">
+        <div class="swatch" style="background: {A_COLOR_1};"></div>
+        <div class="swatch" style="background: {A_COLOR_2};"></div>
+        <div class="swatch" style="background: {A_COLOR_3};"></div>
+        <div class="swatch" style="background: {A_COLOR_4};"></div>
+        <div class="swatch" style="background: {A_COLOR_5};"></div>
+      </div>
+      <div class="sample-nav">
+        <div class="logo" style="font-family: '{A_HEADING_FONT}', sans-serif;">AppName</div>
+        <div class="links">Features &nbsp; Pricing &nbsp; Docs</div>
+      </div>
+      <div style="font-family: '{A_HEADING_FONT}', sans-serif; font-size: 22px; font-weight: 700; line-height: 1.2; letter-spacing: -0.02em;">
+        Build something people actually want
+      </div>
+      <div style="font-size: 13px; line-height: 1.6; opacity: 0.7;">
+        A short description that shows what body text looks like in this direction. Notice the font, weight, and spacing.
+      </div>
+      <div class="sample-card" style="background: {A_SURFACE}; border-radius: {A_RADIUS};">
+        <h3 style="font-family: '{A_HEADING_FONT}', sans-serif;">Sample Card</h3>
+        <p>This is how cards look in this direction. Pay attention to padding, radius, and depth.</p>
+      </div>
+      <div style="display: flex; gap: 8px;">
+        <div class="sample-btn" style="background: {A_PRIMARY}; color: {A_PRIMARY_TEXT}; border-radius: {A_RADIUS};">
+          Primary Action
+        </div>
+        <div class="sample-btn" style="background: transparent; color: {A_TEXT}; border: 1px solid {A_BORDER}; border-radius: {A_RADIUS};">
+          Secondary
+        </div>
+      </div>
+      <div class="sample-input" style="border-color: {A_BORDER}; border-radius: {A_RADIUS}; color: {A_TEXT};" placeholder="Input field...">
+        Input field...
+      </div>
+      <div class="font-info">
+        {A_HEADING_FONT} + {A_BODY_FONT} &middot; {A_RADIUS} radius
+      </div>
+    </div>
+  </div>
+
+  <!-- Repeat for Direction B, C, D... -->
+
+</div>
+
+</body>
+</html>
+```
+
+### How to Use This Template
+
+1. Do NOT copy-paste this template literally. Generate the HTML dynamically with actual values substituted for each direction.
+2. Each `{PLACEHOLDER}` must be replaced with real values from the direction you're previewing.
+3. The font `<link>` tag must include ALL fonts used across ALL directions being compared.
+4. The number of directions (2, 3, or 4) determines the grid columns.
+5. Keep the preview compact -- users should see all options without scrolling.
+
+---
+
+## 3. HTML Template: Full Page Mood Preview
+
+Use this for /mood and Design Brief previews. Shows a complete page layout in the specified style.
+
+Generate a full-page HTML that includes:
+- A navigation bar with logo text, 3-4 links, and a CTA button
+- A hero section with a large heading, subtitle, and primary button
+- A 3-column feature/card section
+- A form section with an input and button
+- A footer with muted text
+
+All styled with the mood's tokens (colors, fonts, radius, spacing). The content should be generic but realistic (not lorem ipsum). Size the page to 1440px viewport width.
+
+---
+
+## 4. HTML Template: Preset Browser Grid
+
+Use this for /preset without arguments. Shows all presets as a browsable grid.
+
+Generate an HTML page with:
+- A title: "Picasso Style Presets"
+- A grid of cards (4 columns, wrapping), one per preset
+- Each card shows:
+  - Preset name (in the preset's heading font)
+  - A 5-swatch color palette strip
+  - A one-line mood description
+  - A tiny sample button in the preset's primary color and radius
+- Cards should be ~280px wide, ~180px tall
+- The card background should use the preset's surface color
+- Card text should use the preset's text color
+
+This gives users a visual catalog to browse before choosing.
+
+---
+
+## 5. Font Loading
+
+### Google Fonts
+
+Most fonts can be loaded via Google Fonts. Construct the URL:
+```
+https://fonts.googleapis.com/css2?family={FontName}:wght@400;600;700&display=swap
+```
+
+Replace spaces with `+` in font names.
+
+### Fontshare (for fonts not on Google)
+
+Some popular Picasso fonts are on Fontshare:
+```
+https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&display=swap
+https://api.fontshare.com/v2/css?f[]=cabinet-grotesk@400,700,800&display=swap
+https://api.fontshare.com/v2/css?f[]=general-sans@400,500,600&display=swap
+https://api.fontshare.com/v2/css?f[]=clash-display@400,600,700&display=swap
+```
+
+### Common Font Mappings
+
+| Font Name | Source | Import URL |
+|-----------|--------|-----------|
+| Satoshi | Fontshare | `https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&display=swap` |
+| Cabinet Grotesk | Fontshare | `https://api.fontshare.com/v2/css?f[]=cabinet-grotesk@400,700,800&display=swap` |
+| General Sans | Fontshare | `https://api.fontshare.com/v2/css?f[]=general-sans@400,500,600&display=swap` |
+| Clash Display | Fontshare | `https://api.fontshare.com/v2/css?f[]=clash-display@400,600,700&display=swap` |
+| Archivo Black | Google | `family=Archivo+Black&display=swap` |
+| Manrope | Google | `family=Manrope:wght@300;400;500;600;700;800&display=swap` |
+| Syne | Google | `family=Syne:wght@400;600;700;800&display=swap` |
+| Space Mono | Google | `family=Space+Mono:wght@400;700&display=swap` |
+| Cormorant | Google | `family=Cormorant:ital,wght@0,400;0,600;1,400&display=swap` |
+| IBM Plex Sans | Google | `family=IBM+Plex+Sans:wght@300;400;500;600&display=swap` |
+| DM Sans | Google | `family=DM+Sans:wght@400;500;600;700&display=swap` |
+| Plus Jakarta Sans | Google | `family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap` |
+| Outfit | Google | `family=Outfit:wght@300;400;500;600;700&display=swap` |
+| Fraunces | Google | `family=Fraunces:ital,wght@0,400;0,600;1,400&display=swap` |
+| Work Sans | Google | `family=Work+Sans:wght@400;500;600;700&display=swap` |
+| JetBrains Mono | Google | `family=JetBrains+Mono:wght@400;500;700&display=swap` |
+| Bodoni Moda | Google | `family=Bodoni+Moda:ital,wght@0,400;0,700;1,400&display=swap` |
+| Inter | Google | `family=Inter:wght@400;500;600;700&display=swap` |
+| Geist | Local/Vercel | Use `system-ui` as fallback in previews |
+
+### Fallback Rule
+
+If a font fails to load (offline, CORS, not available), the preview should still render correctly using `system-ui, -apple-system, sans-serif` as fallback. The font name should be displayed in the `.font-info` footer so the user knows what was intended.
+
+---
+
+## 6. The Show-Don't-Tell Rule
+
+| Decision Type | Show Visual? | Why |
+|---------------|-------------|-----|
+| Aesthetic direction / vibe | YES | Users can't imagine "Bold Signal" from text |
+| Color palette | YES | Hex values mean nothing without seeing them |
+| Font pairing | YES | Font names mean nothing without rendering them |
+| Layout structure | YES | "Asymmetric grid" means different things to everyone |
+| Animation intensity | NO | Must be experienced in running code, not a static preview |
+| Mobile priority level | NO | A number (1-5) is sufficient |
+| Accessibility level | NO | A standard (AA/AAA) is sufficient |
+| Performance budget | NO | A number is sufficient |
+| Sound/haptics | NO | Must be experienced in running code |
+
+The rule: if the decision involves how something LOOKS, show it. If it involves behavior, policy, or priority, text is fine.