Communitygithub.com

Motion Animation Skill for Next.js/React

Introduces the motion animation library to Next.js/React sites, migrates imports from framer-motion, and applies scroll reveals, staggered grids, page transitions, and navigation animations. Does not handle SwiftUI, CSS-only, or Remotion video animations.

What is React?

This skill is designed for Next.js/React developers who want to add sophisticated animations to their sites using the `motion` library (or migrating from `framer-motion`). It provides a structured approach to implement scroll reveals, staggered grids, page transitions, and navigation animations while ensuring content accessibility and visibility are never compromised. The skill covers crucial best practices: detecting the project environment (package manager, Next/React version, router type, server/client components), providing a reference `Reveal` component with a visibility fallback (IntersectionObserver + 2.5s timeout) to prevent animations from hiding content permanently, and applying staggered delays with caps for grids and lists. It also defines animation timing (`ease-out quint` cubic bezier, 0.3-0.8s), respect for `prefers-reduced-motion`, a content-first rule (no entrance animations for LCP elements like H1/hero), and proper server/client component boundaries (client components only for interactive motion elements). The skill includes verification steps (lint + build success) and commit discipline (only add task-related files). It works across App Router (with or without locale prefixing) and Pages Router, and explicitly excludes non-React stacks like SwiftUI, CSS-only, or Remotion.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Objective

Erlin's personal site animation methodology: Introduce the motion library to Next.js/React sites, migrate imports from framer-motion, and apply scroll reveals / staggered grids / page transitions / navigation animations, while never letting animations hide content. Core lesson: whileInView once caused project cards on the homepage to be stuck at opacity:0 ("project cards disappeared"). Therefore, a visibility fallback is required; existing reliable implementations can be kept, Reveal is an optional reference, not a blanket ban on whileInView.

Execution Steps

  1. First determine the project environment (spend 30 seconds confirming before starting to avoid applying the wrong template):

    • Package manager: Identify a single lockfile: pnpm-lock.yaml → pnpm, package-lock.json → npm, yarn.lock → yarn, bun.lock or bun.lockb → bun. Stop and ask the user if multiple lockfiles exist; if no lockfile, read package.json's packageManager field, and stop if still unable to determine—do not guess the package manager. Subsequent install, migration, lint, and build commands must follow the confirmed manager.
    • Next/React version: Check the actual Next/React and animation library versions, peer dependencies, and official compatibility notes. Do not hardcode versions or claim cross-version API compatibility.
    • Router structure (detect before choosing a template, do not default to App Router): If app/ directory exists → App Router, choose a template as per rules below; if only pages/ → Pages Router, no template.tsx mechanism, modify in pages/_app.tsx or the target page component level for transitions and explain the difference to the user; if neither → non-Next project, implement equivalently at the framework's mount point. App Router: For locale-prefixed routes (with app/[locale]/ directory), place the template at app/[locale]/template.tsx; for non-locale routes (e.g., client-side language switching), place it at app/template.tsx, Next.js remounts template on every navigation, so the fade-in works as expected.
    • Whether the component is currently a server component: Isolate interactive motion elements into the smallest possible client component; do not convert entire server-logic components to client.
  2. Use existing dependencies: If framer-motion is already installed and meets requirements, continue using it. Do not default to migration just to add new animations. Only migrate if the user explicitly requests it or if current capabilities/compatibility make it necessary—then check version differences, install motion with the project's package manager, verify motion/react imports and APIs one by one, and remove the old package only after confirming no residual dependencies. Do not modify unrelated comments or documentation.

  3. Apply animations: reference Reveal as needed: Template at assets/reveal.tsx, copy to components/motion/reveal.tsx and adapt path aliases. Design points (adapt per project):

    • Visibility fallback: The template uses IntersectionObserver + 2.5s timeout; 2.5s is just a reference parameter—adjust based on page load behavior. May use verified whileInView or other mechanisms, ensuring content remains accessible if observer, JS, or hydration fails.
    • Handle reduced-motion and observer absence according to SSR/hydration and project lint rules; avoid hydration mismatches and unnecessary synchronous effect updates; do not treat a single lint experience as a ban on all APIs.
    • Render the final state directly for reduced motion.
    • Use pure CSS transition (cubic-bezier(0.22,1,0.36,1)), no motion.div, zero animation runtime overhead.
    • Reveal has a built-in className prop: for cards originally being divs (e.g., glass cards), pass the class directly to Reveal to avoid extra nesting; for semantic elements like article/section, wrap them with Reveal to preserve semantics.
  4. Application positions and stagger formula:

    PositionApproachdelay
    Card grids (multiple blocks on homepage)Wrap each item with RevealMath.min(i * 0.08, 0.4), capped to prevent long grid sluggishness
    Article lists (writing, latest-writing)Wrap each row with Reveali * 0.05~0.07, capped to Math.min(i*0.05, 0.3) to prevent long list sluggishness
    Text column in project image rowsRevealFixed 0.15, staggered from image viewport
    Body/contact cards (about)Large block RevealSecond block 0.1
    Navigation barmotion.header initial y:"-100%" slide-in, scroll hiding reuses the same transform—
    Mobile menuAnimatePresence + opacity/y transition, replaces block/hidden toggling—
    Route transitionsCreate app/template.tsx (non-locale routes) or app/[locale]/template.tsx (locale-prefixed; Next.js remounts template on each navigation) for opacity+y fade-in, 0.35s—
  5. Verify and deliver: Use the package manager confirmed in step 1:

    pnpm lint && pnpm build      # pnpm projects; build must succeed (for fully SSG sites, includes SSG export)
    npm run lint && npm run build  # npm projects
    

    Only commit when the user authorizes, following the project's commit convention, e.g., feat(motion): migrate motion library and add site-wide animations. Only add files related to this task—do not include unrelated uncommitted changes from the repository.

