picasso-skill 2.7.0 → 3.0.0

package/README.md

@@ -5,14 +5,14 @@
 </p>
 
 <p align="center">
-  32 reference domains &bull; 13 slash commands + 22 agent behaviors &bull; 11,000+ lines of actionable design intelligence<br/>
+  33 reference domains &bull; 15 slash commands &bull; 19,000 lines of design intelligence<br/>
   Every interface looks like a senior design engineer spent days on it.
 </p>
 
 <p align="center">
   <a href="#install">Install</a> &bull;
   <a href="#what-makes-picasso-different">Why Picasso</a> &bull;
-  <a href="#the-design-interview">Interview</a> &bull;
+  <a href="#visual-discovery-not-a-questionnaire">Visual Discovery</a> &bull;
   <a href="#creative-commands">Creative Commands</a> &bull;
   <a href="#benchmark">Benchmarks</a> &bull;
   <a href="#commands">All Commands</a> &bull;
@@ -36,7 +36,7 @@ Existing design skills are shallow. They tell you to "use good typography" witho
 
 ### Depth That No Other Skill Matches
 
-Picasso covers **32 specialized reference domains**, each with concrete rules, specific values, and ready-to-use code. This isn't a collection of vague principles -- it's an engineering specification for beautiful interfaces.
+Picasso covers **33 specialized reference domains**, each with concrete rules, specific values, and ready-to-use code. This isn't a collection of vague principles -- it's an engineering specification for beautiful interfaces.
 
 | Domain | What You Get |
 |---|---|
@@ -44,7 +44,7 @@ Picasso covers **32 specialized reference domains**, each with concrete rules, s
 | **Color & Contrast** | OKLCH-based palette construction, tinted neutrals (never pure gray), 60-30-10 rule, dark mode inversion rules, "alpha is a design smell" |
 | **Spatial Design** | 4px base spacing scale, Gestalt proximity ratios (2:1 minimum), Squint Test, asymmetric grid patterns, "cards are not required" |
 | **Motion & Animation** | Duration rule (100/200/300/500ms), only animate transform+opacity, exit = 75% of entrance, grid-template-rows for height, stagger caps |
