picasso-skill 2.4.0 → 2.6.0

package/references/motion-and-animation.md

@@ -5,11 +5,10 @@
 2. Easing Functions
 3. Duration Guidelines
 4. Staggered Reveals
-5. Scroll-Triggered Animation
-6. Text Morphing
-7. Micro-Interactions
-8. Reduced Motion
-9. Common Mistakes
+5. Text Morphing
+6. Reduced Motion
+7. Common Mistakes
+8. Performance
 
 ---
 
@@ -125,42 +124,7 @@ const item = {
 
 ---
 
-## 5. Scroll-Triggered Animation
-
-### CSS-Only with Scroll-Driven Animations
-```css
-@keyframes fade-in {
-  from { opacity: 0; transform: translateY(20px); }
-  to { opacity: 1; transform: translateY(0); }
-}
-
-.scroll-reveal {
-  animation: fade-in linear both;
-  animation-timeline: view();
-  animation-range: entry 0% entry 30%;
-}
-```
-
-### Intersection Observer Pattern
-```js
-const observer = new IntersectionObserver(
-  (entries) => {
-    entries.forEach(entry => {
-      if (entry.isIntersecting) {
-        entry.target.classList.add('visible');
-        observer.unobserve(entry.target);
-      }
-    });
-  },
-  { threshold: 0.15, rootMargin: '0px 0px -50px 0px' }
-);
-
-document.querySelectorAll('.animate-on-scroll').forEach(el => observer.observe(el));
-```
-
----
-
-## 6. Text Morphing
+## 5. Text Morphing
 
 For animated text transitions (changing labels, counters, status updates), use **Torph** (dependency-free).
 
@@ -193,52 +157,7 @@ Torph morphs individual characters with smooth enter/exit animations. It works w
 
 ---
 
-## 7. Micro-Interactions
-
-### Button Press
-```css
-button:active {
-  transform: scale(0.97);
-  transition: transform 80ms var(--ease-in);
-}
-```
-
-### Toggle Switch
-Animate the knob position and background color simultaneously. The knob should arrive slightly before the color finishes changing.
-
-### Checkbox
-Scale the checkmark from 0 to 1 with a slight overshoot:
-```css
-.checkbox-mark {
-  transform: scale(0);
-  transition: transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1);
-}
-.checkbox:checked .checkbox-mark {
-  transform: scale(1);
-}
-```
-
-### Skeleton Loading
-Shimmer from left to right using a gradient animation:
-```css
-.skeleton {
-  background: linear-gradient(90deg,
-    var(--surface-2) 25%,
-    var(--surface-3) 50%,
-    var(--surface-2) 75%
-  );
-  background-size: 200% 100%;
-  animation: shimmer 1.5s infinite;
-}
-@keyframes shimmer {
-  0% { background-position: 200% 0; }
-  100% { background-position: -200% 0; }
-}
-```
-
----
-
-## 8. Reduced Motion
+## 6. Reduced Motion
 
 Always respect the user's motion preference:
 ```css
@@ -256,7 +175,7 @@ This does not mean removing all visual feedback. Opacity changes (fades) are sti
 
 ---
 
-## 9. Common Mistakes
+## 7. Common Mistakes
 
 - Animating everything on the page (creates visual noise, reduces perceived performance)
 - Using `animation-duration: 0` for reduced motion (some browsers behave unexpectedly; use 0.01ms)
@@ -265,3 +184,221 @@ This does not mean removing all visual feedback. Opacity changes (fades) are sti
 - Forgetting `will-change` on frequently animated elements (or overusing it on everything)
 - Staggering 20+ items with visible delays (group them or animate the container)
 - Using `transition: all 0.3s` (animates properties you did not intend; be explicit about which properties to transition)
+
+---
+
+## 8. Performance
+
+### 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;
+}
+```
+
+### 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 */
+```
+
+### 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()`.
+
+### 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%;
+}
+```
+
+### 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.
+
+### 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.
+
+### 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
+
+### 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.
+
+### Performance 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/navigation-patterns.md

@@ -1,36 +1,10 @@
 # Navigation Patterns Reference
 
-## Table of Contents
-1. Breadcrumb Systems
-2. Sidebar and Drawer Navigation
-3. Tab Navigation vs Button Groups
-4. Mobile Bottom Bar vs Hamburger
-5. Sticky Headers
-6. Mega Menus
-7. Skip Links
-8. Common Mistakes
-
 ---
 
 ## 1. Breadcrumb Systems
 
-```html
-<nav aria-label="Breadcrumb">
-  <ol class="flex items-center gap-1.5 text-sm">
-    <li><a href="/" class="text-muted hover:text-primary">Home</a></li>
-    <li aria-hidden="true" class="text-muted">/</li>
-    <li><a href="/products" class="text-muted hover:text-primary">Products</a></li>
-    <li aria-hidden="true" class="text-muted">/</li>
-    <li><span aria-current="page" class="text-primary font-medium">Widget Pro</span></li>
-  </ol>
-</nav>
-```
-
-Rules:
-- Use `<nav aria-label="Breadcrumb">` with `<ol>` (ordered list).
-- Mark current page with `aria-current="page"`. Don't make it a link.
-- Separator (`/` or `>`) gets `aria-hidden="true"`.
-- Show 3-5 levels max. Truncate middle levels with `...` on mobile.
+Use `<nav aria-label="Breadcrumb">` with `<ol>`. Mark current page with `aria-current="page"` (not a link). Separators get `aria-hidden="true"`. Show 3-5 levels max; truncate middle on mobile.
 
 ---
 
@@ -38,23 +12,7 @@ Rules:
 
 Desktop: fixed sidebar, 240-280px width. Mobile: off-canvas drawer with overlay.
 
-```jsx
-<aside className={`fixed inset-y-0 left-0 w-[260px] bg-surface-1 border-r border-border
-  transform transition-transform duration-200 z-50
-  ${mobileOpen ? 'translate-x-0' : '-translate-x-full'} md:translate-x-0`}>
-  <nav aria-label="Main navigation">
-    {/* nav items */}
-  </nav>
-</aside>
-
-{/* Mobile overlay */}
-{mobileOpen && (
-  <div className="fixed inset-0 bg-black/50 z-40 md:hidden"
-    onClick={() => setMobileOpen(false)} />
-)}
-```
-
-Active state: use background tint + accent color text, not bold weight (weight change shifts text width).
+Active state: background tint + accent color text (not bold weight, which shifts text width).
 
 ```css
 .nav-item { padding: 7px 12px; border-radius: 6px; transition: background 100ms; }
