動畫基礎
動畫系統的基礎層。定義了下游技能(motion-patterns、motion-advanced)繼承的每一個值、約束與規則。請在開始任何動畫工作之前載入此技能。
何時啟用
- 從頭開始建立任何動畫元件時
- 設定動畫權杖(tokens)、彈簧預設(spring presets)或緩動值(easing values)時
- 實作
prefers-reduced-motion支援時 - 偵錯因動畫初始狀態導致的 hydration 不匹配問題時
- 評估某個動畫是否應該存在時
產出
此技能產出:
- 一個共用的
motionTokens物件(持續時間、緩動、距離、縮放) - 一個共用的
springs預設對應表(5 個命名配置) - 一個由所有元件使用的
shouldAnimate()閘道 - 透過
useReducedMotion實現符合無障礙標準的動畫預設 - 具有零 hydration 警告的 SSR 安全初始狀態
原則
動畫必須符合以下至少一項,否則應予以移除:
- 引導注意力
- 傳達狀態
- 保持空間連續性
回應性永遠優於流暢性。一個 60 fps 但導致輸入延遲的動畫,比沒有動畫更糟。
規則
這些是不可協商的。它們適用於系統中的每一個元件。
- 僅使用
motion/react。絕不從framer-motion匯入。絕不在同一個樹中混用兩者。 initial必須與伺服器輸出匹配。 如果伺服器渲染opacity: 1,則initial屬性也必須是opacity: 1。沒有例外。- 減少動畫(Reduced motion)優先於一切。 當
useReducedMotion()回傳true或prefersReduced為true時,所有變換(transforms)都會停用。僅允許持續時間 ≤ 0.2 秒的不透明度漸變做為唯一的備用動畫。 - 絕不為佈局屬性設定動畫。
width、height、top、left、margin、padding禁止出現在animate中。僅使用transform與opacity。 - 所有權杖值都來自
motionTokens。 禁止在元件檔案中內嵌硬式編碼的持續時間與緩動。 - 所有彈簧配置都來自
springs對應表。 禁止內嵌stiffness/damping值。 - 每個從
motion/react匯入的檔案都必須加上"use client"。 - 絕不在模組層級讀取
window或navigator。 務必使用typeof window !== "undefined"進行保護。
決策指引
選擇持續時間
| 權杖 | 使用時機 |
|---|---|
instant | 提示框顯示/隱藏、焦點環、徽章更新 |
fast | 按鈕回饋、圖示切換、晶片切換 |
normal | 模態框開啟、卡片展開、頁面元素進入 |
slow | 主要視覺區進入、全頁面轉場 |
crawl | 有意的敘事效果;請謹慎使用 |
選擇彈簧
| 預設 | 使用時機 |
|---|---|
snappy | 預設 UI — 按鈕、晶片、導航項目 |
gentle | 卡片、模態框、面板柔和落地 |
bouncy | 趣味時刻 — 空狀態、引導流程 |
instant | 提示框、彈出視窗、下拉選單 |
release | 拖曳釋放 — 自然的物理手感 |
何時完全停用動畫
在以下情況下停用(讓 shouldAnimate() 回傳 false):
prefersReduced為trueisLowEnd為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
},
}
無障礙
優先順序(由高至低):
prefers-reduced-motion: reduce— 停用所有變換,將不透明度轉場限制在 ≤ 0.2 秒- 低階裝置偵測 — 縮短持續時間,移除非必要的動畫
- 設計偏好 — 其他所有情況
動畫必須優雅降級。絕不能突然消失,導致版面位移或使使用者迷失方向。
// 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的 Tailwindanimate-*類別 - 第三方動畫函式庫(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序列與自訂鉤子。