-| **Interaction Design** | All 8 interactive states (default/hover/focus/active/disabled/loading/error/success), dropdown positioning (#1 bug fix), Popover API, undo > confirmation |
+| **UX Evaluation** | Nielsen's 10 heuristics as actionable checklist, Jobs to Be Done extraction from code, component state machines (8 states), prompt enhancement for vague requests |
 | **Responsive Design** | Input method detection (`@media pointer/hover`), safe areas, container queries, content-driven breakpoints, real device testing |
 | **Sensory Design** | soundcn (700+ CC0 sounds), web-haptics (4 presets + custom), multi-sensory integration patterns |
 | **React/Next.js** | Server Components by default, barrel import avoidance, RSC serialization minimization, React.cache() deduplication |
@@ -69,7 +69,7 @@ Picasso covers **32 specialized reference domains**, each with concrete rules, s
 | **Micro-Interactions** | IntersectionObserver scroll animations, View Transitions API, magnetic cursors, gesture detection (swipe/pinch), animation budget (max 3 concurrent) |
 | **i18n Visual Patterns** | Logical properties for RTL, text expansion by language (+35% German), CJK rendering, Noto font stacks, icon mirroring rules |
 | **Brand & Identity** | Logo sizing (min 24px), clear space rules, lockup variants, 60-30-10 brand color usage, when to bend brand rules |
-| **Animation Performance** | Compositor-only properties (transform + opacity only), will-change lifecycle, layout thrashing batching, `contain` property, GPU hints |
+| **Visual Preview** | Self-contained HTML preview generation, side-by-side direction comparison, preset browser grid, font URL mapping, screenshot protocol |
 | **Code Typography** | JetBrains Mono/Fira Code selection, syntax highlighting contrast (3:1 min), code block design, copy button UX, diff views, terminal styling |
 
 ### The AI-Slop Firewall
@@ -102,33 +102,34 @@ Picasso doesn't just describe tools -- it specifies exactly how to use them with
 
 ---
 
-## The Design Interview
+## Visual Discovery (Not a Questionnaire)
 
-When you first use Picasso on a project, it doesn't just start generating. It asks.
+Most users can't articulate what they want but can instantly react to what they see. So Picasso shows, not asks. The gallery generation is **non-negotiable** -- it cannot be collapsed into questions, text descriptions, or verbal mood boards.
 
 ```
-Picasso: What are we building? New project, redesign, polish, or fixing specific issues?
-You:     New SaaS dashboard for a fintech startup
+1. CRAWL    Picasso agent silently reads your codebase, identifies the
+            product type, studies 2-3 real competitors in your space.
 
-Picasso: Who is this for?
-You:     Financial analysts, 30-50 age range, use Bloomberg terminals all day
+2. ASK      2-3 quick questions max: "What's the primary user action?"
+            "Any brand colors to keep?" "Site you love the look of?"
 
-Picasso: What's the vibe? Any sites you love the look of?
-You:     Dark, dense, like Linear meets Bloomberg. Here's a reference: linear.app
+3. SHOW     Generates 6-10 fast HTML sample pages, each a different
+            design direction applied to YOUR app's actual structure.
+            Screenshots each one. Opens a gallery for you to browse.
 
-Picasso: Rate these 1-5:
-         Animations? Mobile? Accessibility? Dark mode? Performance?
-You:     Animations 3, Mobile 2, A11y 5, Dark mode YES, Perf 5
+4. REACT    You: "Like 3 and 7. Hate the dark ones. 7 is close but
+            the font is too playful."
 
-Picasso: Got it. Here's what I'm building:
-         → Dark-tech aesthetic inspired by Linear
-         → Dense layout (VISUAL_DENSITY: 8), subtle motion (MOTION_INTENSITY: 3)
-         → WCAG AAA accessibility, dark-first, performance-critical
-         → Generating .picasso.md and DESIGN.md now...
-         Sound good?
+5. NARROW   Generates 3-5 refined samples based on your reactions.
+            Each one more polished than round 1.
+
+6. CONFIRM  You pick a direction. Agent generates .picasso.md and
+            hands off to the skill for implementation.
 ```
 
-The interview generates a `.picasso.md` config that persists your preferences across every future session. Run `/picasso` anytime to redo it.
+This process runs automatically when there's no `.picasso.md` in your project. Once you've confirmed a direction, `.picasso.md` stores your tokens and future invocations skip straight to execution. Run `/picasso` to redo discovery at any time.
+
+You never have to go look at design sites for inspiration. Picasso brings it to you. Your reactions reveal more preferences than any questionnaire.
 
 ---
 
@@ -170,19 +171,19 @@ A single 0-100 score, broken down by category. Track it over time.
 
 Typography:    ████████████░░░  12/15
 Color:         ████████████░░░  11/15
-Spacing:       ████████░░       8/10
-Accessibility: ████████████████ 16/20
-Motion:        ██████░░░░       6/10
-Responsive:    ████████░░       8/10
-Performance:   ██████░░░░       6/10
-Anti-Slop:     ██████░░░░       6/10
+Spacing:       ████████░░        8/10
+UX Heuristics: ████████████████ 16/20
+Motion:        ██████░░░░        6/10
+Responsive:    ████████░░        8/10
+Performance:   ██████░░░░        6/10
+Anti-Slop:     ██████░░░░        6/10
 
 Top fixes for +15 points:
-1. Add prefers-reduced-motion support (+4)
-2. Replace #000 with tinted near-black (+3)
-3. Add staggered entrance animation (+3)
-4. Set max-width on body text (+3)
-5. Replace outline:none with focus-visible (+2)
+1. Replace default primary color with industry-appropriate choice (+4)
+2. Set max-width on body text and increase to 16px (+3)
+3. Add prefers-reduced-motion support (+3)
+4. Replace outline:none with focus-visible (+3)
+5. Replace #000 with tinted near-black (+2)
 ```
 
 ### `/steal <url>` -- Extract Any Site's Design DNA
@@ -205,22 +206,22 @@ Generates a complete design system -- palette, fonts, spacing, motion, component
 
 ### `/evolve` -- Iterative Multi-Round Refinement
 
-Instead of generating once and hoping, Picasso proposes 3 distinct directions, lets you pick, then refines through multiple rounds:
+Proposes 3 directions as visual HTML previews, lets you pick, then implements and refines through multiple rounds with screenshots between each:
 
 ```
-Round 1: Here are 3 directions:
-  A) Minimal monochrome -- Geist font, black/white, sharp corners
-  B) Warm editorial -- Instrument Serif headers, terracotta accent, soft radius
-  C) Dark technical -- JetBrains Mono accent, neon green, dense layout
+Round 1: [generates 3 visual preview cards, screenshots them]
+         A) Counsel -- sage/teal, serif headers, 8px radius
+         B) Chambers -- dark, amber accent, monospace, 3px sharp
+         C) Parchment -- warm cream, terracotta, italic serif
 
