adding-animations

name	adding-animations
description	Add micro-interactions and animations using Framer Motion. Use when user asks about animations, transitions, hover effects, or motion design. MANDATORY for every component.
allowed-tools	Read, Write, Edit, Glob, Grep, Task
user-invocable	true

Adding Animations (MANDATORY)

Every component MUST have Framer Motion animations.

APEX WORKFLOW

Phase 0: ANALYZE EXISTING ANIMATIONS

Task: explore-codebase
Prompt: "Find existing Framer Motion patterns: variants, timing,
easing, hover effects. Report animation conventions."

RULE: Match existing animation patterns OR propose migration.

Standard Patterns

Container + Stagger (REQUIRED)

import { motion } from "framer-motion";

const container = {
  hidden: { opacity: 0 },
  show: { opacity: 1, transition: { staggerChildren: 0.1 } }
};

const item = {
  hidden: { opacity: 0, y: 20 },
  show: { opacity: 1, y: 0 }
};

<motion.div variants={container} initial="hidden" animate="show">
  <motion.div variants={item}>Item 1</motion.div>
  <motion.div variants={item}>Item 2</motion.div>
</motion.div>

Hover Effects (REQUIRED)

// Card hover
<motion.div whileHover={{ y: -4 }} transition={{ duration: 0.2 }}>

// Button hover
<motion.button
  whileHover={{ scale: 1.02 }}
  whileTap={{ scale: 0.98 }}
>

Scroll Animation

<motion.div
  initial={{ opacity: 0, y: 40 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-100px" }}
/>

Timing Guidelines

Interaction	Duration	Easing
Hover	50-100ms	ease-out
Button press	100-150ms	ease-out
Modal open	200-300ms	ease-out
Page transition	300-400ms	ease-in-out

FORBIDDEN

// ❌ Random bouncing loops
animate={{ y: [0, -10, 0] }}
transition={{ repeat: Infinity }}

// ❌ Excessive effects
whileHover={{ scale: 1.2, rotate: 5 }}

// ❌ Slow animations
transition={{ duration: 1.5 }}

Accessibility (MANDATORY)

import { useReducedMotion } from "framer-motion";

function Component() {
  const shouldReduce = useReducedMotion();
  return (
    <motion.div
      animate={shouldReduce ? {} : { y: 0 }}
      transition={shouldReduce ? { duration: 0 } : { duration: 0.3 }}
    />
  );
}

Validation

[ ] Existing animations analyzed (Phase 0)
[ ] Patterns match existing OR migration proposed
[ ] Stagger on lists/grids
[ ] Hover on all interactive elements
[ ] prefers-reduced-motion respected
[ ] No excessive/random animations

References

• Motion Patterns: ../../references/motion-patterns.md (Framer Motion patterns)
• Buttons Guide: ../../references/buttons-guide.md (hover 50-100ms, press 100-150ms)
• Cards Guide: ../../references/cards-guide.md (whileHover y: -4, shadow transitions)
• UI Visual Design: ../../references/ui-visual-design.md (micro-interactions, 2026 trends)
• UX Principles: ../../references/ux-principles.md (accessibility, reduced motion)
• Design Patterns: ../../references/design-patterns.md
• Component Examples: ../../references/component-examples.md