Communitygithub.com

erlinerd/erlin-skills

为 Next.js/React 站点引入 motion 动效库、从 framer-motion 迁移导入,并铺设滚动揭示、stagger 网格、页面过渡、导航动效。不负责 SwiftUI、CSS-only 或 Remotion 视频动画。用户提到 Next.js/React 与 motion、framer-motion、滚动揭示、页面过渡或卡片动画时使用。

erlin-skills 是什么?

erlin-skills is a Claude Code agent skill that 为 Next.js/React 站点引入 motion 动效库、从 framer-motion 迁移导入,并铺设滚动揭示、stagger 网格、页面过渡、导航动效。不负责 SwiftUI、CSS-only 或 Remotion 视频动画。用户提到 Next.js/React 与 motion、framer-motion、滚动揭示、页面过渡或卡片动画时使用。.

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/erlinerd/erlin-skills/tree/HEAD/skills/web/erlin-web-motion

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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.

相关技能