From 24e24265d170c29abc281753692eda4077f351f8 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Sat, 25 Jul 2026 18:19:25 -0700 Subject: [PATCH] Refresh stale metric and library references in the command docs From issue #395, the items still present after the v4 consolidation: - optimize.md led its interactivity section with FID, retired as a Core Web Vital in March 2024 when INP replaced it. The section heading and both metric lists now name INP. - optimize.md recommended react-virtualized, superseded by react-window from the same author; the line now points at react-window and TanStack Virtual, matching overdrive.md. - overdrive.md's WebGPU support matrix predated Firefox 141/147 shipping it on Windows/macOS and Safari 26 shipping it across Apple platforms. - audit.md listed "missing will-change" as a defect while animate.md and optimize.md both instruct applying it sparingly and never preemptively; the audit line now flags overuse instead of absence. - harden.md allowed 14px mobile body text while typeset.md sets a 16px ordinary floor; harden now matches the floor, reserving 14px for secondary text, and names the iOS Safari input-zoom consequence. The issue's other items (Framer Motion naming, Popmotion, polish duration cap, humor guidance, HSL phrasing in quieter) were already resolved by the v4 reference rewrite. Prepared with AI assistance (Claude Code), directed by @pbakaus. Co-Authored-By: Claude Code --- skill/reference/audit.md | 3 ++- skill/reference/harden.md | 2 +- skill/reference/optimize.md | 8 ++++---- skill/reference/overdrive.md | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/skill/reference/audit.md b/skill/reference/audit.md index 011071717..be659b1ad 100644 --- a/skill/reference/audit.md +++ b/skill/reference/audit.md @@ -26,7 +26,8 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the **Check for**: - **Layout thrashing**: Reading/writing layout properties in loops - **Expensive animations**: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames -- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change +- **Missing optimization**: Images without lazy loading, unoptimized assets +- **will-change overuse**: `will-change` applied broadly or left on at rest (it is a targeted hint for known expensive animations, not a baseline requirement; see optimize.md) - **Bundle size**: Unnecessary imports, unused dependencies - **Render performance**: Unnecessary re-renders, missing memoization diff --git a/skill/reference/harden.md b/skill/reference/harden.md index 2d2fd01a2..8a8dc2fc6 100644 --- a/skill/reference/harden.md +++ b/skill/reference/harden.md @@ -78,7 +78,7 @@ Systematically improve resilience: **Responsive text sizing**: - Use `clamp()` for fluid typography -- Set minimum readable sizes (14px on mobile) +- Set minimum readable sizes (16px body on mobile, matching typeset.md's floor; 14px only for genuinely secondary text. iOS Safari force-zooms focused inputs under 16px, which breaks form layouts) - Test text scaling (zoom to 200%) - Ensure containers expand with text diff --git a/skill/reference/optimize.md b/skill/reference/optimize.md index e7f08b16a..9c7bb144a 100644 --- a/skill/reference/optimize.md +++ b/skill/reference/optimize.md @@ -5,7 +5,7 @@ Performance is a feature. Identify the actual bottleneck for THIS interface, fix Understand current performance and identify problems: 1. **Measure current state**: - - **Core Web Vitals**: LCP, FID/INP, CLS scores + - **Core Web Vitals**: LCP, INP, CLS scores - **Load time**: Time to interactive, first contentful paint - **Bundle size**: JavaScript, CSS, image sizes - **Runtime performance**: Frame rate, memory usage, CPU usage @@ -106,7 +106,7 @@ elements.forEach((el, i) => { - Minimize DOM depth (flatter is faster) - Reduce DOM size (fewer elements) - Use `content-visibility: auto` for long lists -- Virtual scrolling for very long lists (react-window, react-virtualized) +- Virtual scrolling for very long lists (react-window, TanStack Virtual) **Reduce Paint & Composite**: - Use `transform` and `opacity` for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish @@ -196,7 +196,7 @@ const observer = new IntersectionObserver((entries) => { - Use CDN - Server-side rendering -### First Input Delay (FID < 100ms) / INP (< 200ms) +### Interaction to Next Paint (INP < 200ms) - Break up long tasks - Defer non-critical JavaScript - Use web workers for heavy computation @@ -226,7 +226,7 @@ const observer = new IntersectionObserver((entries) => { - Performance monitoring (Sentry, DataDog, New Relic) **Key metrics**: -- LCP, FID/INP, CLS (Core Web Vitals) +- LCP, INP, CLS (Core Web Vitals; INP replaced FID in March 2024) - Time to Interactive (TTI) - First Contentful Paint (FCP) - Total Blocking Time (TBT) diff --git a/skill/reference/overdrive.md b/skill/reference/overdrive.md index 25585652c..bc4ffd79f 100644 --- a/skill/reference/overdrive.md +++ b/skill/reference/overdrive.md @@ -57,7 +57,7 @@ Organized by what you're trying to achieve, not by technology name. ### Render beyond CSS - **WebGL** (all browsers): shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express. -- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only): next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2. +- **WebGPU** (Chrome/Edge; Safari 26+; Firefox on Windows/macOS; flag only on Firefox Linux/Android): next-gen GPU compute, more powerful than WebGL. Always fall back to WebGL2. - **Canvas 2D / OffscreenCanvas**: custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas. - **SVG filter chains**: displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.