外掛安裝: 在執行設定或更新命令之前,當此技能位於 HyperFrames 外掛內部時,請遵循外掛安裝規則。獨立安裝則保留下方的更新說明。
首先,保持此技能為最新版本 — 在執行前與使用者確認:
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 | 連接器(可用時) | 使用其動態上下文 |
| 5 | 著色器 | 連接器 / 手動匯出 | 使用它或原生匯出 |
REST 被用於所有可行之處(可在高容量、無頭模式下使用)。一個相容的 Figma 連接器對於動態和著色器資料是可選的;如果沒有,要求進行原生匯出。每個路徑都會在本地凍結資產,使渲染保持確定性。分鏡重建將第一階段的資產匯出(REST)與代理驅動的時間軸組合相結合 — 不需要連接器。現有的凍結資產、清單記錄和綁定不受路由變更影響 — 拆分只會改變下一個匯入所使用的憑證。
認證 — 兩種憑證,作用域限定
預檢 — 在第一次 CLI 呼叫之前,檢查 token 是否存在:shell 環境變數([ -n "$FIGMA_TOKEN" ])或專案的 .env 檔案(CLI 會自動載入 — .env 條目即視為已配置)。如果都沒有,請勿執行命令來捕獲錯誤 — 先引導使用者完成一次性設定,然後停止並等待:
- figma.com/settings → 安全性 → 個人存取權杖 → 產生新權杖。
- 範圍 — 唯讀是此整合所需的一切(它永遠不會寫入 Figma):檔案內容:唯讀 + 檔案中繼資料:唯讀。如果你將在非 Enterprise 方案上執行
tokens,請加上函式庫內容:唯讀 — 發布樣式回退會命中/v1/files/:key/styles,沒有此範圍會返回 403(舊版設定文字遺漏的範圍)。可選地加上變數:唯讀以取得品牌變數 — 僅限 Enterprise;沒有它,tokens會自動降級為發布樣式(預期行為,非錯誤 — 請告知)。403 錯誤現在會指出確切缺少的範圍;429 錯誤會自動重試(每分鐘限制,遵循Retry-After)。 - 讓使用者在他們的 shell profile 或專案
.env中設定FIGMA_TOKEN;切勿要求他們將 token 貼到對話中。
在入職時,也請一口氣設定好期望:每次匯入都會以帶有記錄來源的本地凍結檔案形式落地 — 渲染永遠不會呼叫 Figma,重新執行命令只會重新匯入 Figma 中已變更的內容,且一個 token 即可用於資產、品牌權杖及其 Figma 帳戶可檢視的所有檔案中的元件。
- 第 4–5 階段(動態/著色器): 一個相容的 Figma 連接器,其授權與 token 分開。如果它不可用或未經認證,要求使用者連接它或提供原生匯出,然後停止。
- 確切說明失敗階段需要哪個憑證 — 切勿將拆分描述為損壞。
- 流程中出現
BAD_TOKEN(401)→ token 已過期/被撤銷;重新產生。FORBIDDEN(403)→ 訊息指出確切缺少的範圍(例如,樣式回退的library_content:read)— 添加它,或該檔案對該帳戶不可見。REQUIRES_ENTERPRISE(變數上的 403)→ 不是失敗:樣式回退已執行。RATE_LIMITED(429)→ 客戶端已使用退避重試(這適用於每次讀取 — 資產、權杖、樣式、節點樹、版本 — 重試位於共享請求路徑中;遵循Retry-After,上限為 60 秒);如果仍然出現,請等待一分鐘或每次呼叫匯入較少的節點。
速率限制意識(規範 §2.1): 連接器配額因 Figma 方案而異 — 批次處理父影格請求,除非被要求否則跳過驗證截圖,並快取原始回應,以便重新推導永遠不會花費第二次呼叫。REST 是每分鐘的(10+ 次/分鐘,每個端點有各自的桶)— 在高容量下可行,遇到 429 時退避。
路由
使用 parseFigmaRef(URL、fileKey:nodeId、裸 fileKey)解析使用者的 figma 連結。然後根據意圖:
- "使用這個圖層 / 標誌 / 圖片" → 資產 (CLI)
- "提取我的品牌 / 顏色 / 權杖" → 權杖 (CLI)
- "從這個影格建立場景" → 元件 (CLI)
- "匯入這個動畫 / 動態" → 動態(連接器可用時,見下文)
- 分鏡區段 / 場景影格的影片條 → 分鏡(見下文)
- 著色器填充/效果 → 著色器(見下文)
為使用者說明每個步驟 — 在每個命令之前,說明你將從 Figma 提取什麼;在命令之後,說明工件落到了哪裡(凍結路徑 / sidecar / 元件目錄)、合成中發生了什麼變化,以及接下來的立即動作(預覽、添加列印變數、重新匯入以連結綁定)。使用者永遠不應需要問 "成功了嗎?" 或 "現在呢?"。
資產(第 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 "<是什麼>"(它成為索引行 + <img alt>);為命名的品牌標記添加 --entity "<名稱>",以便稍後媒體使用的 resolve --entity 能找到它們(實體匹配跨圖片/圖示運作)。
在一個請求中批次處理多個節點 — 傳遞同一檔案的多個引用(空格分隔或逗號連接):hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。所有內容在單次 /v1/images 呼叫中渲染,這是 figma 自身對每分鐘速率限制的解決方案 — 在提取整個影格的資產時,優於 N 個單獨命令。--description/--entity 應用於批次中的每個節點,因此請批次處理共享相同用途的節點。429 錯誤無論如何都會自動退避重試。
權杖(第 2 階段 — CLI)
hyperframes figma tokens <fileKey>
將變數匯入為合成品牌變數條目 + figma-tokens.json sidecar + 綁定索引記錄(.media/figma-bindings.jsonl)。變數在上游是 Enterprise 專屬的:在其他方案上,此命令會降級為發布樣式中繼資料(值在元件匯入時解析)。將列印的條目添加到合成的 data-composition-variables。
在也需要元件之前匯入權杖 — 這能讓元件顏色連結到品牌變數,而不是烘焙複本。
非 Enterprise 變數路徑(經過實戰測試): REST 變數是 Enterprise 專屬的,但相容的連接器可能提供變數定義。當 tokens 報告 REQUIRES_ENTERPRISE 且連接器可用時,檢索父場景的變數一次,將原始回應快取到 .media/figma-cache/,並使用它來建立綁定索引。REST 節點樹的 boundVariables 提供每個屬性的 VariableID;按節點和屬性連接它們,然後寫入 .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)— 品牌更新會傳播。 - 綁定到未知的權杖 → literal +
data-figma-unresolved標記。命令會告訴你;提供使用者選項:對來源(或函式庫)檔案執行tokens,然後重新匯入元件以連結它們。對每個未知函式庫詢問一次是哪個檔案 — 切勿猜測,切勿按十六進位制比對。
動態(第 4 階段 — 連接器輔助)
使用信標: 連接器輔助階段沒有 CLI 接觸點,因此在開始和結束時觸發技能信標(匿名、需同意、絕不失敗):開始時執行 npx hyperframes events --skill=figma-motion,結束時執行 npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error。著色器(figma-shaders)和分鏡(figma-storyboard)同理。
沒有等效的 REST。當相容的連接器可用時,使用它並將其輸出傳遞給 @hyperframes/core/figma 中的純粹輔助函數;否則要求原生匯出:
- 在一個遞迴請求中檢索父影格的動態上下文,而不是每個元素一個請求。將原始 JSON 儲存在專案旁邊(
.media/figma-cache/),以便重新翻譯是免費的。 - 使用
@hyperframes/core/figma中的motionContextToDocs(rawResponse, { selectorFor, repeat })標準化為MotionDoc— 切勿手動轉錄關鍵幀編號。這個輔助函數機械式地編碼了經過實戰測試的解碼規則:它解析 motion.dev 片段(可靠的編碼 — CSS 片段會拉伸持續時間且可能不一致;它們被忽略),剝離循環包裝的尾部關鍵幀(時間 ≈0.9999→1 的次毫秒片段是循環的即時重置,非編寫的動態 — 包裝是透過repeat重新啟動實現的),並逐字保留貝塞爾緩動。selectorFor必須返回第 3 階段元件匯入的 ID — 不要從節點名稱推導選擇器。 2b. 在宣告完成之前,必須根據基準真相進行驗證:透過可用的連接器匯出群組的根影格,並執行node <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y— 它比較動作能量差異(靜態匯入保真度抵消),並在低於 15dB 最小動作 PSNR 時失敗(校準後:忠實 ≈ 20+,偏差 ≈ 5)。從渲染實際的卡片邊緣測量--crop,不要猜測。失敗意味著重新檢查翻譯,而不是閾值。 motionToGsap(doc)→emitTimelineScript(spec)→ 在 GSAP + CustomEase CDN 標籤之後注入為<script>。暫停、有限、使用文字鍵註冊在window.__timelines上。- 無法翻譯的軌道(著色器驅動、不支援的屬性、複雜遮罩)→ 透過連接器匯出,凍結 MP4,然後將其嵌入為
<video class="clip">。例外:著色器驅動的軌道 — Figma 的匯出路徑會將著色器扁平化為基礎顏色(請參閱下方的著色器),因此那裡的烘焙會悄悄地丟失著色器;改為要求使用者進行原生 Figma 匯出。務必說明你使用了哪個路徑及其原因。映射集合外的已命名緩動會回退為線性 — 對應表位於motionEase.ts;當它觸發時,向使用者標記此回退。 - 在宣告完成之前執行
npx hyperframes check。
著色器(第 5 階段 — 主要為手動)
Figma 的連接器渲染路徑不會執行著色器(它們會扁平化為基礎顏色),且著色器源碼僅對函式庫發布的樣式(付費完整席位)可達。預設路徑:要求使用者在 Figma 中原生匯出著色器影格(PNG 或動態 MP4),然後將其匯入為第 1 階段的資產 / 剪輯。不要嘗試連接器像素捕獲著色器 — 它會悄悄地產生錯誤結果。
分鏡(場景影格的區段 → 動畫)
核心規則:分鏡影格是關鍵影格,而非投影片。 包含相同元素的兩個影格描述了該元素隨時間變化的狀態 — 在狀態之間為該元素製作動畫;絕不能將影格作為一系列靜止影像播放。一個以遞減的 y 繪製在四個連續影格中的標誌,是一個元素在四個關鍵影格中上升。連續播放分鏡影格是失敗模式;重建它們所暗示的元素時間軸才是目標。
分鏡檔案遵循一個你可以機械式解析的文法 — 不要用眼睛看,要解碼:
- 場景單位:在區段內部,每個影格大小的節點都是一個場景 — 包括命名的 FRAME 和 鬆散的全影格 RECTANGLE(設計師直接將靜止影像貼入區段)。按大小過濾(≈ 合成長寬比,例如 >1400×900),而不是按節點類型或名稱。
- 順序 = x 位置(如果條帶包裝,則為行主序)。按
absoluteBoundingBox.x對場景排序。 - 比較相鄰場景以找出哪些元素發生了變化,以及如何變化:
- 相同 figmaId 且相同屬性 → 沒有動態(可能是背景或全域覆蓋層)。
- 相同 figmaId 但屬性不同 → 元素的關鍵影格(位置、縮放、旋轉、不透明度)。
- 一個場景中有 figmaId 而另一個沒有 → 進入/退出。
- 對每個在連續場景之間變化的元素:
- 使用
figma component <nodeId>將其作為元件匯出(如果尚未匯出),追蹤其 figmaId。 - 從場景的
absoluteBoundingBox和effects推導其關鍵影格屬性。 - 使用 GSAP 時間軸在關鍵影格之間製作該元素的動畫,將隱含的狀態轉換為補間。
- 使用
- 處理進入/退出:僅在一個場景中出現的元素應在其出現的場景中從適配狀態(例如,對於位置變化,從其最終位置開始)補入,並在消失的場景中補出到適配狀態。全生命週期補間根據需要穿過場景。
- 結果是一個
<script>區塊,定義一個 GSAP 時間軸,該時間軸逐步播放這些元素補間。
分鏡失敗模式辨識: 如果解析結構時遇到困難(未知節點類型、非標準屬性、模糊的邊界),請要求使用者透過 Figma 的原生匯出功能匯出分鏡區段為 MP4,然後將其匯入為第 1 階段的資產。在 .media/index.md 中將其標記為 "storyboard-export"。切勿猜測結構 — 透過匯出請求和緩降級。
已知限制
- 文字渲染:如上所述,文字邊界框是已知的漂移軸 — 對於主要內容,務必與基準真相像素進行比較。
- 混合模式:Figma 的混合模式子集映射到 CSS
mix-blend-mode;不支援的模式會回退為normal。標記任何回退。 - 自動版面:元件匯出會解析 flex 屬性,但高度動態的自動版面配置(文字換行、容器增長)在 HTML/CSS 中可能匹配不上 figma 的渲染 — 這是另一個驗證點。
- 原型互動:不會匯入原型連結、點擊區域或過渡。僅關注視覺狀態。
- Figma 變數(非 Enterprise):只能透過連接器取得;REST 路徑會降級為發布的樣式。