Communitygithub.com

503496348-ops/mischief-production

React / Next.js 的高级动效模式——拖拽、手势、文字动画、SVG 路径绘制、自定义 Hooks、命令式序列(useAnimate)、加载器以及完整的 API 决策树。需要 motion-foundations 作为前置依赖。

mischief-production 是什么?

该技能(skill)为 React 和 Next.js 开发提供了超越基础动效库的复杂、交互式且基于物理的动画模式。它涵盖了广泛的高级用例,例如拖拽关闭的面板、滑动手势、重新排序列表、逐词/逐字符的文字动画、SVG 路径绘制(包括描边动画和图标变形)、圆形进度指示器,以及自定义钩子(如滚动触发器和光标跟随器)。其核心原则强调基于物理的动效(useSpring)比基于持续时间的动效更自然,并指导开发者合理使用 useMotionValue 与 useTransform 进行无重渲染的连续值计算,以及使用 useAnimate 进行可中断的命令式动画序列编排。该技能还包含了构建加载动画(如骨架屏、脉冲点、闪烁效果)的组件,并提供了清晰的决策指南(决策树),帮助开发者在不同场景下选择最合适的 API(例如,拖拽用 drag + dragTransition,滑动检测用 drag + onDragEnd 的 offset 与 velocity 组合判断)。它严格要求所有动效值从 motion-foundations 导入,并强调了对触摸设备的测试、后台标签页暂停无限动画、清理事件监听等最佳实践。

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

在你喜欢的 AI 中提问

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

文档

Motion Advanced

复杂、交互式且基于物理的动画模式。 需要先设置好 motion-foundations。 当 motion-patterns 不够用时,使用这些模式。

何时激活

  • 构建拖拽关闭的面板、滑动手势或可排序列表
  • 逐词、逐字符地动画文字,或实现实时计数器
  • 绘制 SVG 路径、变形图标或动画化圆形进度
  • 编写自定义动画 Hook(useScrollReveal、磁性按钮、光标跟随器)
  • 使用 useAnimate 命令式地编排多步骤动画序列
  • 构建加载微调器、闪烁骨架屏、脉冲指示器或按钮加载状态

输出

该技能产出:

  • 拖拽交互:可拖拽卡片、拖拽关闭面板、Reorder.Group 列表
  • 手势 Hook:滑动检测、长按、捏合轮廓
  • 文字动画组件:单词揭示、打字机效果、数字计数器
  • SVG 动画:路径绘制、图标变形、笔画进度环
  • 自定义 Hook:useScrollReveal、useHoverScale、useNavigationDirection、useInViewOnce
  • 通过 useAnimate 实现的命令式序列,支持可中断的 async/await
  • 加载组件:微调器、闪烁效果、脉冲点、进度条、按钮加载状态

原则

  • 基于物理的动效(useSpring、springs.*)对于直接操纵来说,总是比基于持续时间的更自然。
  • useMotionValue + useTransform 计算派生值,且不会触发重新渲染。
  • useAnimate 序列是命令式且可中断的——在动画进行中调用 animate() 会自动取消之前的动画。
  • 运动值(useMotionValue、useSpring)是 SSR 安全的,不会导致水合错误。

规则

  1. 拖拽交互必须在触屏设备上测试,而不仅仅是鼠标。drag 属性在两者上都有效,但手感和阈值不同。
  2. 当 document.visibilityState === "hidden" 时,无限动画必须暂停。 后台标签页不得消耗 GPU/CPU。
  3. 滑动手势阈值必须明确指定。 永远不要仅仅从速度推断意图;应结合 offset + velocity 检查。
  4. useAnimate 的作用域 ref 必须附着在一个已挂载的 DOM 元素上。 在挂载前调用 animate() 会静默抛出错误。
  5. 运动值不得在渲染时重新创建。 在组件体内使用 useMotionValue(0) 是正确的;在渲染中使用 new MotionValue(0) 则不是。
  6. 所有令牌值都从 motion-foundations 导入。 禁止使用内联数值。
  7. 自定义 Hook 必须处理清理工作。 每个 window.addEventListener 都需要在 useEffect 的返回函数中有对应的 removeEventListener。
  8. SVG 变形需要相同的路径命令数量。 具有不同命令结构的路径会直接跳变,而不是进行插值动画。

决策指南

选择正确的高级 API

场景API
在释放时具有物理效果的拖拽drag + dragTransition: springs.release
有序的拖拽重排列表Reorder.Group + Reorder.Item
通过拖拽偏移量关闭面板drag="y" + 结合 onDragEnd 进行偏移量检查
向左/向右滑动drag="x" + 结合 onDragEnd 进行偏移量检查
长按useLongPress Hook
随时间平滑的值useSpring
从另一个值派生出的值useTransform
多步骤序列useAnimate 配合 async/await
一次性命令式动画来自 motion 的 animate()
逐词进入的文字在 inline-block 跨度上使用交错效果
SVG 绘制pathLength 从 0 到 1
SVG 变形d 属性的补间(命令数量需相同)
圆形进度strokeDashoffset 的补间

