Motion Animation Library Guide

# Motion Animation Library Guide

Build engaging, performant animations in your Google Antigravity applications using the Motion library. This guide covers animation fundamentals, gestures, layout animations, and performance optimization.

## Basic Animations

Get started with motion components:

```typescript
// components/AnimatedCard.tsx
"use client";

import { motion } from "motion/react";

export function AnimatedCard({ children }: { children: React.ReactNode }) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0, y: -20 }}
      transition={{
        duration: 0.3,
        ease: "easeOut",
      }}
      whileHover={{
        scale: 1.02,
        boxShadow: "0 10px 30px rgba(0,0,0,0.1)",
      }}
      whileTap={{ scale: 0.98 }}
      className="bg-white rounded-xl p-6 border"
    >
      {children}
    </motion.div>
  );
}
```

## Staggered List Animations

Animate lists with staggered children:

```typescript
// components/AnimatedList.tsx
"use client";

import { motion } from "motion/react";

const containerVariants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.1,
      delayChildren: 0.2,
    },
  },
};

const itemVariants = {
  hidden: { opacity: 0, x: -20 },
  visible: {
    opacity: 1,
    x: 0,
    transition: {
      duration: 0.4,
      ease: [0.25, 0.46, 0.45, 0.94],
    },
  },
};

export function AnimatedList<T>({ 
  items, 
  renderItem 
}: {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
}) {
  return (
    <motion.ul
      variants={containerVariants}
      initial="hidden"
      animate="visible"
      className="space-y-4"
    >
      {items.map((item, index) => (
        <motion.li key={index} variants={itemVariants}>
          {renderItem(item, index)}
        </motion.li>
      ))}
    </motion.ul>
  );
}
```

## Page Transitions

Implement smooth page transitions:

```typescript
// components/PageTransition.tsx
"use client";

import { motion, AnimatePresence } from "motion/react";
import { usePathname } from "next/navigation";

const pageVariants = {
  initial: {
    opacity: 0,
    y: 20,
  },
  enter: {
    opacity: 1,
    y: 0,
    transition: {
      duration: 0.4,
      ease: [0.25, 0.46, 0.45, 0.94],
    },
  },
  exit: {
    opacity: 0,
    y: -20,
    transition: {
      duration: 0.3,
    },
  },
};

export function PageTransition({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();

  return (
    <AnimatePresence mode="wait">
      <motion.div
        key={pathname}
        variants={pageVariants}
        initial="initial"
        animate="enter"
        exit="exit"
      >
        {children}
      </motion.div>
    </AnimatePresence>
  );
}
```

## Layout Animations

Animate layout changes smoothly:

```typescript
// components/ExpandableCard.tsx
"use client";

import { useState } from "react";
import { motion, LayoutGroup, AnimatePresence } from "motion/react";

export function ExpandableCard({ title, content }: { 
  title: string; 
  content: string 
}) {
  const [isExpanded, setIsExpanded] = useState(false);

  return (
    <LayoutGroup>
      <motion.div
        layout
        onClick={() => setIsExpanded(!isExpanded)}
        className="bg-white rounded-xl p-6 cursor-pointer overflow-hidden"
        style={{ borderRadius: 16 }}
      >
        <motion.h3 layout="position" className="text-xl font-bold">
          {title}
        </motion.h3>
        
        <AnimatePresence>
          {isExpanded && (
            <motion.p
              initial={{ opacity: 0, height: 0 }}
              animate={{ opacity: 1, height: "auto" }}
              exit={{ opacity: 0, height: 0 }}
              transition={{ duration: 0.3 }}
              className="mt-4 text-gray-600"
            >
              {content}
            </motion.p>
          )}
        </AnimatePresence>
      </motion.div>
    </LayoutGroup>
  );
}
```

## Gesture Handling

Handle complex gestures:

```typescript
// components/DraggableCard.tsx
"use client";

import { motion, useMotionValue, useTransform } from "motion/react";

export function DraggableCard() {
  const x = useMotionValue(0);
  const rotate = useTransform(x, [-200, 200], [-30, 30]);
  const opacity = useTransform(x, [-200, -100, 0, 100, 200], [0, 1, 1, 1, 0]);
  const background = useTransform(
    x,
    [-200, 0, 200],
    ["#ff6b6b", "#fff", "#51cf66"]
  );

  return (
    <motion.div
      drag="x"
      dragConstraints={{ left: 0, right: 0 }}
      style={{ x, rotate, opacity, background }}
      whileDrag={{ scale: 1.05, cursor: "grabbing" }}
      onDragEnd={(_, info) => {
        if (info.offset.x > 100) {
          console.log("Swiped right - Like!");
        } else if (info.offset.x < -100) {
          console.log("Swiped left - Dismiss");
        }
      }}
      className="w-72 h-96 rounded-2xl shadow-xl cursor-grab"
    />
  );
}
```

## Performance Optimization

Optimize animations for performance:

```typescript
// Use transform properties only (GPU accelerated)
const goodAnimation = {
  scale: 1.1,
  rotate: 10,
  x: 100,
  opacity: 0.5,
};

// Use willChange for complex animations
<motion.div
  style={{ willChange: "transform" }}
  animate={{ scale: [1, 1.2, 1] }}
/>
```

## Best Practices

1. **GPU Acceleration**: Animate transform and opacity properties only
2. **Exit Animations**: Use AnimatePresence for unmount animations
3. **Layout Animations**: Use layout prop for position changes
4. **Reduced Motion**: Respect user preferences with useReducedMotion
5. **Performance**: Profile animations in React DevTools
6. **Semantic Motion**: Use motion to enhance, not distract