picasso-skill 2.8.0 → 3.0.0

package/skills/picasso/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

package/skills/picasso/references/ux-evaluation.md

@@ -0,0 +1,211 @@
+# UX Evaluation Reference
+
+Structured frameworks for evaluating interface quality. Use these during /score, /roast, /audit, and the visual discovery crawl phase.
+
+---
+
+## 1. Nielsen's 10 Usability Heuristics (Evaluation Checklist)
+
+For each heuristic, check the listed indicators. Score pass/fail for each.
+
+### H1: Visibility of System Status
+The system should always keep users informed about what is going on.
+- [ ] Loading states exist for async actions (skeletons, spinners, progress bars)
+- [ ] Form submission shows pending/success/error feedback
+- [ ] Current page/section is highlighted in navigation
+- [ ] Active filters/sorts are visually indicated
+- [ ] Upload progress is shown
+- **Check in code:** grep for loading states, skeleton components, progress indicators
+- **Check in screenshot:** is the current nav item highlighted? Are there loading indicators?
+
+### H2: Match Between System and Real World
+Use language and concepts familiar to the user, not system-oriented terms.
+- [ ] Button labels use verbs the user understands ("Save changes" not "Submit")
+- [ ] Error messages explain the problem in plain language
+- [ ] Navigation labels match user mental models
+- [ ] Icons are conventional (trash = delete, pencil = edit, plus = add)
+- **Check in code:** grep for generic labels ("Submit", "Click here", "Data")
+
+### H3: User Control and Freedom
+Users need a clear emergency exit when they make mistakes.
+- [ ] Modals have close buttons AND escape key support
+- [ ] Destructive actions have confirmation OR undo
+- [ ] Multi-step flows have back navigation
+- [ ] Users can cancel in-progress operations
+- **Check in code:** grep for confirm() dialogs, undo patterns, modal close handlers
+
+### H4: Consistency and Standards
+Follow platform conventions. Same action = same result everywhere.
+- [ ] Primary buttons look the same across all pages
+- [ ] Same icon means the same thing everywhere
+- [ ] Spacing and typography follow a consistent scale
+- [ ] Color meanings are consistent (red = error, green = success)
+- **Check in code:** grep for hardcoded colors, inconsistent button styles
+
+### H5: Error Prevention
+Prevent problems from occurring in the first place.
+- [ ] Required fields are marked before submission
+- [ ] Date inputs use pickers (not free text)
+- [ ] Destructive buttons are visually distinct (red/outlined, not primary)
+- [ ] Inline validation catches errors before form submission
+- **Check in code:** grep for required fields, inline validation, input types
+
+### H6: Recognition Rather Than Recall
+Minimize memory load. Make options visible.
+- [ ] Navigation is always visible (not hidden behind hamburger on desktop)
+- [ ] Search results show context around matches
+- [ ] Forms show labels (not placeholder-only)
+- [ ] Recent items, favorites, or shortcuts are available
+- **Check in screenshot:** are labels visible? Is navigation persistent?
+
+### H7: Flexibility and Efficiency of Use
+Allow experts to speed up their workflow.
+- [ ] Keyboard shortcuts exist for frequent actions
+- [ ] Bulk operations are available for lists
+- [ ] Command palette or search exists (Cmd+K)
+- [ ] Default values are intelligent
+- **Check in code:** grep for keyboard event listeners, bulk action patterns
+
+### H8: Aesthetic and Minimalist Design
+Every extra element competes with relevant information.
+- [ ] No decorative elements that don't serve a purpose
+- [ ] Information hierarchy is clear (most important = most prominent)
+- [ ] White space is used to group related elements
+- [ ] No more than 3-4 colors for data categories
+- **Check in screenshot:** squint test -- does hierarchy still read?
+
+### H9: Help Users Recognize, Diagnose, and Recover from Errors
+Error messages should be in plain language, indicate the problem, and suggest a fix.
+- [ ] Error messages follow: what happened + why + how to fix
+- [ ] Form errors appear next to the relevant field
+- [ ] API errors don't show raw technical messages to users
+- [ ] Empty states guide the user on what to do next
+- **Check in code:** grep for error handling, error messages, empty states
+
+### H10: Help and Documentation
+Even though a system should be usable without docs, help should be available.
+- [ ] Tooltips explain non-obvious UI elements
+- [ ] Onboarding exists for first-time users
+- [ ] Complex features have inline help or documentation links
+- [ ] Keyboard shortcuts are discoverable
+- **Check in code:** grep for tooltip components, help text, onboarding flows
+
+---
+
+## 2. Jobs to Be Done (JTBD) Framework
+
+Use JTBD to understand WHY users interact with the app, not just WHAT they do. This informs design decisions during the crawl phase.
+
+### Extracting JTBD from Code
+
+Analyze the codebase to identify user jobs:
+
+1. **Route structure** reveals user tasks:
+   - `/dashboard` = "When I start my day, I want to see what needs attention"
+   - `/clients/[id]` = "When I work on a client, I want all their info in one place"
+   - `/billing` = "When I need to invoice, I want to track time and generate bills"
+   - `/analyze` = "When I receive a contract, I want to understand the risks"
+
+2. **API endpoints** reveal user actions:
+   - POST /api/clients = "I want to onboard a new client"
+   - POST /api/analyze = "I want AI to review this document"
+   - GET /api/dashboard = "I want a summary of my practice"
+
+3. **Component names** reveal UI functions:
+   - `<ClientForm>` = data entry job
+   - `<TimerWidget>` = time tracking job
+   - `<RedlineView>` = document review job
+
+### Using JTBD to Inform Design
+
+For each identified job, ask:
+- **What's the trigger?** When does the user need to do this?
+- **What's the desired outcome?** What does success look like?
+- **What's the anxiety?** What could go wrong?
+- **What's the context?** Where/when do they do this? (mobile? desktop? in a meeting?)
+
+Design decisions should optimize for the job:
+- High-frequency jobs need the fastest path (fewest clicks, most prominent placement)
+- High-stakes jobs need the most clarity (larger text, explicit confirmation, clear feedback)
+- Time-pressured jobs need efficiency (keyboard shortcuts, bulk actions, smart defaults)
+
+---
+
+## 3. Prompt Enhancement
+
+When a user gives a vague design request, enhance it before proceeding.
+
+### Vague-to-Specific Mapping
+
+| User Says | What They Mean | What to Do |
+|-----------|---------------|------------|
+| "Make it look good" | It looks amateur, fix the obvious issues | Run /audit, fix critical+high |
+| "Make it modern" | It looks dated, update the aesthetic | Check font (is it Arial?), colors (pure gray?), radius (sharp corners?) |
+| "Make it clean" | Too much visual noise, simplify | Remove decorative elements, increase whitespace, reduce color count |
+| "Make it pop" | Not enough visual hierarchy, too flat | Increase contrast, add depth, strengthen heading sizes |
+| "Make it professional" | It looks like a student project | Fix typography scale, add consistent spacing, tighten color palette |
+| "I don't know what I want" | They need visual discovery | Generate the 10-20 sample gallery and let them react |
+
+### Enhancement Process
+
+1. Identify the complaint (what's wrong) vs. the goal (what they want)
+2. Map to specific design properties (typography, color, spacing, layout, motion)
+3. Propose concrete changes with before/after preview
+4. Never ask "what do you mean by modern?" -- instead, show 3 interpretations and ask which fits
+
+---
+
+## 4. State Machine for Interactive Components
+
+Map all states for each interactive element. Missing states are the #1 source of unpolished UI.
+
+### The 8 States
+
+Every interactive element should define:
+
+| State | Visual Treatment | Trigger |
+|-------|-----------------|---------|
+| **Default** | Base appearance | Page load |
+| **Hover** | Subtle background/border change | Mouse enters |
+| **Focus** | Visible ring/outline (2px+ solid) | Tab navigation |
+| **Active/Pressed** | Scale down slightly (0.97-0.98) | Mouse down |
+| **Disabled** | Reduced opacity (0.5), no pointer | Programmatic |
+| **Loading** | Spinner or pulse, disabled interaction | Async action |
+| **Error** | Red border/text, error message | Validation fail |
+| **Success** | Green indicator, confirmation | Action complete |
+
+### Audit Checklist
+
+For each component type, verify states exist:
+
+| Component | States to Check |
+|-----------|----------------|
+| Button | default, hover, focus, active, disabled, loading |
+| Input | default, hover, focus, filled, error, disabled |
+| Card (clickable) | default, hover, focus, active |
+| Link | default, hover, focus, visited |
+| Toggle | off, on, hover, focus, disabled |
+| Select | default, hover, focus, open, selected, error |
+| Modal | enter, exit, backdrop |
+
+---
+
+## 5. Scoring with Heuristics
+
+When running /score, add heuristic evaluation points:
+
+```
+Heuristic Evaluation (0-20 pts):
+  H1 System status:    /2  (loading states, feedback)
+  H2 Real world match: /2  (language, icons)
+  H3 User control:     /2  (undo, escape, back)
+  H4 Consistency:      /2  (styles, patterns)
+  H5 Error prevention: /2  (validation, confirmation)
+  H6 Recognition:      /2  (labels, navigation)
+  H7 Efficiency:       /2  (shortcuts, bulk ops)
+  H8 Minimal design:   /2  (hierarchy, whitespace)
+  H9 Error recovery:   /2  (messages, guidance)
+  H10 Help:            /2  (tooltips, onboarding)
+```
+
+This replaces the ad-hoc accessibility scoring with a structured UX evaluation.