picasso-skill 1.6.0 → 2.0.0

package/agents/picasso.md

@@ -1,6 +1,6 @@
 ---
 name: picasso
-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'."
+description: "Senior design engineer agent that audits, enforces, and improves frontend UI quality. Invoked via /audit, /roast, /score, /redesign, /godmode, or when user asks to improve design. Supports Playwright screenshots for visual validation. Enforces mandatory anti-slop gate before any design code generation. 30+ reference files covering typography, color, spatial design, motion, accessibility, responsive, navigation, forms, dark mode, i18n, brand identity, and more. For proactive auto-review on file changes, configure hooks in settings.json."
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
 model: opus
 ---
@@ -112,6 +112,8 @@ The interview is skipped when:
 - User says "just do it" or "skip the interview" or provides a detailed enough prompt
 - Proactive mode (triggered by file changes) -- never interview, just audit
 
+**CRITICAL: Even when the interview is skipped, Phase 0b (Anti-Slop Gate) MUST still run for any design generation task.** The interview captures preferences. The gate ensures quality. They are independent. Skipping one does not skip the other. The only commands that bypass BOTH are pure audit commands (`/audit`, `/score`, `/quick-audit`, `/roast`) which do not generate code.
+
 ### Re-running the Interview
 
 User can run `/picasso` at any time to redo the interview and regenerate `.picasso.md`.
@@ -383,9 +385,17 @@ When invoked with `/polish`, `/redesign`, or when the user says "fix it":
 
 **BEFORE ANY CODE CHANGES:** Run the Anti-Slop Gate (Phase 0b). Write out your commitments. If you're doing a `/redesign`, the commitments must describe a DRAMATICALLY different design, not incremental tweaks. The goal is transformation, not iteration.
 
+### Pre-Flight Checks (before ANY auto-fix)
+
+1. **Check git status** — run `git status`. If there are uncommitted changes, WARN the user: "You have uncommitted changes. Auto-fix will modify files. Commit or stash first?"
+2. **Count affected files** — if auto-fix would touch more than 10 files, list them and ask for confirmation before proceeding.
+3. **Run existing tests** — if a test command exists (`package.json` scripts.test), run it BEFORE fixing. If tests fail before your changes, note it. If tests pass before but fail after, REVERT your changes immediately.
+
+### Fix Execution
+
 1. Start with Critical issues, then High, then Medium
 2. Make the smallest change that fixes the issue
-3. Preserve existing design intent -- improve, don't redesign (unless `/redesign`)
+3. Preserve existing design intent — improve, don't redesign (unless `/redesign`)
 4. After fixing, re-run the audit to verify the score improved
 5. Show a before/after diff summary
 6. **Re-run the 3-Second Test** on screenshots. If it still looks AI-generated, you're not done.
@@ -498,6 +508,8 @@ When the user invokes these commands, execute the corresponding workflow:
 | `/godmode` | The ultimate command: interview + audit + score + roast + fix everything + before/after report |
 | `/quick-audit` | 5-minute fast audit: font, color, spacing, a11y, anti-slop — skip the deep dive |
 | `/autorefine` | Binary evaluation loop: define 6 criteria, mutate one thing at a time, iterate to 95%+ pass rate |
+| `/backlog` | Create persistent design debt backlog with impact-priority scoring in .picasso-backlog.md |
+| `/variants` | Generate 2-3 distinct visual directions for A/B comparison with previews |
 
 ## /godmode -- The Ultimate Design Transformation
 

package/commands/backlog.md

@@ -0,0 +1,34 @@
+Run the Picasso /backlog command -- create and manage a persistent design debt backlog.
+
+Create or update `.picasso-backlog.md` in the project root.
+
+Steps:
+1. Run /quick-audit to get current pass/fail status
+2. Run /score to get quantified baseline
+3. For each failing category, create a backlog item with:
+   - Severity: critical / high / medium / low
+   - Impact: estimated /score improvement (+N points)
+   - Files: which files need changes
+   - Fix: one-line description of what to change
+4. Sort items by impact descending (highest score improvement first)
+5. Write to `.picasso-backlog.md`
+
+Format:
+```markdown
+# Picasso Design Backlog
+Generated: [date] | Baseline Score: [N]/100
+
+## Critical
+- [ ] **Replace pure grays with tinted neutrals** (+6 pts) — globals.css, tailwind.config — Change #808080 to oklch(0.55 0.02 var(--hue))
+
+## High
+- [ ] **Add prefers-reduced-motion guard** (+4 pts) — globals.css — Wrap animations in @media (prefers-reduced-motion: no-preference)
+
+## Medium
+- [ ] **Fix transition:all instances** (+2 pts) — 3 files — Specify exact properties
+
+## Low
+- [ ] **Add skip link** (+1 pt) — layout.tsx — Add visually hidden skip-to-content link
+```
+
+If `.picasso-backlog.md` already exists, update it: mark completed items as done, add new findings, recalculate impacts.

