picasso-skill 2.0.0 → 2.0.2

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  20 reference domains &bull; 35+ commands &bull; 4,700+ lines of actionable design intelligence<br/>
+  32 reference domains &bull; 40+ commands &bull; 11,000+ lines of actionable design intelligence<br/>
   Every interface looks like a senior design engineer spent days on it.
 </p>
 
@@ -36,7 +36,7 @@ Existing design skills are shallow. They tell you to "use good typography" witho
 
 ### Depth That No Other Skill Matches
 
-Picasso covers **20 specialized reference domains**, each with concrete rules, specific values, and ready-to-use code. This isn't a collection of vague principles -- it's an engineering specification for beautiful interfaces.
+Picasso covers **32 specialized reference domains**, each with concrete rules, specific values, and ready-to-use code. This isn't a collection of vague principles -- it's an engineering specification for beautiful interfaces.
 
 | Domain | What You Get |
 |---|---|
@@ -61,6 +61,16 @@ Picasso covers **20 specialized reference domains**, each with concrete rules, s
 | **UX Writing** | Error message formula (what + why + fix), button label rules (verb + object), translation expansion percentages, terminology consistency |
 | **Style Presets** | 22 curated visual presets with hex values, font pairings, border-radius, and signature UI elements, mapped to moods |
 | **Performance Optimization** | Vercel's 45 React/Next.js rules across 7 priority tiers with BAD/GOOD code examples |
+| **Navigation Patterns** | Breadcrumbs with ARIA, sidebar collapse, tabs vs button groups, mobile bottom bar vs hamburger, sticky headers, mega menus, skip links |
+| **Tables & Forms** | Sortable tables with `aria-sort`, responsive strategies, inline editing, multi-select, form validation (blur/submit/real-time), multi-step forms |
+| **Loading & States** | Duration rules (<1s/1-3s/3s+/10s+), skeleton shimmer CSS, 5 empty state types, error boundaries, retry with backoff, offline detection |
+| **Dark Mode** | Preference hierarchy, surface elevation (lighter = higher), mode transitions, accent adjustment, image dimming, forced-colors, autofill fix |
+| **Images & Media** | AVIF/WebP/SVG decision tree, srcset/sizes, CLS prevention, favicon multi-format, OG images (1200x630), video backgrounds |
+| **Micro-Interactions** | IntersectionObserver scroll animations, View Transitions API, magnetic cursors, gesture detection (swipe/pinch), animation budget (max 3 concurrent) |
+| **i18n Visual Patterns** | Logical properties for RTL, text expansion by language (+35% German), CJK rendering, Noto font stacks, icon mirroring rules |
+| **Brand & Identity** | Logo sizing (min 24px), clear space rules, lockup variants, 60-30-10 brand color usage, when to bend brand rules |
+| **Animation Performance** | Compositor-only properties (transform + opacity only), will-change lifecycle, layout thrashing batching, `contain` property, GPU hints |
+| **Code Typography** | JetBrains Mono/Fira Code selection, syntax highlighting contrast (3:1 min), code block design, copy button UX, diff views, terminal styling |
 
 ### The AI-Slop Firewall
 
@@ -272,10 +282,10 @@ We compared Picasso against every publicly available AI design skill as of April
 
 | Metric | Picasso | Anthropic frontend-design | Impeccable | Taste Skill | Generic skills |
 |---|---|---|---|---|---|
-| **Reference domains** | **20** | 1 | 7 | 1 | 1-3 |
-| **Total lines of guidance** | **4,700+** | ~120 | ~2,500 | ~200 | 50-300 |
+| **Reference domains** | **32** | 1 | 7 | 1 | 1-3 |
+| **Total lines of guidance** | **11,000+** | ~120 | ~2,500 | ~200 | 50-300 |
 | **Anti-pattern rules** | **50+** | ~10 | ~30 | ~5 | 0-5 |
-| **Steering commands** | **35+** | 0 | 20 | 0 | 0-3 |
+| **Steering commands** | **40+** | 0 | 20 | 0 | 0-3 |
 | **ARIA patterns documented** | **12 widgets** | 0 | 0 | 0 | 0 |
 | **React performance rules** | **45 (Vercel)** | 0 | 0 | 0 | 0 |
 | **Chart/data viz guidance** | **Full matrix** | None | None | None | None |
