外掛安裝: 在設定或更新命令之前,若此技能位於 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 | 有 Connector 時使用 | 使用其動畫上下文 |
| 5 | 著色器 | Connector / 手動匯出 | 使用它或原生匯出 |
盡可能使用 REST(可大量使用、無頭操作)。相容的 Figma Connector 可選用於動畫與著色器資料;如果沒有,則要求進行原生匯出。每個路徑都會在本機凍結素材,確保渲染結果可預測。分鏡腳本重建會將階段 1 的素材匯出(REST)與代理驅動的時間軸組裝結合 — 無需 Connector。現有的凍結素材、清單記錄和綁定不受路由變更影響 — 分離只會改變下一次匯入所使用的憑證。
授權 — 兩種憑證,各有範圍
前置檢查 — 在首次 CLI 調用前,確認 token 是否存在:shell 環境變數([ -n "$FIGMA_TOKEN" ])或專案 .env 檔案(CLI 會自動載入 — .env 中的條目即視為已設定)。如果兩者都沒有,請勿執行命令來收集錯誤 — 先引導使用者完成一次性設定,然後停止並等待:
- figma.com/settings → Security → Personal access tokens → 產生新 token。
- 範圍 — 此整合永遠只需要唯讀權限(它永遠不會寫入 Figma):File content: Read-only + File metadata: Read-only。如果您要在非 Enterprise 方案上執行
tokens,請加上 Library content: Read-only — 已發布樣式的備用方案會使用/v1/files/:key/styles,如果沒有此權限會回傳 403(這是舊版設定文字遺漏的範圍)。可選用 Variables: Read-only 用於品牌變數 — 僅限 Enterprise 方案;沒有此權限時,tokens會自動降級為使用已發布樣式(這是預期行為,不是錯誤 — 請告知使用者)。現在 403 錯誤會明確指出缺少的範圍;429 錯誤會自動重試(根據每分鐘限制,遵循Retry-After標頭)。 - 請使用者在他們的 shell 設定檔或專案
.env中設定FIGMA_TOKEN;切勿要求他們將 token 貼到對話中。
在引導使用者入門時,也要一次說清楚期望:每次匯入都會產生一個帶有記錄來源的本機凍結檔案 — 渲染永遠不會呼叫 Figma,重新執行命令只會重新匯入 Figma 中已變更的內容,而且一個 token 就能跨他們 Figma 帳戶可查看的所有檔案,用於素材、品牌代碼和元件。
- 階段 4–5(動畫/著色器): 需要一個相容的 Figma Connector,其授權與 token 分開。如果 Connector 不可用或未經認證,請要求使用者連接 Connector 或提供原生匯出,然後停止。
- 明確指出失敗階段所需的是哪個憑證 — 切勿讓分離看起來像是故障。
BAD_TOKEN(401)發生在中途 → token 已過期或撤銷;需要重新產生。FORBIDDEN(403)→ 錯誤訊息會指出缺少的具體範圍(例如樣式備用方案的library_content:read)— 請加上該範圍,否則帳戶無法看到該檔案。REQUIRES_ENTERPRISE(變數的 403)→ 不是失敗:樣式備用方案已運作。RATE_LIMITED(429)→ 用戶端已使用退避機制重試(這適用於所有讀取 — 素材、代碼、樣式、節點樹、版本 — 重試邏輯位於共享的請求路徑中;會遵循Retry-After,最多等待 60 秒);如果仍持續發生,請等待一分鐘或減少每次呼叫匯入的節點數量。
速率限制意識(規格 §2.1): Connector 的配額因 Figma 方案而異 — 請批次處理父影格的請求,除非被要求否則跳過驗證截圖,並快取原始回應,以便重新推導時無需再次呼叫。REST 是每分鐘限制(每分鐘 10+ 次,每個端點有各自的儲存桶)— 大量使用時沒問題,遇到 429 時請退避。
路由
使用 parseFigmaRef 解析使用者的 figma 連結(URL、fileKey:nodeId、純 fileKey)。然後根據意圖:
- "使用這個圖層 / 標誌 / 圖片" → Asset(素材)(CLI)
- "取得我的品牌 / 顏色 / 代碼" → Tokens(代碼)(CLI)
- "從這個影格建立場景" → Component(元件)(CLI)
- "匯入這個動畫 / 動態" → Motion(動畫)(有 Connector 時使用,如下所示)
- 分鏡腳本區域 / 場景影格的連續畫面 → Storyboard(分鏡腳本)(如下所示)
- 著色器填充/效果 → Shaders(著色器)(如下所示)
為使用者解釋每個步驟 — 在每個命令前說明您即將從 Figma 拉取什麼;執行後說明素材放置的位置(凍結路徑 / sidecar 檔案 / 元件目錄)、合成中哪些部分已變更,以及接下來的立即動作(預覽、加入列印變數、重新匯入以連結綁定)。使用者永遠不應該需要問「成功了嗎?」或「接下來呢?」。
素材(階段 1 — CLI)
hyperframes figma asset '<url-or-fileKey:nodeId>' [更多 refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
透過 REST 渲染,清理 SVG,凍結在 .media/images/ 下,將來源資訊附加到清單,重新產生 .media/index.md(共享的媒體使用清單),並印出 <img> 片段。對 fileKey:nodeId:format:scale:version 組合具有冪等性。向量/標誌偏好使用 SVG(可縮放、可動畫化),點陣圖則使用 --scale 2 的 PNG 以獲得精細度。總是傳遞 --description "<這是什麼>"(它會成為索引列和 <img alt>);為命名的品牌標記加上 --entity "<名稱>",以便後續的媒體使用 resolve --entity 可以找到它們(實體比對適用於圖片/圖示)。
在一個請求中批次處理多個節點 — 傳遞數個相同檔案的 refs(空格分隔或以逗號連接):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 方案限制的,但相容的 Connector 可能提供變數定義。當 tokens 回報 REQUIRES_ENTERPRISE 且 Connector 可用時,擷取父場景的變數一次,將原始回應快取到 .media/figma-cache/,並用它來建立綁定索引。REST 節點樹的 boundVariables 會為每個屬性提供 VariableID;按節點和屬性連接它們,然後寫入 .media/figma-bindings.jsonl 行({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version})以及合成變數條目。所有下游處理(元件 var() 解析、更新、執行時期 CSS 變數)都是現成的機制。為使用者標示:「透過 Figma Connector 取得的代碼 — Enterprise 方案可從 hyperframes figma tokens 直接獲得。」
執行時期會將每個宣告的合成變數定義為 CSS 自訂屬性(文件根節點 + 子合成主機),因此當變數預設值變更時,匯入的 var(--slug, literal) 能自動填滿重新著色 — 只需更新 data-composition-variables 中的一個值,就能重新品牌化所有匯入的元件,無需重新匯入任何內容。hyperframes render --variables '<json>' 可在渲染時覆寫它們。
元件(階段 3 — CLI)
hyperframes figma component '<url-or-fileKey:nodeId>'
節點樹 → 可編輯的 HTML,具有精確的 figma 幾何尺寸,打包為 compositions/components/<name>/ 下的登錄檔項目。向量/布林運算會透過階段 1 的匯出自動柵格化。綁定傳遞(規格 §7.1,僅限精確 ID — 永不進行值比對):
- 靜態保真度自我檢查(重要內容強制執行): 匯入後,渲染片段並與 figma 自身的像素進行比較 —
figma asset <相同節點> --format png是標準答案。文字是已知的偏差軸:一個 figma 文字框如果比它的行高還短,其邊界會被垂直修剪(映射器會為此發出text-box-trim;若沒有它,實測偏差在 70px 字型上約為 6px)。如果比較結果顯示映射器未涵蓋的偏差,請回報 — 不要默默手動調整片段。 - 填充綁定到已匯入的代碼 →
var(--slug, #literal)— 品牌更新會自動傳播。 - 綁定到未知的代碼 → 字面值加上
data-figma-unresolved標記。命令會告訴您;提供使用者選擇:對來源(或函式庫)檔案執行tokens,然後重新匯入元件以連結它們。對每個未知函式庫詢問一次是哪個檔案 — 永遠不要猜測,也永遠不要根據十六進位顏色值進行比對。
動畫(階段 4 — Connector 輔助)
使用信標: Connector 輔助的階段沒有 CLI 接觸點,因此在開始和結束時觸發技能信標(匿名、需同意、不會失敗):開始時執行 npx hyperframes events --skill=figma-motion,完成時執行 npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error。著色器(figma-shaders)和分鏡腳本(figma-storyboard)也一樣。
沒有對應的 REST 等效功能。當有相容的 Connector 可用時,使用它並將其輸出傳遞給 @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. 在宣稱完成前,強制對基準真相進行驗證:透過可用的 Connector 匯出群組的根影格,並執行node <SKILL_DIR>/scripts/verify-motion.mjs --reference <匯出.mp4> --render <渲染.mp4> --crop WxH+X+Y— 它會比較運動能量差異(靜態匯入保真度會被抵消),若最小運動 PSNR 低於 15dB 則判定失敗(校準:保真度高 ≈ 20+,偏差大 ≈ 5)。從渲染的實際卡片邊緣測量--crop,不要猜測。失敗意味著需要重新檢查轉譯過程,而不是調整閾值。 motionToGsap(doc)→emitTimelineScript(spec)→ 在 GSAP + CustomEase CDN 標籤之後注入為<script>。暫停、有限次數、以文字鍵註冊在window.__timelines上。- 無法轉譯的軌道(著色器驅動、不支援的屬性、複雜遮罩)→ 透過 Connector 匯出,凍結為 MP4,然後嵌入為
<video class="clip">。例外情況:著色器驅動的軌道 — Figma 的匯出路徑會將著色器扁平化為基底顏色(請參閱下方的著色器說明),因此在該處烘焙會默默地遺失著色器;請要求使用者改用原生的 Figma 匯出。始終說明您使用了哪個路徑及其原因。已命名但超出對應範圍的緩動函式會回退為線性 — 對應表位於motionEase.ts;當發生回退時,請向使用者標示。 - 在宣告完成前執行
npx hyperframes check。
著色器(階段 5 — 主要是手動操作)
Figma 的 Connector 渲染路徑不會執行著色器(它們會被扁平化為基底顏色),而且著色器原始碼只有在已發布的函式庫樣式(付費 Full 席次)下才能存取。預設路徑:要求使用者在 Figma 中原生匯出著色器影格(PNG 或動畫 MP4),然後將其作為階段 1 的素材/剪輯匯入。不要嘗試使用 Connector 像素捕捉著色器 — 它會默默地產生錯誤的結果。
分鏡腳本(場景影格的區域 → 動畫)
基本規則:分鏡腳本影格是關鍵影格,不是投影片。 包含相同元素的兩個影格描述了該元素隨時間變化的狀態 — 在狀態之間為該 ELEMENT 製作動畫;永遠不要將影格播放為一連串靜止畫面。一個標誌在四個連續影格中,y 座標遞減,表示一個元素穿過四個關鍵影格向上移動。將分鏡腳本影格一個接一個播放是失敗模式;重建它們所暗示的元素時間軸才是工作目標。
分鏡腳本檔案遵循您可以機械式解析的文法 — 不要用肉眼判斷,請解碼:
- 場景單位:在 SECTION 內,每個影格大小的節點都是一個場景 — 包括命名的 FRAME 和鬆散的全影格 RECTANGLE(設計師直接將靜止畫面貼到區域中)。按尺寸過濾(≈ 合成長寬比,例如 >1400×900),而非按節點類型或名稱。
- 順序 = X 位置(如果條帶換行則為行優先順序)。按
absoluteBoundingBox.x對場景排序。 - 差異化相鄰場景:使用
hyperframes figma component(REST,無 Connector)匯入每個場景影格。然後,對於在兩個或多個匯入的元件中共享figmaId的每個元素,在該元素的屬性之間建立一個 GSAP 補間動畫,從一個場景跨越到下一個場景。文字的增長或縮小應使用 GSAP 為文字節點設置scale動畫,而不是fontSize,以保持可讀性。對於僅存在於一個影格中的元素,它會在該影格處具有不透明度補間動畫(淡入)或寬度/高度補間動畫(生長),具體取決於下一個場景中是否有明顯的對應元素。始終參考時間 = 場景時間(按 X 排序並標準化為 0–100%)。如果場景描述包含持續時間提示(例如 "0.5s" 或 "200ms"),請使用它;否則假設每個場景持續 1 秒。永遠不要在元素層級引入position: absolute— 由組合器處理。 - 防止常見陷阱: 具有漸層或陰影的文字會失去動畫效果 — GSAP 無法補間它們。透過 Connector 將這些文字烘焙為 PNG 素材,或者如果無法避免,則保持靜止。包含多個巢狀元素的場景影格應使用巢狀 GSAP 時間軸,而不是一個巨大的補間動畫。
- 匯出: 將產生的 GSAP 腳本注入為
<script>元素,類比於階段 4 的路徑。執行npx hyperframes check。將腳本編寫為模組,以正確進行範圍界定。 - 使用信標:
npx hyperframes events --skill=figma-storyboard。
分鏡腳本匯入是冪等的:在相同的一組場景上重新執行會覆蓋時間軸腳本,但永遠不會刪除未使用的素材。如果場景減少,請通知使用者。
使用 @hyperframes/core/figma: 此套件封裝了經過實戰測試的 figma 資料預處理邏輯(快取、速率限制、格式支援),適用於 REST 和 Connector 路徑。如果您的腳本顯式地對 materialized 或 figma-export 目錄進行了假設,請重構為使用核心輔助函式 — 目錄佈局不是公共 API。