Communitygithub.com

Motion 动画模式

为 React / Next.js 提供生产就绪的动画模式,涵盖按钮、模态框、Toast、 交错列表、页面过渡、退出动画、滚动和布局变化,所有模式均基于 motion-foundations 的代币和弹簧。

Motion 动画模式 是什么?

此技能提供了一套可直接复制粘贴的 UI 动画模式,专为 React 和 Next.js 设计,覆盖了按钮反馈、交错列表、模态框、Toast 通知、页面过渡、滚动揭示、展开卡片和共享元素过渡等常见场景。所有模式均强制使用 motion-foundations 定义的代币(如 duration, easing, scale)和弹簧(spring),禁止直接使用数字常量。核心原则包括:条件渲染必须包裹在 AnimatePresence 中并附带 key;必须同时定义 initial、animate 和 exit 动画;基于 layout 的动画仅用于小型、孤立的位移;交错间隔严格限制在 0.05s–0.10s 之间。该技能还详细说明了 AnimatePresence 的契约、 layout 与 layoutId 的区别、以及使用 useScroll + useTransform 实现滚动联动效果的方法。对于可访问性,模态框强制包含焦点捕获、Escape 键关闭、滚动锁定、role="dialog" 和 aria-modal="true"。最终输出是 SSR 安全、无障碍且高度一致的动画组件,直接可集成到 Next.js App Router 项目中。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/503496348-ops/mischief-production/tree/HEAD/skills/ecc-motion-patterns

在你喜欢的 AI 中提问

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

文档

动画模式

可复制粘贴的常见 UI 动画需求模式。 每个模式都基于 motion-foundations 的代币和弹簧构建。 不要在此定义新的持续时间和缓动值——请直接导入它们。

何时激活

  • 为按钮、卡片、模态框或 Toast 通知添加动画
  • 构建列表项的交错进入效果
  • 在 Next.js App Router 中设置页面过渡
  • 为条件渲染内容添加进入或退出动画
  • 实现滚动揭示、滚动联动进度或粘性故事章节
  • 构建展开卡片、手风琴或共享元素过渡

输出

此技能产生:

  • 无障碍的、SSR 安全的常见 UI 组件动画
  • 包裹在 AnimatePresence 中的条件渲染,带有正确的退出行为
  • 适用于 Next.js App Router 的页面过渡包装器组件
  • 使用 useScroll + useTransform 实现的滚动揭示和滚动联动模式
  • 用于展开和淡入淡出元素的布局动画模式(layout, layoutId)

原则

  • 每个模式从 motion-foundations 导入。没有原始数字。
  • 每个条件渲染都包裹在 AnimatePresence 中并带有 key。
  • 退出动画始终与进入动画一起定义——绝不能事后才添加。
  • layout 仅用于小型、孤立的位移。大型子树使用明确的变换。

规则

  1. 始终将条件渲染包裹在带 key 的 AnimatePresence 中,key 放在直接子元素上。没有 key,退出动画永远不会触发。
  2. **在定义 initial + animate 时,始终定义 exit。**没有退出的动画是不完整的。
  3. **在页面过渡中使用 mode="wait"。**进入必须等到退出完成才开始。
  4. **不要在超过约 5 个子元素或深层嵌套 DOM 的子树上使用 layout。**改用明确的 x/y 变换。
  5. **交错间隔必须保持在 0.05s 到 0.10s 之间。**低于此值会显得机械;高于此值会显得迟缓。
  6. 模态框必须始终包含: 焦点捕获、Escape 键关闭、滚动锁定、role="dialog"、aria-modal="true"。
  7. **滚动揭示使用 viewport={{ once: true }}。**在滚动出时重复会分散注意力,而非提供信息。
  8. 所有代币值从 motion-foundations 导入。 没有内联数字。

决策指南

选择合适的模式

情况模式
元素出现/消失AnimatePresence
列表项按顺序加载交错变体
在路由之间导航页面过渡包装器
元素在当前位置改变大小layout 属性
同一元素在不同页面上下文之间移动layoutId
元素在滚动到视口时进入whileInView
值绑定到滚动位置useScroll + useTransform

何时使用 mode="wait" 对比 mode="sync"

模式使用场景
wait页面过渡、内容切换(一次一个)
sync堆叠的通知、列表项(重叠没问题)
popLayout从回流列表中移除的项目

核心概念

AnimatePresence 契约

三个条件必须始终满足:

  1. AnimatePresence 包裹条件渲染
  2. 直接子元素有 key
  3. 子元素有 exit 属性

缺少任何一个,退出动画都会静默失败。

