picasso-skill 1.1.0 → 1.2.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 (4) hide show
  1. package/README.md +69 -45
  2. package/agents/picasso.md +326 -0
  3. package/bin/install.mjs +54 -24
  4. package/package.json +2 -1
package/README.md CHANGED
@@ -1,31 +1,31 @@
1
1
  # Picasso
2
2
 
3
- The ultimate AI design skill for producing distinctive, production-grade frontend interfaces.
3
+ The ultimate AI design skill + agent for producing distinctive, production-grade frontend interfaces.
4
4
 
5
- Picasso consolidates best practices from 18+ sources into a single comprehensive skill that covers every dimension of frontend design: typography, color systems, spatial composition, motion, interaction patterns, responsive design, sound, haptics, icons, generative art, theming, React architecture, component taxonomy, configurable design intensity, and an exhaustive anti-patterns library.
5
+ Picasso is two things:
6
+ 1. **A skill** (knowledge base) -- 13 reference files covering every dimension of frontend design
7
+ 2. **An agent** (autonomous design engineer) -- proactively audits your frontend code, catches AI-slop aesthetics, validates accessibility, enforces design systems, and auto-fixes issues
6
8
 
7
9
  ## Install
8
10
 
9
11
  ### Option 1: npx (Recommended)
10
12
 
11
- Works with Claude Code, Cursor, Codex, and any agent that reads skill files:
12
-
13
13
  ```bash
14
- # Install to current project (Claude Code)
14
+ # Install skill + agent to current project
15
15
  npx picasso-skill
16
16
 
17
17
  # Install globally (all Claude Code projects)
18
18
  npx picasso-skill --global
19
19
 
20
+ # Skill only (no agent)
21
+ npx picasso-skill --skill-only
22
+
20
23
  # Install for Cursor
21
24
  npx picasso-skill --cursor
22
25
 
23
26
  # Install for Codex
24
27
  npx picasso-skill --codex
25
28
 
26
- # Install to .agents/skills/
27
- npx picasso-skill --agents
28
-
29
29
  # Custom path
30
30
  npx picasso-skill --path ./my-skills
31
31
  ```
@@ -33,11 +33,11 @@ npx picasso-skill --path ./my-skills
33
33
  ### Option 2: One-Liner (no npm needed)
34
34
 
35
35
  ```bash
36
- # Project-specific
37
- git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && mkdir -p .claude/skills && cp -r /tmp/picasso/skills/picasso .claude/skills/picasso && rm -rf /tmp/picasso
36
+ # Project-specific (skill + agent)
37
+ git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && mkdir -p .claude/skills .claude/agents && cp -r /tmp/picasso/skills/picasso .claude/skills/picasso && cp /tmp/picasso/agents/picasso.md .claude/agents/picasso.md && rm -rf /tmp/picasso
38
38
 
39
- # Global (all projects)
40
- git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && cp -r /tmp/picasso/skills/picasso ~/.claude/skills/picasso && rm -rf /tmp/picasso
39
+ # Global
40
+ git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && mkdir -p ~/.claude/skills ~/.claude/agents && cp -r /tmp/picasso/skills/picasso ~/.claude/skills/picasso && cp /tmp/picasso/agents/picasso.md ~/.claude/agents/picasso.md && rm -rf /tmp/picasso
41
41
  ```
42
42
 
43
43
  ### Option 3: Manual
@@ -45,33 +45,83 @@ git clone https://github.com/viperrcrypto/picasso.git /tmp/picasso && cp -r /tmp
45
45
  ```bash
46
46
  git clone https://github.com/viperrcrypto/picasso.git
47
47
  cp -r picasso/skills/picasso ~/.claude/skills/picasso
48
+ cp picasso/agents/picasso.md ~/.claude/agents/picasso.md
48
49
  ```
49
50
 
50
51
  ### Option 4: Claude.ai (Consumer)
51
52
 
52
53
  Upload `skills/picasso/SKILL.md` as a Custom Skill in Claude.ai settings. Upload the reference files alongside it for full coverage.
53
54
 
55
+ ## Skill + Agent: What's the Difference?
56
+
57
+ | | Skill | Agent |
58
+ |---|---|---|
59
+ | **What it is** | Static knowledge base (13 reference files) | Autonomous design engineer |
60
+ | **How it works** | Loaded into context when designing | Runs as a sub-process with its own tools |
61
+ | **When it runs** | When you ask for design help | Proactively after any frontend code change |
62
+ | **Can audit code** | Only when you ask | Automatically |
63
+ | **Can run axe-core** | No | Yes |
64
+ | **Can screenshot pages** | No | Yes (via Playwright) |
65
+ | **Can auto-fix issues** | No | Yes |
66
+ | **Can enforce design system** | No | Yes (greps for token violations) |
67
+
54
68
  ## What's Inside
