首先,保持此技能新鮮 — 請先與使用者確認後再執行:
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 外掛對於動畫和著色器資料為選用;若無外掛,則要求原生匯出。每個路徑都會在本機凍結資產,確保渲染結果確定性。分鏡重建會結合階段-1 資產匯出(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 設定檔或專案
.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 方案而異 — 請批次處理父影格請求,除非被要求,否則跳過驗證截圖,並快取原始回應,以便重新推導時無需再次耗費 API 呼叫。REST 為每分鐘限制(每分鐘 10+ 次,依端點劃分桶)— 可應付大量請求,但遇到 429 時請退避。
路由
使用 parseFigmaRef 解析使用者的 figma 連結(URL、fileKey:nodeId、純 fileKey)。然後根據意圖:
- "使用這個圖層 / 標誌 / 圖片" → 資產(CLI)
- "拉取我的品牌 / 顏色 / 標記" → 標記(CLI)
- "從這個影格建立一個場景" → 元件(CLI)
- "匯入這個動畫 / 動態" → 動畫(外掛,若可用,見下文)
- 一個分鏡區段 / 場景影格序列 → 分鏡(下文)
- 著色器填充/效果 → 著色器(下文)
為使用者逐步說明每個步驟 — 在每個命令前告知即將從 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(可縮放、可動畫化),點陣圖偏好使用 --scale 2 的 PNG。務必傳遞 --description "<這是什麼>"(它會成為索引行 + <img alt>);為命名的品牌標記加上 --entity "<名稱>",以便後續的媒體使用 resolve --entity 能找到它們(實體匹配可跨圖片/圖示)。
在單一請求中批次處理多個節點 — 傳遞同一檔案的多個引用(空格分隔或逗號連接):hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。所有節點會在單次 /v1/images 呼叫中渲染,這是 Figma 自身應對每分鐘速率限制的方案 — 當需要提取整個影格的資產時,優先使用此法而非多個分開的命令。--description/--entity 會套用至批次中的每個節點,因此請將共享相同用途的節點分批處理。429 錯誤無論如何都會自動重試並退避。
標記(階段 2 — CLI)
hyperframes figma tokens <fileKey>
將變數匯入為合成場景的品牌變數條目 + figma-tokens.json 側邊檔案 + 繫結索引紀錄(.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>'
節點樹 → 可編輯的 HTML,保持 Figma 精確的幾何尺寸,封裝為 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 — 外掛輔助)
使用信標: 外掛輔助階段沒有 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 skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y— 它會比較動態能量差異(靜態匯入保真度會抵消),若最小動態 PSNR 低於 15dB 則視為失敗(校準:忠實 ≈ 20+,偏差 ≈ 5)。從渲染的實際卡片邊緣測量--crop,不要猜測。FAIL 表示需要重新檢查翻譯,而非調整閾值。 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對場景排序。 - 將相鄰影格差異化為元素鏈 — 這是動畫所在之處。跨連續影格比對子元素:首先按名稱(相同名稱 = 相同元素 → 在其相對 x/y/w/h 狀態之間進行補間);然後按幾何相似性(相似大小和位置,但名稱不同 → 提示使用者確認或手動建立)。產生一個元素時間軸列表,每個時間軸都包含其關鍵影格狀態。
- 組合。對於每個場景,將其元件的節點樹轉換為階段 3 元件匯入(必要時使用階段 1 資產的後備靜態圖片)。然後,對於每個元素鏈,使用階段 4 的 GSAP 時間軸生成器在組合的關鍵影格之間建立補間動畫。結果應是一個流暢的動畫,其元素從一個場景無縫移動、縮放、淡入淡出到另一個場景,而不是一系列跳轉的幀。
- 輸入:一段 Figma 連結,指向一個包含多個場景影格的區段。輸出:一個 HyperFrames 合成場景,其時間軸已初始化為播放分鏡。
連鎖規則:如果一個元素僅出現在一個影格中,則將其視為幻燈片(在最後一個已知狀態持續,直到其場景開始,在場景期間顯示,然後立即消失 — 無補間)。除非被要求,否則不要添加浮誇的過渡效果 — 僅反映設計者的意圖。
邊緣案例與常見問題
- 圖層混合模式:Figma 的 REST API 不提供
blendMode;我們依賴外掛或原生匯出的點陣化渲染作為後備。 - 文字變體與外框化:如果 Figma 文字使用了 web 字型,且該字型無法使用(已外框化或遺失),則回退為連字型的點陣化 SVG/PNG。
- 大量匯入:如果使用者要求「匯入我的整個設計系統」,請依序執行
tokens→component(針對每個必要節點),並在每個步驟之間提供清晰的進度。如果清單超過 50 個元件,請批次處理或詢問是否需要子集。 - 協作:如果使用者與他人協作,請提醒他們 Figma token 的範圍權限可能不足以存取其他使用者的元件庫。