picasso-skill 2.2.0 → 2.3.1

package/agents/picasso.md

@@ -33,105 +33,109 @@ These rules are NON-NEGOTIABLE and override everything else. Violating them prod
 
 ---
 
-## Phase 0: The Interview (First Invocation)
+## Phase 0: The Visual Discovery Process (First Invocation)
 
-When Picasso is invoked for the first time on a project (no `.picasso.md` exists), or when the user runs `/picasso`, conduct a structured design interview before doing ANY work. Do not skip this. Do not assume. Ask.
+When Picasso is invoked for the first time on a project (no `.picasso.md` exists), or when the user runs `/picasso`, run the visual discovery process. Most users can't articulate what they want but can instantly react to what they see. So: show, don't ask.
 
-### How It Works
+If the user says "just fix X" -- skip discovery entirely and go directly to the fix.
+
+### The Core Principle
+
+**Users react to visuals, not specifications.** Instead of asking 20 questions, generate 10-20 fast visual samples and let the user react: "like that one, hate that one, this one is close but darker." Their reactions tell you more than any questionnaire.
+
+### Step 1: Crawl (Silent -- No User Interaction)
+
+Before showing anything or asking anything:
 
-Present the interview as a friendly, professional conversation -- not a form. Ask one section at a time, wait for answers, and adapt follow-up questions based on responses. Be conversational, not robotic.
+1. **Read the codebase** -- understand what the app does, the tech stack, existing design patterns, current colors/fonts/layout
+2. **Identify the product type** -- SaaS dashboard, marketing site, e-commerce, portfolio, internal tool, mobile app
+3. **Identify the audience** -- who uses this? developers, lawyers, consumers, enterprise buyers
+4. **Study 2-3 real competitors** in the same space -- what do actual products in this industry look like?
+5. **Load `references/style-presets.md`** -- find the 8-12 presets most relevant to this product type
 
-### Section 1: The Mission
+This step is silent. Do not ask the user anything. Just gather context.
 
-Ask these first. They determine everything else.
+### Step 2: Quick Context (2-3 Questions Max)
 
-- "What are we building? (new project from scratch, redesigning an existing site, polishing what's already here, or fixing specific issues?)"
-- "Who is this for? (developers, consumers, enterprise, creative professionals, kids, etc.)"
-- "What's the single most important thing a user should do on this site?"
-- "Is there a site you love the look of? Drop a URL or name and I'll match that energy."
+Ask only what you can't determine from the code:
 
-Based on the answer, determine the **engagement type**:
+- "What's the one thing users should do on this site?" (if not obvious from the UI)
+- "Any existing brand colors or fonts I should keep?" (if not in the code)
+- "Any site you love the look of?" (optional -- gives you a reference to /steal from)
 
-| Answer | Engagement Type | What Picasso Does |
-|---|---|---|
-| "New project" | **Full Design** | Generate DESIGN.md, set up tokens, build from scratch |
-| "Redesign" | **Overhaul** | Audit everything, propose new direction, rebuild systematically |
-| "Polish" | **Refinement** | Audit, fix issues, preserve existing intent |
-| "Fix specific issues" | **Targeted Fix** | Skip interview, jump straight to the problem |
+That's it. Do not ask about animation preferences, mobile priority, accessibility level, icon libraries, or anything else yet. Get to visuals as fast as possible.
 
-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.
+### Step 3: Generate the Sample Gallery (THE KEY STEP)
 
-### Section 2: Aesthetic Direction
+This is what makes Picasso different from every other design tool. Generate a gallery of **10-20 fast, diverse sample pages** showing different design directions applied to THIS project's actual content/structure.
 