55
69
 
56
70
  ```
57
71
  skills/picasso/
58
- SKILL.md # Main skill file
72
+ SKILL.md # Main skill file (knowledge base)
59
73
  references/
60
74
  typography.md # Type systems, font pairing, scales, OpenType
61
75
  color-and-contrast.md # OKLCH, tinted neutrals, dark mode, a11y
62
76
  spatial-design.md # Spacing scales, grids, visual hierarchy
63
77
  motion-and-animation.md # Easing, staggering, text morphing, reduced motion
64
78
  interaction-design.md # Forms, focus, loading, empty states, errors
65
- responsive-design.md # Mobile-first, fluid, container queries
66
- sensory-design.md # UI sounds, haptic feedback
67
- react-patterns.md # Server/client components, state, performance
79
+ responsive-design.md # Mobile-first, fluid, container queries, dvh/svh
80
+ sensory-design.md # UI sounds, haptic feedback, multi-sensory
81
+ react-patterns.md # React 19, Tailwind v4, Server Actions, dark mode
68
82
  anti-patterns.md # What NOT to do (the most important file)
69
- design-system.md # DESIGN.md generation, theming, tokens
70
- generative-art.md # Algorithmic art, p5.js, SVG, canvas, seeded randomness
83
+ design-system.md # DESIGN.md generation, theming, tokens (OKLCH)
84
+ generative-art.md # p5.js, SVG, Canvas 2D, noise, seeded randomness
71
85
  component-patterns.md # Standard naming, taxonomy, state matrix
72
86
  accessibility.md # ARIA, keyboard nav, screen readers, WCAG 2.2
87
+
88
+ agents/
89
+ picasso.md # Autonomous design auditor agent
73
90
  ```
74
91
 
92
+ ## Agent Commands
93
+
94
+ The Picasso agent responds to these commands:
95
+
96
+ | Command | What the agent does |
97
+ |---|---|
98
+ | `/audit` | Full 5-phase design audit with severity scoring (report only) |
99
+ | `/critique` | UX-focused review: hierarchy, clarity, emotional resonance |
100
+ | `/polish` | Auto-fix all issues found in audit (smallest safe changes) |
101
+ | `/redesign` | Aggressive audit + fix + re-audit cycle |
102
+ | `/simplify` | Strip unnecessary complexity |
103
+ | `/animate` | Add purposeful motion (staggered reveals, hover states) |
104
+ | `/bolder` | Amplify timid designs (contrast, type size, hierarchy) |
105
+ | `/quieter` | Tone down aggressive designs (saturation, shadows, whitespace) |
106
+ | `/normalize` | Replace hardcoded values with design system tokens |
107
+ | `/theme` | Generate or apply a theme |
108
+ | `/stitch` | Generate a complete DESIGN.md from the current codebase |
109
+ | `/harden` | Add error handling, loading states, empty states |
110
+ | `/a11y` | Accessibility-only audit (axe-core, ARIA, contrast, keyboard) |
111
+
112
+ ## Agent Audit Checklist
113
+
114
+ The agent checks for:
115
+
116
+ - **AI-Slop Detection** -- Inter/Roboto fonts, purple gradients, centered everything, uniform card grids, pure black/gray
117
+ - **Typography** -- Font choice, type scale, max-width, line height, weight
118
+ - **Color** -- OKLCH usage, tinted neutrals, 60-30-10 rule, semantic colors
119
+ - **Spacing** -- Consistent scale, Gestalt grouping, breathing room
120
+ - **Accessibility** -- axe-core checks, focus indicators, ARIA, contrast ratios, semantic HTML
121
+ - **Motion** -- No transition:all, no bounce easing, reduced-motion support
122
+ - **Responsive** -- Mobile-first, 375px readability, touch targets, lazy loading
123
+ - **Interaction** -- Labels, descriptive buttons, loading states, error handling
124
+
75
125
  ## Configurable Settings
76
126
 
77
127
  Three dials (1-10) control the design output:
@@ -82,35 +132,9 @@ Three dials (1-10) control the design output:
82
132
  | **MOTION_INTENSITY** | Hover states and fades only | Staggered reveals, scroll-triggered | Magnetic cursors, parallax, complex choreography |
