Communitygithub.com

503496348-ops/mischief-production

Motion tokens(动画令牌)、弹簧预设、性能规则、设备适配、无障碍强制和SSR安全,专为使用 motion/react 的 React / Next.js 设计。作为基础层——所有其他运动技能都依赖于此。

mischief-production 是什么?

该技能是运动系统的基础层,定义了所有下游技能(如 `motion-patterns` 和 `motion-advanced`)所继承的每个数值、约束和规则。它提供了一套完整的动画基础设施,包括共享的 `motionTokens` 对象(涵盖时长、缓动、距离和缩放)、五个命名的弹簧预设 (`springs`)、一个用于控制动画是否执行的 `shouldAnimate()` 门控函数,以及通过 `useReducedMotion` 实现的无障碍兼容动画默认值。核心原则是动画必须具有功能性(引导注意力、传达状态或保持空间连续性),且在性能与流畅度冲突时,响应性优先于流畅度。该技能专为 `motion/react` 设计(严禁使用 `framer-motion`),并严格确保 SSR 安全——要求 `initial` 属性必须与服务器渲染输出完全一致,以避免水合错误。通过设备性能检测(如 `navigator.hardwareConcurrency`)和 `prefers-reduced-motion` 媒体查询,它会自动降级或禁用非必要动画。反模式包括硬编码时长/弹簧值、使用布局动画属性(如 `width`、`height`)以及在模块级别读取 `window` 或 `navigator`。该技能不涵盖UI组件模式、拖拽、手势或第三方动画库,这些由 `motion-patterns` 和 `motion-advanced` 技能处理。

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

在你喜欢的 AI 中提问

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

文档

运动基础(Motion Foundations)

运动系统的基础层。定义了所有下游技能(motion-patterns、motion-advanced)继承的每个数值、约束和规则。在开始任何动画工作之前,请先加载此技能。

何时激活

  • 从头开始创建任何动画组件时
  • 设置令牌(tokens)、弹簧预设(spring presets)或缓动值(easing values)时
  • 实现 prefers-reduced-motion 支持时
  • 调试由动画初始状态引起的水合不匹配时
  • 评估某个动画是否应该存在时

产出物

本技能产出:

  • 一个共享的 motionTokens 对象(时长、缓动、距离、缩放)
  • 一个共享的 springs 预设映射(5个命名配置)
  • 一个供所有组件使用的 shouldAnimate() 门控函数
  • 通过 useReducedMotion 实现的无障碍兼容动画默认值
  • 零水合警告的 SSR 安全初始状态

原则

运动必须至少满足以下条件之一,否则必须移除:

  • 引导注意力
  • 传达状态
  • 保持空间连续性

响应性始终优先于流畅度。一个导致输入延迟的60fps动画比没有动画更差。

规则

这些规则不可协商,适用于系统中的每个组件。

  1. 仅使用 motion/react。 永远不要从 framer-motion 导入。不要在同一个组件树中混用两者。
  2. initial 必须匹配服务器输出。 如果服务器渲染 opacity: 1,那么 initial 属性也必须是 opacity: 1。没有例外。
  3. 减少运动(Reduced motion)覆盖一切。 当 useReducedMotion() 返回 true 或 prefersReduced 为 true 时,所有变换都被禁用。仅允许持续时间 ≤ 0.2s 的不透明度淡入淡出作为回退方案。
  4. 永远不要动画化布局属性。 width、height、top、left、margin、padding 禁止出现在 animate 中。仅使用 transform 和 opacity。
  5. 所有令牌值来自 motionTokens。 组件文件中禁止硬编码时长和缓动。
  6. 所有弹簧配置来自 springs 映射。 禁止内联 stiffness/damping 值。
  7. 每个从 motion/react 导入的文件必须使用 "use client" 指令。
  8. 永远不要在模块级别读取 window 或 navigator。 始终使用 typeof window !== "undefined" 进行守卫。

决策指南

选择时长

令牌用途
instant工具提示显示/隐藏、焦点环、徽章更新
fast按钮反馈、图标切换、标签切换
normal模态框打开、卡片展开、页面元素进入
slow英雄区域进入、全页过渡
crawl有意的叙事性动画;谨慎使用

选择弹簧预设

预设用途
snappy默认UI — 按钮、标签、导航项
gentle卡片、模态框、面板轻柔落下
bouncy趣味时刻 — 空状态、新手引导
instant工具提示、弹出框、下拉菜单
release拖拽释放 — 自然的物理感受

何时完全禁用动画

在以下情况下禁用(使 shouldAnimate() 返回 false):

  • prefersReduced 为 true
  • isLowEnd 为 true 且动画非必要
  • 元素在屏幕外且永远不会进入视口
  • 动画纯属装饰,无用户体验目的

核心概念

令牌系统

// lib/motion-tokens.ts
export const motionTokens = {
  duration: {
    instant: 0.08,
    fast:    0.18,
    normal:  0.35,
    slow:    0.6,
    crawl:   1.0,
  },
  easing: {
    smooth: [0.22, 1, 0.36, 1],
    sharp:  [0.4, 0, 0.2, 1],
    bounce: [0.34, 1.56, 0.64, 1],
    linear: [0, 0, 1, 1],
  },
  distance: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 48,
  },
  scale: {
    subtle: 0.98,
    press:  0.95,
    pop:    1.04,
  },
}

