Motion & Animation Pack

Ship Fluid Motion Without the Jank, Accessibility Debt, or Layout Thrashing

You're building a component. You want a card to scale up on hover. You write transform: scale(1.05). It works. You feel good. Then you add a staggered list entrance. You loop through items, setting opacity and y with a delay. Suddenly, the scroll stutters on a mid-tier phone. You check Lighthouse. "Avoid large layout shifts." You check the Performance tab. The main thread is blocked by style recalculations.

The problem isn't your imagination; it's the browser rendering pipeline. When you animate layout properties like width, height, top, or margin, the browser triggers a layout recalculation on every frame. This forces the main thread to work twice as hard. MDN documents that animating layout properties is expensive because it requires recomputing the geometry of the element and all its descendants ^[3]. Even if you switch to transform, you might hit the composite layer limit. We've seen will-change abused to the point where the GPU memory usage spikes, causing the browser to evict other layers and thrash the cache.

Then there's the accessibility debt. You ship the animation, and the audit fails. WCAG 2.2 SC 2.3.3 requires that motion animation triggered by interaction can be disabled, unless it's essential ^[7]. Your component has no toggle. No prefers-reduced-motion query. No MotionConfig wrapper. You're shipping a feature that excludes users with vestibular disorders and invites a compliance ticket.

We've analyzed the performance differences between CSS-based and JavaScript-based animation approaches, and the trade-offs are real ^[1]. CSS animations are generally preferred because the browser can optimize them, often offloading work to the compositor thread ^[5]. But CSS isn't a silver bullet. You need to know when to use @keyframes, when to use will-change, and when to use a library like Framer Motion that handles useMotionValue and spring physics correctly. Without a system, you'll end up with a zoo of animation implementations. Some components use vanilla JS requestAnimationFrame. Others use CSS transitions. A third set uses Framer Motion. You'll have inconsistent easing curves. You'll have duplicate prefers-reduced-motion checks scattered across the codebase. You'll have will-change properties set on elements that never animate. This technical debt accumulates. Every new developer adds to the jank. Every refactor risks breaking an animation sequence.

We built this pack so you don't have to debug these issues one by one. We've codified the performance patterns and accessibility requirements into a system you can install and trust. If you're also building a scalable CSS animation system, you might want to look at Implementing CSS Animation System to complement this pack, but the Motion & Animation Pack goes deeper into the React/Framer Motion integration and the programmatic validation that CSS-only tools often miss.

The Jank Tax: What Your Animations Cost in LCP, INP, and Trust

Every frame you drop is a frame the user notices. If your animation stutters, the site feels broken. But the cost goes beyond "it looks bad." It impacts Core Web Vitals.

Animations that block the main thread directly degrade INP (Interaction to Next Paint). If your hover animation triggers a layout recalculation, the browser can't respond to the next user interaction until the frame completes. This makes the UI feel sluggish. If your entrance animation delays the rendering of the main content, you hurt LCP. Performance fundamentals dictate that you should minimize work on the main thread ^[4].

Consider the paint and composite phases. A simple transform update might only trigger composite, which is cheap. But if you animate box-shadow or border-radius, you trigger paint. If you animate width, you trigger layout and paint. On a complex page with many animated elements, these costs compound. The browser has to rasterize layers, promote them to GPU memory, and composite them at 60fps. If you're animating 50 items, you're creating 50 layers. If you're using will-change on all of them, you're forcing the browser to promote all 50, even if only a few are active. The GPU memory usage spikes. The browser starts evicting layers. The scroll gets worse.

Without a system, you'll end up with a zoo of animation implementations. Some components use vanilla JS requestAnimationFrame. Others use CSS transitions. A third set uses Framer Motion. You'll have inconsistent easing curves. You'll have duplicate prefers-reduced-motion checks scattered across the codebase. You'll have will-change properties set on elements that never animate. This technical debt accumulates. Every new developer adds to the jank. Every refactor risks breaking an animation sequence.

If you're also building a scalable CSS animation system, you might want to look at Implementing CSS Animation System to complement this pack, but the Motion & Animation Pack goes deeper into the React/Framer Motion integration and the programmatic validation that CSS-only tools often miss.

How a Dashboard Team Blew GPU Memory and Missed WCAG 2.2

Imagine a fintech dashboard team shipping a data visualization update. They need a staggered entry for 200 chart cards. The frontend lead writes a loop of setTimeout calls triggering CSS transitions. It works locally on a Mac. On a mid-tier Android device, the scroll stutters.

They try to optimize by adding will-change: transform to every card ^[6]. The GPU memory usage spikes. The browser starts evicting layers. The scroll gets worse. They realize they're holding GPU memory they don't need. The will-change property hints to browsers how an element is expected to change, but it's not a substitute for proper animation logic ^[6]. It's a hint, not a guarantee. And it comes with a memory cost.

