Skip to main content
Agent skill

Motion Patterns

Production-ready animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs. Use when animating a specific UI element in React or Next.js — button, modal, toast, stagger, page transition, or scroll.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Motion Patterns when an AI agent needs a reusable SKILL.md workflow for this job: Production-ready animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs. Use when animating a specific UI element in React or Next.js — button, modal, toast, stagger, page transition, or scroll.

When not to use it

Skip Motion Patterns when the task is outside the writing category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/motion-patterns
# Save SKILL.md to ~/.claude/skills/motion-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/motion-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/motion-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Motion Patterns skill for this task: Use Motion Patterns when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
76/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Motion Patterns

Copy-paste patterns for the most common UI animation needs. Every pattern here is built on `motion-foundations` tokens and springs. Do not define new duration or easing values here — import them.

## When to Activate

- Animating a button, card, modal, or toast notification - Building list entrances with stagger - Setting up page transitions in Next.js App Router - Adding entrance or exit animations to conditional content - Implementing scroll-reveal, scroll-linked progress, or sticky story sections - Building expanding cards, accordions, or shared-element transitions

## Outputs

This skill produces:

- Accessible, SSR-safe animation for all standard UI components - `AnimatePresence`-wrapped conditional renders with correct exit behavior - Page transition wrapper component for Next.js App Router - Scroll-reveal and scroll-linked patterns using `useScroll` + `useTransform` - Layout animation patterns (`layout`, `layoutId`) for expanding and crossfading elements

## Principles

- Every pattern imports from `motion-foundations`. No raw numbers. - Every conditional render is wrapped in `AnimatePresence` with a `key`. - Exit animations are always defined alongside enter animations — never as an afterthought. - `layout` is used only for small, isolated shifts. Large subtrees get explicit transforms.

## Rules

1. **Always wrap conditional renders in `AnimatePresence` with a `key`** on the direct child. Without a key, exit animations never fire. 2. **Always define `exit` when defining `initial` + `animate`.** An animation without an exit is incomplete. 3. **Use `mode="wait"` on page transitions.** Enter must not start until exit completes. 4. **Never use `layout` on subtrees with more than ~5 children or deeply nested DOM.** Use explicit `x`/`y` transforms instead. 5. **Stagger interval must stay between `0.05s` and `0.10s`.** Below feels mechanical; above feels sluggish. 6. **Modals must always include:** focus trap, Escape-key close, scroll lock, `role="dialog"`, `aria-modal="true"`. 7. **Scroll reveals use `viewport={{ once: true }}`.** Repeating on scroll-out is distracting, not informative. 8. **All token values are imported from `motion-foundations`.** No inline numbers.

## Decision Guidance

### Choosing the right pattern

| Situation | Pattern | | ---------------------------------------- | ---------------------- | | Element appears / disappears | `AnimatePresence` | | List of items loading in sequence | Stagger variants | | Navigating between routes | Page transition wrapper| | Element changes size in place | `layout` prop | | Same element moves across page contexts | `layoutId` | | Element enters when scrolled into view | `whileInView` | | Value tied to scroll position | `useScroll` + `useTransform` |

### When to use `mode="wait"` vs `mode="sync"`

| Mode | Use when | | ------- | --------------------------------------- | | `wait` | Page transitions, content swaps (one at a time) | | `sync` | Stacked notifications, list items (overlap is fine) | | `popLayout` | Items removed from a reflow list |

## Core Concepts

### AnimatePresence contract

Three things must always be true:

1. `AnimatePresence` wraps the conditional 2. The direct child has a `key` 3. The child has an `exit` prop

Miss any one of these and the exit animation silently fails.

### layout vs layoutId

- `layout` — animates the element's own size/position change in place - `layoutId` — links two separate elements, crossfading between them across renders

Use `layout="position"` on text inside an expanding container to prevent text reflow from animating.

## Code Examples

### Button feedback

