Skip to main content
Agent skill

Motion Foundations

Motion tokens, spring presets, performance rules, device adaptation, accessibility enforcement, and SSR safety for React / Next.js using motion/react. Foundation layer — all other motion skills depend on this. Use when setting up motion tokens, spring presets, reduced-motion handling, or SSR-safe animation in React or Next.js.

Get started

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

When to use this skill

Use Motion Foundations when an AI agent needs a reusable SKILL.md workflow for this job: Motion tokens, spring presets, performance rules, device adaptation, accessibility enforcement, and SSR safety for React / Next.js using motion/react. Foundation layer — all other motion skills depend on this. Use when setting up motion tokens, spring presets, reduced-motion handling, or SSR-safe animation in React or Next.js.

When not to use it

Skip Motion Foundations when the task is outside the coding 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-foundations
# Save SKILL.md to ~/.claude/skills/motion-foundations/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/motion-foundations/SKILL.md. For a shared project, commit the folder at .claude/skills/motion-foundations/ 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 Foundations skill for this task: Use Motion Foundations 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 Foundations

The base layer of the motion system. Defines every value, constraint, and rule that downstream skills (`motion-patterns`, `motion-advanced`) inherit. Load this skill before any animation work begins.

## When to Activate

- Starting any animated component from scratch - Setting up tokens, spring presets, or easing values - Implementing `prefers-reduced-motion` support - Debugging hydration mismatches from animation initial states - Evaluating whether an animation should exist at all

## Outputs

This skill produces:

- A shared `motionTokens` object (duration, easing, distance, scale) - A shared `springs` preset map (5 named configs) - A `shouldAnimate()` gate used by all components - Accessibility-compliant animation defaults via `useReducedMotion` - SSR-safe initial states with zero hydration warnings

## Principles

Motion must do at least one of the following or it must be removed:

- Guide attention - Communicate state - Preserve spatial continuity

Responsiveness always outranks smoothness. A 60 fps animation that causes input delay is worse than no animation.

## Rules

These are non-negotiable. They apply to every component in the system.

1. **Use `motion/react` only.** Never import from `framer-motion`. Never mix the two in the same tree. 2. **`initial` must match server output.** If the server renders `opacity: 1`, the `initial` prop must also be `opacity: 1`. No exceptions. 3. **Reduced motion overrides everything.** When `useReducedMotion()` returns `true` or `prefersReduced` is `true`, all transforms are disabled. Opacity-only fades at ≤ 0.2s are the only permitted fallback. 4. **Never animate layout properties.** `width`, `height`, `top`, `left`, `margin`, `padding` are banned from `animate`. Use `transform` and `opacity` only. 5. **All token values come from `motionTokens`.** Hardcoded durations and easings in component files are forbidden. 6. **All spring configs come from the `springs` map.** Inline `stiffness`/`damping` values are forbidden. 7. **`"use client"` is required** on every file that imports from `motion/react`. 8. **Never read `window` or `navigator` at module level.** Always guard with `typeof window !== "undefined"`.

## Decision Guidance

### Choosing a duration

| Token | Use when | | --------- | -------------------------------------------- | | `instant` | Tooltip show/hide, focus ring, badge update | | `fast` | Button feedback, icon swap, chip toggle | | `normal` | Modal open, card expand, page element enter | | `slow` | Hero entrance, full-page transition | | `crawl` | Deliberate storytelling; use sparingly |

### Choosing a spring

| Preset | Use when | | --------- | ------------------------------------------ | | `snappy` | Default UI — buttons, chips, nav items | | `gentle` | Cards, modals, panels landing softly | | `bouncy` | Playful moments — empty states, onboarding | | `instant` | Tooltips, popovers, dropdowns | | `release` | Drag release — natural physics feel |

### When to disable animation entirely

Disable (make `shouldAnimate()` return `false`) when:

- `prefersReduced` is `true` - `isLowEnd` is `true` and the animation is non-essential - The element is off-screen and will never enter the viewport - The animation is purely decorative with no UX purpose

## Core Concepts

### Token system

```ts // lib/motion-tokens.ts export const motionTokens = { duration: { instant: 0.08, fast: 0.18, normal: 0.35, slow: 0.6, crawl: 1.0, }, easing: { smooth: [0.22, 1, 0.36, 1], sharp: [0.4, 0, 0.2, 1], bounce: [0.34, 1.56, 0.64, 1], linear: [0, 0, 1, 1], }, distance: { xs: 4, sm: 8, md: 16, lg: 24, xl: 48, }, scale: { subtle: 0.98, press: 0.95, pop: 1.04, }, }

export const springs = { snappy: { type: "spring", stiffness: 300, damping: 30 }, gentle: { type: "spring", stiffness: 120, damping: 14 }, bouncy: { type: "spring", stiffness: 400, damping: 10 }, instant: { type: "spring", stiffness: 600, damping: 35 }, release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 }, } ```

### Runtime flags