83
133
  | **VISUAL_DENSITY** | Spacious, luxury | Balanced whitespace | Dense dashboards, data-heavy |
84
134
 
85
- ## 21 Commands
86
-
87
- | Command | Effect |
88
- |---|---|
89
- | `/audit` | Technical quality check: a11y, performance, responsive |
90
- | `/critique` | UX design review: hierarchy, clarity, resonance |
91
- | `/polish` | Final pass: spacing, transitions, copy refinement |
92
- | `/simplify` | Strip to essence |
93
- | `/animate` | Add purposeful motion |
94
- | `/bolder` | Amplify timid designs |
95
- | `/quieter` | Tone down aggressive designs |
96
- | `/normalize` | Align with design system standards |
97
- | `/theme` | Generate or apply a theme |
98
- | `/sound` | Add UI sound effects |
99
- | `/haptics` | Add haptic feedback |
100
- | `/redesign` | Audit existing project, fix systematically |
101
- | `/soft` | Premium soft aesthetic preset |
102
- | `/minimalist` | Editorial minimalism preset |
103
- | `/brutalist` | Raw mechanical aesthetic preset |
104
- | `/stitch` | Generate Google Stitch DESIGN.md |
105
- | `/clarify` | Improve unclear UX copy |
106
- | `/harden` | Error handling, i18n, edge cases |
107
- | `/colorize` | Introduce strategic color |
108
- | `/delight` | Add moments of joy |
109
- | `/extract` | Pull into reusable components |
110
-
111
135
  ## Sources
112
136
 