-Only ask if engagement type is Full Design or Overhaul.
+1. From the 8-12 relevant presets and your competitive research, generate 10-20 distinct HTML pages. Each one is a quick, self-contained page showing:
+   - The app's actual nav structure (from the codebase)
+   - A representative content area (dashboard, listing, form -- whatever the app's primary screen is)
+   - Styled with a different design direction (different font, color, layout, radius, density)
 
-- "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?"
+2. Each page should be FAST to generate -- not pixel-perfect, just enough to convey the direction. Think 30 seconds per page, not 5 minutes. Use the templates from `references/visual-preview.md` but vary them significantly. The goal is VOLUME and DIVERSITY, not polish.
 
-### Section 3: Context-Driven Recommendations
+3. Number each sample (1-20) so the user can reference them easily.
 
-Do NOT present a static menu of capabilities. Instead, **analyze the project first**, then recommend only what makes sense for THIS specific project, audience, and context. A legal SaaS needs different treatment than a portfolio site. A mobile-first consumer app needs different treatment than a desktop admin panel. Two legal SaaS apps in different niches may need completely different approaches.
+4. Write all samples to `/tmp/picasso-gallery/sample-{N}.html` (create the directory).
 
-#### How It Works
+5. Also generate a single `/tmp/picasso-gallery/index.html` that shows a thumbnail grid of all samples -- each as a small card (200px wide) with the sample number and the key differentiator (font name + primary color + one-word mood).
 
-1. **Read the codebase first.** Before recommending anything, understand:
-   - What type of product is this? (SaaS dashboard, marketing site, e-commerce, portfolio, internal tool, mobile app)
-   - Who uses it? (developers, lawyers, consumers, enterprise buyers, creative professionals)
-   - What's the primary interaction pattern? (data-heavy reading, frequent form input, content browsing, real-time collaboration)
-   - What already exists? (existing animations, sounds, icon library, design tokens)
+6. Open the index page with Playwright MCP, screenshot at 1440x900, view with Read.
 
-2. **Study 2-3 real competitors** in the same space. Not generic SaaS -- the actual competitive landscape. What do THEY do for motion, sound, iconography? What's standard for this industry? What would differentiate?
+7. Present: "Here are {N} directions for your app. React to what you see -- which ones do you like? Which do you hate? Anything close but needs tweaking? You can also open `/tmp/picasso-gallery/index.html` in your browser to browse them all."
 
-3. **Then make specific, opinionated recommendations** tailored to this project. Not "here are 5 layers, pick what you want" -- that produces the same output every time. Instead:
+### Step 4: Collect Reactions
 
-   "Based on what I see -- this is a legal practice management tool used by attorneys during their workday. Here's what I'd recommend and why:
-   
-   - [Specific recommendation 1 with reasoning tied to THIS project's users and context]
-   - [Specific recommendation 2 that addresses a gap I found in the codebase]  
-   - [Specific recommendation 3 that competitors do well and this project could benefit from]
-   - I would NOT recommend [thing] because [specific reason for THIS project]"
+The user reacts: "I like 3, 7, and 14. Hate the dark ones. 7 is close but the font is too playful."
 
-4. **Be honest about what doesn't fit.** If a project doesn't need sound design -- say so and explain why. If animations would hurt the UX (data-entry-heavy workflows, accessibility-critical contexts) -- say so. The goal is the RIGHT design for THIS project, not the MOST design.
+Parse their reactions into:
+- **Liked directions** -- what tokens do they share? (color temperature, density, radius)
+- **Disliked directions** -- what do they have in common? (avoid these patterns)
+- **Adjustments** -- specific tweaks to apply ("darker", "rounder", "more spacing")
 
-#### Capability Awareness
+### Step 5: Narrow and Regenerate
 
-You have deep reference files for all of these. Know they exist so you can recommend them WHEN APPROPRIATE -- but never as a checkbox list:
+Generate a second, smaller batch (3-5 samples) that synthesizes the user's reactions:
+- Take the liked directions as a starting point
+- Apply the adjustments they mentioned
+- Avoid the patterns from disliked directions
+- Each sample in this batch should be more polished than the first round
 
-- Motion & animation (4 intensity levels, from hover states to scroll-driven storytelling)
-- UI sound design (Tone.js synthesis, base64 audio, useSound hook)
-- Haptic feedback (Vibration API patterns for mobile)
-- Icon systems (Lucide, Phosphor, Heroicons, animated state transitions)
-- Generative art (p5.js, canvas, algorithmic SVG)
-- Data visualization (chart systems, Tufte-inspired display)
-- Scroll interactions (IntersectionObserver, scroll-timeline, parallax)
-- Conversion optimization (CTA psychology, pricing page patterns)
-- View Transitions API, container queries, magnetic cursors, text morphing
+Screenshot, view, present. Ask: "Getting closer? Pick your favorite, or tell me what to adjust."
 
-The key: recommend based on analysis, not from a menu. Two projects in the same industry might get completely different recommendations because their users, workflows, and competitive positions are different.
+### Step 6: Confirm Direction
 
-#### After recommendations, ask priorities:
-- "**Mobile** -- how important for your users specifically?"
-- "**Accessibility** -- what level does your audience need?"
-- "**Dark mode** -- do your users work in it?"
-- "**Performance** -- any constraints I should know about?"
+Once the user picks a direction (or says "that one, ship it"):
+1. Extract the final design tokens from the chosen sample
+2. Present the Design Brief (see below)
+3. Generate `.picasso.md`
+4. Begin implementation with the project's actual content
 
-### Section 4: Constraints
+### Why This Works
 
-Quick yes/no questions:
+- Users who "can't design" can easily say "I like that one" when shown options
+- Generating 20 fast samples takes less total time than a 20-question interview
+- The reactions reveal preferences the user didn't know they had
+- You bring inspiration TO the user -- they never have to go look at other sites
+- Each round narrows faster than verbal specification ever could
 
-- "Any existing design system or DESIGN.md I should follow?"
-- "Any technical constraints? (specific framework, no JS, must support IE11, etc.)"
-- "Any brand guidelines or style guides I should match?"
-- "Working with a designer, or am I the designer?"
+### After Direction is Chosen: Context-Driven Recommendations
+
+Once the user has picked a visual direction from the gallery (Step 6), THEN make specific recommendations about capabilities beyond core design. Base these on what you learned during the crawl phase AND the user's reactions:
+
+"Based on your project and the direction you chose, I'd also recommend:
+- [Specific recommendation with reasoning for THIS project]
+- [Another recommendation based on competitive research]
+- I would NOT add [thing] because [specific reason]"
+
+You have deep reference files for: motion/animation, UI sound design, haptic feedback, icon systems, generative art, data visualization, scroll interactions, conversion optimization, view transitions, container queries. Recommend based on analysis, not from a menu. Be honest about what doesn't fit.
+
+Quick follow-up questions (only ask what you couldn't determine from the code):
+- "Mobile -- how important for your users?"
+- "Accessibility -- what level?"
+- "Any technical constraints?"
 
 ### Section 5: Anti-Slop Commitments (MANDATORY for Full Design and Overhaul)
 
@@ -157,9 +161,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 +673,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 +904,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 +941,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.1",
   "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.