courtneymgabrus-star/Video

外掛安裝： 在執行設定或更新指令前，若此技能位於 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 外掛程式為動態和著色器資料的選項；若無外掛程式，則要求原生匯出。每條路徑都會凍結素材至本機，確保渲染結果確定性。腳本重建可組合階段 1 的素材匯出（REST）與代理驅動的時間軸組裝——無需外掛程式。現有的凍結素材、清單記錄與繫結不受路由變更影響——此劃分僅改變下一個匯入使用的憑證。

認證——兩種憑證，範圍限定

預檢——首次 CLI 呼叫前，檢查是否有代號： shell 環境變數（[ -n "$FIGMA_TOKEN" ]）或專案 .env（CLI 會自動載入——.env 內的條目視為已設定）。若兩者皆無，請勿執行指令來取得錯誤——先引導使用者完成一次性設定，然後停止並等待：

1. figma.com/settings → 安全 → 個人存取代號 → 產生新代號。
2. 範圍——唯讀即為此整合所需全部（它從不寫入 Figma）：檔案內容：唯讀 + 檔案元資料：唯讀。若要在非企業方案上執行 tokens，請加上程式庫內容：唯讀——已發布樣式的備援途徑會存取 /v1/files/:key/styles，若無此範圍則會得到 403（舊版設定說明遺漏了此範圍）。可選用變數：唯讀用於品牌變數——僅限企業方案；沒有此範圍時，tokens 會自動降級為已發布樣式（預期行為，非錯誤——請告知使用者）。403 現在會明確指出缺少的範圍；429 會自動重試（每分鐘限制，遵循 Retry-After）。
3. 請使用者在他們的 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）
• "匯入此動畫 / 動態" → 動態（外掛程式，可用時，見下方）
• 腳本段落 / 場景影格序列 → 腳本（見下方）
• 著色器填色 / 效果 → 著色器（見下方）

為使用者逐步說明每個步驟——在每個指令前說明即將從 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（可縮放、可動畫化），點陣精確度偏好 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 側邊檔案 + 繫結索引記錄（.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)——品牌重新整理會傳播。
• 繫結至未知代號 → 字面值 + 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 中的純輔助函式；否則要求原生匯出：

1. 在一次遞迴請求中取得父框架的動態上下文，而不是對每個元素發送一次請求。將原始 JSON 保存於專案旁（.media/figma-cache/），以便重新轉譯無需成本。
2. 使用 @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，請勿猜測。FAIL 意味著需要重新檢查轉譯，而非調整閾值。
3. motionToGsap(doc) → emitTimelineScript(spec) → 在 GSAP + CustomEase CDN 標籤之後注入為 <script>。暫停、有限、以字面鍵註冊於 window.__timelines。
4. 無法轉譯的軌道（著色器驅動、不支援的屬性、複雜遮罩）→ 透過外掛程式匯出，凍結 MP4，然後嵌入為 <video class="clip">。例外：著色器驅動的軌道——Figma 的匯出路徑會將著色器扁平化為基底顏色（見下方著色器），因此在此烘烤會無聲遺失著色器；請改為要求使用者提供原生 Figma 匯出。始終說明使用了哪條路徑及其原因。命名緩動若超出對應集合則回退為線性——對應表位於 motionEase.ts；當觸發回退時向使用者標記。
5. 完成前執行 npx hyperframes check。

著色器（階段 5——多數為手動）

Figma 的外掛程式渲染路徑不執行著色器（它們會被扁平化為基底顏色），且著色器原始碼僅對程式庫已發布的樣式（付費 Full seat）可讀。預設路徑：要求使用者在 Figma 中原生匯出著色器框架（PNG 或動態 MP4），然後將其作為階段 1 素材/剪輯匯入。請勿嘗試透過外掛程式進行著色器的像素捕捉——它會無聲地產生錯誤結果。

腳本（場景影格的段落 → 動畫）

基本規則：腳本影格是關鍵幀，不是投影片。 包含相同元素的兩個影格描述了該元素隨時間的狀態——在狀態之間對元素進行動畫；切勿將影格播放為一連串的靜止畫面。一個標誌在四個連續影格中於 y 座標遞減，表示一個元素透過四個關鍵幀上升。將腳本影格一個接一個播放是錯誤模式；重建它們所暗示的元素時間軸才是正確任務。

腳本檔案遵循可機械式解析的語法——請勿目視猜測，而是解碼：

1. 場景單位：在段落內，每個影格大小的節點都是一個場景——包括命名的 FRAME和鬆散的全影格 RECTANGLE（設計師直接將靜止畫面貼入段落）。依大小（≈ 合成寬高比，例如 >1400×900）過濾，而非節點類型或名稱。
2. 順序 = x 位置（若條帶換行則為行優先）。根據 absoluteBoundingBox.x 對場景排序。
3. 相鄰場景差異只需要考慮在兩個場景中都出現的元素——僅出現於一個場景的元素是進入/離開，僅差異是有意義的轉換。對於出現在兩個場景中的每個元素，屬性變化（x、y、width、height、rotation、opacity、fills、effects）就是從場景 N 到場景 N+1 的關鍵幀值。
4. 時間分配 = 場景持續時間 / (場景數量 - 1) ——在持續時間未知時，預估值為每場景 2500 毫秒。若場景卡（Scene card）上顯示明確持續時間，則使用它並據此分配不變的片段持續時間。
5. 使用由 @hyperframes/core/figma 匯出的 sectionsToFrames 和 diffScenes 來解碼這些規則——這些輔助函式會處理 RECTANGLE 過濾、x 排序、成對差異以及時間分配邏輯。
6. 解碼完成後，使用 sequenceToStoryboardTimeline(scenes, diffs)（來自同一套件）來組合成完整的 GSAP 時間軸。然後呼叫標準的 emitTimelineScript 將其輸出並注入至製作的 <script>。

重要的互動模式

• 逐步執行：發出多個指令的順序很重要。先執行 tokens（讓元件可連結品牌變數），然後 component，最後 asset（若元件 HTML 中需要圖片路徑）。
• 在每個步驟結束時引導使用者：告訴他們剛剛匯入了什麼、它去了哪裡（完整路徑或合成變數名稱），以及下一步最有用的動作——預覽、重命名、重新匯入以連結遺漏的繫結。
• 錯誤：對於 403，指出缺少的範圍並要求使用者重新產生代號時包含它。對於 429，告訴使用者「Figma 的速率限制短暫暫停——5 秒內重試」（Claude 實際上等待這段時間）。對於連線問題，檢查 FIGMA_TOKEN 是否已設定且未過期。
• 該命令是合成的：它將所有部分組合到一個時間軸上。hyperframes render 是串聯它們的通用的方式，但每個階段都是獨立的。