@@ -336,6 +346,12 @@ npx picasso-skill --cursor
 # Install for Codex
 npx picasso-skill --codex
 
+# Install for OpenClaw
+npx picasso-skill --openclaw
+
+# Or via ClawHub marketplace
+clawhub install picasso
+
 # Custom path
 npx picasso-skill --path ./my-skills
 ```
@@ -378,14 +394,15 @@ Picasso ships as both a **skill** (knowledge base) and an **agent** (autonomous
 
 | | Skill | Agent |
 |---|---|---|
-| **What it is** | 20 reference files of design intelligence | Autonomous design auditor |
+| **What it is** | 32 reference files of design intelligence | Autonomous design auditor with anti-slop gate |
 | **How it works** | Loaded into context when designing | Runs as a sub-process with its own tools |
-| **When it runs** | When you ask for design help | Proactively after frontend code changes |
-| **Can audit code** | Only when asked | Automatically |
-| **Can run axe-core** | No | Yes |
-| **Can screenshot pages** | No | Yes (via Playwright) |
-| **Can auto-fix issues** | No | Yes |
+| **When it runs** | When you ask for design help | On explicit commands (/audit, /roast, /godmode, etc.) |
+| **Can audit code** | Only when asked | Yes, with structured scoring |
+| **Can run axe-core** | No | Yes (via CLI) |
+| **Can screenshot pages** | No | Yes (via Playwright MCP) |
+| **Can auto-fix issues** | No | Yes (with pre-flight git/test checks) |
 | **Can enforce design system** | No | Yes (greps for token violations) |
+| **Enforces anti-slop gate** | Via SKILL.md instructions | Yes, mandatory before any code generation |
 
 ---
 
@@ -405,8 +422,7 @@ Picasso ships as both a **skill** (knowledge base) and an **agent** (autonomous
 | `/polish` | Final pass before shipping: visual alignment, typography refinement, color/contrast, all 8 interaction states, micro-interactions, content/copy, edge cases |
 | `/simplify` | Strip to essence: reduce scope, flatten structure, remove decorations, progressive disclosure, shorter copy, fewer variants |
 | `/normalize` | Realign to design system standards: fix hardcoded colors, inconsistent tokens, broken dark mode, spacing violations |
-| `/typeset` | Fix typography: font choices, hierarchy clarity, sizing scale, readability (line length, line-height, contrast), OpenType features |
-| `/arrange` | Fix layout: establish spacing system, create visual rhythm, choose right layout tool (Flexbox vs Grid), break card grid monotony |
+| `/harden` | Error handling and edge cases: text overflow, i18n, network errors, empty/loading/error states, browser compat |
 
 ### Amplification
 
@@ -415,8 +431,6 @@ Picasso ships as both a **skill** (knowledge base) and an **agent** (autonomous
 | `/animate` | Add purposeful motion: page load choreography, micro-interactions, state transitions, scroll effects, loading delight |
 | `/bolder` | Amplify timid designs: extreme type scale (3x-5x), vibrant color, spatial drama, dramatic shadows, custom elements |
 | `/quieter` | Tone down aggressive designs: reduce saturation to 70-85%, soften weights, increase whitespace, shorter animation distances |
-| `/colorize` | Introduce strategic color: semantic states, accent application, tinted backgrounds, data visualization, decorative elements |
-| `/delight` | Add moments of joy: button feedback, loading delight, success celebrations, personality in copy, sound cues, easter eggs |
 
 ### Aesthetic Presets
 
@@ -436,15 +450,14 @@ Picasso ships as both a **skill** (knowledge base) and an **agent** (autonomous
 | `/haptics` | Add mobile haptic feedback using web-haptics (4 presets + custom patterns) |
 | `/redesign` | Full audit + identify problems + fix systematically + re-audit cycle |
 
-### Production
+### Design Debt
 
 | Command | What It Does |
 |---|---|
-| `/adapt` | Adapt for devices: mobile (thumb-zone), tablet (two-column), desktop (multi-column), print, email (600px, table-based) |
-| `/clarify` | Improve UX copy: error messages, form labels, button text, help text, empty states, confirmation dialogs |
-| `/optimize` | Performance: image optimization, JS bundle reduction, CSS critical path, font loading, animation 60fps, network efficiency |
-| `/harden` | Error handling and edge cases: text overflow, i18n (RTL, expansion), network errors, empty/loading/error states, browser compat |
-| `/onboard` | Design onboarding: signup friction reduction, first-run experience, progressive feature discovery, setup checklists |
+| `/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 code previews |
+| `/quick-audit` | 5-minute fast audit: 6 binary pass/fail checks (font, color, layout, spacing, a11y, anti-slop) |
+| `/autorefine` | Binary evaluation loop: 6 criteria, mutate one thing at a time, iterate to 95%+ pass rate |
 
 ### `/godmode` -- The Nuclear Option
 