package/commands/variants.md

@@ -0,0 +1,18 @@
+Run the Picasso /variants command -- generate 2-3 distinct visual directions for A/B comparison.
+
+Steps:
+1. Read the current project's design context (.picasso.md, DESIGN.md, or infer from code)
+2. Generate 2-3 genuinely different aesthetic directions. NOT slight variations -- each must differ in at least 3 of: font, color palette, layout structure, border-radius philosophy, motion intensity
+3. For each direction:
+   - Name it (e.g., "Editorial Minimalist", "Dark Terminal", "Warm Organic")
+   - List the 5 key design tokens (font, accent color, radius, shadow style, spacing density)
+   - Describe what makes it distinctive in 1-2 sentences
+   - Show a code snippet of one component (e.g., a card or button) in that style
+4. Present all directions to the user and ask which to pursue
+5. If Playwright is available, generate a quick HTML preview of each direction
+
+Rules:
+- Each direction must pass the 3-second anti-slop test independently
+- No two directions can share the same font
+- At least one direction must be surprising or unconventional
+- Always include one "safe" option and one "bold" option

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picasso-skill",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
   "bin": {
     "picasso-skill": "./bin/install.mjs"

package/skills/picasso/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: picasso
-version: 1.6.0
+version: 2.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:
@@ -31,6 +31,20 @@ When the user says "make it premium" or "luxury feel," drop VISUAL_DENSITY to 2-
 
 ---
 
+## Quick Start (30 seconds)
+
+New to Picasso? Here's the minimum viable workflow:
+
+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).
+3. **Tint your grays** toward your accent hue. Never use pure `#808080` or `#000`.
+4. **Break the center.** Left-align content. Use asymmetric grids (2:1, 3:2). Only center heroes and CTAs.
+5. **Read `references/anti-patterns.md`** before writing any code. It's the most important file.
+
+Then follow the full workflow below. Skip nothing.
+
+---
+
 ## Step 0: Read the Right References
 
 Before writing any code, read the reference files relevant to the task. Each covers a domain in depth with rules, examples, and anti-patterns. Load only what you need.
@@ -50,6 +64,16 @@ Before writing any code, read the reference files relevant to the task. Each cov
 | `references/design-system.md` | Generating DESIGN.md files, theming, systematic tokens |
 | `references/generative-art.md` | Algorithmic art, p5.js, seeded randomness, flow fields |
 | `references/component-patterns.md` | Standard component naming, taxonomy, and state patterns |
