Mattttfb/animation-engineering

Animation Engineering & Motion Craft

This skill equips the agent with industry-standard practices, production-ready patterns, and mathematical physics models to design and code fluid, performant animations across web and application interfaces.

---

1. Golden Rules of Motion Performance

1. Animate ONLY Composite Properties:
   • Always prefer transform (translate3d, scale, rotate) and opacity.
   • NEVER animate geometry properties (width, height, top, left, margin, padding) unless using the FLIP technique (First, Last, Invert, Play). Animating geometry triggers expensive layout recalculations (Reflow) and Paint on the CPU.
2. Promote to GPU Responsibly:
   • Use will-change: transform, opacity; only on actively animated elements, and remove it after animation completes if memory is constrained.
   • Force GPU layer composition with transform: translateZ(0) or backface-visibility: hidden when needed.
3. Respect User Accessibility:
   • Always support @media (prefers-reduced-motion: reduce):

     @media (prefers-reduced-motion: reduce) {
       *, *::before, *::after {
         animation-duration: 0.01ms !important;
         animation-iteration-count: 1 !important;
         transition-duration: 0.01ms !important;
         scroll-behavior: auto !important;
       }
     }
     

4. Natural Timing & Durations:
   • Micro-interactions (button press, toggle, tooltip): 100ms - 200ms
   • Standard transitions (dropdowns, dialogs, drawers, cards): 200ms - 350ms
   • Complex scene transitions / page transitions: 350ms - 500ms
   • Animations longer than 500ms feel sluggish unless they are continuous atmospheric background loops or narrative storytelling.

---

2. Technology Selection Matrix

Scenario / Need	Recommended Tool	Why?
Simple hover, focus, active states, fade/slide	CSS Transitions & @keyframes or Tailwind CSS	Zero JavaScript overhead, 120 FPS hardware acceleration.
React / Next.js UI, Modals, Shared Layout Transitions	Framer Motion (motion)	Declarative API, spring physics, automatic FLIP (layoutId), AnimatePresence.
Complex Timelines, SVG Morphing, Scroll-driven UI	GSAP (GreenSock) + ScrollTrigger	Unmatched choreography control, precise scrubbing, cross-browser consistency.
3D Experiences, Particle Networks, Shaders	Three.js / React Three Fiber / Canvas 2D	Direct WebGL GPU rendering for hundreds of thousands of particles.
Vector Motion Graphics & Character Illustrations	Lottie / dotLottie / Rive	Tiny JSON/binary payloads, scalable vector fidelity, interactive state machines.

---

3. Motion Curves (Easing Tokens)

Never use linear for UI movement unless simulating a constant-speed conveyor belt or infinite spinning loader. Natural movement accelerates and decelerates:

• Snappy Entrance (Standard UI pop/open): cubic-bezier(0.16, 1, 0.3, 1) (Expo Out - fast initial burst, smooth deceleration)
• Smooth Exit (Dismiss/close): cubic-bezier(0.7, 0, 0.84, 0) (Expo In - accelerates off screen)
• Natural Dynamic / Emphasized: cubic-bezier(0.34, 1.56, 0.64, 1) (Subtle overshoot bounce)
• Spring Physics (Preferred for touch & drag):
  • Stiffness: 300 - 400
  • Damping: 25 - 35
  • Mass: 0.8 - 1.0

---

4. Deep Guides & References

For comprehensive code patterns and detailed walkthroughs, consult the references:

• CSS & Tailwind Animations Reference
• Framer Motion & Motion One Patterns
• GSAP & ScrollTrigger Mastery
• Three.js & Canvas Motion
• UI Motion Principles & Accessibility

---

5. Verification Checklist

When building animated components:

• Are animations smooth (60-120 FPS) without stutter or frame drops?
• Are layout shifts (CLS) avoided during animation?
• Are exit animations properly awaited before element unmount?
• Does the UI handle rapid clicking/tapping without glitching (interruptible animations)?
• Is prefers-reduced-motion implemented?