picasso-skill 2.1.2 → 2.3.0

package/commands/roast.md

@@ -2,20 +2,35 @@ Run the Picasso /roast command -- brutally honest design critique.
 
 Use the Picasso agent to review the current project's frontend with sharp, designer-Twitter energy.
 
-MANDATORY FIRST STEP -- Take and VIEW screenshots before writing anything:
+MANDATORY FIRST STEP -- Gather visual evidence before writing anything:
+
+**Option A: Live site (localhost or URL)**
 1. Take screenshots: `npx playwright screenshot http://localhost:PORT /tmp/picasso-roast-desktop.png --viewport-size=1440,900` (and mobile at 375,812)
 2. Use the Read tool to VIEW the screenshot files: `Read /tmp/picasso-roast-desktop.png` and `Read /tmp/picasso-roast-mobile.png`
 3. Base ALL visual observations on what you actually see in the screenshots, NOT on code/CSS classes
-4. If screenshots fail (no server running), tell the user and DO NOT make visual claims. You can still audit code patterns but must prefix findings with "Based on code analysis only (no screenshot):"
+
+**Option B: Figma file (URL provided or MCP available)**
+1. Extract file_key from the Figma URL
+2. Fetch the target frame via `mcp__figma__get_node` for structural data (spacing, colors, typography, auto-layout)
+3. Export the frame as an image via `mcp__figma__get_image` for visual review
+4. Fetch styles via `mcp__figma__get_styles` to check design system usage
+5. Base structural observations on MCP data (exact values) and visual observations on the exported image
+
+**Option C: Both exist (Figma + live site)**
+1. Do both A and B
+2. Include a "Design vs Implementation" delta section in the roast — flag where the dev diverged from the design
+
+4. If NEITHER screenshots NOR Figma MCP work, tell the user and DO NOT make visual claims. You can still audit code patterns but must prefix findings with "Based on code analysis only (no screenshot):"
 
 ANTI-HALLUCINATION RULES:
-- NEVER say "this is light mode" or "dark mode" without viewing a screenshot
+- NEVER say "this is light mode" or "dark mode" without viewing a screenshot or Figma frame data
 - NEVER describe colors, layouts, or visual appearance from code alone
-- NEVER claim "this looks like X" without a screenshot to verify
-- Code classes (e.g. `dark:bg-gray-900`) tell you what COULD render; only screenshots show what DOES render
+- NEVER claim "this looks like X" without a screenshot or Figma export to verify
+- Code classes (e.g. `dark:bg-gray-900`) tell you what COULD render; only screenshots/Figma show what DOES render
+- When using Figma MCP data, you CAN state exact values (e.g., "spacing is 17px" or "fill is #808080") because these are structural facts, not visual guesses
 
 Rules:
-- Be specific about every criticism (file:line or element reference)
+- Be specific about every criticism (file:line, element reference, or Figma node name)
 - Be funny and cutting, but never mean about the developer -- only the design
 - Every roast point MUST include the fix
 - End with a genuine compliment about what IS working
@@ -26,7 +41,7 @@ Format:
 ```
 🔥🔥🔥 ROAST SCORE: X/5
 
-[Sharp, specific critiques with file:line references -- all visual claims backed by screenshot]
+[Sharp, specific critiques with file:line references or Figma node names -- all visual claims backed by screenshot or MCP data]
 
 Here's how to fix it:
 1. [Fix with exact code/instruction]

package/commands/score.md

@@ -2,15 +2,29 @@ Run the Picasso /score command -- quantified design quality score.
 
 Use the Picasso agent to score the current project's frontend design on a 0-100 scale.
 
-MANDATORY FIRST STEP -- Take and VIEW screenshots before scoring:
+MANDATORY FIRST STEP -- Gather visual evidence before scoring:
+
+**Option A: Live site (localhost or URL)**
 1. Take screenshots: `npx playwright screenshot http://localhost:PORT /tmp/picasso-score-desktop.png --viewport-size=1440,900` (and mobile at 375,812)
 2. Use the Read tool to VIEW the screenshot files before scoring visual categories
 3. If screenshots fail, tell the user and score only code-auditable categories (mark visual categories as "N/A - no screenshot")
 
+**Option B: Figma file (URL provided or MCP available)**
+1. Fetch the target frame via `mcp__figma__get_node` for structural data
+2. Fetch styles via `mcp__figma__get_styles` for design system analysis
+3. Export frame as image via `mcp__figma__get_image` for visual review
+4. Score based on both structural data (exact values) and exported image
+5. Add bonus category: Design System Health (0-10)
+
+**Option C: Both (Figma + live site)**
+1. Do both A and B
+2. Add category: Design Fidelity (0-10) -- how closely implementation matches Figma intent
+
 ANTI-HALLUCINATION RULES:
