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
-
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.lockorbun.lockb→ bun. Stop and ask the user if multiple lockfiles exist; if no lockfile, readpackage.json'spackageManagerfield, 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 onlypages/→ Pages Router, notemplate.tsxmechanism, modify inpages/_app.tsxor 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 (withapp/[locale]/directory), place the template atapp/[locale]/template.tsx; for non-locale routes (e.g., client-side language switching), place it atapp/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.
- Package manager: Identify a single lockfile:
-
Use existing dependencies: If
framer-motionis 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, installmotionwith the project's package manager, verifymotion/reactimports and APIs one by one, and remove the old package only after confirming no residual dependencies. Do not modify unrelated comments or documentation. -
Apply animations: reference
Revealas needed: Template atassets/reveal.tsx, copy tocomponents/motion/reveal.tsxand 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
whileInViewor 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)), nomotion.div, zero animation runtime overhead. Revealhas a built-inclassNameprop: for cards originally beingdivs (e.g.,glasscards), pass the class directly toRevealto avoid extra nesting; for semantic elements likearticle/section, wrap them withRevealto preserve semantics.
- 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
-
Application positions and stagger formula:
Position Approach delay Card grids (multiple blocks on homepage) Wrap each item with RevealMath.min(i * 0.08, 0.4), capped to prevent long grid sluggishnessArticle lists (writing, latest-writing) Wrap each row with Reveali * 0.05~0.07, capped toMath.min(i*0.05, 0.3)to prevent long list sluggishnessText column in project image rows RevealFixed 0.15, staggered from image viewportBody/contact cards (about) Large block RevealSecond block 0.1Navigation bar motion.headerinitialy:"-100%"slide-in, scroll hiding reuses the same transform— Mobile menu AnimatePresence+opacity/ytransition, replacesblock/hiddentoggling— Route transitions Create app/template.tsx(non-locale routes) orapp/[locale]/template.tsx(locale-prefixed; Next.js remounts template on each navigation) foropacity+yfade-in, 0.35s— -
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 projectsOnly 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-motionto themotionpackage (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:
SkewRevealhas aninstantprop, or the initial state is already the final state, otherwise SSR text will flicker. - All animations respect
prefers-reduced-motion: useuseReducedMotion(), 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.
- LCP elements (H1, hero) do not get entrance animations:
- 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/.agentsanimation 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
Revealcomponent placement: Copy fromassets/reveal.tsxtocomponents/motion/reveal.tsxand adapt path aliases.- Route transitions:
app/template.tsx(non-locale routes) orapp/[locale]/template.tsx(locale-prefixed),opacity+yfade-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 && buildwith the confirmed package manager;buildmust 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.