```tsx "use client" import { motion } from "motion/react" import { springs, motionTokens } from "@/lib/motion-tokens"

<motion.button whileHover={{ scale: motionTokens.scale.pop }} whileTap={{ scale: motionTokens.scale.press }} transition={springs.snappy} /> ```

### Stagger list

```tsx "use client" import { motion } from "motion/react" import { motionTokens, springs } from "@/lib/motion-tokens"

const container = { hidden: {}, visible: { transition: { staggerChildren: 0.08, // within the 0.05–0.10 rule delayChildren: 0.1, }, }, }

const item = { hidden: { opacity: 0, y: motionTokens.distance.md }, visible: { opacity: 1, y: 0, transition: springs.gentle }, }

<motion.ul variants={container} initial="hidden" animate="visible"> {items.map((i) => ( <motion.li key={i.id} variants={item} /> ))} </motion.ul> ```

### Modal

```tsx "use client" import { motion, AnimatePresence } from "motion/react" import { motionTokens, springs } from "@/lib/motion-tokens"

// Wrap at the call site: // <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>

export function Modal({ onClose }: { onClose: () => void }) { return ( <> {/* Overlay */} <motion.div className="fixed inset-0 bg-black/50" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} onClick={onClose} />

{/* Panel — accessibility requirements: focus trap, Escape close, scroll lock, role="dialog", aria-modal="true" */} <motion.div role="dialog" aria-modal="true" className="fixed inset-x-4 top-1/2 -translate-y-1/2 rounded-xl bg-white p-6" initial={{ opacity: 0, scale: motionTokens.scale.press, y: motionTokens.distance.sm, }} animate={{ opacity: 1, scale: 1, y: 0 }} exit={{ opacity: 0, scale: motionTokens.scale.press, y: motionTokens.distance.sm, }} transition={springs.gentle} /> </> ) } ```

### Toast stack

```tsx "use client" import { motion, AnimatePresence } from "motion/react" import { motionTokens, springs } from "@/lib/motion-tokens"

<AnimatePresence mode="sync"> {toasts.map((t) => ( <motion.div key={t.id} layout initial={{ opacity: 0, x: motionTokens.distance.xl, scale: motionTokens.scale.subtle, }} animate={{ opacity: 1, x: 0, scale: 1 }} exit={{ opacity: 0, x: motionTokens.distance.xl, scale: motionTokens.scale.subtle, }} transition={springs.snappy} /> ))} </AnimatePresence> ```

### Page transition (Next.js App Router)

```tsx // components/page-transition.tsx "use client" import { motion, AnimatePresence } from "motion/react" import { usePathname } from "next/navigation" import { motionTokens } from "@/lib/motion-tokens"

const variants = { initial: { opacity: 0, y: motionTokens.distance.sm }, enter: { opacity: 1, y: 0 }, exit: { opacity: 0, y: -motionTokens.distance.sm }, }

export function PageTransition({ children }: { children: React.ReactNode }) { const pathname = usePathname() return ( <AnimatePresence mode="wait"> <motion.div key={pathname} variants={variants} initial="initial" animate="enter" exit="exit" transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth, }} > {children} </motion.div> </AnimatePresence> ) } ```

### Scroll reveal

```tsx "use client" import { motion } from "motion/react" import { motionTokens, springs } from "@/lib/motion-tokens"

<motion.div initial={{ opacity: 0, y: motionTokens.distance.lg }} whileInView={{ opacity: 1, y: 0 }} viewport={{ once: true, margin: "-80px" }} // once: true — rule 7 transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }} /> ```

### Scroll progress bar

```tsx "use client" import { motion, useScroll } from "motion/react"

export function ScrollProgress() { const { scrollYProgress } = useScroll() return ( <motion.div className="fixed top-0 left-0 h-1 bg-indigo-500 origin-left w-full" style={{ scaleX: scrollYProgress }} /> ) } ```

### Expanding card