export const springs = {
  snappy:  { type: "spring", stiffness: 300, damping: 30 },
  gentle:  { type: "spring", stiffness: 120, damping: 14 },
  bouncy:  { type: "spring", stiffness: 400, damping: 10 },
  instant: { type: "spring", stiffness: 600, damping: 35 },
  release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },
}

运行时标志

// lib/motion-config.ts
export const motionConfig = {
  isLowEnd() {
    return (
      typeof navigator !== "undefined" &&
      navigator.hardwareConcurrency <= 4
    )
  },

  prefersReduced() {
    return (
      typeof window !== "undefined" &&
      window.matchMedia("(prefers-reduced-motion: reduce)").matches
    )
  },

  shouldAnimate({ essential = false } = {}) {
    if (this.prefersReduced()) return false
    if (!essential && this.isLowEnd()) return false
    return true
  },

  duration() {
    return this.isLowEnd() || this.prefersReduced()
      ? motionTokens.duration.instant
      : motionTokens.duration.normal
  },
}

无障碍支持

优先级顺序(从高到低):

  1. prefers-reduced-motion: reduce — 禁用所有变换,将不透明度过渡限制在 ≤ 0.2s
  2. 低端设备检测 — 减少时长,移除非必要动画
  3. 设计偏好 — 其他所有情况

运动必须优雅降级。它绝不能突然消失,导致布局偏移或方向混乱。

// hooks/use-reduced-motion.tsx
"use client"
import { useReducedMotion } from "motion/react"

export function useSafeMotion(fullY: number = 16) {
  const reduce = useReducedMotion()
  return {
    initial: { opacity: 0, y: reduce ? 0 : fullY },
    animate: { opacity: 1, y: 0 },
    exit:    { opacity: 0, y: reduce ? 0 : -fullY },
  }
}
/* globals.css */
@media (prefers-reduced-motion: reduce) {
  .motion-safe-transition  { transition: opacity 0.15s; }
  .motion-reduce-transform { transform: none !important; }
}
<!-- Tailwind -->
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>

SSR / 水合安全性

规则:initial 必须始终与服务器渲染的内容匹配。

// 错误 — 服务器渲染 opacity:1 但 initial 为 0 → 水合不匹配
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />

// 正确 — 使用 AnimatePresence 或延迟到客户端挂载
"use client"
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])

<motion.div
  initial={{ opacity: mounted ? 0 : 1 }}
  animate={{ opacity: 1 }}
/>

代码示例

端到端:令牌 + 弹簧 + 无障碍 + SSR 守卫

// components/fade-in-card.tsx
"use client"

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

interface FadeInCardProps {
  children: React.ReactNode
  delay?: number
}

export function FadeInCard({ children, delay = 0 }: FadeInCardProps) {
  // SSR 守卫 — initial 必须匹配服务器输出(opacity: 1)
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])

  // 无障碍支持 — 当偏好减少运动时禁用变换
  const safeMotion = useSafeMotion(motionTokens.distance.md)

  // 设备门控 — 在低端硬件上跳过动画
  if (!motionConfig.shouldAnimate() || !mounted) {
    return <div>{children}</div>
  }

  return (
    <motion.div
      initial={safeMotion.initial}
      animate={safeMotion.animate}
      exit={safeMotion.exit}
      transition={{
        ...springs.gentle,
        delay,
      }}
      whileHover={{ scale: motionTokens.scale.pop }}
      whileTap={{ scale: motionTokens.scale.press }}
    >
      {children}
    </motion.div>
  )
}

约束 / 非目标

本技能不涵盖:

  • UI 组件模式(按钮、模态框、交错动画)→ 请参见 motion-patterns
  • 拖拽、手势、SVG、文本动画、自定义 Hook → 请参见 motion-advanced
  • 纯 CSS 动画或未使用 motion/react 的 Tailwind animate-* 类
  • 第三方动画库(GSAP、anime.js 等)
  • 动效设计决策(何时动画、强调什么)—— 这是设计问题,不是代码约束

反模式

反模式违反的规则修复方法
import { motion } from "framer-motion"规则 1使用 motion/react
initial={{ opacity: 0 }} 在 SSR 组件中规则 2添加挂载守卫
跳过 useReducedMotion 检查规则 3使用 useSafeMotion Hook
animate={{ width: "100%" }}规则 4改用 scaleX 变换
内联 transition={{ duration: 0.4 }}规则 5使用 motionTokens.duration.normal
内联 { stiffness: 300, damping: 30 }规则 6使用 springs.snappy
缺少 "use client" 指令规则 7添加到文件顶部
navigator.hardwareConcurrency 在模块级别规则 8包裹在 typeof navigator !== "undefined" 中

相关技能

  • motion-patterns — 消费此处定义的令牌和弹簧,构建按钮、模态框、交错动画、页面过渡和滚动模式。不重新定义任何值。
  • motion-advanced — 消费此处定义的令牌和弹簧,用于拖拽、SVG、文本和手势模式。在此基础之上添加 useAnimate 序列和自定义 Hook。

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

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.

相关技能