```ts // lib/motion-config.ts export const motionConfig = { isLowEnd() { return ( typeof navigator !== "undefined" && navigator.hardwareConcurrency <= 4 ) },

prefersReduced() { return ( typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches ) },

shouldAnimate({ essential = false } = {}) { if (this.prefersReduced()) return false if (!essential && this.isLowEnd()) return false return true },

duration() { return this.isLowEnd() || this.prefersReduced() ? motionTokens.duration.instant : motionTokens.duration.normal }, } ```

### Accessibility

**Priority order (highest to lowest):**

1. `prefers-reduced-motion: reduce` — disables all transforms, limits opacity transitions to ≤ 0.2s 2. Low-end device detection — reduces duration, removes non-essential animations 3. Design preference — everything else

Motion must degrade gracefully. It must never disappear abruptly in a way that causes layout shift or confuses orientation.

```tsx // hooks/use-reduced-motion.tsx "use client" import { useReducedMotion } from "motion/react"

export function useSafeMotion(fullY: number = 16) { const reduce = useReducedMotion() return { initial: { opacity: 0, y: reduce ? 0 : fullY }, animate: { opacity: 1, y: 0 }, exit: { opacity: 0, y: reduce ? 0 : -fullY }, } } ```

```css /* globals.css */ @media (prefers-reduced-motion: reduce) { .motion-safe-transition { transition: opacity 0.15s; } .motion-reduce-transform { transform: none !important; } } ```

```html <!-- Tailwind --> <div class="motion-safe:animate-fade motion-reduce:opacity-100"></div> ```

### SSR / hydration safety

**Rule: `initial` must always match what the server renders.**

```tsx // WRONG — server renders opacity:1 but initial says 0 → hydration mismatch <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />

// CORRECT — use AnimatePresence or defer to client mount "use client" const [mounted, setMounted] = useState(false) useEffect(() => setMounted(true), [])

<motion.div initial={{ opacity: mounted ? 0 : 1 }} animate={{ opacity: 1 }} /> ```

## Code Examples

### End-to-end: tokens + springs + accessibility + SSR guard

```tsx // components/fade-in-card.tsx "use client"

import { useState, useEffect } from "react" import { motion } from "motion/react" import { motionTokens, springs } from "@/lib/motion-tokens" import { useSafeMotion } from "@/hooks/use-reduced-motion" import { motionConfig } from "@/lib/motion-config"

interface FadeInCardProps { children: React.ReactNode delay?: number }

export function FadeInCard({ children, delay = 0 }: FadeInCardProps) { // SSR guard — initial must match server output (opacity: 1) const [mounted, setMounted] = useState(false) useEffect(() => setMounted(true), [])

// Accessibility — disables transform when reduced motion is preferred const safeMotion = useSafeMotion(motionTokens.distance.md)

// Device gate — skip animation on low-end hardware if (!motionConfig.shouldAnimate() || !mounted) { return <div>{children}</div> }

return ( <motion.div initial={safeMotion.initial} animate={safeMotion.animate} exit={safeMotion.exit} transition={{ ...springs.gentle, delay, }} whileHover={{ scale: motionTokens.scale.pop }} whileTap={{ scale: motionTokens.scale.press }} > {children} </motion.div> ) } ```

## Constraints / Non-Goals

This skill does **not** cover:

- UI component patterns (button, modal, stagger) → see `motion-patterns` - Drag, gestures, SVG, text animations, custom hooks → see `motion-advanced` - CSS-only animations or Tailwind `animate-*` classes without `motion/react` - Third-party animation libraries (GSAP, anime.js, etc.) - Motion design decisions (when to animate, what to emphasize) — that is a design concern, not a code constraint

## Anti-Patterns

| Anti-pattern | Rule violated | Fix | | --------------------------------------- | ------- | ------------------------------- | | `import { motion } from "framer-motion"` | Rule 1 | Use `motion/react` | | `initial={{ opacity: 0 }}` on SSR component | Rule 2 | Add mount guard | | Skipping `useReducedMotion` check | Rule 3 | Use `useSafeMotion` hook | | `animate={{ width: "100%" }}` | Rule 4 | Use `scaleX` transform instead | | `transition={{ duration: 0.4 }}` inline | Rule 5 | Use `motionTokens.duration.normal` | | `{ stiffness: 300, damping: 30 }` inline | Rule 6 | Use `springs.snappy` | | Missing `"use client"` directive | Rule 7 | Add to top of file | | `navigator.hardwareConcurrency` at module level | Rule 8 | Wrap in `typeof navigator !== "undefined"` |

## Related Skills

- **`motion-patterns`** — consumes tokens and springs defined here to build button, modal, stagger, page transition, and scroll patterns. Does not redefine any values. - **`motion-advanced`** — consumes tokens and springs defined here for drag, SVG, text, and gesture patterns. Adds `useAnimate` sequences and custom hooks on top of this foundation.

Intended uses

  • Use Motion Foundations 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.