-- Visual categories (Typography appearance, Color in practice, Spacing rhythm, Anti-Slop visual check) MUST be scored from screenshots, not code alone
+- Visual categories (Typography appearance, Color in practice, Spacing rhythm, Anti-Slop visual check) MUST be scored from screenshots or Figma exports, not code alone
 - Code-auditable categories (a11y violations via axe, transition:all grep, prefers-reduced-motion grep) can be scored from code
-- Never claim "this looks like X" without viewing a screenshot
+- When using Figma MCP, structural data (exact spacing, color, typography values) IS factual and can be stated directly
+- Never claim "this looks like X" without viewing a screenshot or Figma export
 
 Categories:
 - Typography (0-15): font choice, type scale, max-width, line-height, letter-spacing
@@ -22,4 +36,8 @@ Categories:
 - Performance (0-10): Lighthouse perf score mapped 0-100 -> 0-10
 - Anti-Slop (0-10): deductions for each AI-slop fingerprint detected (-2 each)
 
+Bonus categories (when Figma MCP is available):
+- Design System Health (0-10): style usage %, component coverage, naming consistency, auto-layout adoption
+- Design Fidelity (0-10, only when both Figma + live): token match, spacing accuracy, structural parity
+
 Output format with visual bars and top fixes for maximum point improvement.

package/commands/steal.md

@@ -1,12 +1,43 @@
-Run the Picasso /steal command -- extract design DNA from a URL.
+Run the Picasso /steal command -- extract design DNA from a URL or Figma file.
 
-Use the Picasso agent to extract the design language from the provided URL: $ARGUMENTS
+Use the Picasso agent to extract the design language from the provided source: $ARGUMENTS
+
+## Input Detection
+
+- **Figma URL** (contains `figma.com/design/` or `figma.com/file/`): Use Figma MCP for precise extraction
+- **Live URL** (any other http/https): Use Playwright screenshots + source scraping
+- **Both provided**: Use both sources, Figma as ground truth and live site for verification
+
+## Steps: Figma URL (Preferred)
+
+1. Extract `file_key` and optional `node_id` from the Figma URL
+2. Fetch styles via `mcp__figma__get_styles` — extract all color styles, text styles, effect styles
+3. Fetch target frame via `mcp__figma__get_node` — extract auto-layout spacing, fills, strokes, radii
+4. Fetch components via `mcp__figma__get_components` — understand component structure
+5. Export frame as image via `mcp__figma__get_image` for visual reference
+6. Analyze the extracted data:
+   - **Colors:** All fill/stroke colors → convert to OKLCH. Identify primary, secondary, accent, neutral.
+   - **Typography:** Font families, size scale, weight distribution, line-height ratios.
+   - **Spacing:** Auto-layout itemSpacing and padding → detect base unit (4px? 8px?) and scale.
+   - **Shadows:** Effect styles → map to elevation scale.
+   - **Radii:** Border radius values → detect pattern (uniform? progressive?).
+   - **Layout:** Auto-layout direction, alignment, wrapping → grid/flex patterns.
+7. Generate a `.picasso.md` config matching the extracted aesthetic
+8. Optionally generate a `DESIGN.md` with the full token set
+
+## Steps: Live URL
 
