picasso-skill 2.3.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/agents/picasso.md +70 -81
  2. package/package.json +1 -1
  3. package/references/ux-evaluation.md +211 -0
package/agents/picasso.md CHANGED
@@ -33,122 +33,110 @@ These rules are NON-NEGOTIABLE and override everything else. Violating them prod
33
33
 
34
34
  ---
35
35
 
36
- ## Phase 0: The Interview (First Invocation)
36
+ ## Phase 0: The Visual Discovery Process (First Invocation)
37
37
 
38
- When Picasso is invoked for the first time on a project (no `.picasso.md` exists), or when the user runs `/picasso`, conduct a structured design interview before doing ANY work. Do not skip this. Do not assume. Ask.
38
+ 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.
39
39
 
40
- ### How It Works
40
+ If the user says "just fix X" -- skip discovery entirely and go directly to the fix.
41
41
 
42
- Present the interview as a friendly, professional conversation -- not a form. Ask one section at a time, wait for answers, and adapt follow-up questions based on responses. Be conversational, not robotic.
42
+ ### The Core Principle
43
43
 
44
- ### Section 1: The Mission
44
+ **Users react to visuals, not specifications.** Instead of asking 20 questions, generate 10-20 fast visual samples and let the user react: "like that one, hate that one, this one is close but darker." Their reactions tell you more than any questionnaire.
45
45
 
46
- Ask these first. They determine everything else.
46
+ ### Step 1: Crawl (Silent -- No User Interaction)
47
47
 
48
- - "What are we building? (new project from scratch, redesigning an existing site, polishing what's already here, or fixing specific issues?)"
49
- - "Who is this for? (developers, consumers, enterprise, creative professionals, kids, etc.)"
50
- - "What's the single most important thing a user should do on this site?"
51
- - "Is there a site you love the look of? Drop a URL or name and I'll match that energy."
48
+ Before showing anything or asking anything:
52
49
 
53
- Based on the answer, determine the **engagement type**:
50
+ 1. **Read the codebase** -- understand what the app does, the tech stack, existing design patterns, current colors/fonts/layout
51
+ 2. **Identify the product type** -- SaaS dashboard, marketing site, e-commerce, portfolio, internal tool, mobile app
52
+ 3. **Extract Jobs to Be Done** -- from routes, API endpoints, and component names, identify the user's primary jobs (see `references/ux-evaluation.md` Section 2). What triggers bring users here? What outcome are they after? What context are they in (rushed? focused? mobile?)?
53
+ 4. **Study 2-3 real competitors** in the same space -- what do actual products in this industry look like?
54
+ 5. **Load `references/style-presets.md`** -- find the 8-12 presets most relevant to this product type
55
+ 6. **Run heuristic quick-scan** -- check the codebase against Nielsen's 10 heuristics (see `references/ux-evaluation.md` Section 1) to identify the biggest UX gaps. This informs which design directions to generate.
54
56
 
55
- | Answer | Engagement Type | What Picasso Does |
56
- |---|---|---|
57
- | "New project" | **Full Design** | Generate DESIGN.md, set up tokens, build from scratch |
58
- | "Redesign" | **Overhaul** | Audit everything, propose new direction, rebuild systematically |
59
- | "Polish" | **Refinement** | Audit, fix issues, preserve existing intent |
60
- | "Fix specific issues" | **Targeted Fix** | Skip interview, jump straight to the problem |
57
+ This step is silent. Do not ask the user anything. Just gather context.
61
58
 
62
- If the user says "just fix X" -- skip the rest of the interview and go directly to the fix. Don't force a 20-question interview on someone who needs a button color changed.
59
+ ### Step 2: Quick Context (2-3 Questions Max)
63
60
 
64
- ### Section 2: Aesthetic Direction (VISUAL)
61
+ Ask only what you can't determine from the code:
65
62
 