Then the QA team catches it. The animation triggers immediately on load. There's no way for a user with vestibular disorders to disable it ^[2]. The audit flags SC 2.3.3. The fix requires refactoring the entire entry sequence. They need to switch to requestAnimationFrame or a library that handles the loop correctly. They need to add a prefers-reduced-motion query. They need to use MotionConfig with reducedMotion="user".

This isn't a hypothetical edge case. This is what happens when you rely on ad-hoc animations. You spend three days debugging why the AnimatePresence exit animation causes a reflow. You realize you didn't use LayoutGroup. You missed the useTransform binding. You wasted a sprint fixing mistakes that a system could have prevented. If you're interested in broader Creative Web Animations and Motion Pack techniques, that skill covers more experimental effects, but for production-grade React components with strict performance and accessibility constraints, you need the structure this pack provides.

What Changes When You Install the Motion System

Once you install the Motion & Animation Pack, the workflow shifts from "guess and check" to "install and ship."

You run ./scripts/scaffold-motion.sh MyComponent. You get a directory structure that's already set up for performance. You get AnimatedCard.tsx as a template. It includes AnimatePresence, LayoutGroup, useMotionValue, useTransform, and spring transitions. It has prefers-reduced-motion handled via MotionConfig. It has accessibility props wired up. The template demonstrates how to bind useMotionValue to useTransform for scroll-linked effects, and how to configure spring physics for natural motion.

You use motion-lint.js in your CI pipeline. The validator checks your files for anti-patterns. It flags animations on width or height without layout. It catches missing reduced-motion queries. It exits non-zero on failure. You catch the jank before it ships. The validator is a Node.js script that parses your code and enforces the motion principles defined in the pack.

You reference references/framer-motion-api.md for the API. You don't have to search Context7 docs. You have the embedded reference for AnimatePresence, LayoutGroup, useMotionValue, scroll, stagger, and spring configuration. You reference references/css-animation-guide.md for CSS patterns. You have @keyframes, View Transitions API, and performance tips. The View Transitions API reference covers how to handle group animations and details-content for smooth page transitions.

You look at examples/worked-example.md for a complex sequence. Staggered list with layout animations, scroll-linked effects, and imperative control. You look at examples/accessibility-check.md for the checklist. MotionConfig, reducedMotion='user', and testing strategies. The checklist ensures you've covered all accessibility requirements, including prefers-reduced-motion media queries and MotionConfig setup.

The result? Your animations are GPU-accelerated. Your accessibility is RFC-compliant. Your codebase is consistent. You ship fluid motion without the jank, the debt, or the tickets. You stop guessing about will-change. You stop shipping janky animations. You have a system that enforces performance and accessibility by default.

What's in the Motion & Animation Pack

• skill.md — Orchestrator skill file. Defines the motion design system, references all templates, references, scripts, validators, and examples. Guides the agent on how to use the package.
• references/motion-principles.md — Canonical knowledge on motion design principles, performance optimization (GPU acceleration, will-change, transform vs layout), and accessibility standards (prefers-reduced-motion, MotionConfig).
• references/framer-motion-api.md — Embedded API reference for Framer Motion based on Context7 docs. Covers motion components, AnimatePresence, LayoutGroup, useMotionValue, scroll, stagger, and spring configuration.
• references/css-animation-guide.md — Embedded reference for CSS animations based on Context7 docs. Covers @keyframes, View Transitions API, details-content, and performance tips.
• templates/framer-motion/AnimatedCard.tsx — Production-grade React component template. Demonstrates AnimatePresence, LayoutGroup, useMotionValue, useTransform, spring transitions, hover/tap states, and accessibility props.
• templates/css/ViewTransition.css — Production-grade CSS template for View Transitions API. Includes keyframes for slide/fade effects, group animations, and prefers-reduced-motion media queries.
• scripts/scaffold-motion.sh — Executable script to scaffold a new motion component. Creates directory structure, copies template, and sets up basic imports. Usage: ./scripts/scaffold-motion.sh .
• validators/motion-lint.js — Programmatic validator. Node.js script that checks files for motion anti-patterns (e.g., animating width/height without layout, missing reduced-motion queries). Exits non-zero on failure.
• examples/worked-example.md — Worked example demonstrating a complex animation sequence: staggered list with layout animations, scroll-linked effects, and imperative control.
• examples/accessibility-check.md — Worked example and checklist for implementing accessibility in motion. Covers MotionConfig, reducedMotion='user', and testing strategies.

Stop Shipping Jank. Upgrade to Pro.

You have two choices. You can keep debugging layout thrashing, missing accessibility requirements, and fighting with will-change configurations. You can keep shipping animations that work on your machine but stutter on the user's. You can keep adding technical debt to your codebase that will haunt you in the next sprint.

Or you can install the Motion & Animation Pack. You get the templates, the validator, the examples, and the embedded references. You get a system that enforces performance and accessibility by default. You stop guessing. You start shipping fluid, accessible motion. You ship with confidence.

Upgrade to Pro to install the Motion & Animation Pack. Stop guessing. Start shipping fluid, accessible motion.