picasso-skill 1.5.1 → 2.0.0

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.

package/skills/picasso/references/code-typography.md

@@ -0,0 +1,222 @@
+# Code Typography Reference
+
+## Table of Contents
+1. Monospace Font Selection
+2. Code Block Design
+3. Syntax Highlighting Accessibility
+4. Copy-to-Clipboard
+5. Responsive Code Blocks
+6. Inline Code Styling
+7. Diff Views
+8. Terminal Output
+9. Common Mistakes
+
+---
+
+## 1. Monospace Font Selection
+
+| Font | Ligatures | Style | Best For |
+|---|---|---|---|
+| JetBrains Mono | Yes | Clean, geometric | General purpose, IDEs |
+| Fira Code | Yes | Slightly rounded | Tutorials, docs |
+| Source Code Pro | No | Adobe, professional | Enterprise, clean look |
+| IBM Plex Mono | No | Corporate, legible | Documentation |
+| Geist Mono | No | Vercel, modern | Next.js projects |
+| Cascadia Code | Yes | Microsoft, playful | Terminals |
+
+```css
+code, pre, .mono {
+  font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas', monospace;
+  font-feature-settings: 'liga' 1, 'calt' 1; /* enable ligatures */
+  font-variant-ligatures: common-ligatures;
+}
+```
+
+Ligatures: `=>` becomes ⇒, `!==` becomes ≢, `>=` becomes ≥. Enable for display, disable for editing if users copy code.
+
+---
+
+## 2. Code Block Design
+
+```css
+pre {
+  background: var(--surface-1);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 1rem 1.25rem;
+  font-size: 0.875rem;    /* 14px — slightly smaller than body */
+  line-height: 1.65;       /* Looser than body text for readability */
+  overflow-x: auto;
+  tab-size: 2;
+  -moz-tab-size: 2;
+}
+
+/* Dark mode code blocks on light sites */
+[data-theme="light"] pre {
+  background: oklch(0.14 0.02 230);
+  color: oklch(0.90 0.01 230);
+}
+```
+
+Line numbers (optional):
+```css
+pre.line-numbers {
+  counter-reset: line;
+  padding-left: 3.5rem;
+  position: relative;
+}
+pre.line-numbers .line::before {
+  counter-increment: line;
+  content: counter(line);
+  position: absolute;
+  left: 1rem;
+  color: var(--text-muted);
+  font-size: 0.75rem;
+  user-select: none; /* don't copy line numbers */
+}
+```
+
+---
+
+## 3. Syntax Highlighting Accessibility
+
+Every token color must have **minimum 3:1 contrast** against the code block background. Don't rely on color alone — use font-weight or font-style for emphasis.
+
+| Token Type | Suggested OKLCH (dark bg) | Purpose |
+|---|---|---|
+| Keywords | `oklch(0.75 0.15 300)` | purple-ish, bold |
+| Strings | `oklch(0.72 0.14 150)` | green |
+| Numbers | `oklch(0.75 0.12 60)` | amber |
+| Comments | `oklch(0.50 0.01 230)` | muted, italic |
+| Functions | `oklch(0.78 0.10 230)` | blue |
+| Variables | `oklch(0.85 0.01 230)` | near-white |
+
+```css
+.token-keyword { color: oklch(0.75 0.15 300); font-weight: 600; }
+.token-string { color: oklch(0.72 0.14 150); }
+.token-comment { color: oklch(0.50 0.01 230); font-style: italic; }
+```
+
+---
+
+## 4. Copy-to-Clipboard
+
+Position: top-right corner of the code block. Show on hover. Provide visual feedback.
+
+```jsx
+function CopyButton({ code }) {
+  const [copied, setCopied] = useState(false);
+
+  return (
+    <button
+      onClick={() => {
+        navigator.clipboard.writeText(code);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      }}
+      className="absolute top-2 right-2 p-1.5 rounded-md bg-white/5 hover:bg-white/10 text-xs text-muted"
+      aria-label="Copy code"
+    >
+      {copied ? 'Copied' : 'Copy'}
+    </button>
+  );
+}
+```
+
+---
+
+## 5. Responsive Code Blocks
+
+Code blocks should **scroll horizontally** on mobile, never wrap. Terminal output CAN wrap.
+
+```css
+pre {
+  overflow-x: auto;
+  white-space: pre;         /* code: no wrap */
+  -webkit-overflow-scrolling: touch; /* smooth scroll on iOS */
+}
+
+pre.terminal {
+  white-space: pre-wrap;    /* terminal: wrap is OK */
+  word-break: break-all;
+}
+
+/* Hide scrollbar but keep functionality */
+pre::-webkit-scrollbar { height: 4px; }
+pre::-webkit-scrollbar-thumb { background: var(--border); border-radius: 4px; }
+```
+
+On very small screens (< 375px), consider reducing code font-size to 12px.
+
+---
+
+## 6. Inline Code Styling
+
+Inline code needs subtle visual distinction from body text:
+
+```css
+code:not(pre code) {
+  background: var(--surface-2);
+  padding: 0.15em 0.4em;
+  border-radius: 4px;
+  font-size: 0.9em;        /* slightly smaller than surrounding text */
+  font-weight: 500;
+  border: 1px solid var(--border);
+}
+```
+
+Never use inline code for emphasis. It's for code references (`useState`, `border-radius`, `GET /api/users`), not for highlighting words.
+
+---
+
+## 7. Diff Views
+
+Use color + icon, not color alone (colorblind users):
+
+```css
+.diff-add {
+  background: oklch(0.62 0.19 150 / 0.1);
+  border-left: 3px solid oklch(0.62 0.19 150);
+}
+.diff-add::before { content: '+'; color: oklch(0.62 0.19 150); }
+
+.diff-remove {
+  background: oklch(0.55 0.22 25 / 0.1);
+  border-left: 3px solid oklch(0.55 0.22 25);
+  text-decoration: line-through;
+  opacity: 0.7;
+}
+.diff-remove::before { content: '-'; color: oklch(0.55 0.22 25); }
+```
+
+---
+
+## 8. Terminal Output
+
+Terminal/console styling should feel distinct from code:
+
+```css
+.terminal {
+  background: oklch(0.08 0.01 230);
+  color: oklch(0.80 0.01 150); /* slight green tint for terminal feel */
+  font-family: 'JetBrains Mono', monospace;
+  padding: 1rem;
+  border-radius: 8px;
+}
+.terminal .prompt { color: oklch(0.65 0.10 230); } /* blue prompt */
+.terminal .output { color: oklch(0.75 0.01 230); } /* neutral output */
+.terminal .error { color: oklch(0.65 0.22 25); }   /* red errors */
+```
+
+---
+
+## 9. Common Mistakes
+
+- **Code font too large.** 14px for blocks, 0.9em for inline. Larger fights with body text.
+- **No horizontal scroll on code blocks.** Wrapping code breaks readability. Always `overflow-x: auto`.
+- **Syntax colors with < 3:1 contrast.** Comments especially — they tend to be too faint.
+- **Color-only diff indication.** Always add + / - markers or icons alongside color.
+- **Copying includes line numbers.** Use `user-select: none` on line number elements.
+- **Same styling for code blocks and terminal.** They serve different purposes. Terminal gets darker bg, green tint.
+- **`font-family: monospace` without named fonts.** Browsers default to Courier New which looks dated. Always specify a modern monospace font first.
+- **No copy button.** Users shouldn't have to triple-click and drag to copy code.

