實作動畫 (Implement Motion)
概述 (Overview)
此 Skill 引導你將 Figma 動畫與轉場翻譯成可執行的程式碼(motion.dev、CSS keyframes 或框架專屬函式庫)。
Figma 透過兩個工具來呈現動畫:
get_motion_context— 權威的動畫工具。回傳完整的動畫節點清單、預先計算的程式碼片段(CSS@keyframes+ motion.dev)、當片段不可用時的備用關鍵影格綁定,以及遞迴時間軸協調提示(timelineCohorts)。這是動畫資料與哪些節點 ID 會動畫化的唯一真實來源(source of truth)。get_design_context— 設計的結構:佈局、尺寸、資源、樣式、Code Connect 提示、截圖上下文,以及有時會出現在動畫元素上的動畫放置標記(data-node-id,在分割節點上則是data-motion-keys/data-motion-wrapper-for/data-motion-transform-template)。它可能會將一個動畫節點渲染成普通元素(div、p、span等)或動畫元素(motion.div);但它不會內嵌動畫數值。
兩者透過節點 ID 連結,而這就是整個工作流程。 get_motion_context 告訴你哪些節點會動畫化,並提供關鍵影格數值、緩動函數、時間與片段。get_motion_context 告訴你這些節點長什麼樣子、位於何處。對於 get_motion_context.nodes 中的每個節點,都要在設計上下文中找到對應的 data-node-id,並將動畫合併到該結構中——如果結構元素是普通元素,則加入或包裝成 motion.{tag}。當設計上下文重複使用了一個 Figma 元件時,動畫節點可能還包含 fallbackNodeId;只有在嘗試過精確的 nodeId 之後,才將其作為備用。
Skill 邊界 (Skill Boundaries)
- 當交付成果是使用者儲存庫中的動畫程式碼時,請使用此 Skill。
- 如果使用者要求在 Figma 內部建立/編輯動畫,請切換至 figma-use 並遵循該 Skill。
- 此 Skill 目前涵蓋
get_motion_context所發出的動畫(片段加上備用關鍵影格軌跡,包括已解析為這些形式的預設動畫)。更廣泛的互動變體流程可能仍需要在程式碼中進行產品特定的狀態處理。
先決條件 (Prerequisites)
- Figma MCP 伺服器已連接且可存取。
- 從使用者提供的 Figma URL 中解析出節點 ID。URL 格式:
https://figma.com/design/:fileKey/:fileName?node-id=1-2—— 提取fileKey(/design/之後的片段)和nodeId(node-id查詢參數的值,例如42-15)。 - 目標程式碼庫。動畫輸出格式會根據技術棧進行調整(請參閱框架建議)。
工具選擇 (Tool Choice)
對於動畫實作,請使用兩個工具並區分其角色:
| 情況 | 工具 | 原因 |
|---|---|---|
| 了解靜態結構、資源、樣式、Code Connect 或視覺佈局 | get_design_context | 提供正確放置動畫節點所需的元件/頁面程式碼參考和資源 URL。 |
| 擷取任何節點的動畫資料 | get_motion_context | 專為動畫設計,是時間、緩動函數、片段和關鍵影格的唯一真實來源。 |
節點帶有動畫標記(data-motion-keys、data-motion-wrapper-for) | 標記用於分割放置,get_motion_context 用於數值 | 分割標記告訴你哪些軌跡屬於哪個元素;關鍵影格/緩動函數/時間和動畫節點清單來自 get_motion_context。 |
get_motion_context 接受 recursive: true(上限 500 個節點),當你需要一次取得所有後續節點的動畫時可以使用。
必要工作流程 (Required Workflow)
步驟 1:確認靜態設計上下文可用
get_design_context(fileKey=":fileKey", nodeId="<node-id>")
如果 get_design_context 已經為此節點呼叫過,請重複使用該輸出。如果沒有,則正常呼叫它。
將其用作記錄結構(structure of record) —— 層級、尺寸、樣式、資源、Code Connect 提示、截圖上下文,以及它可能包含的任何動畫放置標記(步驟 3)。動畫節點清單和動畫數值則來自 get_motion_context(步驟 2)。
步驟 2:擷取權威動畫資料
get_motion_context(fileKey=":fileKey", nodeId="<node-id>", recursive=true)
回應格式(每個動畫節點一個條目):
codeSnippets— 預先產生的 CSS@keyframes和 motion.dev 字串。直接使用這些。 不要從備用軌跡資料重新產生。keyframeBindings— 綁定的關鍵影格軌跡,包括已解析為軌跡資料的預設動畫,僅在兩個片段格式都缺失時作為備用資料包含。motionSummary— 每行一個欄位的自然語言動畫描述。僅當沒有片段時才出現(僅有關鍵影格綁定的動態程式碼生成無法以 CSS/motion.dev 表達)。當它存在時,從它建立;只要片段存在,就忽略它。fallbackNodeId— 用於匹配元件化設計上下文的可選備用 ID。如果nodeId是實例限定的 ID,例如I4005:6111;30:8005,D2R 可能會改為使用後端元件 ID (如4002:3957) 來渲染可重複使用的元件本體。在這種情況下,fallbackNodeId是在精確nodeId查找失敗時要尋找的data-node-id。
遞迴回應還包含 timelineCohorts — 一個頂層陣列(非每個節點),包含共享一個時間軸的節點:{ rootNodeId, durationMs, loopMode: 'once' | 'loop' | 'boomerang', memberNodeIds[] }。對於協調的多節點動畫,使用 durationMs(÷1000 轉為秒)和 loopMode,從一個共享的生命週期驅動所有 memberNodeIds——不要從同層順序推斷時間。
對 LLM 重要的實作細節:
- 當片段存在時,
motionSummary、timelineDurationMs和transformOrigin可能會被省略以縮小負載——片段已攜帶持續時間 + 變形原點(motion.devduration/style={{ transformOrigin }},或 CSSanimation/transform-origin),而群組則攜帶durationMs。缺失的欄位從不代表「沒有動畫」。 - 遞迴回應會對完全相同的片段進行去重。一個片段可能被替換為指向第一個具有相同動畫的節點的註解;請重複使用相同的元件、變體、類別或常數,而不是編寫第二個動畫。
- MCP 伺服器會從
clientFrameworks推斷 CSS 與 motion.dev 片段;如果回應僅包含一種片段格式,請將該格式適應使用者的技術棧,而不是假設另一種格式失敗。
步驟 3:合併靜態與動畫上下文
- 從
get_motion_context.nodes開始,而不是從靜態 JSX 中可見的motion.*標籤。每個回傳的節點都是動畫化的。 首先透過精確的nodeId/data-node-id將每個動畫節點匹配回get_design_context。如果且僅如果沒有精確匹配,則嘗試fallbackNodeId/data-node-id。只有在兩個 ID 都失敗後,才回退到使用節點名稱/類型和截圖位置進行匹配。 - 精確 ID 匹配優先於
fallbackNodeId。fallbackNodeId指向 D2R 可能在可重複使用元件內部發出的後端元件 ID。該元件的每個實例都共享它。如果精確的nodeId存在於設計上下文中,則將動畫應用於該處並忽略備用。這對於根實例動畫至關重要:一個實例可以與另一個相同元件的實例進行不同的旋轉或移動,如果將該動畫應用於共享的元件本體,則會錯誤地動畫化所有實例。 - 將每個動畫節點應用於匹配的設計上下文結構,以
data-node-id為鍵。 匹配的data-node-id是結構錨點,不總是最終接收動畫的 DOM 元素。使用片段形狀和放置標記來決定動畫是放在該確切元素、包裝器、內部元素還是內聯 SVG 路徑上。get_design_context可能已經發出了帶有被剝離數值的motion.{tag},或者它可能發出一個普通的結構元素(div、p、span、元件根節點等)。如果它是普通元素且片段目標是該元素本身,則將其轉換為適當的motion.{tag}或添加一個動畫包裝器,同時保留節點的文字、子元素、類別/樣式、屬性和data-node-id。載入 references/examples-and-anti-examples.md 以查看此合併步驟的範例。 - 元件化的子動畫通常透過 fallback 匹配。 當設計上下文將一個 Figma 實例提取為可重複使用的 React 元件時,該元件本體內部的子級通常具有後端元件 ID(
4002:3957),而動畫上下文則報告即時實例 ID(I4005:6111;30:8005)。在這種情況下,使用fallbackNodeId來查找元件本體的data-node-id,但將動畫範圍限制在你正在實作的已渲染實例上。如果有多個實例且只有一個具有不同的根動畫,則精確 ID 匹配會將該每個實例的動畫分開。 - 分割節點帶有
data-motion-keys/data-motion-wrapper-for標記 — 請參閱下方的處理交錯變形。 - 保留
display: contents包裝器 — 除非群組本身有動畫。 佈局透明的群組包裝器會以contents(Tailwindcontents)的形式出現,通常伴隨著一個無效的absolute/inset-[…](這些在contents盒子中不起作用)。對於一個靜態群組,保留display: contents並讓子元素根據最近的實際祖先進行定位——將包裝器的inset轉換為定位盒子會將子元素重新定位到一個較小的盒子中,導致它們渲染得太小/向內偏移。對於一個動畫化的群組(群組節點本身有動畫),display: contents無法承載變形——將其替換為一個真正的定位包裝器,並將群組動畫應用於該包裝器。在實作此情況之前,請載入 references/gotchas.md。 get_motion_context是完整的動畫節點清單。 一些動畫節點渲染為普通(非motion)元素——元件實例根節點(普通定位<div>)、文字(<p>)、遮罩——這些元素仍然帶有data-node-id。走訪動畫回應中的每個節點,並將其動畫應用於具有匹配data-node-id的元素,根據需要進行包裝或轉換。如果一個動畫節點在輸出中完全沒有對應元素(例如,一個動畫遮罩被扁平化為靜態mask-image),不要默默丟棄它——留下一個// TODO: <nodeId> 動畫不支援的註解,並在你的摘要中提及它。- 如果一個節點出現在動畫上下文中但不在靜態 JSX 中,請添加必要的元素來表示它——設計上下文程式碼是一個參考,而不是完整的動畫清單。
- 當設計上下文和動畫上下文之間發生衝突(時間/緩動函數/動畫數值)時,偏好
get_motion_context。 - 路徑級別的 SVG 動畫:內聯 SVG 並動畫化真正的
<path>。 當get_motion_context目標是一個向量的路徑(PATH_TRIM、motion.path、stroke-dasharray),但設計上下文將其渲染為<img>時,內聯該 SVG 並將片段應用於<path>,同時保留佈局包裝器。載入 references/svg-and-path-motion.md 以獲取此情況的完整操作指南(motion.path、pathLength="1"、包裝器+路徑分層、CSS path-trim)。
處理交錯變形 (Handling interleaved transforms)
一個同時具有靜態基礎變形和動畫變形的節點會被分割到巢狀元素中,以便兩者正確組合而不是互相衝突:一個無 ID 的 motion.div 帶有 data-motion-wrapper-for="<nodeId>"(外部包裝器)包裝了一個靜態變形 div(例如 rotate-45 + hypot() 尺寸計算——或者包裝器本身帶有 data-motion-transform-template="<css>"),該靜態變形 div 又包裝了內部節點(data-node-id)。保留 包裝器 > 靜態變形 div > 內部 的巢狀結構——摺疊它會破壞尺寸和基礎變形。
- 根據
data-motion-keys放置軌跡。 包裝器的data-motion-keys(變形軌跡——x/y/rotate/scaleX/scaleY/skewX)放在外部包裝器上;內部元素的data-motion-keys放在內部元素上。 - 重新應用
data-motion-transform-template。 如果包裝器帶有一個,設定transformTemplate={(_, generated) => "<css> " + generated},以便動畫變形疊加在該靜態佈局變形之上。 - 根據靜態基礎偏移動畫變形(避免雙重旋轉)。
get_motion_context提供節點的絕對變形,它已經包含了這些 div 應用的任何靜態基礎。一個rotate-45基礎之上的[45, 125, 125]的rotate片段,意味著包裝器動畫化的是偏移量[0, 80, 80](= 絕對值 − 45),而不是絕對值——否則 45° 會被應用兩次,導致元素在靜止時處於 90°。沒有靜態基礎的軌跡(例如從 0 開始的x/y)則保持不變。請參閱交錯變形範例。 - 保持佈局變形與 Motion 變形分離。 對於每個動畫化
rotate、scale或skew的motion.*元素,請驗證它不依賴於用於居中/定位的 Tailwind 佈局變形,例如-translate-x-1/2或-translate-y-1/2。這些工具與 Motion.dev 內聯寫入的 CSStransform屬性共享,因此 Motion 的變形可能會抹除佈局平移。如果兩者都需要,請將元素分割為一個承載居中/定位變形的靜態佈局包裝器,和一個承載動畫化 rotate/scale/opacity 的內部motion.*元素,或者將佈局偏移編碼在 Motion 本身中(x: "-50%")並為每個關鍵影格保持其存在。
步驟 4:在程式碼中應用動畫
- 片段中存在 motion.dev? 對於 React 目標,直接使用 motion.dev 程式碼。從
motion/react導入——除非程式碼庫已經使用了另一個動畫庫(Framer Motion、React Spring、GSAP),在這種情況下,請調整片段以適應該庫。在適應其他技術棧或選擇庫時,請載入 references/framework-recommendations.md。 - 存在 CSS keyframes? 用於 vanilla/非 React 目標,或當程式碼庫沒有 React 動畫庫時使用。
- 無片段(僅有關鍵影格綁定)? 從
keyframeBindings構建等效的 motion.dev/CSS。keyframeBindings包含一個keyframeTracks陣列,每個軌跡一個property(例如transform.rotate、opacity)。屬性轉換:transform.rotate→.animate({ rotate: [...] })或 CSS@keyframes { to { rotate: ... } }transform.scaleX→.animate({ scaleX: [...] })或 CSS@keyframes { to { scale: ... } }(或者為 scaleX 單獨使用transform: scaleX(...))opacity→.animate({ opacity: [...] })或 CSS@keyframes { to { opacity: ... } }- 任何帶有
transform.前綴的屬性,設定為 motion.dev 中transform物件上的對應鍵(無transform.前綴)。例如transform.translateX→{ x: [...] },而不是{ transform: [...] }。CSS 則寫入transform: translateX(…)形式。 - 每個軌跡也包含
easing(標準化為 CSS easing 字串,例如"cubic-bezier(0.2, 0, 0, 1)"或"ease")和keyframes(一個{ offset: number, value: number }物件陣列)。偏移量為 0–1。僅使用easing的第一個值; CSS 和 motion.dev 僅支援每動畫一個緩動函數(在 CSS 中,緩動函數只能附加在animation之後,而不是每個關鍵影格之後)。 - 如果存在
timelineDurationMs,將其用作持續時間。如果沒有,從keyframes的offset值計算得出是不安全的——預設為 1 秒,或從片段/群組durationMs推斷。
核心點:將要產生滿足實際動畫需求的精簡程式碼。 特別是對於 motion.dev 目標,請使用 animate() 進行一次性/首次載入動畫,使用 useMotionValue() + useTransform() 進行基於手勢的或連續的動畫,使用 whileInView 進行基於滾動視口的觸發,並使用 motion.* 元素屬性聲明(animate、initial、transition、variants)進行宣告式元件動畫。
框架建議 (Framework Recommendations)
載入 references/framework-recommendations.md 以獲取特定於框架的指南。該文件涵蓋:
- React with motion.dev — 預設目標路徑。使用片段。
- Framer Motion — 主題和語法非常相似;映射到
motion和animate。 - CSS only — 當程式碼庫不想要 JavaScript 動畫庫時使用。
- Vue、Svelte、Web Components — 適應指南。
提示與備忘 (Tips & Gotchas)
載入 references/gotchas.md 以獲取常見陷阱:
overflow-hidden在motion.div上會裁剪正在動畫化的內部元素。如果一個元素在容器外動畫化,請將overflow-hidden移動到一個非動畫包裝器或將其移除。- 文字
white-space和word-break可能需要在動畫包裝器上顯式設定以防止換行。 position: absolute; inset: 0群組包裝器與display: contents交互——參見步驟 3 中的contents規則。z-index和position:動畫元素可能需要明確的position: relative/absolute才能正確疊加。will-change警告——讓 motion.dev 處理它。- 鍵控動畫:如果一個元件因為
key改變而被重新掛載,motion.dev 的AnimatePresence可以處理進出場動畫——但前提是結構正確。 - 當使用 Tailwind 時:動畫變形值會覆蓋同一個元素上的靜態 Tailwind 轉換實用類(
translate-x-*、rotate-*、scale-*...)。如果一個元素有className="rotate-45"並且你添加了animate={{ rotate: 90 }},旋轉從 45° 開始到 90°,而不是 0°。請參閱 get_motion_context 處理偏移的方式。
SVG 與路徑動畫 (SVG & Path Motion)
載入 references/svg-and-path-motion.md 以獲取專用參考。