-You: B, but darker
+You: B, but less extreme
 
-Round 2: [implements B with darker surfaces, screenshots]
+Round 2: [implements B with adjustments, screenshots running app]
          What do you love? What's not right?
 
 You: Love the typography. Cards need more breathing room.
 
-Round 3: [adjusts spacing, screenshots]
+Round 3: [adjusts spacing, screenshots again]
          Are we there?
 
 You: Ship it.
@@ -250,19 +251,16 @@ Fix this and you pull ahead significantly.
 
 ### `/before-after` -- Visual Transformation Report
 
-After any `/polish` or `/redesign`, auto-generates side-by-side screenshots showing exactly what changed and why. Shareable HTML report.
+After any design changes, auto-generates side-by-side screenshots showing exactly what changed and why. Shareable HTML report.
 
 ### `/preset <name>` -- One-Command Aesthetic
 
 ```bash
-/preset linear     # Linear-inspired dark minimal
-/preset stripe     # Stripe-inspired gradient editorial
-/preset vercel     # Vercel-inspired black/white sharp
-/preset notion     # Notion-inspired warm readable
-/preset brutalist  # Raw, intentional, monospace
+/preset            # Visual browser grid of all 22 presets -- pick one
+/preset bold-signal  # Preview Bold Signal, then apply it
 ```
 
-Generates `.picasso.md` + `DESIGN.md` + updates your CSS variables in one command.
+Without args: generates a visual grid showing all 22 presets with swatches, fonts, and sample buttons. Pick visually. With a name: shows a full-page preview before applying. Generates `.picasso.md` + `DESIGN.md` + updates CSS variables.
 
 ---
 
@@ -274,10 +272,10 @@ We compared Picasso against every publicly available AI design skill as of April
 
 | Metric | Picasso | Anthropic frontend-design | Impeccable | Taste Skill | Generic skills |
 |---|---|---|---|---|---|
-| **Reference domains** | **32** | 1 | 7 | 1 | 1-3 |
-| **Total lines of guidance** | **11,000+** | ~120 | ~2,500 | ~200 | 50-300 |
+| **Reference domains** | **33** | 1 | 7 | 1 | 1-3 |
+| **Total lines of guidance** | **19,000** | ~120 | ~2,500 | ~200 | 50-300 |
 | **Anti-pattern rules** | **50+** | ~10 | ~30 | ~5 | 0-5 |
-| **Steering commands** | **35** | 0 | 20 | 0 | 0-3 |
+| **Slash commands** | **15** | 0 | 20 | 0 | 0-3 |
 | **ARIA patterns documented** | **12 widgets** | 0 | 0 | 0 | 0 |
 | **React performance rules** | **45 (Vercel)** | 0 | 0 | 0 | 0 |
 | **Chart/data viz guidance** | **Full matrix** | None | None | None | None |
@@ -290,8 +288,8 @@ We compared Picasso against every publicly available AI design skill as of April
 | **Design system generation** | **9-section (Stitch)** | None | None | None | None |
 | **Sound/haptics** | **soundcn + web-haptics** | None | None | None | None |
 | **Scoring system** | **0-100 quantified** | None | /20 + /40 | None | None |
-| **Design interview** | **4-section onboarding** | None | None | None | None |
-| **Creative commands** | **8 (/roast, /steal, /evolve, /mood, /compete, /variants, /preset, /before-after)** | None | None | None | None |
+| **Visual discovery** | **6-10 HTML gallery + reaction loop** | None | None | None | None |
+| **Creative commands** | **15 (/roast, /score, /godmode, /steal, /evolve, /mood, /compete, /variants, /preset, /before-after, /figma, /preview, /backlog, /quick-audit, /autorefine)** | None | None | None | None |
 | **Tool integrations** | **7 libraries** | 0 | 0 | 0 | 0 |
 | **Sources consolidated** | **15+ repos** | 1 | 1 | 1 | 0-1 |
 
@@ -380,21 +378,39 @@ Upload `SKILL.md` as a Custom Skill in Claude.ai settings. Upload reference file
 
 ---
 
-## Skill + Agent
+## Skill + Agent: A Unified Pipeline
+
+Picasso ships as both a **skill** (design knowledge + execution framework) and an **agent** (autonomous discovery + validation). They are NOT alternatives -- they are sequential phases of the same pipeline.
 
