picasso-skill 2.7.0 → 3.0.0

package/skills/picasso/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: picasso
-version: 2.0.2
+version: 3.0.0
 description: >
   The ultimate frontend design and UI engineering skill. Use this whenever the user asks to build, design, style, or improve any web interface, component, page, application, dashboard, landing page, artifact, poster, or visual output. Covers typography, color systems, spatial design, motion/animation, interaction design, responsive layouts, sound design, haptic feedback, icon systems, generative art, theming, React best practices, and DESIGN.md system generation. Also use when the user asks to audit, critique, polish, simplify, animate, or normalize a frontend. Triggers on any mention of "make it look good," "fix the design," "UI," "UX," "frontend," "component," "landing page," "dashboard," "artifact," "poster," "design system," "theme," "animation," "responsive," or any request to improve visual quality. Use this skill even when the user does not explicitly ask for design help but the task involves producing a visual interface.
 metadata:
@@ -17,6 +17,18 @@ The ultimate design skill for producing distinctive, production-grade frontend i
 
 Every output should look like it was built by a senior design engineer who spent days refining it, not generated by an AI in seconds.
 
+## How the Skill and Agent Work Together
+
+The Picasso **skill** (this file) and the Picasso **agent** (`agents/picasso.md`) are a unified system. They are NOT alternatives -- they are sequential phases of the same pipeline:
+
+1. **Discovery (Agent):** When no `.picasso.md` exists, the Picasso agent MUST be spawned to run the full Visual Discovery Process -- crawl codebase, generate 6-10 HTML sample galleries, collect user reactions, narrow, confirm direction, generate `.picasso.md`. The skill BLOCKS until this completes.
+2. **Execution (Skill):** Once `.picasso.md` exists with confirmed tokens, the skill's workflow takes over -- read references, anti-slop gate, design thinking, aesthetic execution, implementation, audit, polish.
+3. **Validation (Agent):** After execution produces code, the agent can be re-spawned to screenshot, audit, and verify the output matches the confirmed direction.
+
+**The main Claude conversation MUST spawn the Picasso agent for discovery. It MUST NOT attempt to run discovery itself.** The agent has a dedicated context window optimized for the multi-step gallery generation process. The skill provides the design knowledge base that informs both the agent's gallery generation and the subsequent code execution.
+
+**NO SHORTCUTS AT ANY PHASE.** The discovery gallery is not optional. The anti-slop gate is not optional. The screenshot validation is not optional. Every step exists because skipping it produces generic output.
+
 ---
 
 ## Configurable Settings
@@ -31,9 +43,56 @@ When the user says "make it premium" or "luxury feel," drop VISUAL_DENSITY to 2-
 
 ---
 
