Communitygithub.com

Devin-AXIS/iPolloWork

將 Figma 動畫與轉場效果翻譯成可直接執行的應用程式碼。當使用者提及「實作這個動畫」、「從 Figma 加入動畫」、「為這個元件加入動畫」,提供含有動畫節點的 Figma URL,或當 `get_design_context` 回傳動畫資料或指示你呼叫 `get_motion_context` 時使用。

iPolloWork 是什麼?

此技能(Devin-AXIS/iPolloWork)專門用於將 Figma 設計中的動畫與轉場效果,精準地轉換成適用於各種技術棧(例如 motion.dev、CSS keyframes、或其他框架專屬動畫庫)的生產級應用程式碼。其核心工作流程仰賴兩個 Figma MCP 工具:作為權威動畫資料來源的 `get_motion_context`,它提供完整的動畫節點清單、預先計算的程式碼片段(CSS `@keyframes` 與 motion.dev)、備用的關鍵影格綁定資料,以及多節點協調時間軸提示(`timelineCohorts`);以及 `get_design_context`,它負責提供設計的靜態結構,如佈局、樣式、資源與動畫位置標記。這兩個工具透過 `nodeId` 相互連結,實作時必須將 `get_motion_context` 提供的動畫數值,合併到 `get_design_context` 所描述的靜態結構的對應元素上。此技能的主要支援平台為 Figma MCP 伺服器與任何目標程式碼庫。技能內含詳細的邊界條件(例如,不在 Figma 內部建立動畫)、前提條件(需要 Figma MCP 伺服器與節點ID)、以及處理複雜案例(如交錯變形、SVG 路徑動畫、組件化設計中 fallbackNodeId 的使用)的嚴謹規則。它強調優先使用 `get_motion_context` 提供的現成片段,並在設計與動畫資料衝突時,以動畫資料為最終依據。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Devin-AXIS/iPolloWork/tree/HEAD/examples/plugin-packages/figma/skills/figma-implement-motion

在你喜歡的 AI 中提問

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

說明文件

實作動畫 (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.dev duration / style={{ transformOrigin }},或 CSS animation / 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(Tailwind contents)的形式出現,通常伴隨著一個無效的 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 內聯寫入的 CSS transform 屬性共享,因此 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 以獲取專用參考。

Individual skills in this repo

This repo contains 17 individual skills — each has its own dedicated page.

Devin-AXIS/iPolloWork

Create deterministic animation and transitions for the active iPollo Video project.

Devin-AXIS/iPolloWork

Inspect, validate, preview, and render the active iPollo Video project with its bundled HyperFrames CLI.

Devin-AXIS/iPolloWork

Apply the core composition, timing, media, and determinism contract used by iPollo Video.

Devin-AXIS/iPolloWork

Plan visual direction, typography, pacing, audio, and composition for iPollo Video projects.

Devin-AXIS/iPolloWork

Build seek-safe keyframe animation for the active iPollo Video timeline.

Devin-AXIS/iPolloWork

Reuse approved HyperFrames blocks and components inside the active iPollo Video project.

Devin-AXIS/iPolloWork

Route video creation and editing through the active iPollo Video project and its built-in HyperFrames runtime.

Devin-AXIS/iPolloWork

Create or edit the active iPolloWork video's visual assets, installed recipes, editable composition and seek-safe motion; use for assembly or local picture/text/theme changes.

Devin-AXIS/iPolloWork

Add or revise music, sound effects and their mix in the active iPolloWork video, using authorized sources, real editable tracks and measured event cues.

Devin-AXIS/iPolloWork

Write or revise the active iPolloWork video's native STORYBOARD.md, with source coverage, content-led sequence and provisional timing; use for script-only work.

Devin-AXIS/iPolloWork

Route the active iPolloWork video request to its current storyboard, compose, voiceover or soundtrack work, preserving the client-owned delivery flow.

Devin-AXIS/iPolloWork

Add or revise scene-bound narration or speech-linked captions in the active iPolloWork video using actual voice settings, measured audio and alignment.

Devin-AXIS/iPolloWork

Create product launch and promotional videos through the active iPollo Video workflow.

Devin-AXIS/iPolloWork

Develop or update reusable visual components for iPolloWork Video, including maps, charts, rankings, diagrams, openings and endings. Use for component authoring rules, manifests, editable variables, shared data forms, inherited design themes, AI editing slots and seekable HyperFrames timelines. Not for producing a whole video, authoring a full-project template, or packaging a DeepSeek host plugin.

Devin-AXIS/iPolloWork

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

Devin-AXIS/iPolloWork

Plan and create short videos using the installed short-video-studio workspace app. Manage its creative canvas, scripts, storyboards, characters and local assets, generate images or video through connected Work channels, and hand off editable tracks to Work Video Studio.

Devin-AXIS/iPolloWork

Find, generate, process, and reuse media through the active iPollo Video session's media services.

相關技能