@@ -465,29 +478,6 @@ GODMODE Complete: 42 → 87 (+45 points), 47 files modified, 23 issues fixed
 
 ---
 
-### Creative
-
-| Command | What It Does |
-|---|---|
-| `/godmode` | The ultimate command: interview + audit + score + roast + fix everything + before/after report |
-| `/picasso` | Run the design interview -- deep discovery conversation, generates `.picasso.md` config |
-| `/roast` | Brutally honest critique with designer-Twitter energy. Every roast includes the fix. Rated 🔥-🔥🔥🔥🔥🔥. |
-| `/score` | Quantified 0-100 design score with category breakdown (typography, color, spacing, a11y, motion, responsive, perf, anti-slop) |
-| `/steal <url>` | Extract design DNA from any live website into a `.picasso.md` config |
-| `/mood <word>` | Generate complete design system from a single evocative word (cyberpunk, cottage, luxury, etc.) |
-| `/evolve` | Multi-round iterative refinement: 3 directions → pick → refine → ship |
-| `/compete <url>` | Head-to-head design comparison against a competitor with per-category scoring |
-| `/before-after` | Visual side-by-side comparison report after changes (HTML export) |
-| `/mood-board` | Generate interactive HTML mood board from adjectives |
-| `/design-system-sync` | Detect and auto-fix drift between DESIGN.md and actual code |
-| `/preset <name>` | Apply a curated preset (linear, stripe, vercel, notion, brutalist, etc.) |
-
-### Advanced
-
-| Command | What It Does |
-|---|---|
-| `/overdrive` | Technically extraordinary effects. View Transitions, scroll-driven animations, WebGL, @property gradients, Web Audio, spring physics. 60fps. Progressive enhancement. |
-
 ### Automation (Agent-Only)
 
 | Command | What It Does |
