外掛安裝： 在執行設定或更新命令之前，若此技能位於 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 | 連接器（可用時） | 使用其 motion 上下文 |
| 5 | 著色器 | 連接器 / 手動匯出 | 使用它或原生匯出 |
盡可能使用 REST（可大量使用、無頭）。兼容的 Figma 連接器對動畫和著色器數據為可選；若無，則要求原生匯出。每個路徑都會將素材凍結在本地，以確保渲染具有確定性。故事板重建組合第一階段的素材匯出（REST）與代理驅動的時間軸組裝 — 無需連接器。現有的凍結素材、清單記錄和綁定不受路由變更影響 — 拆分僅會變更下一個匯出所使用的憑證。
授權 — 兩個憑證，範圍限定
前置檢查 — 在首次 CLI 調用前，檢查令牌是否存在：shell 環境變數 ([ -n "$FIGMA_TOKEN" ]) 或 專案 .env 檔案（CLI 會自動載入 — .env 條目即視為已設定）。若兩者皆無，請勿執行命令去捕獲錯誤 — 先引導使用者完成一次性設定，然後停止並等待：
- figma.com/settings → Security → Personal access tokens → 產生新令牌。
- 範圍 — 此整合僅需要唯讀權限（它從不寫入 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；切勿要求他們將令牌貼到對話中。
在引導過程中，一口氣設定好期望：每次匯入都會產生一個帶有記錄來源的本地凍結檔案 — 渲染永不呼叫 Figma，重新執行命令僅會重新匯入 Figma 中有變更的部分，一個令牌即可用於其 Figma 帳戶能檢視的所有檔案的素材、品牌代碼和元件。
- 階段 4–5（動畫/著色器）： 一個兼容的 Figma 連接器，其授權與令牌分開。若它不可用或未經認證，請要求使用者連接它或提供原生匯出，然後停止。
- 務必明確指出失敗階段所需的是哪個憑證 — 切勿暗示拆分有問題。
BAD_TOKEN（401）流程中斷 → 令牌已過期/撤銷；重新產生。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）
- "匯入這個動畫" → 動畫（連接器可用時使用，見下文）
- 故事板章節 / 場景影格的 filmstrip → 故事板（見下文）
- 著色器填充/效果 → 著色器（見下文）
為使用者解說每個步驟 — 在每個命令前說明您即將從 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（可縮放、可動畫），點陣圖則偏好 PNG --scale 2 以獲得保真度。務必傳遞 --description "<這是什麼>"（它會成為清單列與 <img alt>）；對於有命名的品牌標記，加上 --entity "<名稱>"，以便 media-use 的 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>/ 下的註冊表項目。向量/布林運算透過第一階段匯出自動點陣化。綁定階段（規格 §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重啟實現的），並逐字保留貝茲曲線的 easing。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 匯出。始終說明您使用了哪個路徑及其原因。不在映射集合內的命名 easing 會降級為線性 — 映射表位於motionEase.ts中；當其觸發時，請向使用者標明此降級。 - 在宣告完成前，執行
npx hyperframes check。
著色器（階段 5 — 主要為手動）
Figma 的連接器渲染路徑不會執行著色器（它們會被扁平化為基礎顏色），且著色器原始碼僅能透過函式庫發布的樣式（付費 Full seat）取得。預設路徑：要求使用者原生在 Figma 中匯出著色器影格（PNG 或動畫 MP4），然後將其作為第一階段的素材/剪輯匯入。不要嘗試透過連接器像素捕捉著色器 — 它會默默地產生錯誤的結果。
故事板（場景影章的 SECTION → 動畫）
首要規則：故事板影格是關鍵影格，不是投影片。 包含相同元素的兩個影格描述了該元素隨時間變化的狀態 — 對該元素在各狀態之間進行動畫；絕不要將影格播放為一連串的靜止畫面。一個在四個連續影格中以遞減 y 值繪製的標誌是一個元素在四個關鍵影格中上升。將故事板影格連續播放是失敗模式；重構它們所暗示的元素時間軸才是任務。
故事板檔案遵循一種您可以機械式解析的文法 — 不要用眼看，要解碼：
- 場景單元：在 SECTION 內，每個影格大小的節點都是一個場景 — 包含命名的 FRAME 和鬆散的全影格 RECTANGLE（設計師會將靜止畫面直接貼到章節中）。按大小（≈ 合成寬高比，例如 >1400×900）過濾，而非按節點類型或名稱。
- 順序 = x 位置（若膠卷條換行則為行主序）。按
absoluteBoundingBox.x排序場景。 - 比較相鄰場景 — 任何兩個影格中同名的元素（由
name或 figma id 配對）都是該元素的關鍵影格。一個元素在影格 N 中存在但在影格 N+1 中不存在意味著在 N 處退場；出現在 N+1 但不在 N 中意味著在 N+1處入場。 - 跨場景屬性解析：
fills,strokes,position,rotation,opacity（增強的屬性是開放式的；將motionEase.ts映射套用到每個屬性）。在影格之間僅插值可動畫的屬性 — 忽略固定屬性。 - 產生時間軸：
- 連續的影格索引 → 持續時間 = 影格跨度 × （如果使用者指定了節拍/秒，則為基於文字的節拍，否則為每個場景影格 1 秒）。
- 入場 →
from（在影格索引 -1 處隱藏，在影格 0 處動畫進入）；退場 →to（在影格索引 +1 處動畫退出）。 - 跨越多個影格的元素獲得
to/from序列。 - 使用
motionToGsap(doc)作為基礎，並以StoryboardTimeline包裝器進行補充。 - 注入為一個 GSAP
<script>。
劇本: 提交一個場景拍攝序列命令（hyperframes figma storyboard <fileKey:sectionNodeId>），該命令：
- 解析章節
- 匯出關鍵影格：在一次呼叫中，使用
hyperframes figma asset批次取得所有場景，而不是 N 個單獨的命令 - 映射動畫
- 將時間軸架設到 GSAP
- 執行
npx hyperframes check
階段 1–3 的 REST 命令也可用於對組成故事板的場景影格進行更精細的迭代和元資料注入。若無章節（例如僅為單一影格），則使用 hyperframes figma component。