package/skills/picasso/references/color-and-contrast.md

@@ -9,7 +9,9 @@
 6. CSS Variables Pattern
 7. Curated Color Palettes
 8. Wide Gamut Colors (P3)
-9. Common Mistakes
+9. `light-dark()` CSS Function
+10. `color-mix()` for Runtime Blending
+11. Common Mistakes
 
 ---
 
@@ -412,7 +414,58 @@ Note: OKLCH values automatically map to the widest gamut the browser and display
 
 ---
 
-## 9. Common Mistakes
+## 9. `light-dark()` CSS Function
+
+The `light-dark()` function returns one of two values depending on the current `color-scheme`. This eliminates the need for duplicate variable declarations in many cases:
+
+```css
+:root {
+  color-scheme: light dark;
+}
+
+.surface {
+  background: light-dark(oklch(0.97 0.005 260), oklch(0.17 0.012 260));
+}
+.text {
+  color: light-dark(oklch(0.20 0.015 260), oklch(0.93 0.01 260));
+}
+.border {
+  border-color: light-dark(oklch(0.88 0.01 260), oklch(0.25 0.01 260));
+}
+```
+
+Use `light-dark()` for simple color flips (surfaces, text, borders). For complex theme differences (shadow systems, accent adjustments, chroma changes), continue using `[data-theme="dark"]` selectors or CSS custom properties for full control.
+
+Browser support: baseline since March 2024 (Chrome 123, Firefox 120, Safari 17.5).
+
+---
+
+## 10. `color-mix()` for Runtime Blending
+
+`color-mix()` blends two colors at runtime without defining intermediate tokens. Useful for hover states, tinted surfaces, and dynamic theming:
+
+```css
+/* Hover: darken accent by mixing with black */
+.btn:hover {
+  background: color-mix(in oklch, var(--accent), black 15%);
+}
+
+/* Subtle tint: mix accent into white */
+.surface-tinted {
+  background: color-mix(in oklch, var(--accent), white 92%);
+}
+
+/* Disabled: reduce opacity feel by mixing with the surface */
+.btn:disabled {
+  background: color-mix(in oklch, var(--accent), var(--surface-0) 60%);
+}
+```
+
+Always specify `in oklch` for perceptually uniform blending. Mixing `in srgb` produces muddier results, especially across hues.
+
+---
+
+## 11. Common Mistakes
 
 - Using pure black (#000) for text (use tinted near-black instead)
 - Using gray text on colored backgrounds (low contrast, hard to read)
@@ -421,3 +474,4 @@ Note: OKLCH values automatically map to the widest gamut the browser and display
 - Forgetting to test dark mode after building light mode
 - Using brand colors at full saturation for large surfaces (they vibrate and cause eye strain; reserve full chroma for small accents)
 - Not providing hover/focus states with visible color change
+- Using `color-mix(in srgb, ...)` instead of `color-mix(in oklch, ...)` (sRGB blending produces muddier, less predictable results)