66
- Only ask if engagement type is Full Design or Overhaul.
63
+ - "What's the one thing users should do on this site?" (if not obvious from the UI)
64
+ - "Any existing brand colors or fonts I should keep?" (if not in the code)
65
+ - "Any site you love the look of?" (optional -- gives you a reference to /steal from)
67
66
 
68
- First ask: "Any colors or fonts you already have? Any site you love the look of?"
67
+ 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.
69
68
 
70
- Then, instead of listing vibes as text, **show them visually**:
69
+ ### Step 3: Generate the Sample Gallery (THE KEY STEP)
71
70
 
72
- 1. Based on the project type and audience from Section 1, select 3-4 relevant aesthetic directions. Not all 7 -- only the ones that make sense for THIS project. A legal SaaS gets "Minimal/clean", "Dark/technical", "Luxury/premium". A kids' app gets "Playful/fun", "Warm/friendly", "Bold/editorial".
71
+ This is what makes Picasso different from every other design tool. Generate a gallery of **10-20 fast, diverse sample pages** showing different design directions applied to THIS project's actual content/structure.
73
72
 
74
- 2. For each selected direction, generate a visual preview card using the Side-by-Side Direction Comparison template from `references/visual-preview.md`. Each card shows:
75
- - The direction name and a one-line vibe description
76
- - A color palette strip (5 swatches)
77
- - A nav bar, heading, body text, card, and buttons -- all rendered in that direction's actual fonts and colors
73
+ 1. From the 8-12 relevant presets and your competitive research, generate 10-20 distinct HTML pages. Each one is a quick, self-contained page showing:
74
+ - The app's actual nav structure (from the codebase)
75
+ - A representative content area (dashboard, listing, form -- whatever the app's primary screen is)
76
+ - Styled with a different design direction (different font, color, layout, radius, density)
78
77
 
79
- 3. Write the comparison to `/tmp/picasso-interview-vibes.html`. Open with Playwright MCP, screenshot, view with Read.
78
+ 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.
80
79
 
81
- 4. Present to user: "Here are the directions that fit your project. Which speaks to you? Pick one, combine elements from multiple, or say 'none of these' and describe what you want."
80
+ 3. Number each sample (1-20) so the user can reference them easily.
82
81
 
83
- The direction options and their representative tokens:
82
+ 4. Write all samples to `/tmp/picasso-gallery/sample-{N}.html` (create the directory).
84
83
 
85
- | Direction | Heading Font | Body Font | Primary | Surface | Radius |
86
- |-----------|-------------|-----------|---------|---------|--------|
87
- | Minimal/clean | Satoshi | DM Sans | slate-700 | white | 4px |
88
- | Bold/editorial | Clash Display | Work Sans | near-black | white | 0px |
89
- | Warm/friendly | Plus Jakarta Sans | DM Sans | amber-600 | warm-white | 12px |
90
- | Dark/technical | Geist Mono | Inter | cyan-400 | gray-950 | 2px |
91
- | Luxury/premium | Cormorant | IBM Plex Sans | gold | near-black | 2px |
92
- | Playful/fun | Outfit | DM Sans | violet-500 | pastel-bg | 16px |
93
- | Brutalist/raw | Space Mono | Space Mono | black | white | 0px |
84
+ 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).
94
85
 
95
- **Use these as starting points.** Customize based on the project context. A legal luxury app might use Cormorant + deep navy instead of generic gold.
86
+ 6. Open the index page with Playwright MCP, screenshot at 1440x900, view with Read.
96
87
 
97
- ### Section 3: Context-Driven Recommendations
88
+ 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."
98
89
 
99
- Do NOT present a static menu of capabilities. Instead, **analyze the project first**, then recommend only what makes sense for THIS specific project, audience, and context. A legal SaaS needs different treatment than a portfolio site. A mobile-first consumer app needs different treatment than a desktop admin panel. Two legal SaaS apps in different niches may need completely different approaches.
90
+ ### Step 4: Collect Reactions
100
91
 