-Picasso ships as both a **skill** (knowledge base) and an **agent** (autonomous design engineer).
+```
+User asks for design work
+  -> Skill loads, checks for .picasso.md
+  -> No .picasso.md? BLOCK. Spawn Picasso agent.
+  -> Agent crawls codebase silently
+  -> Agent asks 2-3 questions max
+  -> Agent generates 6-10 HTML sample pages to /tmp/picasso-gallery/
+  -> Agent screenshots gallery, presents to user
+  -> User reacts (like/hate/adjust)
+  -> Agent narrows to 3-5 refined samples
+  -> User picks direction
+  -> Agent generates .picasso.md
+  -> Control returns to skill for execution
+  -> Skill runs anti-slop gate, references, design thinking, code
+  -> Agent re-spawned for post-execution screenshot validation
+```
 
-| | Skill | Agent |
+| | Skill (Execution) | Agent (Discovery + Validation) |
 |---|---|---|
-| **What it is** | 32 reference files of design intelligence | Autonomous design auditor with anti-slop gate |
-| **How it works** | Loaded into context when designing | Runs as a sub-process with its own tools |
-| **When it runs** | When you ask for design help | On explicit commands (/audit, /roast, /godmode, etc.) |
-| **Can audit code** | Only when asked | Yes, with structured scoring |
-| **Can run axe-core** | No | Yes (via CLI) |
-| **Can screenshot pages** | No | Yes (via Playwright MCP) |
+| **What it is** | 33 reference files + anti-slop gate + implementation standards | Autonomous design engineer with visual discovery |
+| **How it works** | Loaded into context for design execution | Runs as a sub-process with its own dedicated context |
+| **When it runs** | After `.picasso.md` exists, for all design code work | First invocation (no `.picasso.md`), slash commands, validation |
+| **Owns** | References, anti-slop gate, design thinking, code standards | Visual discovery gallery, screenshots, direction confirmation |
+| **Can screenshot** | No | Yes (via `npx playwright screenshot`) |
+| **Can generate gallery** | No | Yes (6-10 HTML sample pages) |
 | **Can auto-fix issues** | No | Yes (with pre-flight git/test checks) |
-| **Can enforce design system** | No | Yes (greps for token violations) |
-| **Enforces anti-slop gate** | Via SKILL.md instructions | Yes, mandatory before any code generation |
+| **Enforces anti-slop gate** | Yes, before any code | Yes, mandatory before any generation |
+
+**Neither works alone on design-level tasks.** Discovery (agent) then execution (skill) then validation (agent).
 
 ---
 
@@ -419,7 +435,9 @@ These have dedicated command files and can be invoked directly.
 | `/compete <url>` | Head-to-head design comparison against a competitor site |
 | `/before-after` | Visual side-by-side comparison after changes with HTML report |
 | `/preset <name>` | Apply a curated community design preset (linear, stripe, vercel, notion, etc.) |
-| `/variants` | Generate 2-3 distinct visual directions for A/B comparison with code previews |
+| `/variants` | Generate 2-3 distinct visual directions with side-by-side visual HTML previews |
+| `/preview` | Visual preview of design tokens, presets, or side-by-side direction comparison |
+| `/figma` | Figma MCP integration: extract design tokens, audit, compare Figma vs live |
 | `/backlog` | Create persistent design debt backlog with impact-priority scoring in `.picasso-backlog.md` |
 
 ### `/godmode` -- The Nuclear Option
@@ -443,70 +461,55 @@ GODMODE Complete: 42 → 87 (+45 points), 47 files modified, 23 issues fixed
 
 ### Agent Behaviors (Internal)
 
-These are defined in the Picasso agent and run as part of pipelines (e.g., `/godmode` calls several of these internally). They work when the Picasso agent is active but don't have standalone command files.
+These are capabilities defined in the Picasso agent that run as part of pipelines (e.g., `/godmode` calls several internally). They work when the Picasso agent is active but aren't standalone slash commands.
 
 | Behavior | What It Does |
 |---|---|
