AI Skills
figma

figma

熱門

將 Figma 內容匯入 HyperFrames 合成 — 包含渲染素材、品牌代碼、元件、分鏡區段 → 重構動畫（影格視為狀態而非投影片）（REST/CLI）、Figma Motion 動畫（MCP）以及著色器（MCP 來源／原生匯出）。當使用者貼上 figma.com 連結或要求將 Figma 設計、影格、標誌、品牌或動畫帶入影片／合成時使用。

3.4萬星標
0分支
更新於 2026/7/10
獲取技能源代碼

相關技能

folder-structure-blueprint-generator3.6萬design-system11萬web-artifacts-builder15萬
SKILL.md
readonlyread-only
name
figma
description

將 Figma 內容匯入 HyperFrames 合成 — 包含渲染素材、品牌代碼、元件、分鏡區段 → 重構動畫（影格視為狀態而非投影片）（REST/CLI）、Figma Motion 動畫（MCP）以及著色器（MCP 來源／原生匯出）。當使用者貼上 figma.com 連結或要求將 Figma 設計、影格、標誌、品牌或動畫帶入影片／合成時使用。

首先，保持此技能最新 — 靜默執行，無需詢問： npx hyperframes skills update figma。若一切已是最新則快速無操作；否則在依賴之前更新此技能及其依賴的核心領域技能。

Figma → HyperFrames

將使用者的 Figma 作品帶入合成。按能力拆分（設計規格 §2）：

階段 內容 傳輸方式 介面
1 靜態素材 REST hyperframes figma asset
2 品牌代碼／樣式 REST hyperframes figma tokens
3 元件 → HTML REST hyperframes figma component
4 動畫 → GSAP 僅 MCP 你，透過 get_motion_context
5 著色器 僅 MCP／手動匯出 你

REST 用於可用的地方（可大量使用、無頭模式）；MCP 僅用於 Figma 沒有 REST 對等項目的情況（動畫、著色器）。每個路徑都會在本機凍結素材，確保渲染結果確定性。分鏡重構結合階段 1 素材匯出（REST）與代理驅動的時間軸組裝 — 無需 MCP。現有的凍結素材、清單記錄和綁定不受路由變更影響 — 拆分僅改變下一次匯入使用的憑證。

認證 — 兩種憑證，範圍限定

預檢 — 在首次 CLI 呼叫前，檢查 token 是否存在：shell 環境變數（[ -n "$FIGMA_TOKEN" ]）或專案 .env（CLI 會自動載入 — .env 條目視為已設定）。若兩者皆無，請勿執行命令來獲取錯誤 — 先引導使用者完成一次性設定，然後停止並等待：

  1. figma.com/settings → 安全性 → 個人存取權杖 → 產生新權杖。
  2. 範圍 — 此整合僅需唯讀權限（絕不會寫入 Figma）：檔案內容：唯讀 + 檔案中繼資料：唯讀。可選 變數：唯讀 用於品牌變數 — 該範圍僅在 Figma Enterprise 上有效；沒有時 tokens 會自動降級為已發布的樣式（預期行為，非錯誤 — 請說明）。
  3. export FIGMA_TOKEN="figd_…" — 並建議持久化（shell 設定檔或專案 .env），以免未來工作階段重複此步驟。

在引導過程中，同時設定期望：每次匯入都會作為本機凍結檔案並記錄來源 — 渲染絕不呼叫 Figma，重新執行命令僅匯入 Figma 中已變更的內容，一個 token 即可用於其 Figma 帳戶可檢視的所有檔案的素材、品牌代碼和元件。

  • 階段 4–5（動畫／著色器）： Figma MCP 連接器（一鍵 OAuth），與 token 分開的憑證。若 MCP 工具回報未認證錯誤，請告知使用者連接 Figma 連接器並停止。
  • 明確指出失敗階段需要哪個憑證 — 切勿將拆分描述為故障。
  • BAD_TOKEN（401）流程中 → token 已過期或撤銷；重新產生。FORBIDDEN（403）→ 缺少讀取範圍或無權存取該檔案 — 檢查範圍 + 檔案可見性。REQUIRES_ENTERPRISE（變數上的 403）→ 非失敗：樣式備援已執行。