+| `references/navigation-patterns.md` | Breadcrumbs, sidebar, tabs, bottom bar, mega menus, skip links |
+| `references/tables-and-forms.md` | Sortable tables, inline editing, multi-step forms, validation |
+| `references/loading-and-states.md` | Skeletons, spinners, empty states, error boundaries, offline |
+| `references/dark-mode.md` | Preference hierarchy, surface elevation, transitions, testing |
+| `references/images-and-media.md` | Format selection, responsive images, favicons, OG images |
+| `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 |
 
 ---
 
@@ -73,7 +97,7 @@ This step is non-negotiable. It takes 30 seconds and prevents hours of rework.
    - Same spacing everywhere
    - Three equal-width items in a row
 
-If you skip this gate, the output WILL look AI-generated. There are no exceptions.
+**HALT CONDITION:** If you cannot fill out the commitments above with specific, non-default values, you MUST NOT proceed to Step 1. Go back to the references. Read anti-patterns.md. Try again. There is no "just do it" bypass for this step. The gate exists because without it, every output converges to the same generic AI aesthetic. This is not optional. No code until commitments are written.
 
 ---
 

package/skills/picasso/references/animation-performance.md

@@ -0,0 +1,244 @@
+# Animation Performance Reference
+
+## Table of Contents
+1. Compositor-Only Properties
+2. Will-Change Best Practices
+3. Layout Thrashing
+4. IntersectionObserver vs Scroll Events
+5. Web Animations API
+6. Performance Measurement
+7. Testing on Low-End Devices
+8. Contain Property
+9. Common Mistakes
+
+---
+
+## 1. Compositor-Only Properties
+
+Only two CSS properties can be animated without triggering layout or paint: **transform** and **opacity**. Everything else causes reflow.
+
+| Property | Layout | Paint | Composite | Animate? |
+|---|---|---|---|---|
+| `transform` | No | No | Yes | **Yes** |
+| `opacity` | No | No | Yes | **Yes** |
+| `filter` | No | Yes | Yes | Carefully |
+| `background-color` | No | Yes | No | Avoid |
+| `width`, `height` | Yes | Yes | No | **Never** |
+| `top`, `left` | Yes | Yes | No | **Never** |
+| `margin`, `padding` | Yes | Yes | No | **Never** |
+| `border-radius` | No | Yes | No | Avoid |
+
+```css
+/* Good: compositor-only */
+.slide-in {
+  transform: translateX(-100%);
+  opacity: 0;
+  transition: transform 300ms var(--ease-out), opacity 300ms var(--ease-out);
+}
+.slide-in.active {
+  transform: translateX(0);
+  opacity: 1;
+}
+
+/* Bad: triggers layout on every frame */
+.slide-in-bad {
+  left: -100%;
+  transition: left 300ms ease;
+}
+```
+
+---
+
+## 2. Will-Change Best Practices
+
+`will-change` promotes an element to its own compositor layer. This speeds up animation but consumes GPU memory.
+
+Rules:
+- Add `will-change` BEFORE the animation starts (e.g., on hover, not in the animation itself).
+- Remove it AFTER the animation completes.
+- Never use `will-change: all` — it promotes everything.
+- Never apply it to more than 10 elements simultaneously.
+- Don't put it in your stylesheet permanently.
+
+```js
+// Good: apply before, remove after
+element.addEventListener('mouseenter', () => {
+  element.style.willChange = 'transform';
+});
+element.addEventListener('transitionend', () => {
+  element.style.willChange = 'auto';
+});
+```
+
+```css
+/* Acceptable: for elements that are ALWAYS animated (e.g., loading spinners) */
+.spinner { will-change: transform; }
+
+/* Bad: permanent will-change on static elements */
+.card { will-change: transform, opacity; } /* don't do this */
+```
+
+---
+
+## 3. Layout Thrashing
+
+Reading layout properties then writing them in a loop forces the browser to recalculate layout on every iteration.
+
+```js
+// BAD: layout thrashing (read-write-read-write)
+elements.forEach(el => {
+  const height = el.offsetHeight;    // READ — forces layout
+  el.style.height = height + 10 + 'px'; // WRITE — invalidates layout
+});
+
+// GOOD: batch reads, then batch writes
+const heights = elements.map(el => el.offsetHeight); // all reads first
+elements.forEach((el, i) => {
+  el.style.height = heights[i] + 10 + 'px'; // all writes after
+});
+```
+
+Properties that trigger forced layout when read: `offsetHeight`, `offsetWidth`, `getBoundingClientRect()`, `scrollTop`, `clientHeight`, `getComputedStyle()`.
+
+---
+
+## 4. IntersectionObserver vs Scroll Events
+
+| | `scroll` event | IntersectionObserver |
+|---|---|---|
+| Performance | Fires every pixel, blocks main thread | Async, fires on threshold crossing |
+| Throttling | Manual (requestAnimationFrame) | Built-in |
+| Use case | Scroll-linked animation (position) | Visibility detection (enter/exit) |
+| Recommendation | Almost never | Almost always |
+
+```js
+// Good: IntersectionObserver for reveal animations
+const observer = new IntersectionObserver(
+  (entries) => {
+    entries.forEach(entry => {
+      entry.target.classList.toggle('visible', entry.isIntersecting);
+    });
+  },
+  { threshold: 0.1 }
+);
+```
+
+For scroll-linked animations where you need exact scroll position, use the Scroll-Driven Animations API:
+
+```css
+@keyframes fade-in {
+  from { opacity: 0; transform: translateY(20px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.scroll-reveal {
+  animation: fade-in linear;
+  animation-timeline: view();
+  animation-range: entry 0% entry 100%;
+}
+```
+
+---
+
+## 5. Web Animations API
+
+For complex JS-driven animations, use WAAPI instead of manual `requestAnimationFrame`:
+
+```js
+element.animate(
+  [
+    { transform: 'translateY(20px)', opacity: 0 },
+    { transform: 'translateY(0)', opacity: 1 }
+  ],
+  {
+    duration: 300,
+    easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
+    fill: 'forwards'
+  }
+);
+```
+
+Benefits over CSS: programmable, cancellable, can read progress, can reverse.
+
+---
+
+## 6. Performance Measurement
+
+```js
+// Measure animation frame rate
+let frames = 0;
+let lastTime = performance.now();
+
+function countFrames() {
+  frames++;
+  const now = performance.now();
+  if (now - lastTime >= 1000) {
+    console.log(`FPS: ${frames}`);
+    frames = 0;
+    lastTime = now;
+  }
+  requestAnimationFrame(countFrames);
+}
+requestAnimationFrame(countFrames);
+```
+
+Chrome DevTools:
+1. Performance tab → Record → interact with animations → Stop
+2. Look for long frames (> 16ms) in the flame chart
+3. Rendering tab → Paint flashing (green = repaint, should be minimal)
+4. Rendering tab → Layer borders (orange = composited layers)
+
+Target: 60fps = 16.67ms per frame. If ANY frame takes > 33ms, users perceive jank.
+
+---
+
+## 7. Testing on Low-End Devices
+
+Your M-series Mac is not representative. Test with:
+- **Chrome DevTools CPU throttling:** Performance tab → CPU → 6x slowdown
+- **Network throttling:** Slow 3G preset to test loading animations
+- **Real device:** Test on a 3-year-old Android phone if possible
+
+If an animation stutters at 6x CPU throttle, reduce:
+1. Number of concurrent animations
+2. Element count being animated
+3. Complexity of each animation
+
+---
+
+## 8. Contain Property
+
+`contain` tells the browser what NOT to recalculate when an element changes.
+
+```css
+/* Isolate layout/paint to this element */
+.card {
+  contain: layout paint;
+}
+
+/* Full isolation — best for off-screen or independent components */
+.widget {
+  contain: strict; /* = size + layout + paint + style */
+}
+
+/* Content containment — layout + paint + style (most common) */
+.list-item {
+  contain: content;
+}
+```
+
+Use `contain: content` on repeated elements (list items, cards) to prevent layout changes from propagating to siblings.
+
+---
+
+## 9. Common Mistakes
+
+- **Animating `width`/`height`/`top`/`left`.** Use `transform: translate/scale` instead.
+- **`will-change` on everything.** Max 10 elements. Remove after animation completes.
+- **`addEventListener('scroll')` for visibility.** Use IntersectionObserver.
+- **Reading layout properties in animation loops.** Batch reads before writes.
+- **Testing only on fast hardware.** Use Chrome CPU throttling at 6x.
+- **No frame budget awareness.** 16ms per frame. If your JS takes 20ms, you drop frames.
+- **CSS `transition: all`.** Transitions every property including layout triggers.
+- **Forgetting `contain` on repeated elements.** One card's layout change recalculates the entire list.
+- **`requestAnimationFrame` without cancellation.** Always store the ID and `cancelAnimationFrame` on cleanup.

package/skills/picasso/references/brand-and-identity.md

@@ -0,0 +1,136 @@
+# Brand and Identity Reference
+
+## Table of Contents
+1. Logo Sizing Rules
+2. Logo Placement
+3. Logo Lockup Variants
+4. Brand Color Usage
+5. Brand Typography
+6. Consistency Across Pages
+7. When to Bend Brand Rules
+8. Common Mistakes
+
+---
+
+## 1. Logo Sizing Rules
+
+- **Minimum size:** 24px height for icon-only, 32px height for full logo. Below this it's illegible.
+- **Clear space:** Minimum clear space around logo = the height of the logo's icon element. No text or elements may intrude.
+- **Typical sizes by context:**
+
+| Context | Height |
+|---|---|
+| Favicon | 32px |
+| Mobile header | 28-32px |
+| Desktop header | 32-40px |
+| Footer | 24-28px |
+| Hero/marketing | 48-64px |
+| App splash | 80-120px |
+
+```css
+.logo { height: 32px; width: auto; } /* maintain aspect ratio */
+.logo-icon { height: 28px; width: 28px; }
+```
+
+---
+
+## 2. Logo Placement
+
+- **Header:** top-left for LTR, top-right for RTL. Always links to homepage.
+- **Footer:** bottom-left or bottom-center. Smaller than header.
+- **Marketing pages:** centered for hero sections, left-aligned for navigation.
+- **Loading/splash:** centered vertically and horizontally.
+
+The header logo is the most important. It should be the first visual element the user sees, but not dominate the page. Keep it slim.
+
+---
+
+## 3. Logo Lockup Variants
+
+Every brand needs at least 3 logo variants:
+
+1. **Full lockup:** icon + wordmark (for headers, marketing)
+2. **Icon only:** for favicons, app icons, small spaces, mobile headers
+3. **Wordmark only:** for editorial/text-heavy contexts
+
+```jsx
+// Responsive logo: icon on mobile, full on desktop
+<Link href="/" className="flex items-center gap-2">
+  <img src="/logo-icon.svg" alt="" className="h-7 w-7" />
+  <span className="hidden sm:inline text-sm font-bold tracking-tight">Brand Name</span>
+</Link>
+```
+
+---
+
+## 4. Brand Color Usage
+
+Follow the 60-30-10 rule with brand colors:
+- **60%** — neutral surfaces (backgrounds, cards). Brand color should NOT be the 60%.
+- **30%** — supporting colors (borders, secondary text, section backgrounds).
+- **10%** — brand/accent color (CTAs, active states, highlights). This is where brand color goes.
+
+```css
+:root {
+  --brand: oklch(0.55 0.25 250);       /* Primary brand color — use at 10% */
+  --brand-subtle: oklch(0.95 0.03 250); /* Tinted background — use sparingly */
+  --brand-on-dark: oklch(0.70 0.18 250); /* Lighter variant for dark backgrounds */
+}
+```
+
+Never use brand color as background for large areas (hero sections, full-width bars) unless the brand is specifically known for it (like Spotify's green). Large saturated surfaces are fatiguing.
+
+---
+
+## 5. Brand Typography
+
+If the brand has a custom/licensed font, use it for headings only. Body text should be a readable, web-optimized font.
+
+```css
+/* Brand font for headings */
+h1, h2, h3 { font-family: 'Brand Display', var(--font-body); }
+
+/* Readable font for body */
+body { font-family: 'DM Sans', system-ui, sans-serif; }
+```
+
+If the brand font isn't available for web, find the closest web-safe alternative:
+- Futura → use Outfit or Jost
+- Helvetica Neue → use Inter (only acceptable here) or Geist
+- Garamond → use EB Garamond or Cormorant
+
+---
+
+## 6. Consistency Across Pages
+
+Every page should share:
+- Same header and footer (identical, not "similar")
+- Same color palette (no page-specific colors)
+- Same typography scale
+- Same border-radius philosophy
+- Same spacing scale
+
+Variation should come from layout and content, not from inconsistent styling. A dashboard page and a marketing page can look different through layout while sharing the same design tokens.
+
+---
+
+## 7. When to Bend Brand Rules
+
+Strict brand adherence isn't always right:
+- **Data-dense dashboards:** Brand color as accent only. Don't fight with data colors.
+- **Error states:** Use standard red for errors, not brand color. Users need instant recognition.
+- **Third-party embeds:** Payment forms, maps, chat widgets have their own styling. Don't fight it.
+- **Dark mode:** Brand color may need lightness/chroma adjustment to maintain contrast.
+- **Accessibility:** If brand colors don't meet WCAG contrast, accessibility wins.
+
+---
+
+## 8. Common Mistakes
+
+- **Logo too small in the header.** Minimum 28px height. Users need to identify the brand instantly.
+- **Brand color as full-width background.** Fatiguing. Use at 10% ratio maximum.
+- **Different fonts on every page.** Pick 2 fonts and use them everywhere.
+- **Logo without clear space.** Crowded logos look unprofessional. Enforce minimum padding.
+- **No icon-only variant.** Mobile needs a compact logo. Don't just shrink the full lockup.
+- **Brand color unchanged in dark mode.** Adjust lightness and chroma for dark backgrounds.
+- **Inconsistent border radius between pages.** One sharp page and one rounded page = two brands.