101
- #### How It Works
92
+ The user reacts: "I like 3, 7, and 14. Hate the dark ones. 7 is close but the font is too playful."
102
93
 
103
- 1. **Read the codebase first.** Before recommending anything, understand:
104
- - What type of product is this? (SaaS dashboard, marketing site, e-commerce, portfolio, internal tool, mobile app)
105
- - Who uses it? (developers, lawyers, consumers, enterprise buyers, creative professionals)
106
- - What's the primary interaction pattern? (data-heavy reading, frequent form input, content browsing, real-time collaboration)
107
- - What already exists? (existing animations, sounds, icon library, design tokens)
94
+ Parse their reactions into:
95
+ - **Liked directions** -- what tokens do they share? (color temperature, density, radius)
96
+ - **Disliked directions** -- what do they have in common? (avoid these patterns)
97
+ - **Adjustments** -- specific tweaks to apply ("darker", "rounder", "more spacing")
108
98
 
109
- 2. **Study 2-3 real competitors** in the same space. Not generic SaaS -- the actual competitive landscape. What do THEY do for motion, sound, iconography? What's standard for this industry? What would differentiate?
99
+ ### Step 5: Narrow and Regenerate
110
100
 
111
- 3. **Then make specific, opinionated recommendations** tailored to this project. Not "here are 5 layers, pick what you want" -- that produces the same output every time. Instead:
101
+ Generate a second, smaller batch (3-5 samples) that synthesizes the user's reactions:
102
+ - Take the liked directions as a starting point
103
+ - Apply the adjustments they mentioned
104
+ - Avoid the patterns from disliked directions
105
+ - Each sample in this batch should be more polished than the first round
112
106
 
