Agent-Skills.md

Agent Skills: Performance Optimization

Use when animation runs slow, janky, or causes frame drops

UncategorizedID: dylantarre/animation-principles/performance-optimization

Repository

dylantarre/animation-principles
dylantarreLicense: MIT
52

Install this agent skill to your local

pnpm dlx add-skill https://github.com/dylantarre/animation-principles/tree/HEAD/skills/12-by-problem-type/performance-optimization

Skill Files

Browse the full folder contents for performance-optimization.

Download Skill

Loading file tree…

skills/12-by-problem-type/performance-optimization/SKILL.md

Skill Metadata

Name
performance-optimization
Description
Use when animation runs slow, janky, or causes frame drops

Performance Optimization

Diagnose and fix slow or janky animations using Disney's 12 principles.

Problem Indicators

  • Frame rate drops below 60fps
  • Stuttering or choppy motion
  • UI feels sluggish
  • Battery drain on mobile
  • Layout thrashing

Diagnosis by Principle

Straight Ahead vs Pose-to-Pose

Issue: Calculating every frame in real-time Fix: Use pose-to-pose (keyframe) animation. Let the browser interpolate between states using CSS transitions or will-change.

Timing

Issue: Too many simultaneous animations Fix: Stagger animations. Offset start times by 50-100ms to reduce concurrent calculations.

Secondary Action

Issue: Too many secondary effects Fix: Remove non-essential secondary animations on low-power devices. Use prefers-reduced-motion query.

Solid Drawing

Issue: Animating expensive properties (width, height, top, left) Fix: Only animate transform and opacity. These are GPU-accelerated and skip layout/paint.

Staging

Issue: Animating off-screen elements Fix: Only animate what's visible. Use Intersection Observer to pause off-screen animations.

Quick Fixes

  1. Replace JS animations with CSS - Browser-optimized
  2. Use transform instead of position properties - GPU layer
  3. Add will-change sparingly - Hints to browser
  4. Reduce simultaneous animations - Stagger or sequence
  5. Lower animation complexity on mobile - Detect device capability

Troubleshooting Checklist

  • [ ] Check DevTools Performance tab for long frames
  • [ ] Verify animations use transform/opacity only
  • [ ] Count simultaneous animations (keep under 3-4)
  • [ ] Test on lowest-spec target device
  • [ ] Check for layout thrashing (forced reflows)
  • [ ] Verify will-change isn't overused
  • [ ] Test with CPU throttling enabled
  • [ ] Check if animations pause when tab is hidden

Code Pattern

/* Fast */
.element {
  will-change: transform;
  transition: transform 200ms ease-out;
}
.element:hover {
  transform: translateY(-4px);
}

/* Slow - avoid */
.element:hover {
  top: -4px; /* Triggers layout */
}