Communitygithub.com

503496348-ops/mischief-production

適用於 React / Next.js 的產品級動畫模式 — 按鈕、選單、提示、交錯、頁面轉場、離開動畫、滾動及佈局 — 基於 motion-foundations 代幣與彈簧建構。

mischief-production 是什麼?

此技能提供一組可直接複製貼上的產品級 UI 動畫模式,專為 React 與 Next.js 設計。所有模式皆建構在 `motion-foundations` 的設計代幣與彈簧參數之上,開發者無需自行定義持續時間或緩動函數,只需匯入即可。支援的動畫類型涵蓋按鈕回饋、卡片擴展、提示堆疊、列表交錯進場、頁面轉場、滾動觸發顯示、滾動進度條,以及共享元素跨場景淡變等。技能內建嚴格規則以確保可及性與 SSR 安全,例如所有條件渲染必須使用 `AnimatePresence` 搭配 `key`,並且必須同時定義進入與離開動畫。這份技能適用於 Claude Code、Cursor 等開發工具,能大幅減少開發者在實作常見動畫時的思考與試錯時間。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Motion Patterns

可直接複製貼上最常見的 UI 動畫需求模式。 此處的所有模式都建構在 motion-foundations 的代幣與彈簧之上。請勿在此定義新的持續時間或緩動值——請從那裡匯入。

啟用時機

  • 為按鈕、卡片、選單或提示通知加入動畫
  • 使用交錯效果構建列表進場
  • 在 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 prop
相同元素跨頁面上下文移動layoutId
元素在滾動到視野時進入whileInView
值與滾動位置綁定useScroll + useTransform

使用 mode="wait" 與 mode="sync" 的時機

模式適用時機
wait頁面轉場、內容切換(一次一個)
sync堆疊通知、列表項目(重疊可以接受)
popLayout從重排列表中移除項目

核心概念

AnimatePresence 約定

三件事必須永遠成立:

  1. AnimatePresence 包裹了條件式
  2. 直接子元素有 key
  3. 子元素有 exit prop

任何一項缺失都會導致離開動畫無聲失敗。

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}
      />
    </>
  )
}

提示堆疊

"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}>Remove</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.

相關技能