-Steps:
 1. Screenshot the URL at desktop (1440x900) and mobile (375x812)
 2. Fetch the page source and extract: font-family declarations, color values (#hex, rgb, oklch), border-radius values, box-shadow values
 3. Analyze the screenshots visually for: layout structure, spacing rhythm, typography hierarchy, color palette, animation style
-4. Generate a .picasso.md config that matches the extracted aesthetic
-5. Optionally generate a DESIGN.md with the full token set
+4. Generate a `.picasso.md` config that matches the extracted aesthetic
+5. Optionally generate a `DESIGN.md` with the full token set
+
+## Steps: Both (Figma + Live URL)
+
+1. Run Figma extraction (ground truth for intended design)
+2. Run live URL extraction (what actually shipped)
+3. Generate tokens from Figma source
+4. Note any divergences between design and implementation in the output
 
-If no URL is provided, ask the user for one.
+If no URL is provided, ask the user for one. Accept both Figma URLs and live URLs.

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.1.2",
+  "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/figma-mcp.md

@@ -0,0 +1,190 @@
+# Figma MCP Integration
+
+Reference for using Figma's Model Context Protocol (MCP) server to access design data directly from Figma files. This replaces or supplements Playwright screenshots with structured design information.
+
+## Why Figma MCP > Screenshots
+
+Screenshots show pixels. Figma MCP gives you the **design graph**: layers, tokens, spacing values, component instances, styles, and constraints. This means:
+
+- **Accurate color extraction:** Get exact hex/OKLCH values, not color-picked approximations
+- **Real spacing values:** Read auto-layout gaps, padding, and margins as the designer set them
+- **Typography facts:** Font family, weight, size, line-height, letter-spacing — all exact
+- **Component structure:** See which components are instances, variants, and overrides
+- **Design intent:** Understand constraints, auto-layout direction, and responsive behavior
+
+## When to Use Figma MCP vs Playwright
+
+| Scenario | Use Figma MCP | Use Playwright |
+|---|---|---|
+| Auditing a Figma design before implementation | ✅ | ❌ |
+| Extracting design tokens from a Figma file | ✅ | ❌ |
+| Reviewing a live deployed site | ❌ | ✅ |
+| Comparing Figma design vs live implementation | ✅ + ✅ | ✅ only |
+| Generating a DESIGN.md from existing design | ✅ preferred | ✅ fallback |
+| Roasting a design that only exists in Figma | ✅ | ❌ |
+
+**Rule:** If the user provides a Figma URL or mentions a Figma file, always prefer Figma MCP. If they provide a live URL or localhost, use Playwright. If both exist, use both for comparison.
+
+## MCP Server Options
+
+Two main Figma MCP implementations:
+
+### Option A: Figma's Official MCP (REST API)
+Package: `@anthropic/figma-mcp` or Figma's official MCP server
+- Uses Figma REST API with a personal access token
+- Read-only: fetch files, nodes, styles, components, export images
+- Best for: CI/CD, automated audits, headless analysis
+- Tools: `get_file`, `get_node`, `get_styles`, `get_components`, `get_image`
+
+### Option B: Talk to Figma MCP (Live Connection)
+Package: `cursor-talk-to-figma-mcp` (localhost:3055)
+- Connects to a running Figma instance via plugin
+- **Read AND write**: read frames, update text/properties, create shapes, adjust spacing
+- Best for: interactive design work, syncing copy, wireframing
+- Can snapshot frames and verify changes visually
+
+**Which to use:**
+- For Picasso audits/roasts/scoring → Either works. REST API is simpler.
+- For `/steal` token extraction → REST API preferred (structured data).
+- For `/figma --compare` → REST API for Figma data + Playwright for live site.
+- For interactive design updates (changing copy, adjusting spacing) → Talk to Figma MCP.
+
+## Available MCP Tools (REST API)
+
+### `mcp__figma__get_file`
+Fetch the full structure of a Figma file.
+- Input: `file_key` (extracted from Figma URL)
+- Returns: Document tree with pages, frames, components, styles
+- Use for: Understanding overall file structure, finding specific frames
+
+### `mcp__figma__get_node`
+Fetch a specific node (frame, component, group) by ID.
+- Input: `file_key`, `node_id`
+- Returns: Full node properties including fills, strokes, effects, layout, children
+- Use for: Deep-diving into specific components or sections
+
+### `mcp__figma__get_styles`
+Fetch all published styles from the file.
+- Input: `file_key`
+- Returns: Color styles, text styles, effect styles, grid styles
+- Use for: Extracting the design system / token set
+
+### `mcp__figma__get_components`
+Fetch all components and component sets.
+- Input: `file_key`
+- Returns: Component names, descriptions, variant properties
+- Use for: Understanding the component library structure
+
+### `mcp__figma__get_image`
+Export a node as a rendered image (PNG/SVG/PDF).
+- Input: `file_key`, `node_id`, `format`, `scale`
+- Returns: Image URL
+- Use for: Visual verification when you need to see rendered output alongside data
+
+## Available MCP Tools (Talk to Figma — Live Connection)
+
+When using the Talk to Figma plugin (localhost:3055), additional capabilities:
+
+- **Read frames**: List pages, get frame contents, read text layers
+- **Update text**: Change text content in any text layer
+- **Update properties**: Modify fills, strokes, effects, spacing
+- **Create shapes**: Add rectangles, frames, text nodes
+- **Adjust spacing**: Modify auto-layout padding and gaps
+- **Snapshot**: Export current frame state for visual verification
+
+**Critical rule:** After any Figma write operation, snapshot the frame and verify it looks correct before proceeding. Figma changes are live — there's no undo via MCP.
+
+## Extracting a Figma File Key
+
+From a Figma URL:
+```
+https://www.figma.com/design/ABC123xyz/My-Design-File?node-id=0-1
+                              ^^^^^^^^^
+                              file_key = ABC123xyz
+```
+
+From a Figma node URL:
+```
+https://www.figma.com/design/ABC123xyz/My-Design-File?node-id=123-456
+                              ^^^^^^^^^                        ^^^^^^^
+                              file_key                         node_id (use 123:456 in API)
+```
+
+**Note:** URL uses `-` separator in node-id, but the API expects `:` separator. Convert `123-456` → `123:456`.
+
+## Design Token Extraction Workflow
+
+When extracting design tokens from Figma for DESIGN.md generation:
+
+1. **Get styles** via `get_styles` — these are the designer's intended token set
+2. **Get the root frame** via `get_node` — check auto-layout settings for spacing rhythm
+3. **Map to Picasso tokens:**
+   - Color styles → `--color-*` tokens (convert to OKLCH)
+   - Text styles → typography scale (check for consistent ratio)
+   - Effect styles → shadow scale, blur values
+   - Grid styles → layout columns, gutter, margin
+
+### Spacing Extraction
+Read auto-layout `itemSpacing` and `paddingTop/Right/Bottom/Left` from frames. Look for patterns:
+- If spacing values are multiples of 4 or 8 → 4px or 8px base unit
+- If spacing values follow a ratio → extract the scale
+
+### Color Extraction
+Figma stores colors as RGBA (0-1 float). Convert to OKLCH for Picasso:
+- Extract fills from color styles
+- Group into: primary, secondary, accent, neutral, semantic (success/warning/error)
+- Check that neutrals are tinted (not pure gray) — flag if they aren't
+
+### Typography Extraction
+From text styles, extract:
+- Font family (flag if it's Inter/Roboto/system default — suggest alternatives)
+- Size scale (check for consistent modular ratio)
+- Weight usage (should have clear hierarchy: regular body, medium labels, semibold headings)
+- Line-height (check it's proportional, not fixed px for all sizes)
+
+## Anti-Patterns to Flag
+
+When analyzing Figma files, watch for these common design issues:
+
+1. **Detached instances** — Components used but detached from the library. Design debt.
+2. **Inconsistent spacing** — Auto-layout frames with ad-hoc spacing values (17px, 23px, 31px instead of a rhythm).
+3. **Unnamed layers** — "Frame 247", "Group 13". Signals hasty work.
+4. **Color styles not used** — Hardcoded colors instead of style references.
+5. **Text styles not used** — Hardcoded typography instead of style references.
+6. **Missing auto-layout** — Frames positioned absolutely instead of using auto-layout. Breaks responsive behavior.
+7. **Single-variant components** — Components that should have variants but don't (e.g., a button with only one state).
+8. **Enormous frame nesting** — 10+ levels deep. Simplify.
+
+## Copy Sync Workflow
+
+When working with both Figma designs and code, copy (text content) is a common source of drift. Use Figma MCP to keep them synchronized:
+
+1. **Read current copy from Figma** — extract all text layers from target frames
+2. **Compare against code** — diff the Figma text against what's rendered in the implementation
+3. **Determine source of truth** — typically Figma is upstream (design → code), but if copy was updated in code first, flag it
+4. **Sync direction:**
+   - Figma newer → update code to match
+   - Code newer → flag for designer review (don't auto-write to Figma without confirmation)
+5. **Verify** — after syncing, screenshot the live site and compare against Figma export
+
+This is especially useful for:
+- Marketing pages where copy changes frequently
+- Multi-language sites where translations update in Figma
+- Design handoff where developers may use placeholder text
+
+## Comparison Workflow: Figma vs Implementation
+
+When both a Figma file and live implementation exist:
+
+1. Extract tokens from Figma via MCP
+2. Screenshot the live site via Playwright
+3. Compare:
+   - Are the Figma fonts actually loaded on the site?
+   - Do spacing values match? (Common drift: Figma says 24px, CSS says 1.5rem which computes to 24px — match. Or CSS says `gap-6` which is 24px — match.)
+   - Are colors within ΔE < 3 tolerance? (Figma RGBA → site computed OKLCH)
+   - Are components structurally similar or did the dev reinterpret the design?
+4. Report discrepancies with severity:
+   - **Critical:** Wrong font, wrong primary color, missing sections
+   - **High:** Spacing off by >8px, wrong font weights, missing states
+   - **Medium:** Minor color drift, slightly different border radius, extra whitespace
+   - **Low:** Subpixel differences, minor animation timing differences