Animation Performance Auditor

What this skill does

Scans a codebase for CSS and JS-driven animations that animate layout or paint properties (e.g., width, top, box-shadow) and proposes equivalent compositor-only animations using transform or opacity.

Inputs

• repo_dir: project root.
• Optional glob: defaults to src/**/*.{css,scss,jsx,tsx,js,ts}.
• Optional framework: framer-motion, gsap, react-spring, none.

Steps

1. Find CSS animations: rg -nN 'animation\s*:|@keyframes' <repo_dir> --glob '*.{css,scss}'. Parse each @keyframes block.
2. Find CSS transitions: rg -nN 'transition\s*:' <repo_dir> --glob '*.{css,scss}'. Extract the comma-separated property list.
3. Identify offending properties: any of top, left, right, bottom, width, height, margin, padding, font-size, box-shadow, filter (filter is paint-only) signals layout or paint reflow.
4. For JS animations, scan based on framework:
   • framer-motion: rg -nN '<motion\.\w+\s+(animate|whileHover)' --glob '*.{jsx,tsx}'. Inspect the animated keys.
   • gsap: rg -nN 'gsap\.(to|from|fromTo)\(' --glob '*.{js,ts,jsx,tsx}'.
   • react-spring: rg -nN 'useSpring\b' --glob '*.{jsx,tsx}'.
5. For each finding, produce a fix suggestion: animate top: 0 -> top: 100px -> animate transform: translateY(0) -> translateY(100px). Animate width: 0 -> width: 100% -> animate transform: scaleX(0) -> scaleX(1) plus a transform-origin: left.
6. Tag each finding compositor-only-possible or requires-refactor based on whether a 1:1 swap is straightforward.
7. Cite the source file:line and the offending property.
8. Emit a markdown report grouped by file.

Output

animation-audit.md with: summary counts (CSS animations, CSS transitions, JS animations), table of findings with file:line and suggested fix, and one "before/after" code block per top-impact finding.

Verification

For each suggested swap, render the component in a Chromium browser with the Performance panel recording, and confirm the modified animation does not appear in the "Layout" or "Paint" lanes (it should sit in "Compositor"). Visually compare original vs. modified animation under reduced-motion preferences. If a finding cannot be expressed as a transform (e.g., animating border-radius from 0 to 50%), keep it but mark requires-refactor.

Edge cases

• Animations behind prefers-reduced-motion: still audit but lower the priority.
• 3D transforms: those promote to compositor automatically; flag oversights where 2D is used unnecessarily.
• Animations on text-shadow / box-shadow used for emphasis: refactor to filter: drop-shadow only if the visual diff is acceptable; ship a "before/after" screenshot suggestion.
• Library-internal animations (e.g., a Material-UI ripple): note but do not modify upstream.