@@ -62,186 +20,71 @@ Active state: use background tint + accent color text, not bold weight (weight c
 .nav-item.active { background: oklch(0.65 0.15 230 / 0.1); color: var(--accent); }
 ```
 
-Section labels: 10px, uppercase, `tracking-[0.12em]`, muted color. Group related items visually.
+Section labels: 10px, uppercase, `tracking-[0.12em]`, muted color. Group related items.
 
 ---
 
 ## 3. Tab Navigation vs Button Groups
 
-**Tabs:** switch between views of the SAME content. One is always active. Use `role="tablist"`.
-
-```html
-<div role="tablist" aria-label="Account sections">
-  <button role="tab" aria-selected="true" aria-controls="panel-profile" id="tab-profile">
-    Profile
-  </button>
-  <button role="tab" aria-selected="false" aria-controls="panel-billing" id="tab-billing">
-    Billing
-  </button>
-</div>
-<div role="tabpanel" id="panel-profile" aria-labelledby="tab-profile">
-  <!-- content -->
-</div>
-```
-
-**Button groups:** trigger independent ACTIONS. Multiple can be active (toggle group) or none.
-
-```html
-<div role="group" aria-label="View options">
-  <button aria-pressed="true">Grid</button>
-  <button aria-pressed="false">List</button>
-</div>
-```
+| Pattern | Purpose | ARIA | Selection |
+|---------|---------|------|-----------|
+| Tabs | Switch views of SAME content | `role="tablist"` / `role="tab"` / `aria-selected` | One always active |
+| Button groups | Trigger independent actions | `role="group"` / `aria-pressed` | Multiple or none active |
 
-Decision: if clicking switches what you see → tabs. If clicking does something → button group.
+Decision: clicking switches what you see = tabs. Clicking does something = button group.
 
 ---
 
 ## 4. Mobile Bottom Bar vs Hamburger
 
-Bottom bar outperforms hamburger for engagement. Hamburger hides navigation behind a tap, reducing discoverability.
+| Criteria | Bottom Bar | Hamburger |
+|----------|------------|-----------|
+| Destinations | 3-5 primary | 6+ items |
+| App type | Mobile-first app | Marketing/content site |
+| Frequency | Frequent switching | Infrequent navigation |
 
-**When to use bottom bar:**
-- 3-5 primary destinations
-- Mobile-first app (not marketing site)
-- User needs to switch between sections frequently
-
-**When to use hamburger:**
-- 6+ navigation items
-- Marketing/content site with hierarchical nav
-- Secondary navigation (settings, help)
-
-```css
-.bottom-bar {
-  position: fixed;
-  bottom: 0;
-  left: 0;
-  right: 0;
-  height: 56px; /* 48px min for touch, 56px comfortable */
-  padding-bottom: env(safe-area-inset-bottom); /* notch-safe */
-  display: flex;
-  justify-content: space-around;
-  align-items: center;
-  background: var(--surface-1);
-  border-top: 1px solid var(--border);
-  z-index: 50;
-}
-
-.bottom-bar-item {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: 2px;
-  min-width: 64px;
-  padding: 4px 12px;
-  font-size: 10px;
-}
-```
+Bottom bar: `position: fixed; bottom: 0; height: 56px; padding-bottom: env(safe-area-inset-bottom);`
 
 ---
 
 ## 5. Sticky Headers
 
-Keep slim: 48-56px height. Hide on scroll-down, reveal on scroll-up.
-
-```js
-let lastScroll = 0;
-const header = document.querySelector('header');
-
-window.addEventListener('scroll', () => {
-  const current = window.scrollY;
-  if (current > lastScroll && current > 80) {
-    header.style.transform = 'translateY(-100%)';
-  } else {
-    header.style.transform = 'translateY(0)';
-  }
-  lastScroll = current;
-}, { passive: true });
-```
-
-```css
-header {
-  position: sticky;
-  top: 0;
-  height: 56px;
-  z-index: 40;
-  backdrop-filter: blur(12px);
-  background: oklch(var(--bg-l) var(--bg-c) var(--bg-h) / 0.8);
-  border-bottom: 1px solid var(--border);
-  transition: transform 200ms ease-out;
-}
-```
+Keep slim: 48-56px height. Hide on scroll-down, reveal on scroll-up (track `scrollY` delta). Use `backdrop-filter: blur(12px)` with semi-transparent background. Add `{ passive: true }` to scroll listener.
 
 ---
 
 ## 6. Mega Menus
 
-For sites with 20+ navigation items. Two approaches:
-
-**Full-width panel** (preferred): Flyout spans full viewport width. Organized in columns.
-
-```css
-.mega-menu {
-  position: absolute;
-  top: 100%;
-  left: 0;
-  right: 0;
-  padding: 2rem;
-  display: grid;
-  grid-template-columns: repeat(4, 1fr);
-  gap: 2rem;
-  background: var(--surface-1);
-  border-top: 1px solid var(--border);
-  box-shadow: var(--shadow-lg);
-}
-```
-
-**Alternatives to mega menus:**
-- Search-first navigation (Command+K palette)
-- Two-level sidebar (category → items)
-- Card-based navigation page
+For sites with 20+ navigation items. Full-width panel with 4-column grid is preferred. Keep hover delay at 200-300ms to prevent accidental opens.
 
-Keep mega menu hover delay at 200-300ms to prevent accidental opens.
+**Alternatives**: Command+K palette, two-level sidebar, card-based navigation page.
 
 ---
 
 ## 7. Skip Links
 
-First focusable element on the page. Visually hidden until focused.
+First focusable element on the page. Visually hidden until focused:
 
 ```html
 <a href="#main-content" class="skip-link">Skip to main content</a>
-<!-- header, nav, etc -->
 <main id="main-content" tabindex="-1">
 ```
 
 ```css
-.skip-link {
-  position: absolute;
-  top: -100%;
-  left: 1rem;
-  z-index: 100;
-  padding: 0.5rem 1rem;
-  background: var(--accent);
-  color: white;
-  border-radius: 0 0 8px 8px;
-  font-weight: 600;
-}
-.skip-link:focus {
-  top: 0;
-}
+.skip-link { position: absolute; top: -100%; z-index: 100; }
+.skip-link:focus { top: 0; }
 ```
 
 ---
 
 ## 8. Common Mistakes
 
-- **Hamburger as the only mobile navigation.** Bottom bar is better for primary destinations.
-- **Active nav state using `font-weight: bold`.** Shifts text width. Use background/color instead.
-- **Sidebar over 300px wide.** Steals too much screen. 240-280px is ideal.
-- **Sticky header over 64px.** Takes too much vertical space. 48-56px max.
-- **No `aria-current="page"` on breadcrumbs.** Screen readers can't identify current page.
-- **Tabs without `role="tablist"`/`role="tab"`.** Not accessible.
-- **Mega menu without hover delay.** Opens accidentally when moving mouse across nav.
-- **No skip link.** Keyboard users must tab through entire header to reach content.
-- **Bottom bar without `safe-area-inset-bottom`.** Content hides behind iPhone notch.
+- Hamburger as the only mobile navigation (bottom bar is better for primary destinations)
+- Active state using `font-weight: bold` (shifts text width; use background/color)
+- Sidebar over 300px wide (240-280px is ideal)
+- Sticky header over 64px (48-56px max)
+- No `aria-current="page"` on breadcrumbs
+- Tabs without `role="tablist"`/`role="tab"`
+- Mega menu without hover delay
+- No skip link
+- Bottom bar without `safe-area-inset-bottom`