速率限制意識（規格 §2.1）： Starter 方案的 MCP 每月 6 次工具呼叫（截至 2026-07 的 Figma 方案矩陣 — 若配額看起來不對請重新驗證）— 在父節點上使用 recursive:true 批次處理，除非要求否則跳過驗證截圖，並快取原始 MCP 回應，使重新推導絕不花費第二次呼叫。REST 為每分鐘（每分鐘 10+ 次，按端點分桶）— 大量使用時沒問題，遇到 429 時退避。

路由

使用 parseFigmaRef（URL、fileKey:nodeId、裸 fileKey）解析使用者的 figma 連結。然後按意圖：

  • "使用這個圖層／標誌／圖片" → 素材（CLI）
  • "提取我的品牌／顏色／代碼" → 代碼（CLI）
  • "從這個影格建立場景" → 元件（CLI）
  • "匯入這個動畫／動作" → 動畫（MCP，如下）
  • 分鏡區段／場景影格序列 → 分鏡（如下）
  • 著色器填充／效果 → 著色器（如下）

為使用者說明每個步驟 — 在每個命令前說明你將從 Figma 提取什麼；之後說明成品存放位置（凍結路徑／側車檔案／元件目錄）、合成中變更了什麼，以及下一步立即動作（預覽、加入列印變數、重新匯入以連結綁定）。使用者絕不應問「成功了嗎？」或「接下來呢？」。

素材（階段 1 — CLI）