@@ -505,27 +495,39 @@ GODMODE Complete: 42 → 87 (+45 points), 47 files modified, 23 issues fixed
 ## References
 
 ```
-references/
-  typography.md                   # Type systems, font pairing, scales, OpenType, vertical rhythm
-  color-and-contrast.md           # OKLCH, tinted neutrals, dark mode, 60-30-10, dangerous combos
-  spatial-design.md               # 4px spacing scale, grids, hierarchy, Squint Test, optical adjustments
-  motion-and-animation.md         # Duration rule, easing curves, staggering, text morphing, reduced motion
-  interaction-design.md           # 8 states, forms, focus, loading, Popover API, dropdown positioning
-  responsive-design.md            # Input method detection, safe areas, container queries, real device testing
-  sensory-design.md               # soundcn, web-haptics, multi-sensory integration patterns
-  react-patterns.md               # Server Components, composition, state management, data fetching, styling
-  anti-patterns.md                # 50+ banned patterns across all domains (the most important file)
-  design-system.md                # 9-section DESIGN.md format, theme generation, token structure, 4 themes
-  generative-art.md               # Philosophy-first process, p5.js, seeded randomness, parameter controls
-  component-patterns.md           # 40+ components, state matrix, compound patterns, sizing conventions
-  ux-psychology.md                # Gestalt, Fitts's/Hick's/Miller's/Jakob's Law, F/Z-pattern, Peak-End
-  data-visualization.md           # Chart selection matrix, dashboard layouts, data palettes, Tufte, sparklines
-  modern-css-performance.md       # Nesting, :has(), @layer, anchor positioning, View Transitions, Tailwind v4
-  conversion-design.md            # Landing pages, CTAs, pricing, onboarding, navigation/IA, notifications
-  accessibility-wcag.md           # 12 ARIA patterns, WCAG 2.2, SPA focus, accessible tables, drag-and-drop
-  ux-writing.md                   # Error formula, button labels, empty states, i18n, terminology
-  style-presets.md                # 22 visual presets with colors, fonts, signature elements, mood mapping
-  performance-optimization.md     # 45 Vercel rules across 7 priority tiers with code examples
+references/                          # 32 files, 9,300+ lines
+  anti-patterns.md                   # 50+ banned patterns (THE MOST IMPORTANT FILE)
+  typography.md                      # Type systems, font pairing, scales, OpenType, vertical rhythm
+  color-and-contrast.md              # OKLCH, tinted neutrals, dark mode, 60-30-10, dangerous combos
+  spatial-design.md                  # 4px spacing scale, grids, hierarchy, Squint Test
+  depth-and-elevation.md             # Dual shadows, layering, shadow scale, z-index, hover patterns
+  motion-and-animation.md            # Duration rule, easing curves, staggering, text morphing
+  micro-interactions.md              # Scroll animations, View Transitions, gestures, magnetic cursors
+  animation-performance.md           # Compositor-only props, will-change, layout thrashing, contain
+  interaction-design.md              # 8 states, forms, focus, Popover API, dropdown positioning
+  navigation-patterns.md             # Breadcrumbs, sidebar, tabs, bottom bar, mega menus, skip links
+  tables-and-forms.md                # Sortable tables, inline editing, validation, multi-step forms
+  loading-and-states.md              # Skeletons, error boundaries, 5 empty state types, offline
+  responsive-design.md               # Input method detection, safe areas, container queries
+  dark-mode.md                       # Preference hierarchy, elevation, transitions, testing
+  images-and-media.md                # Format selection, srcset, favicons, OG images, video
+  brand-and-identity.md              # Logo sizing, brand color 60-30-10, lockup variants
+  i18n-visual-patterns.md            # RTL, logical properties, text expansion, CJK, Noto stacks
+  code-typography.md                 # Monospace fonts, syntax highlighting, code blocks, diff views
+  sensory-design.md                  # soundcn, web-haptics, multi-sensory integration
+  react-patterns.md                  # Server Components, composition, state management, styling
+  design-system.md                   # 9-section DESIGN.md format, theme generation, tokens
+  generative-art.md                  # Philosophy-first process, p5.js, seeded randomness
+  component-patterns.md              # 40+ components, state matrix, compound patterns
+  ux-psychology.md                   # Gestalt, Fitts's/Hick's/Miller's/Jakob's Law, F/Z-pattern
+  ux-writing.md                      # Error formula, button labels, empty states, terminology
+  data-visualization.md              # Chart selection matrix, dashboard layouts, Tufte
+  conversion-design.md               # Landing pages, CTAs, pricing, onboarding, notifications
+  accessibility-wcag.md              # 12 ARIA patterns, WCAG 2.2, SPA focus, accessible tables
+  modern-css-performance.md          # Nesting, :has(), @layer, View Transitions, Tailwind v4
+  performance-optimization.md        # 45 Vercel rules across 7 priority tiers
+  style-presets.md                   # 22 visual presets with OKLCH values and font pairings
+  tools-catalog.md                   # torph, soundcn, Lucide, Facehash, better-icons
 ```
 
 ---

package/agents/picasso.md

