Motion — animation for React / Next.js

0. Before anything

• Resolve the project root with ${CLAUDE_PLUGIN_ROOT}/scripts/profile.sh root and use it (absolute paths) for .hyperui/ and for every repo read/write. If <root>/.hyperui/profile.md is missing, invoke the hyperui skill first (it onboards and routes); otherwise read profile.md and state.md and never re-ask what they hold. With several roots (profile.sh roots), work in the repo the request or the touched file belongs to, with that repo's .hyperui/ (rules: ${CLAUDE_PLUGIN_ROOT}/references/workspace.md). Profile fields used: archetype, conversation_language, design.*, tone_notes; also .hyperui/design.md.
• design.motion sets the register: restrained → only the hero sequence and micro-feedback; expressive → add scroll reveals and shared-element transitions. Unset → restrained. prefers-reduced-motion is honored by default (recipe H) — never ask whether to.
• Use the durations and easings already in the tokens (--dur-*, --ease-*) before the defaults below.
• Reply in the conversation language; keep internal reasoning, code and files in English.
• Tone per archetype: non-tech → one or two plain sentences per step; dev → the fact + one line of why; senior → the fact.

Use the Motion AI Kit when present. If the official /motion skill exists (<root>/.claude/skills/motion or ~/.claude/skills/motion) or the motion MCP is connected, use it for docs and example search, CSS springs and MotionScore audits (springs and audits need Motion+). This skill stays the taste and choreography layer: the language, recipes and QA below decide what moves and why. If neither is present, say once that /hyperui:setup installs it.

1. Install and import

npm install motion

"use client"; // required in Next.js App Router for any file that uses motion components/hooks
import { motion, AnimatePresence, MotionConfig, useReducedMotion, useScroll, useTransform, useInView } from "motion/react";

• motion/react is the current import path. The legacy framer-motion package still works and exposes the same API; prefer motion/react in new code and do not mix both in one project.
• Vanilla / non-React code: import { animate, scroll, inView, stagger } from "motion".
• stagger() from "motion" is the standalone helper; inside React variants use transition: { staggerChildren } (see recipe A).
• Before using an API not listed here, check https://motion.dev/docs with WebFetch (or the Motion MCP). Do not guess prop names.

2. Motion language

• Durations: 150–250 ms for micro-feedback (hover, press, toggle), 300–500 ms for entrances, ≤ 800 ms for a hero sequence. Nothing a user waits for takes longer than 500 ms.
• Easing: ease-out ([0.16, 1, 0.3, 1]) for things entering, ease-in-out for things moving between places, springs for things the user touches (stiffness 300–500, damping 25–35).
• Properties: animate transform (x, y, scale, rotate) and opacity only; clip-path and filter sparingly. Never animate width/height/top/left directly — use the layout prop.
• Distances: entrances travel 8–24 px. Scale from 0.96–0.98, never from 0.
• Stagger: 40–80 ms between siblings; cap the visible staggered set at ~8 items.
• One choreography per view. The hero gets a sequence; everything below gets at most a quiet reveal. If everything moves, nothing does.
• Reason, in priority order: orientation (where did this come from) → feedback (did my action register) → continuity (same object, new place) → delight. No reason, no animation.
• Reduced motion is not optional: useReducedMotion() → drop transforms, keep opacity fades, shorten durations. Wire it once at the root with MotionConfig (recipe H).

3. Recipes

A. Variants + stagger for a hero or list

const list = { hidden: {}, show: { transition: { staggerChildren: 0.06, delayChildren: 0.1 } } };
const item = { hidden: { opacity: 0, y: 16 }, show: { opacity: 1, y: 0, transition: { duration: 0.4, ease: [0.16, 1, 0.3, 1] } } };

<motion.ul variants={list} initial="hidden" animate="show">
  {items.map((it) => <motion.li key={it.id} variants={item}>{it.label}</motion.li>)}
</motion.ul>

B. Button with spring feedback

<motion.button
  whileHover={{ scale: 1.02, y: -1 }}
  whileTap={{ scale: 0.97 }}
  transition={{ type: "spring", stiffness: 400, damping: 28 }}
>
  Download
</motion.button>

C. AnimatePresence for swapped content (modal, step, tab panel)

<AnimatePresence mode="wait" initial={false}>
  <motion.div
    key={step}                      // a stable, unique key per state is mandatory
    initial={{ opacity: 0, y: 8 }}
    animate={{ opacity: 1, y: 0 }}
    exit={{ opacity: 0, y: -8 }}
    transition={{ duration: 0.2 }}
  >
    {content[step]}
  </motion.div>