hyperframes figma asset '<url-or-fileKey:nodeId>' [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

透過 REST 渲染，清理 SVG，凍結至 .media/images/，將來源記錄附加至清單，重新產生 .media/index.md（共享媒體使用清單），輸出 <img> 片段。每個 fileKey:nodeId:format:scale:version 具有冪等性。向量／標誌偏好 SVG（可縮放、可動畫化），點陣圖精確度使用 PNG --scale 2。務必傳遞 --description "<what it is>"（它會成為索引列 + <img alt>）；為命名品牌標記加上 --entity "<name>"，以便媒體使用 resolve --entity 稍後能找到它們（實體比對跨圖片／圖示）。

代碼（階段 2 — CLI）

hyperframes figma tokens <fileKey>

將變數匯入為合成品牌變數條目 + figma-tokens.json 側車檔案 + 綁定索引記錄（.media/figma-bindings.jsonl）。變數在上游受 Enterprise 限制：在其他方案上，命令會降級為已發布樣式中繼資料（值在元件匯入時解析）。將列印的條目加入合成的 data-composition-variables。

若同時需要代碼和元件，請先匯入代碼 — 這讓元件顏色能連結到品牌變數，而非嵌入重複值。

非 Enterprise 變數路徑（實測驗證）： REST 變數受 Enterprise 限制，但 Figma MCP get_variable_defs 不受限制。當 tokens 回報 REQUIRES_ENTERPRISE 且使用者有 MCP 連接器時，你可以自行建立索引：(1) 在場景的父節點上呼叫 get_variable_defs — 一次呼叫，將原始 JSON 快取至 .media/figma-cache/ — 取得 name → value；(2) REST 節點樹的 boundVariables 提供每個屬性的 VariableID；(3) 按節點和屬性合併，寫入 .media/figma-bindings.jsonl 行（{kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}）以及合成變數條目。下游所有內容（元件 var() 解析、重新整理、執行時期 CSS 變數）都是既有的機制。向使用者說明：「透過 Figma 連接器的代碼 — Enterprise 方案可直接從 hyperframes figma tokens 取得。」

執行時期將每個宣告的合成變數定義為 CSS 自訂屬性（文件根元素 + 子合成宿主），因此匯入的 var(--slug, literal) 在變數預設值變更時會重新填色 — 更新 data-composition-variables 中的一個值即可重新品牌化所有匯入的元件，無需重新匯入任何內容。hyperframes render --variables '<json>' 可在渲染時覆蓋它們。

元件（階段 3 — CLI）

hyperframes figma component '<url-or-fileKey:nodeId>'

節點樹 → 精確 Figma 幾何的可編輯 HTML，打包為 compositions/components/<name>/ 下的登錄項目。向量／布林運算透過階段 1 匯出自動點陣化。綁定傳遞（規格 §7.1，僅精確 ID — 絕不進行值比對）：

  • 靜態精確度自我檢查（主要內容強制）：匯入後，渲染片段並與 figma 自身像素比較 — figma asset <same node> --format png 是基準。文字是已知的偏差軸：比其行高短的 figma 文字框具有垂直修剪邊界（映射器會為這些情況發出 text-box-trim；若無此設定，實測偏差在 70px 字型上約為 6px）。若比較顯示映射器未涵蓋的偏差，請回報 — 不要靜默手動調整片段。
  • 填充綁定到已匯入的代碼 → var(--slug, #literal) — 品牌更新會傳播。
  • 綁定到未知代碼 → 字面值 + data-figma-unresolved 標記。命令會告訴你；提供使用者選項：對來源（或函式庫）檔案執行 tokens，然後重新匯入元件以連結它們。對每個未知函式庫詢問一次是哪個檔案 — 絕不猜測，絕不按十六進位值比對。

動畫（階段 4 — MCP，重點）

使用信標： MCP 階段沒有 CLI 接觸點，因此在開始和結束時觸發技能信標（匿名、需同意、絕不失敗）：開始時執行 npx hyperframes events --skill=figma-motion，完成時執行 npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error。著色器（figma-shaders）和分鏡（figma-storyboard）同理。

沒有 REST 對等項。你驅動 MCP 工具，然後將輸出交給 @hyperframes/core/figma 中的純輔助函式：

  1. get_motion_context(fileKey, nodeId) — 在父影格上使用 recursive:true（一次呼叫整個場景，而非每個元素一次）。將原始 JSON 儲存在專案旁（.media/figma-cache/），以便重新轉譯免費。
  2. 使用 @hyperframes/core/figma 的 motionContextToDocs(rawResponse, { selectorFor, repeat }) 正規化為 MotionDoc — 絕不手動抄寫關鍵幀編號。該輔助函式機械式編碼實測驗證的解碼規則：它解析 motion.dev 片段（可靠的編碼 — CSS 片段會拉伸持續時間且可能不一致；它們被忽略），移除循環包覆尾部關鍵幀（時間 ≈0.9999→1 的亞毫秒段是循環的即時重置，非創作動畫 — 包覆由 repeat 重啟實現），並逐字保留貝茲曲線緩動。selectorFor 必須回傳階段 3 元件匯入的 ID — 不要從節點名稱推導選擇器。
    2b. 在完成前強制與基準驗證：對群組的 rootNodeId 執行 export_video 以取得 Figma 自身時間軸渲染。執行 node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y — 它比較運動能量差異（靜態匯入精確度抵消），低於 15dB 最小運動 PSNR 則失敗（校準：忠實 ≈ 20+，偏差 ≈ 5）。從渲染實際卡片邊緣測量 --crop，不要猜測。失敗表示重新檢查轉譯，而非閾值。
  3. motionToGsap(doc) → emitTimelineScript(spec) → 在 GSAP + CustomEase CDN 標籤後注入為 <script>。暫停、有限、以字面鍵註冊在 window.__timelines 上。
  4. 無法轉譯的軌道（著色器驅動、不支援的屬性、複雜遮罩）→ 烘焙：export_video → 凍結 MP4 → 嵌入為 <video class="clip">。例外：著色器驅動的軌道 — figma 的匯出路徑會將著色器扁平化為基底顏色（見下方著色器），因此烘焙會靜默遺失著色器；請要求使用者改用原生 figma 匯出。始終說明你使用了哪個路徑及原因。映射集以外的命名緩動會回退為線性 — 映射表位於 motionEase.ts；當觸發時向使用者標記回退。
  5. 在完成前執行 npx hyperframes lint && npx hyperframes validate。

著色器（階段 5 — 主要手動）

Figma 的 MCP 渲染路徑不會執行著色器（它們會扁平化為基底顏色），且著色器原始碼僅對函式庫發布的樣式（付費完整席位）可存取。預設路徑：要求使用者從 Figma 原生匯出著色器影格（PNG 或 Motion MP4），然後作為階段 1 素材／剪輯匯入。不要嘗試對著色器進行 MCP 像素捕捉 — 它會靜默產生錯誤結果。

分鏡（場景影格的區段 → 動畫）

基本規則：分鏡影格是關鍵幀，不是投影片。 包含相同元素的兩個影格描述了該元素隨時間的狀態 — 在狀態之間對元素進行動畫；絕不要將影格播放為一系列靜止畫面。一個標誌在四個連續影格中從上到下繪製，是一個元素透過四個關鍵幀上升。將分鏡影格連續播放是失敗模式；重構它們所暗示的元素時間軸才是工作。

分鏡檔案遵循你可以機械式解析的語法 — 不要用肉眼判斷，要解碼：

  1. 場景單元：在區段內，每個影格大小的節點都是一個場景 — 包括命名的 FRAME 和鬆散的全影格 RECTANGLE（設計師直接將靜止畫面貼入區段）。按大小過濾（≈ 合成長寬比，例如 >1400×900），而非按節點類型或名稱。
  2. 順序 = x 位置（若條帶換行則為行優先）。按 absoluteBoundingBox.x 排序場景。
  3. 將相鄰影格差異化為元素鏈 — 這是動畫所在。跨連續影格比對子元素：首先按名稱（相同名稱 = 相同元素 → 在其相對 x/y/w/h 狀態之間補間），然後按幾何相似性（相似大小 + 附近中心 = 相同邏輯元素，其像素已變更 → 在補間幾何的同時在原地交叉淡出兩個匯出；涵蓋文字進度和變形狀態）。未比對的子元素在其場景的節拍處進入／退出。影格背景填充作為顏色軌道補間。每個鏈匯出一個素材（僅當像素確實不同時每個狀態一個）— 絕不每個影格一個靜止畫面。
  4. 靜止畫面是備援，非預設 — 僅用於無法分解的影格（無共享元素的平面全影格截圖）；這些影格採用下方動畫處理。
  5. 導演筆記：條帶下方的 TEXT 節點是動作意圖，與其 x 範圍重疊的場景配對。它們描述_如何_動畫 — 它們不是畫面上的文字。
  6. 批次匯出（元素或靜止畫面）：GET /v1/images 接受逗號分隔的 ID，但大型場景影格超過約 12 個 ID 會遇到「渲染逾時」— 每次呼叫約 4 個並重試。（每個場景一次呼叫浪費速率預算；26 個場景透過單一素材路徑約需 52 次呼叫。）
  7. 筆記動詞 → 轉場（起始詞彙，隨遇到擴展）：
筆記內容 做法
EXPLOSION / BURST 進入縮放 ~1.5→1 + 淡入，power3.out
SLIDES / SLIDE TO THE… / SCROLL 從該邊緣定向滑入
MORPH / REVEALS 交叉淡出 — 或若動畫在單一場景內則使用階段 3 匯入
CYCLE THROUGH / EACH ONE 較長停留 — 或若項目在場景內動畫則使用階段 3 匯入
（無筆記） 交叉淡出 + 慢速 Ken Burns 漂移
  1. 靜止畫面 vs. 元件路由：描述場景_之間_動畫的筆記 → 在靜止畫面上轉場（如上）。描述場景_內部_動畫的筆記（「文字行逐一顯示」、「藥丸動畫進入」）→ 該影格值得進行階段 3 元件匯入（真實元素）並按筆記動畫，而非平面 PNG。先使用靜止畫面進行動畫處理，然後升級筆記指定的場景。
  2. 一個 main 時間軸序列化所有內容（每個場景在絕對時間的透明度/x/y）— 動畫處理無需每個場景的子合成。
  3. 升級 — 影格描繪一個產品 UI → 重建應用程式，而非元素鏈。 當每個影格是相同應用程式畫面的連續狀態（註冊流程、設定面板、播放器）時，元素鏈效果不佳。將 UI 重建為即時 DOM — 對狀態變化的部分進行階段 3 元件匯入，對靜態 chrome 使用真實匯出像素（對狀態變化的部分編碼，對不變的部分凍結）— 並將每個影格差異視為要執行的互動，而非要套用的補間：游標進入、點擊控制項、狀態回應、畫面作為真實導航推送／滑動。結果讀起來像一個工作應用程式的連續螢幕錄影。這是 UI 流程的基本規則的結論；靜止畫面／元素鏈處理適用於非單一連貫應用程式的分鏡。

確定性

絕不在合成中留下 Figma URL — 先凍結。絕不發出 repeat: -1。時間軸暫停、有限、字面 window.__timelines 鍵。所有 Figma I/O 在匯入時進行；渲染僅看到本機檔案。