Overview
This skill provides a comprehensive motion design and animation engineering workflow for UI transitions, microinteractions, canvas motion, scroll animation, and game-like feedback. It ensures animations are implemented using the lightest possible engineering layer while preserving performance and accessibility.
When to Use
Use this skill when you need to:
- Add or review UI animations, transitions, or microinteractions.
- Implement motion using CSS, Web Animations API (WAAPI), GSAP, Framer Motion, Three.js, or canvas.
- Design motion systems, animation specs, and spatial orientation.
- Ensure animations respect accessibility (a11y) constraints like
prefers-reduced-motion.
- Optimize animation performance to maintain 60fps/120fps.
Prerequisites
- Windows host is primary (PowerShell). Ensure Node.js and package managers (npm/yarn/pnpm) are available in your PowerShell environment.
- Re-check official/current docs before relying on provider-specific APIs, policy, pricing, security behavior, or platform rules.
- Collect target users, primary task, platform, viewport range, existing design system, accessibility requirements, brand constraints, data density, interaction states, and success metric. Ask for screenshots or reference URLs when visual fidelity matters.
Procedure
1. Architectural Motion Layer Selection
Choose the lightest possible engineering layer that satisfies the design intent:
- CSS Transitions/Keyframes: Best for static state-to-state properties (hover, active, focus). Runs on the browser's compositor thread.
- Web Animations API (WAAPI): Best for programmatic control of simple sequences without external libraries.
- Framer Motion: Best for React environments. Simplifies layout transition tracking and handles entry/exit DOM manipulation cleanly.
- GSAP (GreenSock): Best for complex timelines, morphing SVG vector lines, or scroll-driven scenes.
- Canvas / WebGL (Three.js): Reserved for rendering large point-clouds, physical particle fields, custom shaders, and interactive 3D models.
2. Easing and Timing Mechanics
Animations should feel natural, reflecting physical laws of inertia:
- Standard Timing Windows:
- Micro-interactions (toggles, button feedback): 100ms - 150ms
- Segment expansions, dropdown triggers: 200ms - 300ms
- Full-screen route adjustments, modal slide-ins: 300ms - 400ms
- Easing Profiles:
- Ease-Out (Deceleration): Fast entrance, slow settlement. Best for elements entering the viewport.
- Ease-In (Acceleration): Slow start, fast exit. Best for elements exiting active layouts.
- Elastic / Bounce Ease: Reserved for interfaces mimicking rubber-band limits. Never apply to structural page components.
3. Performance Optimization and Reflow Mitigation
To keep animations running at a smooth 60fps/120fps:
- GPU Accelerated Properties: Only animate
transform (translation, scaling, rotation) and opacity. The browser delegates these directly to the GPU compositor thread.
- Avoid Layout-Thrashing Properties: Do not animate
width, height, margin, top, or left. These force reflow and repaint, causing jank.
- Will-Change Strategy: For complex vector paths or large elements, apply
will-change: transform, opacity in CSS to pre-allocate GPU memory buffers. Remove this class when animations finish to release resources.
4. Motion Engineering Engine Matrix
| Feature |
CSS Transitions |
WAAPI |
GSAP |
Framer Motion |
Three.js |
| Runtime Overhead |
None |
Low (Browser Native) |
Medium (~25KB bundle) |
High (~35-50KB React lib) |
Extreme (>150KB WebGL wrapper) |
| Complex Timelines |
Hard (CSS Keyframe chains) |
Medium |
Exceptional (Timeline nesting) |
Medium (Sequential triggers) |
Custom (Loop-driven updates) |
| React Integration |
Style hooks |
Class refs |
Refs + useGSAP |
Native components |
Native via Fiber wrapper |
| Hardware Accelerated |
Yes (Compositor only) |
Yes (Compositor only) |
JS main-thread driven |
JS main-thread driven |
Yes (Direct WebGL pipeline) |
| SVG Sub-path Morphing |
No |
No |
Outstanding |
Medium |
N/A |
5. Implementation Workflow
- Start from purpose: feedback, continuity, hierarchy, causality, spatial orientation, progress, or delight.
- Define motion tokens: duration, easing, delay, distance, spring behavior, reduced-motion behavior, and interruption rules.
- Map states: idle, hover, focus, active, pressed, loading, success, error, disabled, drag, drop, enter, exit, and route change.
- Choose technology by job: CSS for simple states, Motion for React layout/component animation, GSAP for orchestration, Lottie/Rive for authored vector animation, Three.js/WebGL for spatial scenes.
- Validate accessibility and performance before polish.
6. Code Examples
Performance-Optimized Web Animations API (WAAPI) Transition:
class PerformanceAnimationEngine {
constructor() {
const query = window.matchMedia("(prefers-reduced-motion: reduce)");
this.prefersReducedMotion = query.matches;
query.addEventListener("change", (e) => {
this.prefersReducedMotion = e.matches;
});
}
animateElement(element, keyframes, options) {
if (!element) return null;
if (this.prefersReducedMotion) {
const finalStyles = keyframes[keyframes.length - 1];
Object.keys(finalStyles).forEach((prop) => {
element.style[prop] = finalStyles[prop];
});
return { finished: Promise.resolve(), cancel: () => {} };
}
const defaultOptions = {
duration: 250,
easing: "cubic-bezier(0.16, 1, 0.3, 1)",
fill: "both"
};
const combinedOptions = { ...defaultOptions, ...options };
const animation = element.animate(keyframes, combinedOptions);
animation.finished
.then(() => {
const finalFrame = keyframes[keyframes.length - 1];
Object.keys(finalFrame).forEach((prop) => {
element.style[prop] = finalFrame[prop];
});
animation.cancel();
})
.catch((e) => {
console.warn("Animation cleanup interrupted:", e);
});
return animation;
}
}
Declarative Framer Motion Transition with Layout Matching (React):
import * as React from "react";
import { motion, AnimatePresence, useReducedMotion } from "framer-motion";
interface TaskItem {
id: string;
label: string;
}
export function TaskList({ items }: { items: TaskItem[] }) {
const shouldReduceMotion = useReducedMotion();
const containerVariants = {
hidden: { opacity: 0 },
visible: {
opacity: 1,
transition: { staggerChildren: shouldReduceMotion ? 0 : 0.05 }
}
};
const itemVariants = {
hidden: {
opacity: 0,
y: shouldReduceMotion ? 0 : 15
},
visible: {
opacity: 1,
y: 0,
transition: { type: "spring", stiffness: 300, damping: 30 }
},
exit: {
opacity: 0,
scale: shouldReduceMotion ? 1 : 0.95,
transition: { duration: 0.15 }
}
};
return (
<motion.ul
variants={containerVariants}
initial="hidden"
animate="visible"
className="space-y-2 p-4 bg-background border rounded-lg"
>
<AnimatePresence mode="popLayout">
{items.map((item) => (
<motion.li
key={item.id}
layout={!shouldReduceMotion}
variants={itemVariants}
exit="exit"
className="p-3 bg-card text-card-foreground border rounded shadow-sm flex items-center justify-between"
>
<span>{item.label}</span>
</motion.li>
))}
</AnimatePresence>
</motion.ul>
);
}
Pitfalls
Anti-Patterns in UI Motion
- Non-Accelerated Geometry Morphing: Animating dialog card expansions using
width and height instead of transform: scale(). This forces layout recalculation on every frame.
- Unbounded Loop Execution: Leaving
requestAnimationFrame loops or React intervals running indefinitely after components unmount. This causes CPU leaks and battery drain.
- Blocking Pointer Targets: Leaving interactive elements active during exit animations. Disable clicking immediately (
pointer-events: none) to prevent double-click actions.
Gotchas and Edge Cases
- Flexbox Layout Scaling Shunting: Using
transform: scale() on flex child elements can scale background colors while leaving border coordinates unchanged. Use explicit parent wrappers to isolate scaling.
- Z-Index Layer Clipping during Rotations: 3D perspective transforms (
rotateY) can clip behind container boundaries. Ensure parent containers have transform-style: preserve-3d and backface-visibility: hidden.
- Keyboard Navigation Synchronization: Animating components off-screen using
opacity: 0 while keeping them in the DOM allows screen readers and keyboard users to focus hidden elements. Set visibility: hidden or display: none once exit animations complete.
Accessibility (a11y) Constraints
- Flash animations and high-velocity transitions can trigger seizures in users with photosensitive epilepsy. Avoid high-frequency flickering.
- Use the CSS variable
transition: var(--transition-speed, 200ms) coupled with a global theme class to globally disable animations for testing or reduced motion.
- A user's preference for reduced motion does not mean a worse experience. Keep layout transformations functional by swapping sliding transitions for simple, rapid opacity crossfades.
Verification
Quality Checklist
Failure Handling
If requirements conflict, prioritize usability, accessibility, and product fit over novelty. If a requested visual pattern harms readability or accessibility, explain the tradeoff and offer a better variant. Verify current platform guidance when building for Apple, Android, or a specific design system.
Related skills
ui-ux-design-craft: For general interface design, UX review, and responsive layouts.
frontend-architecture-craft: For broader frontend implementation guidance and state management.
1---
2name: motion-animation-craft
3description: "Chooses the lightest web motion engine (CSS, WAAPI, GSAP, Framer Motion, canvas/WebGL) for UI transitions, scroll scenes, and game-like micro-feedback. Use when setting duration/easing tokens, GPU-only transform/opacity, or prefers-reduced-motion fallbacks. Not for Remotion compositions or Emil Kowalski popover/drawer/toast recipes."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/motion-animation-craft
7---
8
9## Overview
10This skill provides a comprehensive motion design and animation engineering workflow for UI transitions, microinteractions, canvas motion, scroll animation, and game-like feedback. It ensures animations are implemented using the lightest possible engineering layer while preserving performance and accessibility.
11
12## When to Use
13Use this skill when you need to:
14- Add or review UI animations, transitions, or microinteractions.
15- Implement motion using CSS, Web Animations API (WAAPI), GSAP, Framer Motion, Three.js, or canvas.
16- Design motion systems, animation specs, and spatial orientation.
17- Ensure animations respect accessibility (a11y) constraints like `prefers-reduced-motion`.
18- Optimize animation performance to maintain 60fps/120fps.
19
20## Prerequisites
21- Windows host is primary (PowerShell). Ensure Node.js and package managers (npm/yarn/pnpm) are available in your PowerShell environment.
22- Re-check official/current docs before relying on provider-specific APIs, policy, pricing, security behavior, or platform rules.
23- Collect target users, primary task, platform, viewport range, existing design system, accessibility requirements, brand constraints, data density, interaction states, and success metric. Ask for screenshots or reference URLs when visual fidelity matters.
24
25## Procedure
26
27### 1. Architectural Motion Layer Selection
28Choose the lightest possible engineering layer that satisfies the design intent:
29- **CSS Transitions/Keyframes:** Best for static state-to-state properties (hover, active, focus). Runs on the browser's compositor thread.
30- **Web Animations API (WAAPI):** Best for programmatic control of simple sequences without external libraries.
31- **Framer Motion:** Best for React environments. Simplifies layout transition tracking and handles entry/exit DOM manipulation cleanly.
32- **GSAP (GreenSock):** Best for complex timelines, morphing SVG vector lines, or scroll-driven scenes.
33- **Canvas / WebGL (Three.js):** Reserved for rendering large point-clouds, physical particle fields, custom shaders, and interactive 3D models.
34
35### 2. Easing and Timing Mechanics
36Animations should feel natural, reflecting physical laws of inertia:
37- **Standard Timing Windows:**
38 - Micro-interactions (toggles, button feedback): **100ms - 150ms**
39 - Segment expansions, dropdown triggers: **200ms - 300ms**
40 - Full-screen route adjustments, modal slide-ins: **300ms - 400ms**
41- **Easing Profiles:**
42 - **Ease-Out (Deceleration):** Fast entrance, slow settlement. Best for elements entering the viewport.
43 - **Ease-In (Acceleration):** Slow start, fast exit. Best for elements exiting active layouts.
44 - **Elastic / Bounce Ease:** Reserved for interfaces mimicking rubber-band limits. Never apply to structural page components.
45
46### 3. Performance Optimization and Reflow Mitigation
47To keep animations running at a smooth 60fps/120fps:
48- **GPU Accelerated Properties:** Only animate `transform` (translation, scaling, rotation) and `opacity`. The browser delegates these directly to the GPU compositor thread.
49- **Avoid Layout-Thrashing Properties:** Do not animate `width`, `height`, `margin`, `top`, or `left`. These force reflow and repaint, causing jank.
50- **Will-Change Strategy:** For complex vector paths or large elements, apply `will-change: transform, opacity` in CSS to pre-allocate GPU memory buffers. Remove this class when animations finish to release resources.
51
52### 4. Motion Engineering Engine Matrix
53
54| Feature | CSS Transitions | WAAPI | GSAP | Framer Motion | Three.js |
55| :--- | :--- | :--- | :--- | :--- | :--- |
56| **Runtime Overhead** | None | Low (Browser Native) | Medium (~25KB bundle) | High (~35-50KB React lib) | Extreme (>150KB WebGL wrapper) |
57| **Complex Timelines** | Hard (CSS Keyframe chains) | Medium | Exceptional (Timeline nesting) | Medium (Sequential triggers) | Custom (Loop-driven updates) |
58| **React Integration** | Style hooks | Class refs | Refs + `useGSAP` | Native components | Native via Fiber wrapper |
59| **Hardware Accelerated**| Yes (Compositor only) | Yes (Compositor only) | JS main-thread driven | JS main-thread driven | Yes (Direct WebGL pipeline) |
60| **SVG Sub-path Morphing**| No | No | Outstanding | Medium | N/A |
61
62### 5. Implementation Workflow
631. Start from purpose: feedback, continuity, hierarchy, causality, spatial orientation, progress, or delight.
642. Define motion tokens: duration, easing, delay, distance, spring behavior, reduced-motion behavior, and interruption rules.
653. Map states: idle, hover, focus, active, pressed, loading, success, error, disabled, drag, drop, enter, exit, and route change.
664. Choose technology by job: CSS for simple states, Motion for React layout/component animation, GSAP for orchestration, Lottie/Rive for authored vector animation, Three.js/WebGL for spatial scenes.
675. Validate accessibility and performance before polish.
68
69### 6. Code Examples
70
71**Performance-Optimized Web Animations API (WAAPI) Transition:**
72```javascript
73class PerformanceAnimationEngine {
74 constructor() {
75 const query = window.matchMedia("(prefers-reduced-motion: reduce)");
76 this.prefersReducedMotion = query.matches;
77 query.addEventListener("change", (e) => {
78 this.prefersReducedMotion = e.matches;
79 });
80 }
81
82 animateElement(element, keyframes, options) {
83 if (!element) return null;
84
85 if (this.prefersReducedMotion) {
86 const finalStyles = keyframes[keyframes.length - 1];
87 Object.keys(finalStyles).forEach((prop) => {
88 element.style[prop] = finalStyles[prop];
89 });
90 return { finished: Promise.resolve(), cancel: () => {} };
91 }
92
93 const defaultOptions = {
94 duration: 250,
95 easing: "cubic-bezier(0.16, 1, 0.3, 1)",
96 fill: "both"
97 };
98
99 const combinedOptions = { ...defaultOptions, ...options };
100 const animation = element.animate(keyframes, combinedOptions);
101
102 animation.finished
103 .then(() => {
104 const finalFrame = keyframes[keyframes.length - 1];
105 Object.keys(finalFrame).forEach((prop) => {
106 element.style[prop] = finalFrame[prop];
107 });
108 animation.cancel();
109 })
110 .catch((e) => {
111 console.warn("Animation cleanup interrupted:", e);
112 });
113
114 return animation;
115 }
116}
117```
118
119**Declarative Framer Motion Transition with Layout Matching (React):**
120```tsx
121import * as React from "react";
122import { motion, AnimatePresence, useReducedMotion } from "framer-motion";
123
124interface TaskItem {
125 id: string;
126 label: string;
127}
128
129export function TaskList({ items }: { items: TaskItem[] }) {
130 const shouldReduceMotion = useReducedMotion();
131
132 const containerVariants = {
133 hidden: { opacity: 0 },
134 visible: {
135 opacity: 1,
136 transition: { staggerChildren: shouldReduceMotion ? 0 : 0.05 }
137 }
138 };
139
140 const itemVariants = {
141 hidden: {
142 opacity: 0,
143 y: shouldReduceMotion ? 0 : 15
144 },
145 visible: {
146 opacity: 1,
147 y: 0,
148 transition: { type: "spring", stiffness: 300, damping: 30 }
149 },
150 exit: {
151 opacity: 0,
152 scale: shouldReduceMotion ? 1 : 0.95,
153 transition: { duration: 0.15 }
154 }
155 };
156
157 return (
158 <motion.ul
159 variants={containerVariants}
160 initial="hidden"
161 animate="visible"
162 className="space-y-2 p-4 bg-background border rounded-lg"
163 >
164 <AnimatePresence mode="popLayout">
165 {items.map((item) => (
166 <motion.li
167 key={item.id}
168 layout={!shouldReduceMotion}
169 variants={itemVariants}
170 exit="exit"
171 className="p-3 bg-card text-card-foreground border rounded shadow-sm flex items-center justify-between"
172 >
173 <span>{item.label}</span>
174 </motion.li>
175 ))}
176 </AnimatePresence>
177 </motion.ul>
178 );
179}
180```
181
182## Pitfalls
183
184### Anti-Patterns in UI Motion
185- **Non-Accelerated Geometry Morphing:** Animating dialog card expansions using `width` and `height` instead of `transform: scale()`. This forces layout recalculation on every frame.
186- **Unbounded Loop Execution:** Leaving `requestAnimationFrame` loops or React intervals running indefinitely after components unmount. This causes CPU leaks and battery drain.
187- **Blocking Pointer Targets:** Leaving interactive elements active during exit animations. Disable clicking immediately (`pointer-events: none`) to prevent double-click actions.
188
189### Gotchas and Edge Cases
190- **Flexbox Layout Scaling Shunting:** Using `transform: scale()` on flex child elements can scale background colors while leaving border coordinates unchanged. Use explicit parent wrappers to isolate scaling.
191- **Z-Index Layer Clipping during Rotations:** 3D perspective transforms (`rotateY`) can clip behind container boundaries. Ensure parent containers have `transform-style: preserve-3d` and `backface-visibility: hidden`.
192- **Keyboard Navigation Synchronization:** Animating components off-screen using `opacity: 0` while keeping them in the DOM allows screen readers and keyboard users to focus hidden elements. Set `visibility: hidden` or `display: none` once exit animations complete.
193
194### Accessibility (a11y) Constraints
195- Flash animations and high-velocity transitions can trigger seizures in users with photosensitive epilepsy. Avoid high-frequency flickering.
196- Use the CSS variable `transition: var(--transition-speed, 200ms)` coupled with a global theme class to globally disable animations for testing or reduced motion.
197- A user's preference for reduced motion does not mean a worse experience. Keep layout transformations functional by swapping sliding transitions for simple, rapid opacity crossfades.
198
199## Verification
200
201### Quality Checklist
202- [ ] User can complete the core task quickly and repeatedly.
203- [ ] UI supports keyboard, screen readers, visible focus, and sufficient contrast.
204- [ ] Mobile and desktop layouts do not overlap or rely on fragile viewport-scaled text.
205- [ ] Controls use familiar affordances and expose state clearly.
206- [ ] Motion is purposeful and respects reduced-motion preferences.
207- [ ] Visual direction is intentional and consistent with the product domain.
208- [ ] Motion never blocks task completion.
209- [ ] Animation is interruptible, reversible, and does not cause layout shift.
210- [ ] Durations are short enough for repeated work and long enough to be legible.
211
212### Failure Handling
213If requirements conflict, prioritize usability, accessibility, and product fit over novelty. If a requested visual pattern harms readability or accessibility, explain the tradeoff and offer a better variant. Verify current platform guidance when building for Apple, Android, or a specific design system.
214
215## Related skills
216- `ui-ux-design-craft`: For general interface design, UX review, and responsive layouts.
217- `frontend-architecture-craft`: For broader frontend implementation guidance and state management.