-| `/picasso` | Run the design interview, generates `.picasso.md` |
-| `/audit` | Full technical audit across typography, color, spacing, a11y, motion, responsive, interaction |
-| `/critique` | UX-focused review: hierarchy, clarity, emotional resonance, user flow |
-| `/polish` | Auto-fix all audit findings with smallest safe changes |
-| `/redesign` | Full audit + aggressive fixes + re-audit to verify improvement |
-| `/simplify` | Strip unnecessary complexity: flatten nesting, reduce color count |
-| `/animate` | Add purposeful motion: staggered reveals, hover states, scroll-triggered animations |
-| `/bolder` | Amplify timid designs: increase contrast, enlarge type, strengthen hierarchy |
-| `/quieter` | Tone down aggressive designs: reduce saturation, soften shadows, increase whitespace |
-| `/normalize` | Align with design system: replace hardcoded values with tokens |
-| `/harden` | Add error handling, loading states, empty states, edge case handling |
-| `/theme` | Generate or apply a theme via DESIGN.md |
-| `/stitch` | Generate a complete DESIGN.md from the current codebase |
-| `/a11y` | Full accessibility audit: axe-core + pa11y + Lighthouse with JSON parsing |
-| `/perf` | Lighthouse performance audit with Core Web Vitals pass/fail thresholds |
-| `/visual-diff` | Screenshot desktop + mobile in light/dark mode, analyze visually |
-| `/consistency` | Multi-page consistency check across all routes |
-| `/lint-design` | Find hardcoded colors, spacing violations, font inconsistencies, z-index chaos |
-| `/mood-board` | Generate visual inspiration HTML from adjectives |
-| `/design-system-sync` | Detect and fix drift between DESIGN.md and code |
-| `/install-hooks` | Generate git pre-commit hook for automated design checks |
-| `/ci-setup` | Generate GitHub Actions workflow for PR design review with scores |
+| Visual Discovery | Crawl codebase, generate HTML gallery, collect reactions, confirm direction, write `.picasso.md` |
+| Design Audit | Full technical audit across typography, color, spacing, UX heuristics, motion, responsive |
+| Auto-Fix | Fix audit findings with smallest safe changes, re-audit to verify |
+| Screenshot Validation | Take and view screenshots between every major edit to verify output |
+| Anti-Slop Gate | Mandatory pre-code checklist: font, color, layout, differentiation commitments |
+| Competitor Research | Study 2-3 real competitors in the same domain before any redesign |
 
 ---
 
 ## References
 
 ```
-references/                          # 32 files, 9,300+ lines
+references/                          # 33 files, 7,000 lines
   anti-patterns.md                   # 50+ banned patterns (THE MOST IMPORTANT FILE)
-  typography.md                      # Type systems, font pairing, scales, OpenType, vertical rhythm
-  color-and-contrast.md              # OKLCH, tinted neutrals, dark mode, 60-30-10, dangerous combos
+  typography.md                      # Type systems, font pairing, scales, vertical rhythm
+  color-and-contrast.md              # OKLCH, tinted neutrals, dark mode, 60-30-10
   spatial-design.md                  # 4px spacing scale, grids, hierarchy, Squint Test
-  depth-and-elevation.md             # Dual shadows, layering, shadow scale, z-index, hover patterns
-  motion-and-animation.md            # Duration rule, easing curves, staggering, text morphing
-  micro-interactions.md              # Scroll animations, View Transitions, gestures, magnetic cursors
-  animation-performance.md           # Compositor-only props, will-change, layout thrashing, contain
-  interaction-design.md              # 8 states, forms, focus, Popover API, dropdown positioning
-  navigation-patterns.md             # Breadcrumbs, sidebar, tabs, bottom bar, mega menus, skip links
-  tables-and-forms.md                # Sortable tables, inline editing, validation, multi-step forms
-  loading-and-states.md              # Skeletons, error boundaries, 5 empty state types, offline
-  responsive-design.md               # Input method detection, safe areas, container queries
-  dark-mode.md                       # Preference hierarchy, elevation, transitions, testing
-  images-and-media.md                # Format selection, srcset, favicons, OG images, video
-  brand-and-identity.md              # Logo sizing, brand color 60-30-10, lockup variants
-  i18n-visual-patterns.md            # RTL, logical properties, text expansion, CJK, Noto stacks
-  code-typography.md                 # Monospace fonts, syntax highlighting, code blocks, diff views
-  sensory-design.md                  # soundcn, web-haptics, multi-sensory integration
-  react-patterns.md                  # Server Components, composition, state management, styling
-  design-system.md                   # 9-section DESIGN.md format, theme generation, tokens
+  depth-and-elevation.md             # Shadows, layering, z-index, hover patterns
+  motion-and-animation.md            # Duration, easing, staggering, performance (merged)
+  micro-interactions.md              # Scroll animations, View Transitions, gestures, cursors
+  navigation-patterns.md             # Breadcrumbs, sidebar, tabs, bottom bar, mega menus
+  tables-and-forms.md                # Sortable tables, inline editing, validation
+  loading-and-states.md              # Skeletons, error boundaries, empty states, offline
+  responsive-design.md               # Input method detection, container queries
+  dark-mode.md                       # Preference hierarchy, elevation, transitions
+  images-and-media.md                # Format selection, srcset, favicons, OG images
+  brand-and-identity.md              # Logo sizing, brand color, lockup variants
+  i18n-visual-patterns.md            # RTL, logical properties, text expansion, CJK
+  code-typography.md                 # Monospace fonts, syntax highlighting, code blocks
+  sensory-design.md                  # useSound hook, haptic patterns, multi-sensory
+  react-patterns.md                  # Server Components, composition, Tailwind v4
+  design-system.md                   # DESIGN.md format, theme generation, tokens
   generative-art.md                  # Philosophy-first process, p5.js, seeded randomness
   component-patterns.md              # 40+ components, state matrix, compound patterns
-  ux-psychology.md                   # Gestalt, Fitts's/Hick's/Miller's/Jakob's Law, F/Z-pattern
-  ux-writing.md                      # Error formula, button labels, empty states, terminology
+  ux-psychology.md                   # Gestalt, Fitts's/Hick's/Miller's/Jakob's Law
+  ux-writing.md                      # Error formula, button labels, terminology
+  ux-evaluation.md                   # Nielsen's 10 heuristics, JTBD, state machines
   data-visualization.md              # Chart selection matrix, dashboard layouts, Tufte
-  conversion-design.md               # Landing pages, CTAs, pricing, onboarding, notifications
-  accessibility-wcag.md              # 12 ARIA patterns, WCAG 2.2, SPA focus, accessible tables
+  conversion-design.md               # Landing pages, CTAs, pricing, onboarding
+  accessibility-wcag.md              # ARIA patterns, WCAG 2.2, focus management
   modern-css-performance.md          # Nesting, :has(), @layer, View Transitions, Tailwind v4
-  performance-optimization.md        # 45 Vercel rules across 7 priority tiers
-  style-presets.md                   # 22 visual presets with OKLCH values and font pairings
+  performance-optimization.md        # Core Web Vitals, priority tiers
+  style-presets.md                   # 22 visual presets with values and font pairings
+  visual-preview.md                  # HTML preview generation, templates, font mapping
+  figma-mcp.md                       # Figma MCP workflows, token extraction
   tools-catalog.md                   # torph, soundcn, Lucide, Facehash, better-icons
 ```
 