layout 对比 layoutId

  • layout — 动画化元素自身在当前位置的大小/位置变化
  • layoutId — 连接两个独立的元素,在渲染之间淡入淡出

在展开容器内部的文本上使用 layout="position" 以防止文本重排带动画效果。

代码示例

按钮反馈

"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"

<motion.button
  whileHover={{ scale: motionTokens.scale.pop }}
  whileTap={{ scale: motionTokens.scale.press }}
  transition={springs.snappy}
/>

交错列表

"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

const container = {
  hidden: {},
  visible: {
    transition: {
      staggerChildren: 0.08,   // 在 0.05–0.10 规则范围内
      delayChildren: 0.1,
    },
  },
}

const item = {
  hidden:  { opacity: 0, y: motionTokens.distance.md },
  visible: { opacity: 1, y: 0, transition: springs.gentle },
}

<motion.ul variants={container} initial="hidden" animate="visible">
  {items.map((i) => (
    <motion.li key={i.id} variants={item} />
  ))}
</motion.ul>

模态框

"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

// 在调用点包裹:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>

export function Modal({ onClose }: { onClose: () => void }) {
  return (
    <>
      {/* 遮罩层 */}
      <motion.div
        className="fixed inset-0 bg-black/50"
        initial={{ opacity: 0 }}
        animate={{ opacity: 1 }}
        exit={{ opacity: 0 }}
        onClick={onClose}
      />

      {/* 面板 — 可访问性要求:焦点捕获、Escape 关闭、
          滚动锁定、role="dialog"、aria-modal="true" */}
      <motion.div
        role="dialog"
        aria-modal="true"
        className="fixed inset-x-4 top-1/2 -translate-y-1/2 rounded-xl bg-white p-6"
        initial={{
          opacity: 0,
          scale: motionTokens.scale.press,
          y: motionTokens.distance.sm,
        }}
        animate={{ opacity: 1, scale: 1, y: 0 }}
        exit={{
          opacity: 0,
          scale: motionTokens.scale.press,
          y: motionTokens.distance.sm,
        }}
        transition={springs.gentle}
      />
    </>
  )
}

Toast 堆叠

"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

<AnimatePresence mode="sync">
  {toasts.map((t) => (
    <motion.div
      key={t.id}
      layout
      initial={{
        opacity: 0,
        x: motionTokens.distance.xl,
        scale: motionTokens.scale.subtle,
      }}
      animate={{ opacity: 1, x: 0, scale: 1 }}
      exit={{
        opacity: 0,
        x: motionTokens.distance.xl,
        scale: motionTokens.scale.subtle,
      }}
      transition={springs.snappy}
    />
  ))}
</AnimatePresence>

页面过渡(Next.js App Router)

// components/page-transition.tsx
"use client"
import { motion, AnimatePresence } from "motion/react"
import { usePathname } from "next/navigation"
import { motionTokens } from "@/lib/motion-tokens"

const variants = {
  initial: { opacity: 0, y: motionTokens.distance.sm },
  enter:   { opacity: 1, y: 0 },
  exit:    { opacity: 0, y: -motionTokens.distance.sm },
}

export function PageTransition({ children }: { children: React.ReactNode }) {
  const pathname = usePathname()
  return (
    <AnimatePresence mode="wait">
      <motion.div
        key={pathname}
        variants={variants}
        initial="initial"
        animate="enter"
        exit="exit"
        transition={{
          duration: motionTokens.duration.normal,
          ease: motionTokens.easing.smooth,
        }}
      >
        {children}
      </motion.div>
    </AnimatePresence>
  )
}

滚动揭示

"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

<motion.div
  initial={{ opacity: 0, y: motionTokens.distance.lg }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true, margin: "-80px" }}   // once: true — 规则 7
  transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>

滚动进度条

"use client"
import { motion, useScroll } from "motion/react"

export function ScrollProgress() {
  const { scrollYProgress } = useScroll()
  return (
    <motion.div
      className="fixed top-0 left-0 h-1 bg-indigo-500 origin-left w-full"
      style={{ scaleX: scrollYProgress }}
    />
  )
}

展开卡片

"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"

export function ExpandingCard({ title, body }: { title: string; body: string }) {
  const [expanded, setExpanded] = useState(false)

  return (
    <motion.div layout onClick={() => setExpanded(!expanded)} className="cursor-pointer">
      {/* layout="position" 防止文本重排带动画效果 */}
      <motion.h2 layout="position" className="font-semibold">
        {title}
      </motion.h2>

      <AnimatePresence>
        {expanded && (
          <motion.p
            key="body"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            transition={{ duration: motionTokens.duration.fast }}
          >
            {body}
          </motion.p>
        )}
      </AnimatePresence>
    </motion.div>
  )
}