@@ -176,23 +176,44 @@ If 3+ are checked, you MUST change your commitments until fewer than 3 remain.
 Your design knowledge comes from the Picasso skill reference files. Before any audit or design work, load the relevant references:
 
 ```
-skills/picasso/SKILL.md                          # Core rules and workflow
-skills/picasso/references/anti-patterns.md       # What NOT to do (always load this)
-skills/picasso/references/typography.md           # Font selection, scales, pairing
-skills/picasso/references/color-and-contrast.md   # OKLCH, tinted neutrals, dark mode
-skills/picasso/references/spatial-design.md       # Spacing, grids, hierarchy
-skills/picasso/references/motion-and-animation.md # Easing, staggering, reduced motion
-skills/picasso/references/interaction-design.md   # Forms, focus, loading, errors
-skills/picasso/references/responsive-design.md    # Mobile-first, container queries
-skills/picasso/references/sensory-design.md       # Sound, haptics
-skills/picasso/references/react-patterns.md       # React 19, Tailwind v4, dark mode
-skills/picasso/references/accessibility.md        # ARIA, WCAG 2.2, keyboard nav
-skills/picasso/references/design-system.md        # DESIGN.md, theming, tokens
-skills/picasso/references/generative-art.md       # p5.js, SVG, canvas
-skills/picasso/references/component-patterns.md   # Naming, taxonomy, state matrix
+skills/picasso/SKILL.md                              # Core rules and workflow (always load)
+skills/picasso/references/anti-patterns.md           # What NOT to do (always load)
+
+# Load based on what the task involves:
+skills/picasso/references/typography.md              # Fonts, scales, pairing
+skills/picasso/references/color-and-contrast.md      # OKLCH, tinted neutrals
+skills/picasso/references/spatial-design.md          # Spacing, grids, hierarchy
+skills/picasso/references/depth-and-elevation.md     # Shadows, z-index, layering
+skills/picasso/references/motion-and-animation.md    # Easing, staggering, duration
+skills/picasso/references/micro-interactions.md      # Scroll animations, gestures, View Transitions
+skills/picasso/references/animation-performance.md   # Compositor props, will-change, contain
+skills/picasso/references/interaction-design.md      # Forms, focus, states, Popover API
+skills/picasso/references/navigation-patterns.md     # Breadcrumbs, sidebar, tabs, bottom bar
+skills/picasso/references/tables-and-forms.md        # Sortable tables, validation, multi-step
+skills/picasso/references/loading-and-states.md      # Skeletons, empty states, error boundaries
+skills/picasso/references/responsive-design.md       # Mobile-first, container queries
+skills/picasso/references/dark-mode.md               # Preference hierarchy, elevation, testing
+skills/picasso/references/images-and-media.md        # Formats, srcset, favicons, OG images
+skills/picasso/references/brand-and-identity.md      # Logo sizing, brand color usage
+skills/picasso/references/i18n-visual-patterns.md    # RTL, logical properties, CJK
+skills/picasso/references/code-typography.md         # Monospace, syntax highlighting, diffs
+skills/picasso/references/sensory-design.md          # Sound, haptics
+skills/picasso/references/react-patterns.md          # Server Components, Tailwind v4
+skills/picasso/references/accessibility-wcag.md      # ARIA, WCAG 2.2, keyboard nav
+skills/picasso/references/design-system.md           # DESIGN.md, theming, tokens
+skills/picasso/references/generative-art.md          # p5.js, SVG, canvas
+skills/picasso/references/component-patterns.md      # Naming, taxonomy, state matrix
+skills/picasso/references/ux-psychology.md           # Gestalt, Fitts's Law, heuristics
+skills/picasso/references/ux-writing.md              # Error messages, microcopy, CTAs
+skills/picasso/references/data-visualization.md      # Chart matrix, dashboards, Tufte
+skills/picasso/references/conversion-design.md       # Landing pages, CTAs, pricing
+skills/picasso/references/modern-css-performance.md  # Nesting, :has(), @layer, subgrid
+skills/picasso/references/performance-optimization.md # 45 Vercel rules, Core Web Vitals
+skills/picasso/references/style-presets.md           # 22 curated presets with values
+skills/picasso/references/tools-catalog.md           # torph, soundcn, Lucide, Facehash
 ```
 
-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.
+Find these files by searching `.claude/skills/picasso/`, `~/.claude/skills/picasso/`, or by globbing `**/picasso/SKILL.md`. Load `anti-patterns.md` on every invocation. Load other references based on what you find in the code.
 
 ## Phase 1: Gather Context
 

package/bin/install.mjs

@@ -29,7 +29,7 @@ if (command === "help" || command === "--help" || command === "-h") {
     npx picasso-skill --path DIR   Install to a custom directory
 
   What gets installed:
-    .claude/skills/picasso/        Skill (knowledge base: 13 reference files)
+    .claude/skills/picasso/        Skill (knowledge base: 32 reference files)
     .claude/agents/picasso.md      Agent (autonomous design auditor)
   `);
   process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picasso-skill",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
   "bin": {
     "picasso-skill": "./bin/install.mjs"
@@ -35,7 +35,7 @@
     "agents/",
     "commands/",
     "references/",
-    "checklists/",
+    "templates/",
     "LICENSE"
   ]
 }

package/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.