package/agents/picasso.md

@@ -1,6 +1,6 @@
 ---
 name: picasso
-description: "Senior design engineer agent that audits, enforces, and improves frontend UI quality. Invoked via /audit, /roast, /score, /redesign, /godmode, /figma, or when user asks to improve design. Supports Playwright screenshots for visual validation AND Figma MCP for direct design file analysis. When a Figma URL is provided or Figma MCP is available, prefers structured design data over screenshots for accuracy. Enforces mandatory anti-slop gate before any design code generation. 30+ reference files covering typography, color, spatial design, motion, accessibility, responsive, navigation, forms, dark mode, i18n, brand identity, Figma MCP workflows, and more. For proactive auto-review on file changes, configure hooks in settings.json."
+description: "Senior design engineer agent that owns visual discovery and design validation. Runs the full discovery pipeline (codebase crawl, HTML gallery generation, user reaction collection, direction confirmation, .picasso.md generation). Also handles design audits, screenshot validation, and anti-slop enforcement. Invoked via /roast, /score, /godmode, /figma, or when user asks to improve design. Supports Playwright screenshots for visual validation and Figma MCP for design file analysis. 33 reference files covering typography, color, spatial design, motion, accessibility, responsive, navigation, forms, dark mode, i18n, brand identity, and more."
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "mcp__figma__get_file", "mcp__figma__get_node", "mcp__figma__get_styles", "mcp__figma__get_components", "mcp__figma__get_image", "mcp__talk_to_figma"]
 model: opus
 ---
@@ -9,8 +9,19 @@ model: opus
 
 You are a senior design engineer with an obsessive eye for detail. Your job is to ensure every frontend interface looks like a human designer spent days refining it, not like an AI generated it in seconds.
 