Decision Rules

  • When to use: Adding animations/effects to Next.js sites; migrating framer-motion to the motion package (check current version API before migration); user requests "scroll reveal", "stagger", "page transitions", "more animations".
  • Not responsible for: SwiftUI, CSS-only, or Remotion video animations.
  • Animation design rules (lessons learned):
    • LCP elements (H1, hero) do not get entrance animations: SkewReveal has an instant prop, or the initial state is already the final state, otherwise SSR text will flicker.
    • All animations respect prefers-reduced-motion: use useReducedMotion(), render the final state when reduced / do not register listeners.
    • Unified easing [0.22, 1, 0.36, 1] (easeOutQuint style), duration 0.3–0.8s, prioritize restraint.
    • Hover animations should use CSS transitions only (e.g., hover:-translate-y-1, group-hover:scale-105), no need for motion.
    • When client-side filtering (e.g., tag filtering) changes, list items with unchanged keys do not replay animation—this is expected behavior; newly appearing items trigger automatically.
  • Existing component ownership: SkewReveal entrance, Parallax, Magnetic, MouseParallax can remain as-is; new animations coexist in the same directory; if the project already has a .zcode/.agents animation directory (e.g., components/motion/), place new components there.
  • Server/client boundary: Server components can directly render Reveal (it is a client component, but safe to use as a child component).

Visually inspect animations, accessibility, and content visibility before completion; this skill governs Next.js/React motion implementation techniques; animations for RN/Expo or other stacks should be implemented directly following the same principles, without relying on this skill's scripts.

Output Format

  • Reveal component placement: Copy from assets/reveal.tsx to components/motion/reveal.tsx and adapt path aliases.
  • Route transitions: app/template.tsx (non-locale routes) or app/[locale]/template.tsx (locale-prefixed), opacity+y fade-in 0.35s.
  • Commit message: conventional commits + Chinese description, e.g., feat(motion): migrate motion library and add site-wide animations.

Examples

User Query

"Add scroll reveals to the site, and replace framer-motion with motion."

Tool Response

pnpm

pnpm add motion && pnpm remove framer-motion succeeds, package.json shows a compatible motion version; pnpm lint && pnpm build keeps the fully SSG site building successfully.

sed

sed -i '' 's/from "framer-motion"/from "motion\/react"/g' <files> executed, all imports now point to motion/react; only update migration-related and genuinely outdated comments.

Final Output

components/motion/reveal.tsx (manual IntersectionObserver + 2.5s fuse) + card/list stagger + app/template.tsx route fade-in; lint, build pass; actual verification reported; only commit related files if already authorized.

Gates

  • Content red line: Never let animations hide content—verify SSR, reduced-motion, observer/script failure scenarios ensure content is accessible; Reveal and timeout parameters are reference implementations, do not mechanically ban APIs.
  • Accessibility red line: All animations respect prefers-reduced-motion; LCP elements (H1, hero) do not get entrance animations.
  • Verification: Run lint && build with the confirmed package manager; build must remain successful (for fully SSG projects, SSG export must also not be broken; SSR/ISR projects pass based on build success, do not fabricate SSG requirements).
  • Commit discipline: Only add files related to this task; do not include unrelated uncommitted changes from the repository.
  • Progressive enhancement: Do not modify already working animation components to "unify style"; base decisions on requirements and accessibility evidence.

Related Skills