```tsx "use client" import { useState } from "react" import { motion, AnimatePresence } from "motion/react" import { springs, motionTokens } from "@/lib/motion-tokens"

export function ExpandingCard({ title, body }: { title: string; body: string }) { const [expanded, setExpanded] = useState(false)

return ( <motion.div layout onClick={() => setExpanded(!expanded)} className="cursor-pointer"> {/* layout="position" prevents text reflow from animating */} <motion.h2 layout="position" className="font-semibold"> {title} </motion.h2>

<AnimatePresence> {expanded && ( <motion.p key="body" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} transition={{ duration: motionTokens.duration.fast }} > {body} </motion.p> )} </AnimatePresence> </motion.div> ) } ```

### Shared-element crossfade

```tsx // Source context <motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />

// Destination context (same layoutId — motion handles the transition) <motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" /> ```

### Accordion

```tsx <motion.div initial={false} animate={{ opacity: open ? 1 : 0, scaleY: open ? 1 : 0 }} style={{ transformOrigin: "top", overflow: "hidden" }} transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth, }} > {children} </motion.div> ```

## End-to-End Example

A staggered list that enters on mount, handles conditional presence, and respects reduced motion — combining tokens, springs, AnimatePresence, and the accessibility hook from `motion-foundations`:

```tsx "use client" import { useState } from "react" import { motion, AnimatePresence } from "motion/react" import { motionTokens, springs } from "@/lib/motion-tokens" import { useSafeMotion } from "@/hooks/use-reduced-motion"

const containerVariants = { hidden: {}, visible: { transition: { staggerChildren: 0.08, delayChildren: 0.1 }, }, }

function ListItem({ label, onRemove }: { label: string; onRemove: () => void }) { const safe = useSafeMotion(motionTokens.distance.sm) return ( <motion.li variants={{ hidden: safe.initial, visible: safe.animate, }} exit={safe.exit} transition={springs.gentle} className="flex items-center justify-between p-3 rounded-lg bg-white shadow-sm" > <span>{label}</span> <button onClick={onRemove}>Remove</button> </motion.li> ) }

export function AnimatedList({ items, onRemove }: { items: { id: string; label: string }[] onRemove: (id: string) => void }) { return ( <motion.ul variants={containerVariants} initial="hidden" animate="visible" className="space-y-2" > <AnimatePresence mode="popLayout"> {items.map((item) => ( <ListItem key={item.id} label={item.label} onRemove={() => onRemove(item.id)} /> ))} </AnimatePresence> </motion.ul> ) } ```

## Constraints / Non-Goals

This skill does **not** cover:

- Token and spring definitions → see `motion-foundations` - Drag interactions, swipe gestures, reorderable lists → see `motion-advanced` - Text animations (word/character reveal, counters) → see `motion-advanced` - SVG path drawing or morphing → see `motion-advanced` - Custom animation hooks → see `motion-advanced` - CSS-only transitions not using `motion/react`

## Anti-Patterns

| Anti-pattern | Rule violated | Fix | | -------------------------------------------- | ------- | ------------------------------------------ | | `AnimatePresence` child missing `key` | Rule 1 | Add stable `key` to the direct child | | `initial` + `animate` without `exit` | Rule 2 | Always define all three together | | Page transition without `mode="wait"` | Rule 3 | Add `mode="wait"` to `AnimatePresence` | | `layout` on a 50-item list | Rule 4 | Use `mode="popLayout"` or explicit transforms | | `staggerChildren: 0.2` on a 10-item list | Rule 5 | Cap at `0.08–0.10` | | Modal without focus trap | Rule 6 | Add `focus-trap-react` or Radix Dialog | | `whileInView` without `viewport={{ once: true }}` | Rule 7 | Repeating entrances distract, not inform | | `transition={{ duration: 0.3 }}` inline | Rule 8 | Use `motionTokens.duration.normal` |

## Related Skills

- **`motion-foundations`** — defines all tokens, springs, the `useSafeMotion` hook, and SSR guards that every pattern here imports. Must be set up first. - **`motion-advanced`** — extends these patterns with drag, gestures, SVG, text, custom hooks, and imperative sequencing. Does not redefine any patterns from this skill.

Intended uses

  • Use Motion Patterns when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.