何时使用 useSpring 与弹簧过渡

useSpringtransition: springs.*
用于光标跟随器、指针跟踪值离散的状态变化
更新方式连续的,每帧更新由状态变化触发
中断方式平滑——物理引擎从当前速度接管从当前值重新开始

核心概念

useMotionValue + useTransform

无重渲染的响应式计算:

const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
// opacity 随 x 的每帧变化而更新——无需 setState,无需重渲染

useAnimate

返回 [scope, animate]。作用域 ref 必须附着在一个 DOM 元素上。 animate() 调用是可中断的——在动画进行中调用会取消上一次运行。

const [scope, animate] = useAnimate()

async function play() {
  await animate(".step-1", { opacity: 1 }, { duration: 0.3 })
  await animate(".step-2", { x: 0 },       { duration: 0.4 })
        animate(".step-3", { scale: 1 },    { duration: 0.25 })  // 启动后不等待
}

return <div ref={scope}>...</div>

代码示例

可拖拽卡片

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

<motion.div
  drag
  dragConstraints={{ left: -100, right: 100, top: -100, bottom: 100 }}
  dragElastic={0.1}
  whileDrag={{
    scale: motionTokens.scale.pop,
    boxShadow: "0 16px 40px rgba(0,0,0,0.2)",
  }}
  dragTransition={springs.release}
/>

拖拽关闭面板

"use client"
import { motion, useMotionValue, useTransform } from "motion/react"

export function BottomSheet({ onClose }: { onClose: () => void }) {
  const y = useMotionValue(0)
  const opacity = useTransform(y, [0, 200], [1, 0])

  return (
    <motion.div
      drag="y"
      dragConstraints={{ top: 0 }}
      style={{ y, opacity }}
      onDragEnd={(_, info) => {
        // 规则 3:结合 offset + velocity
        if (info.offset.y > 120 || info.velocity.y > 500) onClose()
      }}
    />
  )
}

可排序列表

"use client"
import { Reorder } from "motion/react"

export function SortableList() {
  const [items, setItems] = useState(initialItems)
  return (
    <Reorder.Group axis="y" values={items} onReorder={setItems}>
      {items.map((item) => (
        <Reorder.Item key={item.id} value={item}>
          {item.label}
        </Reorder.Item>
      ))}
    </Reorder.Group>
  )
}

滑动检测

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

const OFFSET_THRESHOLD  = 50
const VELOCITY_THRESHOLD = 300

<motion.div
  drag="x"
  dragConstraints={{ left: 0, right: 0 }}
  onDragEnd={(_, info) => {
    const swipedRight = info.offset.x > OFFSET_THRESHOLD  || info.velocity.x > VELOCITY_THRESHOLD
    const swipedLeft  = info.offset.x < -OFFSET_THRESHOLD || info.velocity.x < -VELOCITY_THRESHOLD
    if (swipedRight) onSwipeRight()
    if (swipedLeft)  onSwipeLeft()
  }}
/>

长按 Hook

import { useRef } from "react"

export function useLongPress(callback: () => void, ms = 600) {
  const timerRef = useRef<ReturnType<typeof setTimeout>>()
  return {
    onPointerDown:  () => { timerRef.current = setTimeout(callback, ms) },
    onPointerUp:    () => clearTimeout(timerRef.current),
    onPointerLeave: () => clearTimeout(timerRef.current),
  }
}

逐词揭示

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

export function AnimatedText({ text }: { text: string }) {
  return (
    <motion.p
      variants={{ visible: { transition: { staggerChildren: 0.05 } } }}
      initial="hidden"
      animate="visible"
    >
      {text.split(" ").map((word, i) => (
        <motion.span
          key={i}
          className="inline-block mr-1"
          variants={{
            hidden:  { opacity: 0, y: 12 },
            visible: { opacity: 1, y: 0, transition: springs.gentle },
          }}
        >
          {word}
        </motion.span>
      ))}
    </motion.p>
  )
}

数字计数器

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

export function Counter({ to }: { to: number }) {
  const nodeRef = useRef<HTMLSpanElement>(null)

  useEffect(() => {
    const controls = animate(0, to, {
      duration: motionTokens.duration.crawl,
      ease: motionTokens.easing.smooth,
      onUpdate: (v) => {
        if (nodeRef.current) nodeRef.current.textContent = Math.round(v).toString()
      },
    })
    return controls.stop   // 规则 7:清理
  }, [to])

  return <span ref={nodeRef} />
}

SVG 路径绘制

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