-You have three modes:
-1. **Interview** (`/picasso` or first invocation) -- deep discovery conversation before any work begins
+## How You Work With the Picasso Skill
+
+The Picasso **skill** (SKILL.md) provides the design execution framework -- references, anti-slop gates, implementation standards. The Picasso **agent** (this file, you) owns the discovery and validation process. They work together:
+
+1. **The skill gates on you.** Before any design-level work, the skill REQUIRES spawning you (the agent) to run Visual Discovery if `.picasso.md` doesn't exist. The skill will not proceed to design execution without a confirmed direction from you.
+2. **You gate on the skill.** After discovery completes and `.picasso.md` is generated, the skill's execution steps (references, anti-slop, design thinking, code) take over. Your Phase 0b anti-slop gate and the skill's Step 0.5 anti-slop gate are the same process -- run it once, not twice.
+3. **You validate the skill's output.** After the skill produces code, you can be re-invoked to audit, screenshot, and verify that the implementation matches the confirmed direction.
+
+**Neither the skill nor the agent should ever work alone on design-level tasks.** Discovery (agent) then execution (skill) then validation (agent). This is the full pipeline.
+
+## Modes
+
+1. **Discovery** (`/picasso` or first invocation) -- full visual discovery process before any work begins. MANDATORY when no `.picasso.md` exists.
 2. **Reactive** (invoked explicitly for audits, critiques, or fixes)
 3. **Proactive** (triggered automatically after frontend code changes)
 
@@ -33,11 +44,11 @@ These rules are NON-NEGOTIABLE and override everything else. Violating them prod
 
 ---
 
-## Phase 0: The Visual Discovery Process (First Invocation)
+## Phase 0: The Visual Discovery Process (MANDATORY)
 
-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.
+When Picasso is invoked and no `.picasso.md` exists, or when the user runs `/picasso`, you MUST run the full visual discovery process. No exceptions. No shortcuts. No collapsing steps. Most users can't articulate what they want but can instantly react to what they see. So: show, don't ask.
 
-If the user says "just fix X" -- skip discovery entirely and go directly to the fix.
+**The only bypass:** The user says "just fix [one specific element]" (e.g., "fix the button color on line 42"). Targeted single-element fixes skip discovery. Anything broader -- "fix the design", "make it look good", "redesign this", "style this page" -- requires full discovery.
 
 ### The Core Principle
 
@@ -66,26 +77,38 @@ Ask only what you can't determine from the code:
 
 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.
 
-### Step 3: Generate the Sample Gallery (THE KEY STEP)
+### Step 3: Generate the Sample Gallery (THE KEY STEP -- NON-NEGOTIABLE)
+
+This is what makes Picasso different from every other design tool. You MUST generate actual HTML files. You MUST NOT substitute this with text descriptions, questions, verbal mood boards, or "let me describe what I'm thinking." The user needs to SEE options, not READ about them.
 
-This is what makes Picasso different from every other design tool. Generate a gallery of **6-10 fast, diverse sample pages** showing different design directions applied to THIS project's actual content/structure.
+**HARD RULE: If you reach this step and do not generate at least 6 HTML files, you have failed. There is no valid reason to skip this. Not time, not complexity, not "the user seems to know what they want." Generate the gallery.**
+
+Generate a gallery of **6-10 fast, diverse sample pages** showing different design directions applied to THIS project's actual content/structure.
 
 1. From the 8-12 relevant presets and your competitive research, generate 6-10 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)
+   - Each sample MUST be visually distinct from every other sample. If two samples look similar, replace one.
 
 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.
 
 3. Number each sample (1-10) so the user can reference them easily.
 
-4. Write all samples to `/tmp/picasso-gallery/sample-{N}.html` (create the directory).
+4. Write all samples to `/tmp/picasso-gallery/sample-{N}.html` (create the directory via `mkdir -p /tmp/picasso-gallery`).
 
 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).
 
-6. Screenshot via Bash: `npx playwright screenshot /tmp/picasso-gallery/index.html /tmp/picasso-gallery.png --viewport-size=1200,800`. View: `Read /tmp/picasso-gallery.png`.
+6. Screenshot via Bash: `npx playwright screenshot /tmp/picasso-gallery/index.html /tmp/picasso-gallery.png --viewport-size=1200,800`. Then VIEW the screenshot: `Read /tmp/picasso-gallery.png`. Taking without viewing is the same as not taking one.
+
+7. Also screenshot each individual sample for the user to browse inline:
+   ```bash
+   for i in $(seq 1 N); do npx playwright screenshot /tmp/picasso-gallery/sample-$i.html /tmp/picasso-gallery/sample-$i.png --viewport-size=1200,800; done
+   ```
+
+8. 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."
 