共享元素淡入淡出

// 源上下文
<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />

// 目标上下文(相同的 layoutId — motion 处理过渡)
<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />

手风琴

<motion.div
  initial={false}
  animate={{ opacity: open ? 1 : 0, scaleY: open ? 1 : 0 }}
  style={{ transformOrigin: "top", overflow: "hidden" }}
  transition={{
    duration: motionTokens.duration.normal,
    ease: motionTokens.easing.smooth,
  }}
> {children}
</motion.div>

端到端示例

一个在挂载时进入、处理条件存在性并尊重缩减动画的交错列表——结合了代币、弹簧、AnimatePresence 以及来自 motion-foundations 的可访问性钩子:

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

const containerVariants = {
  hidden: {},
  visible: {
    transition: { staggerChildren: 0.08, delayChildren: 0.1 },
  },
}

function ListItem({ label, onRemove }: { label: string; onRemove: () => void }) {
  const safe = useSafeMotion(motionTokens.distance.sm)
  return (
    <motion.li
      variants={{
        hidden:  safe.initial,
        visible: safe.animate,
      }}
      exit={safe.exit}
      transition={springs.gentle}
      className="flex items-center justify-between p-3 rounded-lg bg-white shadow-sm"
    >
      <span>{label}</span>
      <button onClick={onRemove}>移除</button>
    </motion.li>
  )
}

export function AnimatedList({ items, onRemove }: {
  items: { id: string; label: string }[]
  onRemove: (id: string) => void
}) {
  return (
    <motion.ul
      variants={containerVariants}
      initial="hidden"
      animate="visible"
      className="space-y-2"
    >
      <AnimatePresence mode="popLayout">
        {items.map((item) => (
          <ListItem
            key={item.id}
            label={item.label}
            onRemove={() => onRemove(item.id)}
          />
        ))}
      </AnimatePresence>
    </motion.ul>
  )
}

约束 / 非目标

此技能不涵盖:

  • 代币和弹簧定义 → 参见 motion-foundations
  • 拖拽交互、滑动手势、可重新排序列表 → 参见 motion-advanced
  • 文本动画(文字/字符揭示、计数器) → 参见 motion-advanced
  • SVG 路径绘制或变形 → 参见 motion-advanced
  • 自定义动画钩子 → 参见 motion-advanced
  • 不使用 motion/react 的纯 CSS 过渡

反模式

反模式违反的规则修复方法
AnimatePresence 子元素缺少 key规则 1在直接子元素上添加稳定的 key
有 initial + animate 但没有 exit规则 2始终同时定义三者
页面过渡没有 mode="wait"规则 3在 AnimatePresence 上添加 mode="wait"
在包含 50 个项目的列表上使用 layout规则 4使用 mode="popLayout" 或显式变换
在包含 10 个项目的列表上使用 staggerChildren: 0.2规则 5限制在 0.08–0.10
模态框没有焦点捕获规则 6添加 focus-trap-react 或 Radix Dialog
whileInView 没有 viewport={{ once: true }}规则 7重复进入会分散注意力,而非提供信息
内联 transition={{ duration: 0.3 }}规则 8使用 motionTokens.duration.normal

相关技能

  • motion-foundations — 定义了此模式中所有导入的代币、弹簧、useSafeMotion 钩子和 SSR 守卫。必须首先设置。
  • motion-advanced — 使用拖拽、手势、SVG、文本、自定义钩子和命令式序列扩展这些模式。不重新定义此技能中的任何模式。

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

503496348-ops/mischief-production

Use this skill when inspecting Blender characters, rigs, poses, animation retargeting, ground contact, facing direction, or model-vs-motion alignment where screenshots alone are not enough.

503496348-ops/mischief-production

Build reusable Manim explainers for technical concepts, graphs, system diagrams, and product walkthroughs, then hand off to the wider HCP video stack if needed. Use when the user wants a clean animated explainer rather than a generic talking-head script.

503496348-ops/mischief-production

Advanced motion patterns for React / Next.js — drag & drop, gestures, text animations, SVG path drawing, custom hooks, imperative sequences (useAnimate), loaders, and the full API decision tree. Requires motion-foundations.

503496348-ops/mischief-production

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.

503496348-ops/mischief-production

Production-ready UI motion system for React/Next.js. Use when implementing animations, transitions, or motion patterns.

503496348-ops/mischief-production

Best practices for Remotion - Video creation in React. 29 domain-specific rules covering 3D, animations, audio, captions, charts, transitions, and more.

503496348-ops/mischief-production

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

相关技能