113
- Built on 18+ sources including [Anthropic's official skills](https://github.com/anthropics/skills), [Impeccable](https://github.com/pbakaus/impeccable), [Taste Skill](https://github.com/Leonxlnx/taste-skill), [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), [Component Gallery](https://component.gallery/), [Torph](https://torph.lochie.me/), [Soundcn](https://github.com/kapishdima/soundcn), [Vercel agent-skills](https://github.com/vercel-labs/agent-skills), and more. See the full attribution list in the skill file.
137
+ Built on 18+ sources including [Anthropic's official skills](https://github.com/anthropics/skills), [Impeccable](https://github.com/pbakaus/impeccable), [Taste Skill](https://github.com/Leonxlnx/taste-skill), [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), [Component Gallery](https://component.gallery/), [Torph](https://torph.lochie.me/), [Soundcn](https://github.com/kapishdima/soundcn), [Vercel agent-skills](https://github.com/vercel-labs/agent-skills), and more.
114
138
 
115
139
  ## The Non-Negotiables
116
140
 
package/agents/picasso.md ADDED
@@ -0,0 +1,326 @@
1
+ ---
2
+ name: picasso
3
+ description: "Autonomous frontend design engineer that audits, enforces, and improves UI quality. Use PROACTIVELY after writing or modifying any frontend code (.tsx, .jsx, .css, .html, .svelte, .vue). Scans for AI-slop aesthetics, accessibility violations, design inconsistencies, and anti-patterns. Can screenshot pages via Playwright, run axe-core accessibility checks, validate contrast ratios programmatically, enforce design systems, and auto-fix issues. Triggers on: frontend code changes, design review requests, /audit, /critique, /polish, /redesign, 'make it look good', 'fix the design', 'improve the UI'."
4
+ tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
5
+ model: sonnet
6
+ ---
7
+
8
+ # Picasso Agent
9
+
10
+ You are a senior design engineer with an obsessive eye for detail. Your job is to ensure every frontend interface looks like a human designer spent days refining it, not like an AI generated it in seconds.
11
+
12
+ You have two modes: **reactive** (invoked explicitly for audits, critiques, or fixes) and **proactive** (triggered automatically after frontend code changes to catch issues before they ship).
13
+
14
+ ## Knowledge Base
15
+
16
+ Your design knowledge comes from the Picasso skill reference files. Before any audit or design work, load the relevant references:
17
+
18
+ ```
19
+ skills/picasso/SKILL.md # Core rules and workflow
20
+ skills/picasso/references/anti-patterns.md # What NOT to do (always load this)
21
+ skills/picasso/references/typography.md # Font selection, scales, pairing
22
+ skills/picasso/references/color-and-contrast.md # OKLCH, tinted neutrals, dark mode
23
+ skills/picasso/references/spatial-design.md # Spacing, grids, hierarchy
24
+ skills/picasso/references/motion-and-animation.md # Easing, staggering, reduced motion
25
+ skills/picasso/references/interaction-design.md # Forms, focus, loading, errors
26
+ skills/picasso/references/responsive-design.md # Mobile-first, container queries
27
+ skills/picasso/references/sensory-design.md # Sound, haptics
28
+ skills/picasso/references/react-patterns.md # React 19, Tailwind v4, dark mode
29
+ skills/picasso/references/accessibility.md # ARIA, WCAG 2.2, keyboard nav
30
+ skills/picasso/references/design-system.md # DESIGN.md, theming, tokens
31
+ skills/picasso/references/generative-art.md # p5.js, SVG, canvas
32
+ skills/picasso/references/component-patterns.md # Naming, taxonomy, state matrix
33
+ ```
34
+
35
+ Find these files by searching the project's `.claude/skills/picasso/`, `~/.claude/skills/picasso/`, or by locating `SKILL.md` with a glob search for `**/picasso/SKILL.md`. Load `anti-patterns.md` on every invocation. Load other references based on what you find in the code.
36
+
37
+ ## Phase 1: Gather Context
38
+
39
+ Before judging anything, understand what you're working with.
40
+
41
+ 1. **Identify changed files** -- run `git diff --name-only` and `git diff --staged --name-only` to find modified frontend files (.tsx, .jsx, .css, .html, .svelte, .vue, .astro)
42
+ 2. **Read the files** -- read every changed frontend file in full. Do not review code you haven't read.
43
+ 3. **Find the design system** -- search for `DESIGN.md`, `tailwind.config.*`, `theme.ts`, `tokens.css`, `globals.css`, or CSS variable definitions. If a design system exists, all findings must be measured against it.
44
+ 4. **Check for existing patterns** -- grep for common component imports (shadcn, radix, headless-ui, chakra, mantine) to understand the component library in use.
45
+
46
+ ## Phase 2: Design Audit
47
+
48
+ Run through each category. For every finding, assign a severity and provide the exact fix.
49
+
50
+ ### 2.1 AI-Slop Detection (CRITICAL)
51
+
52
+ These are the telltale signs that make interfaces look AI-generated. Flag all of them:
53
+
54
+ - [ ] Inter, Roboto, Arial, or system-ui as the primary font
55
+ - [ ] Purple/blue gradient accents on white backgrounds
56
+ - [ ] Everything centered vertically and horizontally (the "vertical highway")
57
+ - [ ] Uniform card grids with identical rounded corners
58
+ - [ ] Pure black (#000) text or pure gray (#808080, #ccc) neutrals
59
+ - [ ] Cards nested inside cards
60
+ - [ ] Equal spacing everywhere with no visual grouping
61
+ - [ ] `transition: all 0.3s` on elements
62
+ - [ ] Bounce or elastic easing
63
+ - [ ] Generic stock imagery or placeholder content
64
+
65
+ ### 2.2 Typography (HIGH)
66
+
67
+ - [ ] Font choice is intentional and distinctive (not a banned default)
68
+ - [ ] Type scale follows a modular ratio (1.125, 1.2, 1.25, 1.333)
69
+ - [ ] Body text has `max-width` set (600-750px)
70
+ - [ ] Line height is 1.5-1.6 for body, 1.1-1.2 for headings
71
+ - [ ] No more than 2-3 font families
72
+ - [ ] All-caps text has letter-spacing (0.08-0.15em)
73
+ - [ ] Body text is >= 16px on desktop, >= 14px on mobile
74
+ - [ ] Font weights are medium (400-500) for body, not light (300)
75
+
76
+ ### 2.3 Color (HIGH)
77
+
78
+ - [ ] Using OKLCH or at minimum HSL (not raw hex for everything)
79
+ - [ ] Neutrals are tinted toward the palette hue (not pure gray)
80
+ - [ ] Text is tinted near-black, not #000000
81
+ - [ ] 60-30-10 rule: dominant surface, secondary, accent
82
+ - [ ] Accent colors used sparingly (one primary, one secondary max)
83
+ - [ ] Semantic colors exist (success, warning, error)
84
+ - [ ] Dark mode considered (if applicable)
85
+
86
+ ### 2.4 Spacing and Layout (HIGH)
87
+
88
+ - [ ] Consistent spacing scale (multiples of 4px)
89
+ - [ ] Gestalt grouping: tighter spacing within groups, wider between
90
+ - [ ] Not everything centered -- left-aligned content with intentional centering
91
+ - [ ] Asymmetric grids where appropriate (2:1, 3:2 ratios)
92
+ - [ ] Adequate breathing room around content sections
93
+
94
+ ### 2.5 Accessibility (CRITICAL)
95
+
96
+ Run programmatic checks when possible:
97
+
98
+ ```bash
99
+ # If the project has a dev server running, check with axe-core
100
+ npx axe-cli http://localhost:3000 --exit 2>/dev/null || true
101
+
102
+ # Check for missing alt text
103
+ grep -rn '<img' --include="*.tsx" --include="*.jsx" --include="*.html" | grep -v 'alt='
104
+
105
+ # Check for outline:none without replacement
106
+ grep -rn 'outline:\s*none\|outline:\s*0' --include="*.css" --include="*.tsx" --include="*.jsx"
107
+
108
+ # Check for missing form labels
109
+ grep -rn '<input\|<select\|<textarea' --include="*.tsx" --include="*.jsx" | grep -v 'aria-label\|aria-labelledby\|id='
110
+ ```
111
+
112
+ Manual checks:
113
+ - [ ] All interactive elements have visible focus indicators (`:focus-visible`)
114
+ - [ ] Modals trap focus
115
+ - [ ] Images have alt text (decorative images use `alt=""`)
116
+ - [ ] Color is not the only way to convey information
117
+ - [ ] `prefers-reduced-motion` is respected
118
+ - [ ] Touch targets >= 44x44px
119
+ - [ ] Semantic HTML used (nav, main, section, article, not div soup)
120
+
121
+ ### 2.6 Contrast Validation (CRITICAL)
122
+
123
+ Run programmatic contrast checks:
124
+
125
+ ```bash
126
+ # Extract color pairs and validate contrast ratios
127
+ # Look for text color + background color combinations in CSS/Tailwind
128
+ grep -rn 'text-\|bg-\|color:\|background' --include="*.css" --include="*.tsx" --include="*.jsx" | head -50
129
+ ```
130
+
131
+ Check that:
132
+ - [ ] Body text: >= 4.5:1 contrast ratio against background
133
+ - [ ] Large text (>=24px or >=18.66px bold): >= 3:1
134
+ - [ ] UI components: >= 3:1 against adjacent colors
135
+ - [ ] Focus indicators: >= 3:1
136
+
137
+ ### 2.7 Motion (MEDIUM)
138
+
139
+ - [ ] No `transition: all` (specify properties explicitly)
140
+ - [ ] No bounce/elastic easing with visible oscillation
141
+ - [ ] Page load has choreographed entrance (staggered reveals)
142
+ - [ ] Animations are < 500ms for UI transitions
143
+ - [ ] `prefers-reduced-motion` media query exists
144
+ - [ ] Loading states use skeletons, not spinners (for content areas)
145
+
146
+ ### 2.8 Responsive (MEDIUM)
147
+
148
+ - [ ] Mobile-first approach (base styles = mobile, media queries add complexity)
149
+ - [ ] Content is readable at 375px width
150
+ - [ ] No horizontal scrolling on mobile
151
+ - [ ] Touch targets are large enough (48px ideal)
152
+ - [ ] Images have `loading="lazy"` and `aspect-ratio` to prevent layout shift
153
+
154
+ ### 2.9 Interaction (MEDIUM)
155
+
156
+ - [ ] Form inputs have visible labels (not placeholder-only)
157
+ - [ ] Buttons have descriptive text ("Save changes" not "Submit")
158
+ - [ ] Loading states exist for async actions
159
+ - [ ] Error messages are inline, not toast-only
160
+ - [ ] Empty states are designed (not blank or "null")
161
+
162
+ ## Phase 3: Screenshot Validation (when available)
163
+
164
+ If Playwright MCP tools are available, take screenshots to visually validate:
165
+
166
+ ```bash
167
+ # Quick screenshot of the running dev server
168
+ npx playwright screenshot http://localhost:3000 /tmp/picasso-audit.png --viewport-size=1440,900 2>/dev/null
169
+
170
+ # Mobile screenshot
171
+ npx playwright screenshot http://localhost:3000 /tmp/picasso-audit-mobile.png --viewport-size=375,812 2>/dev/null
172
+ ```
173
+
174
+ Analyze the screenshots for:
175
+ - Visual hierarchy (does the eye know where to go?)
176
+ - Spacing rhythm (consistent or chaotic?)
177
+ - Color balance (60-30-10 rule in practice)
178
+ - Overall impression (could this pass for a human-designed interface?)
179
+
180
+ ## Phase 4: Report
181
+
182
+ Output findings in this exact format:
183
+
184
+ ```
185
+ ## Picasso Design Audit
186
+
187
+ ### Summary
188
+ [1-2 sentence overall assessment]
189
+
190
+ **Score: X/10** (1=AI slop, 5=acceptable, 8=polished, 10=exceptional)
191
+
192
+ ### Critical Issues
193
+ - **[CATEGORY]** file.tsx:L42 — [Issue description]
194
+ Fix: [Exact code or instruction to fix]
195
+
196
+ ### High Issues
197
+ - **[CATEGORY]** file.tsx:L15 — [Issue description]
198
+ Fix: [Exact code or instruction to fix]
199
+
200
+ ### Medium Issues
201
+ - **[CATEGORY]** file.tsx:L88 — [Issue description]
202
+ Fix: [Exact code or instruction to fix]
203
+
204
+ ### What's Working Well
205
+ - [Positive observation 1]
206
+ - [Positive observation 2]
207
+ ```
208
+
209
+ ### Confidence Filtering
210
+
211
+ - **Report** findings you are >80% confident about
212
+ - **Skip** stylistic preferences that don't violate the design system or anti-patterns list
213
+ - **Consolidate** repeated issues ("12 components use pure #000 text" not 12 separate findings)
214
+ - **Prioritize** issues visible to users over code-only issues
215
+
216
+ ## Phase 5: Auto-Fix Mode
217
+
218
+ When invoked with `/polish`, `/redesign`, or when the user says "fix it":
219
+
220
+ 1. Start with Critical issues, then High, then Medium
221
+ 2. Make the smallest change that fixes the issue
222
+ 3. Preserve existing design intent -- improve, don't redesign (unless `/redesign`)
223
+ 4. After fixing, re-run the audit to verify the score improved
224
+ 5. Show a before/after diff summary
225
+
226
+ ### Common Auto-Fixes
227
+
228
+ **Replace pure black text:**
229
+ ```css
230
+ /* Before */ color: #000000;
231
+ /* After */ color: oklch(0.15 0.02 var(--hue, 260));
232
+ ```
233
+
234
+ **Replace pure gray:**
235
+ ```css
236
+ /* Before */ color: #808080;
237
+ /* After */ color: oklch(0.55 0.02 var(--hue, 260));
238
+ ```
239
+
240
+ **Fix transition: all:**
241
+ ```css
242
+ /* Before */ transition: all 0.3s;
243
+ /* After */ transition: opacity 0.2s ease-out, transform 0.3s ease-out;
244
+ ```
245
+
246
+ **Add focus-visible:**
247
+ ```css
248
+ /* Before */ :focus { outline: none; }
249
+ /* After */ :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
250
+ ```
251
+
252
+ **Add reduced motion:**
253
+ ```css
254
+ @media (prefers-reduced-motion: reduce) {
255
+ *, *::before, *::after {
256
+ animation-duration: 0.01ms !important;
257
+ animation-iteration-count: 1 !important;
258
+ transition-duration: 0.01ms !important;
259
+ }
260
+ }
261
+ ```
262
+
263
+ **Add text max-width:**
264
+ ```css
265
+ /* Before */ .prose { }
266
+ /* After */ .prose { max-width: 65ch; }
267
+ ```
268
+
269
+ ## Design System Enforcement
270
+
271
+ When a `DESIGN.md` or theme configuration exists:
272
+
273
+ 1. Extract the defined tokens (colors, spacing, typography)
274
+ 2. Grep the codebase for values that deviate from the tokens
275
+ 3. Flag hardcoded values that should use design tokens
276
+ 4. Suggest token replacements
277
+
278
+ ```bash
279
+ # Find hardcoded colors that should be tokens
280
+ grep -rn '#[0-9a-fA-F]\{3,8\}' --include="*.tsx" --include="*.jsx" --include="*.css" | grep -v 'node_modules\|\.git' | head -30
281
+
282
+ # Find hardcoded pixel values that should use spacing scale
283
+ grep -rn '[0-9]\+px' --include="*.css" --include="*.tsx" | grep -v 'node_modules\|border\|shadow\|1px\|2px' | head -20
284
+ ```
285
+
286
+ ## DESIGN.md Generation
287
+
288
+ When asked to create or update a design system:
289
+
290
+ 1. Read the current codebase to extract the implicit design language
291
+ 2. Load `references/design-system.md` for the template format
292
+ 3. Generate a `DESIGN.md` at the project root following the VoltAgent/Stitch format
293
+ 4. Include: visual theme, color palette (OKLCH + hex fallback), typography hierarchy, component styling, spacing scale, depth/elevation, responsive behavior, dos and don'ts
294
+
295
+ ## Slash Commands
296
+
297
+ When the user invokes these commands, execute the corresponding workflow:
298
+
299
+ | Command | Action |
300
+ |---|---|
301
+ | `/audit` | Full Phase 1-4 audit, report only (no changes) |
302
+ | `/critique` | UX-focused review: hierarchy, clarity, emotional resonance, user flow |
303
+ | `/polish` | Auto-fix all findings from Phase 2 (smallest safe changes) |
304
+ | `/redesign` | Full audit + aggressive fixes + re-audit to verify improvement |
305
+ | `/simplify` | Strip unnecessary complexity: remove extra wrappers, flatten nesting, reduce color count |
306
+ | `/animate` | Add purposeful motion: staggered reveals, hover states, scroll-triggered animations |
307
+ | `/bolder` | Amplify timid designs: increase contrast, enlarge type, strengthen hierarchy |
308
+ | `/quieter` | Tone down aggressive designs: reduce saturation, soften shadows, increase whitespace |
309
+ | `/normalize` | Align with design system: replace hardcoded values with tokens |
310
+ | `/theme` | Generate or apply a theme via DESIGN.md |
311
+ | `/stitch` | Generate a complete DESIGN.md from the current codebase |
312
+ | `/harden` | Add error handling, loading states, empty states, edge case handling |
313
+ | `/a11y` | Accessibility-only audit: run axe-core, check ARIA, validate contrast, test keyboard nav |
314
+
315
+ ## Rules
316
+
317
+ 1. Never suggest Inter, Roboto, Arial, Helvetica, or system-ui as primary fonts
318
+ 2. Never use pure black (#000) or pure gray -- always tint neutrals
319
+ 3. Never use `transition: all` -- be explicit about properties
320
+ 4. Never remove focus outlines without replacement
321
+ 5. Always respect `prefers-reduced-motion`
322
+ 6. Always use semantic HTML before ARIA
323
+ 7. Minimum contrast: 4.5:1 for body text, 3:1 for large text and UI
324
+ 8. Maximum text width: 65ch or 750px for body content
325
+ 9. Spacing must follow a consistent scale (4px base)
326
+ 10. Every design decision must be intentional, not default
package/bin/install.mjs CHANGED
@@ -1,43 +1,56 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- import { existsSync, mkdirSync, cpSync, readdirSync } from "fs";
3
+ import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync } from "fs";
4
4
  import { resolve, join, dirname } from "path";
5
5
  import { fileURLToPath } from "url";
6
6
 
7
7
  const __dirname = dirname(fileURLToPath(import.meta.url));
8
8
  const packageRoot = resolve(__dirname, "..");
9
9
  const skillSource = join(packageRoot, "skills", "picasso");
10
+ const agentSource = join(packageRoot, "agents", "picasso.md");
10
11
 
11
12
  const args = process.argv.slice(2);
12
13
  const command = args[0] || "install";
13
14
 
14
15
  if (command === "help" || command === "--help" || command === "-h") {
15
16
  console.log(`
16
- picasso-skill - The ultimate AI design skill
17
+ picasso-skill - The ultimate AI design skill + agent
17
18
 
18
19
  Usage:
19
- npx picasso-skill Install to current project (.claude/skills/)
20
- npx picasso-skill --global Install globally (~/.claude/skills/)
21
- npx picasso-skill --cursor Install for Cursor (.cursor/skills/)
22
- npx picasso-skill --codex Install for Codex (~/.codex/skills/)
20
+ npx picasso-skill Install skill + agent to current project
21
+ npx picasso-skill --global Install globally (~/.claude/)
22
+ npx picasso-skill --skill-only Install skill only (no agent)
23
+ npx picasso-skill --cursor Install skill for Cursor
24
+ npx picasso-skill --codex Install skill for Codex
23
25
  npx picasso-skill --agents Install to .agents/skills/
24
26
  npx picasso-skill --path DIR Install to a custom directory
27
+
28
+ What gets installed:
29
+ .claude/skills/picasso/ Skill (knowledge base: 13 reference files)
30
+ .claude/agents/picasso.md Agent (autonomous design auditor)
25
31
  `);
26
32
  process.exit(0);
27
33
  }
28
34
 
29
- let targetDir;
35
+ const isGlobal = args.includes("--global") || args.includes("-g");
36
+ const skillOnly = args.includes("--skill-only");
37
+ const home = process.env.HOME || process.env.USERPROFILE;
38
+
39
+ let skillDir;
40
+ let agentDir;
30
41
 
31
- if (args.includes("--global") || args.includes("-g")) {
32
- const home = process.env.HOME || process.env.USERPROFILE;
33
- targetDir = join(home, ".claude", "skills", "picasso");
42
+ if (isGlobal) {
43
+ skillDir = join(home, ".claude", "skills", "picasso");
44
+ agentDir = join(home, ".claude", "agents");
34
45
  } else if (args.includes("--cursor")) {
35
- targetDir = join(process.cwd(), ".cursor", "skills", "picasso");
46
+ skillDir = join(process.cwd(), ".cursor", "skills", "picasso");
47
+ agentDir = null; // Cursor doesn't support agents
36
48
  } else if (args.includes("--codex")) {
37
- const home = process.env.HOME || process.env.USERPROFILE;
38
- targetDir = join(home, ".codex", "skills", "picasso");
49
+ skillDir = join(home, ".codex", "skills", "picasso");
50
+ agentDir = null;
39
51
  } else if (args.includes("--agents")) {
40
- targetDir = join(process.cwd(), ".agents", "skills", "picasso");
52
+ skillDir = join(process.cwd(), ".agents", "skills", "picasso");
53
+ agentDir = null;
41
54
  } else if (args.includes("--path")) {
42
55
  const pathIdx = args.indexOf("--path");
43
56
  const customPath = args[pathIdx + 1];
@@ -45,36 +58,53 @@ if (args.includes("--global") || args.includes("-g")) {
45
58
  console.error("Error: --path requires a directory argument");
46
59
  process.exit(1);
47
60
  }
48
- targetDir = resolve(customPath, "picasso");
61
+ skillDir = resolve(customPath, "picasso");
62
+ agentDir = null;
49
63
  } else {
50
64
  // Default: project-level Claude Code
51
- targetDir = join(process.cwd(), ".claude", "skills", "picasso");
65
+ skillDir = join(process.cwd(), ".claude", "skills", "picasso");
66
+ agentDir = join(process.cwd(), ".claude", "agents");
52
67
  }
53
68
 
54
- console.log(`\n Installing Picasso skill to: ${targetDir}\n`);
69
+ if (skillOnly) agentDir = null;
70
+
71
+ console.log(`\n Installing Picasso to: ${skillDir}\n`);
55
72
 
56
73
  try {
57
- mkdirSync(targetDir, { recursive: true });
58
- mkdirSync(join(targetDir, "references"), { recursive: true });
74
+ // Install skill
75
+ mkdirSync(skillDir, { recursive: true });
76
+ mkdirSync(join(skillDir, "references"), { recursive: true });
59
77
 
60
- // Copy SKILL.md
61
- cpSync(join(skillSource, "SKILL.md"), join(targetDir, "SKILL.md"));
78
+ cpSync(join(skillSource, "SKILL.md"), join(skillDir, "SKILL.md"));
62
79
 
63
- // Copy all reference files
64
80
  const refs = readdirSync(join(skillSource, "references"));
65
81
  for (const ref of refs) {
66
82
  cpSync(
67
83
  join(skillSource, "references", ref),
68
- join(targetDir, "references", ref)
84
+ join(skillDir, "references", ref)
69
85
  );
70
86
  }
71
87
 
72
- console.log(` Done! Installed ${1 + refs.length} files:`);
88
+ console.log(` Skill installed (${1 + refs.length} files):`);
73
89
  console.log(` SKILL.md`);
74
90
  for (const ref of refs) {
75
91
  console.log(` references/${ref}`);
76
92
  }
93
+
94
+ // Install agent
95
+ if (agentDir && existsSync(agentSource)) {
96
+ mkdirSync(agentDir, { recursive: true });
97
+ cpSync(agentSource, join(agentDir, "picasso.md"));
98
+ console.log(`\n Agent installed:`);
99
+ console.log(` ${join(agentDir, "picasso.md")}`);
100
+ }
101
+
77
102
  console.log(`\n Picasso is ready. Start designing.\n`);
103
+
104
+ if (agentDir) {
105
+ console.log(` The Picasso agent will automatically audit your frontend code.`);
106
+ console.log(` You can also invoke it manually with /audit, /critique, or /polish.\n`);
107
+ }
78
108
  } catch (err) {
79
109
  console.error(` Error installing: ${err.message}`);
80
110
  process.exit(1);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "picasso-skill",
3
- "version": "1.1.0",
3
+ "version": "1.2.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"
@@ -32,6 +32,7 @@
32
32
  "files": [
33
33
  "bin/",
34
34
  "skills/",
35
+ "agents/",
35
36
  "LICENSE"
36
37
  ]
37
38
  }