</AnimatePresence>

D. Shared-element tab indicator

{tabs.map((t) => (
  <button key={t} onClick={() => setActive(t)} style={{ position: "relative" }}>
    {t}
    {active === t && (
      <motion.span layoutId="tab-indicator" style={{ position: "absolute", inset: "auto 0 0 0", height: 2, background: "var(--accent)" }}
        transition={{ type: "spring", stiffness: 500, damping: 35 }} />
    )}
  </button>
))}

E. Scroll reveal (once, slightly before fully in view)

<motion.section
  initial={{ opacity: 0, y: 24 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-10%" }}
  transition={{ duration: 0.5, ease: [0.16, 1, 0.3, 1] }}
/>

F. Scroll-linked progress bar and parallax

const { scrollYProgress } = useScroll();                       // page progress 0..1
<motion.div style={{ scaleX: scrollYProgress, transformOrigin: "0 0", height: 2, background: "var(--accent)", position: "fixed", top: 0, left: 0, right: 0 }} />

const ref = useRef(null);
const { scrollYProgress: p } = useScroll({ target: ref, offset: ["start end", "end start"] });
const y = useTransform(p, [0, 1], [-40, 40]);                  // parallax drift in px
<motion.img ref={ref} style={{ y }} src="/hero.png" alt="" />

G. Reduced-motion-safe variants

export function useMotionSafe() {
  const reduce = useReducedMotion();
  const item = reduce
    ? { hidden: { opacity: 0 }, show: { opacity: 1, transition: { duration: 0.2 } } }
    : { hidden: { opacity: 0, y: 16 }, show: { opacity: 1, y: 0, transition: { duration: 0.4, ease: [0.16, 1, 0.3, 1] } } };
  const list = { hidden: {}, show: { transition: { staggerChildren: reduce ? 0 : 0.06 } } };
  return { item, list, reduce };
}

H. Root config (do this once, in the app layout's client provider)

<MotionConfig reducedMotion="user" transition={{ duration: 0.25, ease: [0.16, 1, 0.3, 1] }}>
  {children}
</MotionConfig>

reducedMotion="user" makes Motion skip transform/layout animations automatically when the OS setting is on; recipe G is for cases where you want explicit control of the fallback.

4. Performance and pitfalls

• Let Motion manage will-change; do not sprinkle it in CSS — it costs memory on every element.
• Do not animate hundreds of nodes individually; animate the container, or virtualize and only animate what is visible (whileInView).
• Hydration flicker on mount: pass initial={false} to AnimatePresence or to the component so the first paint is the final state.
• SSR: motion.* components render their static markup on the server; the initial state is applied as inline style, so a hidden initial means the element is invisible until JS runs. Use it only on elements that are fine being hidden briefly, never on the main heading/CTA without a short duration.
• AnimatePresence needs stable, unique keys on direct children; without them exit animations never run.
• layout animations inside scroll containers: mark the scroller with layoutScroll; for independent layout groups use LayoutGroup (verify on motion.dev).
• Images and video inside layout elements distort during the transition; put layout on a wrapper and keep the media layout="position".
• Test with CPU throttling 4× and on a real phone; if anything drops frames, remove the animation rather than tuning it for an hour.

5. QA checklist

1. OS "Reduce motion" on → no transforms, only short fades; nothing becomes unreachable.
2. Every interactive element gives feedback within 150 ms on hover and tap.
3. No animation blocks reading or clicking; no entrance runs longer than 500 ms except the hero.
4. 60 fps at 4× CPU throttle on the heaviest page; no layout thrash in the Performance panel.
5. AnimatePresence exits actually play (keys are stable), and nothing flickers on first paint.
6. Seen in a browser, with evidence (${CLAUDE_PLUGIN_ROOT}/skills/design/references/browser-verify.md): capture the choreography (a short GIF with Claude in Chrome when available) AND the reduced-motion path at 360 and 1280, recorded under ## Browser evidence in design.md; no browser tool → say so, never "feels smooth".

6. Close the turn

When a choreography is settled (what moves, durations, easings), write it to .hyperui/design.md (motion section), the next step to state.md, and one ADR-lite line to decisions.md (date · decision · why · source).

Sources

Cite only URLs that are listed in a skill/reference or that you opened this session; never construct or guess a URL.

Verify API names before use. Canonical references: references/sources.md. Motion AI Kit (skill + MCP, free vs Motion+): https://motion.dev/docs/ai-kit · install: https://motion.dev/docs/ai-kit-install