+## MANDATORY FIRST STEP: Visual Discovery Gate (BLOCKING -- before EVERYTHING else)
+
+This gate runs BEFORE any design work, BEFORE reading references, BEFORE the anti-slop gate, BEFORE design thinking, BEFORE any code. It is the absolute first thing that happens when Picasso is invoked for any design task.
+
+### When this gate fires:
+
+- **ANY** design generation, build, redesign, overhaul, "make it look good", or new UI task
+- **ANY** invocation where `.picasso.md` does NOT exist in the project root
+- **ANY** time the user explicitly asks for design direction, styling, or visual work on a project that hasn't gone through discovery
+- When the user runs `/picasso`
+
+### When this gate does NOT fire:
+
+- Pure audit commands that generate NO code: `/audit`, `/score`, `/quick-audit`, `/roast`
+- The user says "just fix [specific single thing]" (e.g., "fix the button color", "fix the spacing on line 42") -- targeted fixes to ONE element, not design-level work
+- `.picasso.md` already exists AND the user is doing incremental work within the established direction
+
+### What happens:
+
+**You MUST spawn the Picasso agent** (subagent_type: "picasso") to run the full Visual Discovery Process. Do NOT attempt to run discovery yourself in the main conversation. The agent has a dedicated context window for this multi-step process.
+
+The agent will:
+1. **Crawl the codebase silently** -- understand the app, tech stack, product type, competitors
+2. **Ask 2-3 quick context questions max** -- only what can't be determined from code
+3. **Generate 6-10 fast HTML sample pages** showing diverse design directions using the project's actual content/structure -- written to `/tmp/picasso-gallery/`
+4. **Screenshot and present the gallery** -- the user reacts (like/hate/adjust), NOT specifies
+5. **Narrow and regenerate** -- 3-5 refined samples based on reactions
+6. **Confirm direction** -- extract tokens, present Design Brief with visual preview
+7. **Generate `.picasso.md`** -- lock in the chosen direction
+
+**HARD RULES:**
+- The agent MUST generate the HTML sample gallery. It MUST NOT collapse this step into questions, text descriptions, or "let me describe what I'm thinking." The entire point is SHOWING, not TELLING.
+- The agent MUST generate at least 6 distinct visual samples on the first round. Volume and diversity matter more than polish.
+- The agent MUST screenshot the gallery and VIEW the screenshot before presenting to the user.
+- The agent MUST wait for user reactions before narrowing. Do not assume preferences.
+- The agent MUST NOT write any project code until the user has confirmed a direction and `.picasso.md` is generated.
+
+**NO SHORTCUTS. NO COLLAPSING STEPS. NO SKIPPING THE GALLERY.**
+
+The discovery process exists because users react to visuals, not specifications. Skipping it produces generic output. Every time. Without exception.
+
+### After Discovery Completes:
+
+Once `.picasso.md` exists with confirmed tokens, proceed to Step 0 below. The skill steps (references, anti-slop gate, design thinking, execution) all operate WITHIN the direction established by discovery.
+
+---
+
 ## Quick Start (30 seconds)
 
-New to Picasso? Here's the minimum viable workflow:
+Already have a `.picasso.md`? Here's the minimum viable workflow for incremental work:
 
 1. **Pick a font** that isn't Inter, Roboto, or Arial. Try: Satoshi, Cabinet Grotesk, Outfit, General Sans, Clash Display.
 2. **Pick a color** in OKLCH. Not Tailwind's default indigo. Try: `oklch(0.65 0.25 25)` (warm red), `oklch(0.55 0.20 160)` (teal), `oklch(0.60 0.22 300)` (violet).
@@ -56,7 +115,6 @@ Before writing any code, read the reference files relevant to the task. Each cov
 | `references/spatial-design.md` | Layout, spacing, grids, visual hierarchy, whitespace |
 | `references/depth-and-elevation.md` | Dual shadows, layering technique, shadow scale, z-index, hover patterns |
 | `references/motion-and-animation.md` | Transitions, scroll effects, text morphing, micro-interactions |
-| `references/interaction-design.md` | Forms, focus states, loading, empty states, error handling |
 | `references/responsive-design.md` | Mobile-first, fluid, container queries, touch targets |
 | `references/sensory-design.md` | UI sound effects, haptic feedback, multi-sensory interfaces |
 | `references/react-patterns.md` | React/Next.js component architecture, hooks, performance |
@@ -72,7 +130,6 @@ Before writing any code, read the reference files relevant to the task. Each cov
 | `references/micro-interactions.md` | Scroll animations, page transitions, gestures, magnetic effects |
 | `references/i18n-visual-patterns.md` | RTL, logical properties, text expansion, CJK, number formatting |
 | `references/brand-and-identity.md` | Logo sizing, brand color usage, consistency, lockup variants |
-| `references/animation-performance.md` | Compositor-only props, will-change, layout thrashing, contain |
 | `references/code-typography.md` | Monospace fonts, syntax highlighting, code blocks, diff views |
 | `references/accessibility-wcag.md` | WCAG 2.2, ARIA patterns, keyboard nav, screen reader testing |
 | `references/conversion-design.md` | Landing pages, CTAs, pricing tables, friction reduction |
@@ -83,6 +140,9 @@ Before writing any code, read the reference files relevant to the task. Each cov
 | `references/tools-catalog.md` | Tool recommendations: torph, soundcn, Lucide, Facehash, better-icons |
 | `references/ux-psychology.md` | Gestalt principles, Fitts's Law, Hick's Law, cognitive load, heuristics |
 | `references/ux-writing.md` | Error messages, microcopy, terminology, voice and tone, CTAs |
