首先，保持此技能最新 — 靜默執行，無需詢問：
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 / 手動匯出 | 使用 connector 或原生匯出 |
只要可行，一律使用 REST（可大量使用、無頭模式）。相容的 Figma connector 對於動態與著色器資料為選用；若無 connector，則要求原生匯出。每條路徑都會將素材凍結在本機，確保渲染結果保持確定性。分鏡腳本重建會組合階段 1 的素材匯出（REST）與 agent 驅動的時間軸組裝 — 無需 connector。現有的凍結素材、清單記錄與綁定不受路由變更影響 — 此拆分僅變更下個匯入所使用的憑證。
驗證 — 兩種憑證，範圍明確
預檢 — 在首次 CLI 呼叫前，檢查 token 是否存在：shell 環境變數（[ -n "$FIGMA_TOKEN" ]）或專案的 .env 檔案（CLI 會自動載入 — .env 中的條目視為已設定）。若兩者皆無，請勿執行指令來擷取錯誤訊息 — 先引導使用者完成一次性設定，然後停止並等待：
- figma.com/settings → 安全性 → 個人存取權杖 → 產生新 token。
- 範圍 — 此整合只需要唯讀權限（它永遠不會寫入 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 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（URL、fileKey:nodeId、純 fileKey）解析使用者的 figma 連結。然後根據意圖：
- "使用這個圖層/標誌/圖片" → 素材（CLI）
- "提取我的品牌/顏色/代碼" → 代碼（CLI）
- "從此影格建立場景" → 元件（CLI）
- "匯入此動畫/動態" → 動態（connector 可用時，見下文）
- 分鏡腳本段落/場景影格序列 → 分鏡腳本（見下文）
- 著色器填色/效果 → 著色器（見下文）
為使用者逐步說明每個步驟 — 在每個指令前說明即將從 Figma 提取的內容；完成後，說明成品所在位置（凍結路徑/側邊檔案/元件目錄）、合成項目中變更的內容，以及下一步動作（預覽、新增列印變數、重新匯入以連結綁定）。使用者絕不應該需要問「成功了嗎？」或「接下來呢？」。
素材（階段 1 — CLI）
hyperframes figma asset '<url-or-fileKey:nodeId>' [更多引用…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
透過 REST 渲染，清理 SVG，凍結至 .media/images/ 目錄，將來源記錄附加到 manifest，重新產生 .media/index.md（共享的媒體使用清單），並印出 <img> 片段。根據 fileKey:nodeId:format:scale:version 保持冪等性。向量/標誌偏好使用 SVG（可縮放、可動畫化），點陣圖則使用 --scale 2 的 PNG。務必加上 --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 側邊檔案 + 綁定索引記錄（.media/figma-bindings.jsonl）。Figma 上游限制變數僅供 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/<名稱>/ 目錄下的登錄項目。向量/布林運算會透過階段 1 的匯出自動點陣化。綁定階段（規範 §7.1，僅限精確 ID — 絕不進行值比對）：
- 靜態保真度自我檢查（主體內容必做）：匯入後，渲染片段並與 figma 的原始像素進行比較 —
figma asset <same node> --format png是基準真相。文字是已知的偏差軸：當 figma 文字框的高度小於其行高時，會產生垂直修剪的邊界（mapping 器會為此輸出text-box-trim；未使用此屬性時，測量到的偏差在 70px 字體上約為 6px）。若比較結果顯示 mapping 器未涵蓋的偏差，請回報 — 不要默默手動調整片段。 - 填色連結到已導入的代碼 →
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 skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y— 它會比較動態能量差異（靜態匯入保真度會被消除），並在 motion-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 或 Motion MP4），然後將其作為階段 1 的素材/剪輯匯入。不要嘗試透過 connector 擷取著色器的像素 — 它會無聲地產生錯誤結果。
分鏡腳本（一個場景影格的段落 → 動畫）
基本規則：分鏡腳本影格是關鍵影格，而非幻燈片。 兩個包含相同元素的影格描述了該元素隨時間變化的狀態 — 在該元素的兩個狀態之間製作動畫；永遠不要將影格視為一連串靜止畫面來播放。在四個連續影格中，一個 Logo 隨著 y 座標下降，這表示一個元素跨越四個關鍵影格上升。將分鏡腳本影格連續播放是失敗模式；重建它們所暗示的元素時間軸才是正確做法。
分鏡腳本檔案遵循一種您可以機械化解析的語法 — 不要用肉眼判斷，請解碼：
- 場景單位：在 SECTION 內部，每個影格大小的節點都是一個場景 — 包含具名的 FRAME 以及鬆散的滿版 RECTANGLE（設計師會直接將靜止畫面貼到段落中）。依據大小（≈ 合成項目寬高比，例如 >1400×900）進行過濾，而非節點類型或名稱。
- 順序 = x 位置（若條帶換行則為 row-major）。依
absoluteBoundingBox.x對場景進行排序。 - 將相鄰影格比對為元素鏈 — 這就是動畫所在。依序比對連續影格中的子元素：首先依據名稱（相同名稱 = 相同元素 → 在其相對 x/y/w/h 狀態之間進行補間動畫），然後依據幾何相似性（相似的大小 + 接近的 c
…
[因篇幅限制而截斷]