npm - picasso-skill - Versions diffs - 2.7.0 → 3.0.0 - Mend

picasso-skill 2.7.0 → 3.0.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 (11) hide show

package/README.md +118 -115
package/agents/picasso.md +44 -17
package/bin/install.mjs +5 -3
package/commands/godmode.md +3 -4
package/package.json +1 -1
package/skills/picasso/SKILL.md +82 -21
package/skills/picasso/references/figma-mcp.md +190 -0
package/skills/picasso/references/ux-evaluation.md +211 -0
package/skills/picasso/references/visual-preview.md +367 -0
package/skills/picasso/references/animation-performance.md +0 -244
package/skills/picasso/references/interaction-design.md +0 -162

package/skills/picasso/references/visual-preview.md ADDED Viewed

@@ -0,0 +1,367 @@
+# Visual Preview Reference
+Generate self-contained HTML previews to show users what design options look like before they commit. This replaces text-only descriptions with actual visual examples.
+---
+## 1. The Preview Protocol
+Every time Picasso presents 2+ aesthetic options for the user to choose from, generate a visual preview. Text-only option lists are banned for aesthetic decisions.
+### Standard Flow
+1. **Generate** a self-contained HTML file with inline styles (NO external font imports -- use `system-ui` with font name labels)
+2. **Write** to `/tmp/picasso-preview-{name}.html`
+3. **Screenshot** via Bash: `npx playwright screenshot /tmp/picasso-preview-{name}.html /tmp/picasso-preview-{name}.png --viewport-size=1200,800`
+   - `npx playwright screenshot` accepts file paths directly (no `file://` prefix needed)
+   - Do NOT use `mcp__playwright__browser_navigate` + `mcp__playwright__browser_take_screenshot` -- these timeout on external font loading and block `file://` protocol
+4. **View** the screenshot with `Read /tmp/picasso-preview-{name}.png` (mandatory -- never skip this)
+5. **Present** to the user with both paths (HTML for full-res browser viewing, PNG for quick preview)
+### If npx playwright Is Unavailable
+1. Write the HTML file to `/tmp/`
+2. Tell the user: "I've generated a visual preview at `/tmp/picasso-preview-{name}.html` -- open it in your browser to see the options."
+3. Do NOT make visual claims about what the preview looks like without viewing it
+### Font Rule for Previews
+Do NOT import Google Fonts or Fontshare fonts via `<link>` or `@import` in preview HTML. External font loading causes screenshot timeouts. Instead:
+- Use `system-ui, -apple-system, sans-serif` for body text
+- Use `Georgia, serif` for serif directions
+- Use `ui-monospace, monospace` for mono directions
+- **Label the intended font** in each preview card: "Font: Satoshi + DM Sans" so the user knows what will be used in the real implementation
+### File Naming
+- Interview aesthetics: `/tmp/picasso-interview-vibes.html`
+- Design brief preview: `/tmp/picasso-brief-preview.html`
+- Variants comparison: `/tmp/picasso-variants.html`
+- Mood preview: `/tmp/picasso-mood-{word}.html`
+- Preset browser: `/tmp/picasso-preset-browser.html`
+- Standalone preview: `/tmp/picasso-preview.html`
+---
+## 2. HTML Template: Side-by-Side Direction Comparison
+Use this when showing 2-4 aesthetic directions for the user to choose from (interview, /variants, /preview compare).
+Generate the full HTML dynamically. For each direction, substitute the actual font, colors, radius, and spacing values. The template below is a structural guide -- adapt the content to match each specific direction.
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Picasso: Choose a Direction</title>
+<!-- Import fonts for all directions shown -->
+<!-- No external font imports -- use system fonts to avoid screenshot timeouts -->
+<!-- Label intended fonts in the .font-info footer of each card -->
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: system-ui, sans-serif;
+    background: #f5f5f5;
+    padding: 32px;
+    color: #1a1a1a;
+  }
+  h1 {
+    text-align: center;
+    font-size: 20px;
+    font-weight: 600;
+    margin-bottom: 8px;
+    letter-spacing: -0.02em;
+  }
+  .subtitle {
+    text-align: center;
+    font-size: 13px;
+    color: #666;
+    margin-bottom: 32px;
+  }
+  .grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(340px, 1fr));
+    gap: 24px;
+    max-width: 1200px;
+    margin: 0 auto;
+  }
+  .direction {
+    border-radius: 12px;
+    overflow: hidden;
+    box-shadow: 0 2px 12px rgba(0,0,0,0.08);
+  }
+  .direction-label {
+    padding: 12px 16px;
+    font-size: 13px;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    background: #fff;
+    border-bottom: 1px solid #eee;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+  .direction-label span {
+    font-size: 11px;
+    font-weight: 400;
+    text-transform: none;
+    letter-spacing: 0;
+    color: #999;
+  }
+  /* Each .preview is a mini page rendered in the direction's style */
+  .preview {
+    padding: 24px;
+    min-height: 400px;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+  }
+  /* Palette strip */
+  .palette {
+    display: flex;
+    gap: 4px;
+    height: 24px;
+    border-radius: 4px;
+    overflow: hidden;
+  }
+  .palette .swatch {
+    flex: 1;
+    position: relative;
+  }
+  /* Sample nav */
+  .sample-nav {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 8px 0;
+  }
+  .sample-nav .logo {
+    font-weight: 700;
+    font-size: 15px;
+  }
+  .sample-nav .links {
+    display: flex;
+    gap: 16px;
+    font-size: 12px;
+    opacity: 0.6;
+  }
+  /* Sample card */
+  .sample-card {
+    padding: 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .sample-card h3 {
+    font-size: 16px;
+    font-weight: 600;
+  }
+  .sample-card p {
+    font-size: 12px;
+    line-height: 1.6;
+    opacity: 0.7;
+  }
+  /* Sample button */
+  .sample-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 8px 20px;
+    font-size: 12px;
+    font-weight: 600;
+    border: none;
+    cursor: pointer;
+    width: fit-content;
+  }
+  /* Sample input */
+  .sample-input {
+    padding: 8px 12px;
+    font-size: 12px;
+    border: 1px solid;
+    background: transparent;
+    width: 100%;
+  }
+  /* Font info footer */
+  .font-info {
+    font-size: 10px;
+    opacity: 0.4;
+    padding-top: 8px;
+    border-top: 1px solid;
+    border-color: inherit;
+  }
+</style>
+</head>
+<body>
+<h1>Choose a Direction</h1>
+<p class="subtitle">Pick one, combine elements, or describe something different.</p>
+<div class="grid">
+  <!-- Direction A -->
+  <div class="direction">
+    <div class="direction-label">
+      A: {DIRECTION_A_NAME}
+      <span>{DIRECTION_A_VIBE}</span>
+    </div>
+    <div class="preview" style="background: {A_BG}; color: {A_TEXT}; font-family: '{A_BODY_FONT}', sans-serif;">
+      <div class="palette">
+        <div class="swatch" style="background: {A_COLOR_1};"></div>
+        <div class="swatch" style="background: {A_COLOR_2};"></div>
+        <div class="swatch" style="background: {A_COLOR_3};"></div>
+        <div class="swatch" style="background: {A_COLOR_4};"></div>
+        <div class="swatch" style="background: {A_COLOR_5};"></div>
+      </div>
+      <div class="sample-nav">
+        <div class="logo" style="font-family: '{A_HEADING_FONT}', sans-serif;">AppName</div>
+        <div class="links">Features &nbsp; Pricing &nbsp; Docs</div>
+      </div>
+      <div style="font-family: '{A_HEADING_FONT}', sans-serif; font-size: 22px; font-weight: 700; line-height: 1.2; letter-spacing: -0.02em;">
+        Build something people actually want
+      </div>
+      <div style="font-size: 13px; line-height: 1.6; opacity: 0.7;">
+        A short description that shows what body text looks like in this direction. Notice the font, weight, and spacing.
+      </div>
+      <div class="sample-card" style="background: {A_SURFACE}; border-radius: {A_RADIUS};">
+        <h3 style="font-family: '{A_HEADING_FONT}', sans-serif;">Sample Card</h3>
+        <p>This is how cards look in this direction. Pay attention to padding, radius, and depth.</p>
+      </div>
+      <div style="display: flex; gap: 8px;">
+        <div class="sample-btn" style="background: {A_PRIMARY}; color: {A_PRIMARY_TEXT}; border-radius: {A_RADIUS};">
+          Primary Action
+        </div>
+        <div class="sample-btn" style="background: transparent; color: {A_TEXT}; border: 1px solid {A_BORDER}; border-radius: {A_RADIUS};">
+          Secondary
+        </div>
+      </div>
+      <div class="sample-input" style="border-color: {A_BORDER}; border-radius: {A_RADIUS}; color: {A_TEXT};" placeholder="Input field...">
+        Input field...
+      </div>
+      <div class="font-info">
+        {A_HEADING_FONT} + {A_BODY_FONT} &middot; {A_RADIUS} radius
+      </div>
+    </div>
+  </div>
+  <!-- Repeat for Direction B, C, D... -->
+</div>
+</body>
+</html>
+```
+### How to Use This Template
+1. Do NOT copy-paste this template literally. Generate the HTML dynamically with actual values substituted for each direction.
+2. Each `{PLACEHOLDER}` must be replaced with real values from the direction you're previewing.
+3. The font `<link>` tag must include ALL fonts used across ALL directions being compared.
+4. The number of directions (2, 3, or 4) determines the grid columns.
+5. Keep the preview compact -- users should see all options without scrolling.
+---
+## 3. HTML Template: Full Page Mood Preview
+Use this for /mood and Design Brief previews. Shows a complete page layout in the specified style.
+Generate a full-page HTML that includes:
+- A navigation bar with logo text, 3-4 links, and a CTA button
+- A hero section with a large heading, subtitle, and primary button
+- A 3-column feature/card section
+- A form section with an input and button
+- A footer with muted text
+All styled with the mood's tokens (colors, fonts, radius, spacing). The content should be generic but realistic (not lorem ipsum). Size the page to 1440px viewport width.
+---
+## 4. HTML Template: Preset Browser Grid
+Use this for /preset without arguments. Shows all presets as a browsable grid.
+Generate an HTML page with:
+- A title: "Picasso Style Presets"
+- A grid of cards (4 columns, wrapping), one per preset
+- Each card shows:
+  - Preset name (in the preset's heading font)
+  - A 5-swatch color palette strip
+  - A one-line mood description
+  - A tiny sample button in the preset's primary color and radius
+- Cards should be ~280px wide, ~180px tall
+- The card background should use the preset's surface color
+- Card text should use the preset's text color
+This gives users a visual catalog to browse before choosing.
+---
+## 5. Font Loading
+### Google Fonts
+Most fonts can be loaded via Google Fonts. Construct the URL:
+```
+https://fonts.googleapis.com/css2?family={FontName}:wght@400;600;700&display=swap
+```
+Replace spaces with `+` in font names.
+### Fontshare (for fonts not on Google)
+Some popular Picasso fonts are on Fontshare:
+```
+https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&display=swap
+https://api.fontshare.com/v2/css?f[]=cabinet-grotesk@400,700,800&display=swap
+https://api.fontshare.com/v2/css?f[]=general-sans@400,500,600&display=swap
+https://api.fontshare.com/v2/css?f[]=clash-display@400,600,700&display=swap
+```
+### Common Font Mappings
+| Font Name | Source | Import URL |
+|-----------|--------|-----------|
+| Satoshi | Fontshare | `https://api.fontshare.com/v2/css?f[]=satoshi@400,500,700&display=swap` |
+| Cabinet Grotesk | Fontshare | `https://api.fontshare.com/v2/css?f[]=cabinet-grotesk@400,700,800&display=swap` |
+| General Sans | Fontshare | `https://api.fontshare.com/v2/css?f[]=general-sans@400,500,600&display=swap` |
+| Clash Display | Fontshare | `https://api.fontshare.com/v2/css?f[]=clash-display@400,600,700&display=swap` |
+| Archivo Black | Google | `family=Archivo+Black&display=swap` |
+| Manrope | Google | `family=Manrope:wght@300;400;500;600;700;800&display=swap` |
+| Syne | Google | `family=Syne:wght@400;600;700;800&display=swap` |
+| Space Mono | Google | `family=Space+Mono:wght@400;700&display=swap` |
+| Cormorant | Google | `family=Cormorant:ital,wght@0,400;0,600;1,400&display=swap` |
+| IBM Plex Sans | Google | `family=IBM+Plex+Sans:wght@300;400;500;600&display=swap` |
+| DM Sans | Google | `family=DM+Sans:wght@400;500;600;700&display=swap` |
+| Plus Jakarta Sans | Google | `family=Plus+Jakarta+Sans:wght@400;500;600;700&display=swap` |
+| Outfit | Google | `family=Outfit:wght@300;400;500;600;700&display=swap` |
+| Fraunces | Google | `family=Fraunces:ital,wght@0,400;0,600;1,400&display=swap` |
+| Work Sans | Google | `family=Work+Sans:wght@400;500;600;700&display=swap` |
+| JetBrains Mono | Google | `family=JetBrains+Mono:wght@400;500;700&display=swap` |
+| Bodoni Moda | Google | `family=Bodoni+Moda:ital,wght@0,400;0,700;1,400&display=swap` |
+| Inter | Google | `family=Inter:wght@400;500;600;700&display=swap` |
+| Geist | Local/Vercel | Use `system-ui` as fallback in previews |
+### Fallback Rule
+If a font fails to load (offline, CORS, not available), the preview should still render correctly using `system-ui, -apple-system, sans-serif` as fallback. The font name should be displayed in the `.font-info` footer so the user knows what was intended.
+---
+## 6. The Show-Don't-Tell Rule
+| Decision Type | Show Visual? | Why |
+|---------------|-------------|-----|
+| Aesthetic direction / vibe | YES | Users can't imagine "Bold Signal" from text |
+| Color palette | YES | Hex values mean nothing without seeing them |
+| Font pairing | YES | Font names mean nothing without rendering them |
+| Layout structure | YES | "Asymmetric grid" means different things to everyone |
+| Animation intensity | NO | Must be experienced in running code, not a static preview |
+| Mobile priority level | NO | A number (1-5) is sufficient |
+| Accessibility level | NO | A standard (AA/AAA) is sufficient |
+| Performance budget | NO | A number is sufficient |
+| Sound/haptics | NO | Must be experienced in running code |
+The rule: if the decision involves how something LOOKS, show it. If it involves behavior, policy, or priority, text is fine.

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

@@ -1,244 +0,0 @@
-# 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.