Communitygithub.com

503496348-ops/mischief-production

為 React / Next.js 使用 motion/react 提供動畫權杖、彈簧預設、效能規則、裝置適配、無障礙強制與 SSR 安全的基礎層。所有其他動作技能皆依賴於此。

mischief-production 是什麼?

此技能是動畫系統的基礎層,定義了所有下游技能(如 `motion-patterns` 和 `motion-advanced`)繼承的值、約束與規則。它專為使用 `motion/react` 的 React / Next.js 專案設計,建立統一的 `motionTokens` 物件(包含持續時間、緩動、距離與縮放)與 `springs` 預設地圖(提供 5 種命名配置)。它強制執行非妥協的規則:僅能使用 `motion/react`、伺服器端渲染(SSR)安全(`initial` 必須與伺服器輸出匹配)、透過 `useReducedMotion` 鉤子與全域 CSS 媒體查詢支援 `prefers-reduced-motion`、禁止動畫配置屬性(應改用 `transform` 與 `opacity`),以及所有值必須來自權杖系統,不得內嵌硬式編碼。此技能也包含一個 `shouldAnimate()` 閘道,可根據使用者偏好與裝置能力決定是否允許動畫。它產生可共用的元件、鉤子與配置函式,確保動畫不會導致可及性或效能問題,並提供詳細的決策指引以協助開發者選擇正確的持續時間與彈簧預設,或判斷何時應完全停用動畫。

相容平台~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-patterns、motion-advanced)繼承的每一個值、約束與規則。請在開始任何動畫工作之前載入此技能。

何時啟用

  • 從頭開始建立任何動畫元件時
  • 設定動畫權杖(tokens)、彈簧預設(spring presets)或緩動值(easing values)時
  • 實作 prefers-reduced-motion 支援時
  • 偵錯因動畫初始狀態導致的 hydration 不匹配問題時
  • 評估某個動畫是否應該存在時

產出

此技能產出:

  • 一個共用的 motionTokens 物件(持續時間、緩動、距離、縮放)
  • 一個共用的 springs 預設對應表(5 個命名配置)
  • 一個由所有元件使用的 shouldAnimate() 閘道
  • 透過 useReducedMotion 實現符合無障礙標準的動畫預設
  • 具有零 hydration 警告的 SSR 安全初始狀態

原則

動畫必須符合以下至少一項,否則應予以移除:

  • 引導注意力
  • 傳達狀態
  • 保持空間連續性

回應性永遠優於流暢性。一個 60 fps 但導致輸入延遲的動畫,比沒有動畫更糟。

規則

這些是不可協商的。它們適用於系統中的每一個元件。

  1. 僅使用 motion/react。絕不從 framer-motion 匯入。絕不在同一個樹中混用兩者。
  2. initial 必須與伺服器輸出匹配。 如果伺服器渲染 opacity: 1,則 initial 屬性也必須是 opacity: 1。沒有例外。
  3. 減少動畫(Reduced motion)優先於一切。 當 useReducedMotion() 回傳 true 或 prefersReduced 為 true 時,所有變換(transforms)都會停用。僅允許持續時間 ≤ 0.2 秒的不透明度漸變做為唯一的備用動畫。
  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 且動畫非必要
  • 元素在螢幕外且永遠不會進入可視區域
  • 動畫純屬裝飾且無 UX 用途

核心概念

權杖系統

// 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.2 秒
  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 / hydration 安全

規則:initial 必須永遠與伺服器渲染的內容匹配。

// 錯誤 — 伺服器渲染 opacity:1 但 initial 設為 0 → hydration 不匹配
<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、文字動畫、自訂鉤子 → 請見 motion-advanced
  • 純 CSS 動畫或未使用 motion/react 的 Tailwind animate-* 類別
  • 第三方動畫函式庫(GSAP、anime.js 等)
  • 動畫設計決策(何時動畫、強調什麼)— 這是設計考量,而非程式碼約束

反模式

反模式違反的規則修正方式
import { motion } from "framer-motion"規則 1使用 motion/react
在 SSR 元件中 initial={{ opacity: 0 }}規則 2加入掛載防護 (mount guard)
跳過 useReducedMotion 檢查規則 3使用 useSafeMotion 鉤子
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 序列與自訂鉤子。

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.

相關技能