picasso-skill 1.6.0 → 2.0.1

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 |
 
 ---
 
@@ -481,6 +498,10 @@ GODMODE Complete: 42 → 87 (+45 points), 47 files modified, 23 issues fixed
 | `/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.) |
+| `/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 |
+| `/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 |
 
 ### Advanced
 
@@ -505,27 +526,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

@@ -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.1",
   "description": "The ultimate AI design skill for producing distinctive, production-grade frontend interfaces",
   "bin": {
     "picasso-skill": "./bin/install.mjs"

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.

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