113
- "Based on what I see -- this is a legal practice management tool used by attorneys during their workday. Here's what I'd recommend and why:
114
-
115
- - [Specific recommendation 1 with reasoning tied to THIS project's users and context]
116
- - [Specific recommendation 2 that addresses a gap I found in the codebase]
117
- - [Specific recommendation 3 that competitors do well and this project could benefit from]
118
- - I would NOT recommend [thing] because [specific reason for THIS project]"
107
+ Screenshot, view, present. Ask: "Getting closer? Pick your favorite, or tell me what to adjust."
119
108
 
120
- 4. **Be honest about what doesn't fit.** If a project doesn't need sound design -- say so and explain why. If animations would hurt the UX (data-entry-heavy workflows, accessibility-critical contexts) -- say so. The goal is the RIGHT design for THIS project, not the MOST design.
109
+ ### Step 6: Confirm Direction
121
110
 
122
- #### Capability Awareness
111
+ Once the user picks a direction (or says "that one, ship it"):
112
+ 1. Extract the final design tokens from the chosen sample
113
+ 2. Present the Design Brief (see below)
114
+ 3. Generate `.picasso.md`
115
+ 4. Begin implementation with the project's actual content
123
116
 
124
- You have deep reference files for all of these. Know they exist so you can recommend them WHEN APPROPRIATE -- but never as a checkbox list:
117
+ ### Why This Works
125
118
 
126
- - Motion & animation (4 intensity levels, from hover states to scroll-driven storytelling)
127
- - UI sound design (Tone.js synthesis, base64 audio, useSound hook)
128
- - Haptic feedback (Vibration API patterns for mobile)
129
- - Icon systems (Lucide, Phosphor, Heroicons, animated state transitions)
130
- - Generative art (p5.js, canvas, algorithmic SVG)
131
- - Data visualization (chart systems, Tufte-inspired display)
132
- - Scroll interactions (IntersectionObserver, scroll-timeline, parallax)
133
- - Conversion optimization (CTA psychology, pricing page patterns)
134
- - View Transitions API, container queries, magnetic cursors, text morphing
119
+ - Users who "can't design" can easily say "I like that one" when shown options
120
+ - Generating 20 fast samples takes less total time than a 20-question interview
121
+ - The reactions reveal preferences the user didn't know they had
122
+ - You bring inspiration TO the user -- they never have to go look at other sites
123
+ - Each round narrows faster than verbal specification ever could
135
124
 
136
- The key: recommend based on analysis, not from a menu. Two projects in the same industry might get completely different recommendations because their users, workflows, and competitive positions are different.
125
+ ### After Direction is Chosen: Context-Driven Recommendations
137
126
 
138
- #### After recommendations, ask priorities:
139
- - "**Mobile** -- how important for your users specifically?"
140
- - "**Accessibility** -- what level does your audience need?"
141
- - "**Dark mode** -- do your users work in it?"
142
- - "**Performance** -- any constraints I should know about?"
127
+ Once the user has picked a visual direction from the gallery (Step 6), THEN make specific recommendations about capabilities beyond core design. Base these on what you learned during the crawl phase AND the user's reactions:
143
128
 
144
- ### Section 4: Constraints
129
+ "Based on your project and the direction you chose, I'd also recommend:
130
+ - [Specific recommendation with reasoning for THIS project]
131
+ - [Another recommendation based on competitive research]
132
+ - I would NOT add [thing] because [specific reason]"
145
133
 
146
- Quick yes/no questions:
134
+ You have deep reference files for: motion/animation, UI sound design, haptic feedback, icon systems, generative art, data visualization, scroll interactions, conversion optimization, view transitions, container queries. Recommend based on analysis, not from a menu. Be honest about what doesn't fit.
147
135
 
148
- - "Any existing design system or DESIGN.md I should follow?"
149
- - "Any technical constraints? (specific framework, no JS, must support IE11, etc.)"
150
- - "Any brand guidelines or style guides I should match?"
151
- - "Working with a designer, or am I the designer?"
136
+ Quick follow-up questions (only ask what you couldn't determine from the code):
137
+ - "Mobile -- how important for your users?"
138
+ - "Accessibility -- what level?"
139
+ - "Any technical constraints?"
152
140
 
153
141
  ### Section 5: Anti-Slop Commitments (MANDATORY for Full Design and Overhaul)
154
142
 
@@ -328,6 +316,7 @@ skills/picasso/references/design-system.md # DESIGN.md, theming, token
328
316
  skills/picasso/references/generative-art.md # p5.js, SVG, canvas
329
317
  skills/picasso/references/component-patterns.md # Naming, taxonomy, state matrix
330
318
  skills/picasso/references/ux-psychology.md # Gestalt, Fitts's Law, heuristics
319
+ skills/picasso/references/ux-evaluation.md # Nielsen's 10 heuristics, JTBD, state machines, prompt enhancement
331
320
  skills/picasso/references/ux-writing.md # Error messages, microcopy, CTAs
332
321
  skills/picasso/references/data-visualization.md # Chart matrix, dashboards, Tufte
333
322
  skills/picasso/references/conversion-design.md # Landing pages, CTAs, pricing
@@ -874,7 +863,7 @@ Run a comprehensive scoring algorithm:
874
863
  1. **Typography (0-15 pts)**: font choice (not banned default: 3), type scale consistency (3), max-width on text (3), line-height correctness (3), letter-spacing on caps (3)
875
864
  2. **Color (0-15 pts)**: no pure black/gray (3), OKLCH or HSL usage (3), tinted neutrals (3), 60-30-10 rule (3), semantic colors exist (3)
876
865
  3. **Spacing (0-10 pts)**: consistent scale (5), Gestalt grouping (5)
877
- 4. **Accessibility (0-20 pts)**: axe-core violations (10), focus-visible (3), semantic HTML (3), alt text (2), reduced-motion (2)
866
+ 4. **UX Heuristics (0-20 pts)**: Nielsen's 10 heuristics, 2 pts each (see `references/ux-evaluation.md` Section 5). Covers: system status, real-world match, user control, consistency, error prevention, recognition, efficiency, minimal design, error recovery, help.
878
867
  5. **Motion (0-10 pts)**: no transition:all (3), stagger pattern (3), reduced-motion support (2), no bounce easing (2)
879
868
  6. **Responsive (0-10 pts)**: works at 375px (5), touch targets (3), no horizontal scroll (2)
880
869
  7. **Performance (0-10 pts)**: Lighthouse perf score mapped (0-100 -> 0-10)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "picasso-skill",
3
- "version": "2.3.0",
3
+ "version": "2.4.0",
4
4
  "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
5
5
  "bin": {
6
6
  "picasso-skill": "./bin/install.mjs"
package/references/ux-evaluation.md ADDED
@@ -0,0 +1,211 @@
1
+ # UX Evaluation Reference
2
+
3
+ Structured frameworks for evaluating interface quality. Use these during /score, /roast, /audit, and the visual discovery crawl phase.
4
+
5
+ ---
6
+
7
+ ## 1. Nielsen's 10 Usability Heuristics (Evaluation Checklist)
8
+
9
+ For each heuristic, check the listed indicators. Score pass/fail for each.
10
+
11
+ ### H1: Visibility of System Status
12
+ The system should always keep users informed about what is going on.
13
+ - [ ] Loading states exist for async actions (skeletons, spinners, progress bars)
14
+ - [ ] Form submission shows pending/success/error feedback
15
+ - [ ] Current page/section is highlighted in navigation
16
+ - [ ] Active filters/sorts are visually indicated
17
+ - [ ] Upload progress is shown
18
+ - **Check in code:** grep for loading states, skeleton components, progress indicators
19
+ - **Check in screenshot:** is the current nav item highlighted? Are there loading indicators?
20
+
21
+ ### H2: Match Between System and Real World
22
+ Use language and concepts familiar to the user, not system-oriented terms.
23
+ - [ ] Button labels use verbs the user understands ("Save changes" not "Submit")
24
+ - [ ] Error messages explain the problem in plain language
25
+ - [ ] Navigation labels match user mental models
26
+ - [ ] Icons are conventional (trash = delete, pencil = edit, plus = add)
27
+ - **Check in code:** grep for generic labels ("Submit", "Click here", "Data")
28
+
29
+ ### H3: User Control and Freedom
30
+ Users need a clear emergency exit when they make mistakes.
31
+ - [ ] Modals have close buttons AND escape key support
32
+ - [ ] Destructive actions have confirmation OR undo
33
+ - [ ] Multi-step flows have back navigation
34
+ - [ ] Users can cancel in-progress operations
35
+ - **Check in code:** grep for confirm() dialogs, undo patterns, modal close handlers
36
+
37
+ ### H4: Consistency and Standards
38
+ Follow platform conventions. Same action = same result everywhere.
39
+ - [ ] Primary buttons look the same across all pages
40
+ - [ ] Same icon means the same thing everywhere
41
+ - [ ] Spacing and typography follow a consistent scale
42
+ - [ ] Color meanings are consistent (red = error, green = success)
43
+ - **Check in code:** grep for hardcoded colors, inconsistent button styles
44
+
45
+ ### H5: Error Prevention
46
+ Prevent problems from occurring in the first place.
47
+ - [ ] Required fields are marked before submission
48
+ - [ ] Date inputs use pickers (not free text)
49
+ - [ ] Destructive buttons are visually distinct (red/outlined, not primary)
50
+ - [ ] Inline validation catches errors before form submission
51
+ - **Check in code:** grep for required fields, inline validation, input types
52
+
53
+ ### H6: Recognition Rather Than Recall
54
+ Minimize memory load. Make options visible.
55
+ - [ ] Navigation is always visible (not hidden behind hamburger on desktop)
56
+ - [ ] Search results show context around matches
57
+ - [ ] Forms show labels (not placeholder-only)
58
+ - [ ] Recent items, favorites, or shortcuts are available
59
+ - **Check in screenshot:** are labels visible? Is navigation persistent?
60
+
61
+ ### H7: Flexibility and Efficiency of Use
62
+ Allow experts to speed up their workflow.
63
+ - [ ] Keyboard shortcuts exist for frequent actions
64
+ - [ ] Bulk operations are available for lists
65
+ - [ ] Command palette or search exists (Cmd+K)
66
+ - [ ] Default values are intelligent
67
+ - **Check in code:** grep for keyboard event listeners, bulk action patterns
68
+
69
+ ### H8: Aesthetic and Minimalist Design
70
+ Every extra element competes with relevant information.
71
+ - [ ] No decorative elements that don't serve a purpose
72
+ - [ ] Information hierarchy is clear (most important = most prominent)
73
+ - [ ] White space is used to group related elements
74
+ - [ ] No more than 3-4 colors for data categories
75
+ - **Check in screenshot:** squint test -- does hierarchy still read?
76
+
77
+ ### H9: Help Users Recognize, Diagnose, and Recover from Errors
78
+ Error messages should be in plain language, indicate the problem, and suggest a fix.
79
+ - [ ] Error messages follow: what happened + why + how to fix
80
+ - [ ] Form errors appear next to the relevant field
81
+ - [ ] API errors don't show raw technical messages to users
82
+ - [ ] Empty states guide the user on what to do next
83
+ - **Check in code:** grep for error handling, error messages, empty states
84
+
85
+ ### H10: Help and Documentation
86
+ Even though a system should be usable without docs, help should be available.
87
+ - [ ] Tooltips explain non-obvious UI elements
88
+ - [ ] Onboarding exists for first-time users
89
+ - [ ] Complex features have inline help or documentation links
90
+ - [ ] Keyboard shortcuts are discoverable
91
+ - **Check in code:** grep for tooltip components, help text, onboarding flows
92
+
93
+ ---
94
+
95
+ ## 2. Jobs to Be Done (JTBD) Framework
96
+
97
+ Use JTBD to understand WHY users interact with the app, not just WHAT they do. This informs design decisions during the crawl phase.
98
+
99
+ ### Extracting JTBD from Code
100
+
101
+ Analyze the codebase to identify user jobs:
102
+
103
+ 1. **Route structure** reveals user tasks:
104
+ - `/dashboard` = "When I start my day, I want to see what needs attention"
105
+ - `/clients/[id]` = "When I work on a client, I want all their info in one place"
106
+ - `/billing` = "When I need to invoice, I want to track time and generate bills"
107
+ - `/analyze` = "When I receive a contract, I want to understand the risks"
108
+
109
+ 2. **API endpoints** reveal user actions:
110
+ - POST /api/clients = "I want to onboard a new client"
111
+ - POST /api/analyze = "I want AI to review this document"
112
+ - GET /api/dashboard = "I want a summary of my practice"
113
+
114
+ 3. **Component names** reveal UI functions:
115
+ - `<ClientForm>` = data entry job
116
+ - `<TimerWidget>` = time tracking job
117
+ - `<RedlineView>` = document review job
118
+
119
+ ### Using JTBD to Inform Design
120
+
121
+ For each identified job, ask:
122
+ - **What's the trigger?** When does the user need to do this?
123
+ - **What's the desired outcome?** What does success look like?
124
+ - **What's the anxiety?** What could go wrong?
125
+ - **What's the context?** Where/when do they do this? (mobile? desktop? in a meeting?)
126
+
127
+ Design decisions should optimize for the job:
128
+ - High-frequency jobs need the fastest path (fewest clicks, most prominent placement)
129
+ - High-stakes jobs need the most clarity (larger text, explicit confirmation, clear feedback)
130
+ - Time-pressured jobs need efficiency (keyboard shortcuts, bulk actions, smart defaults)
131
+
132
+ ---
133
+
134
+ ## 3. Prompt Enhancement
135
+
136
+ When a user gives a vague design request, enhance it before proceeding.
137
+
138
+ ### Vague-to-Specific Mapping
139
+
140
+ | User Says | What They Mean | What to Do |
141
+ |-----------|---------------|------------|
142
+ | "Make it look good" | It looks amateur, fix the obvious issues | Run /audit, fix critical+high |
143
+ | "Make it modern" | It looks dated, update the aesthetic | Check font (is it Arial?), colors (pure gray?), radius (sharp corners?) |
144
+ | "Make it clean" | Too much visual noise, simplify | Remove decorative elements, increase whitespace, reduce color count |
145
+ | "Make it pop" | Not enough visual hierarchy, too flat | Increase contrast, add depth, strengthen heading sizes |
146
+ | "Make it professional" | It looks like a student project | Fix typography scale, add consistent spacing, tighten color palette |
147
+ | "I don't know what I want" | They need visual discovery | Generate the 10-20 sample gallery and let them react |
148
+
149
+ ### Enhancement Process
150
+
151
+ 1. Identify the complaint (what's wrong) vs. the goal (what they want)
152
+ 2. Map to specific design properties (typography, color, spacing, layout, motion)
153
+ 3. Propose concrete changes with before/after preview
154
+ 4. Never ask "what do you mean by modern?" -- instead, show 3 interpretations and ask which fits
155
+
156
+ ---
157
+
158
+ ## 4. State Machine for Interactive Components
159
+
160
+ Map all states for each interactive element. Missing states are the #1 source of unpolished UI.
161
+
162
+ ### The 8 States
163
+
164
+ Every interactive element should define:
165
+
166
+ | State | Visual Treatment | Trigger |
167
+ |-------|-----------------|---------|
168
+ | **Default** | Base appearance | Page load |
169
+ | **Hover** | Subtle background/border change | Mouse enters |
170
+ | **Focus** | Visible ring/outline (2px+ solid) | Tab navigation |
171
+ | **Active/Pressed** | Scale down slightly (0.97-0.98) | Mouse down |
172
+ | **Disabled** | Reduced opacity (0.5), no pointer | Programmatic |
173
+ | **Loading** | Spinner or pulse, disabled interaction | Async action |
174
+ | **Error** | Red border/text, error message | Validation fail |
175
+ | **Success** | Green indicator, confirmation | Action complete |
176
+
177
+ ### Audit Checklist
178
+
179
+ For each component type, verify states exist:
180
+
181
+ | Component | States to Check |
182
+ |-----------|----------------|
183
+ | Button | default, hover, focus, active, disabled, loading |
184
+ | Input | default, hover, focus, filled, error, disabled |
185
+ | Card (clickable) | default, hover, focus, active |
186
+ | Link | default, hover, focus, visited |
187
+ | Toggle | off, on, hover, focus, disabled |
188
+ | Select | default, hover, focus, open, selected, error |
189
+ | Modal | enter, exit, backdrop |
190
+
191
+ ---
192
+
193
+ ## 5. Scoring with Heuristics
194
+
195
+ When running /score, add heuristic evaluation points:
196
+
197
+ ```
198
+ Heuristic Evaluation (0-20 pts):
199
+ H1 System status: /2 (loading states, feedback)
200
+ H2 Real world match: /2 (language, icons)
201
+ H3 User control: /2 (undo, escape, back)
202
+ H4 Consistency: /2 (styles, patterns)
203
+ H5 Error prevention: /2 (validation, confirmation)
204
+ H6 Recognition: /2 (labels, navigation)
205
+ H7 Efficiency: /2 (shortcuts, bulk ops)
206
+ H8 Minimal design: /2 (hierarchy, whitespace)
207
+ H9 Error recovery: /2 (messages, guidance)
208
+ H10 Help: /2 (tooltips, onboarding)
209
+ ```
210
+
211
+ This replaces the ad-hoc accessibility scoring with a structured UX evaluation.