-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."
+9. **STOP AND WAIT.** Do not proceed until the user reacts. Do not assume preferences. Do not pre-select a direction. The user's job is to react, your job is to show.
 
 ### Step 4: Collect Reactions
 
@@ -180,13 +203,17 @@ After the user confirms the brief, load the SPECIFIC reference files for what th
 
 Then ACTUALLY READ those files before writing code. Use the specific code patterns and hooks from the references -- don't reinvent them. The references contain production-ready code (useSound hook, haptic patterns, scroll observers, etc.).
 
-### Skipping the Interview
+### Skipping the Visual Discovery Process
+
+The visual discovery process (Phase 0, Steps 1-6) is skipped ONLY when:
+- `.picasso.md` already exists AND the user is working within the established direction
+- User runs a pure audit command that generates no code (`/audit`, `/score`, `/quick-audit`, `/roast`)
+- User asks to fix ONE specific element ("fix the button on line 42") -- not design-level work
+- Proactive mode (triggered by file changes) -- audit only, no generation
+
+**"Just do it" and "skip the interview" do NOT skip discovery.** They skip the 2-3 context questions (Step 2) and go straight to gallery generation. The user still sees visual samples and still reacts. The gallery is not part of the interview -- it IS the process. A "detailed enough prompt" means the user described a specific aesthetic in enough detail that you can generate samples matching it -- you still generate the samples, you just use their description to inform the directions.
 
-The interview is skipped when:
-- `.picasso.md` already exists (preferences are loaded from it)
-- User runs a specific command (`/audit`, `/polish`, `/a11y`, etc.) -- execute directly
-- User says "just do it" or "skip the interview" or provides a detailed enough prompt
-- Proactive mode (triggered by file changes) -- never interview, just audit
+**NEVER skip the gallery for design-level work.** If the task involves choosing fonts, colors, layout direction, or overall aesthetic, the gallery runs. Period.
 
 **CRITICAL: Even when the interview is skipped, Phase 0b (Anti-Slop Gate) MUST still run for any design generation task.** The interview captures preferences. The gate ensures quality. They are independent. Skipping one does not skip the other. The only commands that bypass BOTH are pure audit commands (`/audit`, `/score`, `/quick-audit`, `/roast`) which do not generate code.
 

package/bin/install.mjs

@@ -29,8 +29,8 @@ if (command === "help" || command === "--help" || command === "-h") {
     npx picasso-skill --path DIR   Install to a custom directory
 
   What gets installed:
-    .claude/skills/picasso/        Skill (knowledge base: 32 reference files)
-    .claude/agents/picasso.md      Agent (autonomous design auditor)
+    .claude/skills/picasso/        Skill (knowledge base: 33 reference files)
+    .claude/agents/picasso.md      Agent (visual discovery + design validation)
   `);
   process.exit(0);
 }
@@ -127,7 +127,9 @@ try {
   console.log(`\n  Picasso is ready. Start designing.\n`);
 
   if (agentDir) {
-    console.log(`  Try: /godmode, /roast, /score, /mood, /evolve, /steal, /compete\n`);
+    console.log(`  15 commands: /godmode /roast /score /mood /evolve /steal /compete`);
+    console.log(`               /variants /preset /preview /figma /backlog /autorefine`);
+    console.log(`               /quick-audit /before-after\n`);
   }
 } catch (err) {
   console.error(`  Error installing: ${err.message}`);

package/commands/godmode.md

@@ -14,10 +14,9 @@ Phase 2: ASSESS
 - Take BEFORE screenshots (desktop + mobile) and VIEW them with the Read tool.
 - Run /score to establish the BEFORE score (0-100 with category breakdown).
 - Run /roast for the brutally honest assessment (must be based on screenshots, not code guessing).
-- Run /audit for full technical audit with severity-ranked findings.
-- Run /a11y (axe-core + pa11y + Lighthouse accessibility).
-- Run /perf (Lighthouse Core Web Vitals).
-- Run /lint-design (find hardcoded colors, spacing violations, font inconsistencies).
+- Run the full Phase 2 design audit from the agent definition (typography, color, spacing, layout, a11y, contrast, motion, responsive, interaction).
+- Run axe-core accessibility check if dev server is available: `npx axe-cli http://localhost:PORT --exit 2>/dev/null || true`
+- Grep for hardcoded colors, spacing violations, font inconsistencies, transition:all, outline:none.
 
 Phase 3: PLAN
 - Compile all findings into a prioritized fix list (Critical -> High -> Medium -> Low).

package/package.json

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