<motion.path
  d="M 0 100 Q 50 0 100 100"
  initial={{ pathLength: 0, opacity: 0 }}
  animate={{ pathLength: 1, opacity: 1 }}
  transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>

笔画进度环

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

const CIRCUMFERENCE = 2 * Math.PI * 40   // r=40

export function ProgressRing({ progress }: { progress: number }) {
  return (
    <svg width="100" height="100" viewBox="0 0 100 100">
      <circle cx="50" cy="50" r="40" fill="none" stroke="#e5e7eb" strokeWidth="8" />
      <motion.circle
        cx="50" cy="50" r="40"
        fill="none" stroke="#6366f1" strokeWidth="8"
        strokeLinecap="round"
        strokeDasharray={CIRCUMFERENCE}
        animate={{ strokeDashoffset: CIRCUMFERENCE - (progress / 100) * CIRCUMFERENCE }}
        transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
        style={{ rotate: -90, transformOrigin: "center" }}
      />
    </svg>
  )
}

useScrollReveal Hook

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

export function useScrollReveal() {
  const ref = useRef(null)
  const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] })
  const opacity = useTransform(scrollYProgress, [0, 0.3], [0, 1])
  const y       = useTransform(scrollYProgress, [0, 0.3], [motionTokens.distance.lg, 0])
  return { ref, style: { opacity, y } }
}

// 使用方式
const { ref, style } = useScrollReveal()
<motion.section ref={ref} style={style} />

光标跟随器

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

export function CursorFollower() {
  const x = useMotionValue(-100)
  const y = useMotionValue(-100)
  const sx = useSpring(x, springs.gentle)
  const sy = useSpring(y, springs.gentle)

  useEffect(() => {
    const move = (e: MouseEvent) => { x.set(e.clientX); y.set(e.clientY) }
    window.addEventListener("mousemove", move)
    return () => window.removeEventListener("mousemove", move)   // 规则 7
  }, [])

  return (
    <motion.div
      className="fixed top-0 left-0 w-6 h-6 rounded-full bg-indigo-500
                 pointer-events-none -translate-x-1/2 -translate-y-1/2 z-50"
      style={{ x: sx, y: sy }}
    />
  )
}

闪烁骨架屏

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

export function ShimmerSkeleton({ className = "" }: { className?: string }) {
  const controls = useAnimation()

  useEffect(() => {
    const play = () =>
      controls.start({
        x: ["-100%", "100%"],
        transition: {
          repeat: Infinity,
          duration: motionTokens.duration.crawl,
          ease: motionTokens.easing.linear,
        },
      })

    const handleVisibility = () => {
      if (document.visibilityState === "hidden") controls.stop()
      else void play()
    }

    void play()
    document.addEventListener("visibilitychange", handleVisibility)
    return () => {
      controls.stop()
      document.removeEventListener("visibilitychange", handleVisibility)
    }
  }, [controls])

  return (
    <div className={`relative overflow-hidden bg-gray-200 rounded ${className}`}>
      <motion.div
        className="absolute inset-0 bg-gradient-to-r from-transparent via-white/60 to-transparent"
        initial={{ x: "-100%" }}
        animate={controls}
      />
    </div>
  )
}

按钮加载状态

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

export function LoadingButton({
  loading,
  label,
  onClick,
}: {
  loading: boolean
  label: string
  onClick: () => void
}) {
  return (
    <motion.button
      onClick={onClick}
      animate={{ opacity: loading ? 0.7 : 1 }}
      whileTap={loading ? {} : { scale: motionTokens.scale.press }}
      transition={springs.snappy}
      disabled={loading}
    >
      <AnimatePresence mode="wait">
        {loading ? (
          <motion.span
            key="loading"
            initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
            transition={{ duration: motionTokens.duration.fast }}
          >
            …
          </motion.span>
        ) : (
          <motion.span
            key="label"
            initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
            transition={{ duration: motionTokens.duration.fast }}
          >
            {label}
          </motion.span>
        )}
      </AnimatePresence>
    </motion.button>
  )
}

带可见性暂停的无限动画

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

export function PulseDot() {
  const controls = useAnimation()

  useEffect(() => {
    const pulse = () =>
      controls.start({
        scale: [1, 1.4, 1],
        opacity: [1, 0.6, 1],
        transition: { repeat: Infinity, duration: motionTokens.duration.crawl },
      })

    // 规则 2:当标签页隐藏时暂停
    const handleVisibility = () => {
      if (document.visibilityState === "hidden") controls.stop()
      else void pulse()
    }

    void pulse()
    document.addEventListener("visibilitychange", handleVisibility)

    return () => {
      controls.stop()
      document.removeEventListener("visibilitychange", handleVisibility)
    }
  }, [controls])

  return (
    <motion.div
      className="w-3 h-3 rounded-full bg-indigo-500"
      animate={controls}
    />
  )
}

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

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 animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs.

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.

相关技能