+| `references/ux-evaluation.md` | Nielsen's 10 heuristics, Jobs to Be Done, state machines, prompt enhancement |
+| `references/visual-preview.md` | HTML preview generation, side-by-side direction comparison, font URL mapping |
+| `references/figma-mcp.md` | Figma MCP workflows, token extraction, design file analysis |
 
 ---
 
@@ -235,26 +295,25 @@ When the task involves algorithmic art, generative visuals, or static poster/pri
 
 ## Commands
 
-These optional directives can be used to steer design refinement:
+Available slash commands:
 
 | Command | Effect |
 |---|---|
-| `/audit` | Technical quality check: accessibility, performance, responsive |
-| `/critique` | UX design review: hierarchy, clarity, emotional resonance |
-| `/polish` | Final pass: refine spacing, transitions, copy |
-| `/simplify` | Strip to essence, remove visual noise |
-| `/animate` | Add purposeful motion and transitions |
-| `/bolder` | Amplify timid designs with stronger visual choices |
-| `/quieter` | Tone down overly aggressive designs |
-| `/normalize` | Align with design system standards |
-| `/theme` | Generate or apply a color/font theme |
-| `/sound` | Add UI sound effects to interactions |
-| `/haptics` | Add haptic feedback for mobile web |
-| `/redesign` | Audit an existing project, identify design problems, fix them systematically |
-| `/soft` | Apply premium soft aesthetic: generous whitespace, depth, smooth spring animations |
-| `/minimalist` | Apply editorial minimalism: monochrome, crisp borders, inspired by Linear/Notion |
-| `/brutalist` | Apply raw mechanical aesthetic: Swiss typography meets CRT terminal |
-| `/stitch` | Generate a Google Stitch-compatible DESIGN.md for the current project |
+| `/roast` | Brutally honest design critique |
+| `/score` | Quantified 0-100 design quality score with category breakdown |
+| `/quick-audit` | 5-minute fast design audit: 6 binary checks |
+| `/godmode` | The ultimate design transformation pipeline |
+| `/figma` | Analyze a Figma file and extract its design DNA |
+| `/steal` | Extract design DNA from a URL or Figma file |
+| `/variants` | Generate 2-3 distinct visual directions with side-by-side previews |
+| `/preview` | Generate visual previews of design directions or current tokens |
+| `/evolve` | Iterative multi-round design refinement |
+| `/mood` | Generate a complete design system from a mood word |
+| `/preset` | Browse and apply curated design presets with visual previews |
+| `/autorefine` | Binary evaluation loop: define criteria, mutate, iterate to 95%+ pass |
+| `/backlog` | Create and manage a persistent design debt backlog |
+| `/before-after` | Visual transformation report |
+| `/compete` | Head-to-head design comparison |
 
 ---
 
@@ -318,3 +377,5 @@ These are not best practices. These are things that actually break in production
 5. Every detail matters. The shadow radius, the letter spacing, the hover transition duration, the border color in dark mode. These are not small decisions.
 6. **The Anti-Slop Gate (Step 0.5) must be completed before writing any design code.** No exceptions. If you cannot articulate specific, non-default commitments for font, color, layout, and differentiation, you are not ready to design. Go back to the references.
 7. **Transformation means transformation.** When asked to redesign or improve a site, the result must be visually unrecognizable from the original. Changing CSS variables and swapping fonts is engineering, not design. A redesign changes the spatial logic, the visual hierarchy, the emotional register, and the layout structure. If someone could confuse the before and after, the redesign failed.
+8. **The Visual Discovery Gate must complete before any design-level execution.** If `.picasso.md` does not exist, spawn the Picasso agent for full visual discovery. Do not attempt to run discovery in the main conversation. Do not skip the gallery. Do not substitute questions for visuals. The agent generates HTML samples, the user reacts, direction is confirmed, `.picasso.md` is created. Only then does execution begin.
+9. **Post-execution validation is mandatory.** After implementing design changes, screenshot the result and compare against the `.picasso.md` direction. If the implementation drifts from the confirmed direction, fix it before delivering. Every major edit gets a screenshot. Not just at the end -- between each significant change.

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.