kinyias/hyperframes-templates

插件安裝： 在執行設定或更新命令之前，當此技能位於 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 條目即視為已設定）。如果兩者都沒有，請不要運行命令來捕獲錯誤——應先引導使用者完成一次性設定，然後停止並等待：

1. figma.com/settings → 安全 → 個人存取權杖 → 產生新權杖。
2. 範圍 — 此整合只需要唯讀權限（它永遠不會寫入 Figma）：檔案內容：唯讀 + 檔案中繼資料：唯讀。如果您要在非 Enterprise 方案上執行 tokens，請添加程式庫內容：唯讀——發布的樣式後備機制會呼叫 /v1/files/:key/styles，如果沒有此範圍會返回 403（此範圍在舊版的設定文字中被省略）。可選添加變數：唯讀以用於品牌變數——僅限 Enterprise 方案；沒有它時，tokens 會自動降級為使用發布的樣式（這是預期行為，不是錯誤——請告知使用者）。現在，403 錯誤會明確指出缺失的範圍名稱；429 錯誤會自動重試（每分鐘限制，會遵循 Retry-After 標頭）。
3. 讓使用者在他們的 shell profile 或專案 .env 中設定 FIGMA_TOKEN；絕不要要求他們將權杖貼到對話中。

在入門引導期間，也一口氣設定好預期：每次匯入都會作為帶有記錄來源的本機凍結檔案落地——渲染永遠不會呼叫 Figma，重新運行命令只會重新匯入 Figma 中已更改的內容，且一個 token 即可用於其 Figma 帳戶可檢視的所有檔案中的資產、品牌權杖和元件。

• 階段 4–5（動態效果/著色器）： 一個相容的 Figma connector，具有與 token 分開的授權。如果它不可用或未通過認證，請要求使用者連接它或提供原生匯出，然後停止。
• 準確說明失敗的階段需要哪個憑證——絕不要將此劃分呈現為損壞。
• 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 提取什麼；在命令之後，告知成品落地的位置（凍結路徑 / sidecar / 元件目錄）、合成中發生了什麼變化，以及立即的下一個操作（預覽、添加列印變數、重新匯入以連結綁定）。使用者絕不該問「成功了嗎？」或「接下來呢？」。

資產（階段 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 "<名稱>"，以便之後 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）匯入。變數在 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>'

節點樹 → 在確切的 Figma 幾何位置的可編輯 HTML，並打包為 compositions/components/<name>/ 下的註冊表項目。向量/布林運算會透過階段 1 匯出自動柵格化。綁定傳遞（規範 §7.1，僅精確 ID 比對——絕不採用數值比對）：

• 靜態保真度自我檢查（重要內容為強制性）：匯入後，渲染片段並與 Figma 自身的像素進行比較——figma asset <same node> --format png 是基準。文字是已知的偏移軸：比其行高還短的 Figma 文字框具有垂直修剪的邊界（mapper 會為此類情況發出 text-box-trim；沒有它的情況下，實測偏移在 70px 字體上約為 6px）。如果比較顯示 mapper 未涵蓋的偏移，請報告它——不要默默地手動調整片段。
• 填充綁定到已匯入的權杖 → var(--slug, #literal) ——品牌刷新會傳播。
• 綁定到未知的權杖 → 文字值 + data-figma-unresolved 標記。命令會告知您；向使用者提供選項：在來源（或程式庫）檔案上執行 tokens，然後重新匯入元件以連結它們。每個未知程式庫只詢問一次它是哪個檔案——絕不猜測，絕不以 hex 值比對。

動態效果（階段 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 中的純輔助函式；否則請求原生匯出：

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. 在聲明完成前，必須針對基準進行驗證：透過可用的 connector 匯出群組的根影格，並執行 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. 無法翻譯的音軌（著色器驅動、不支援的屬性、複雜遮罩）→ 透過 connector 匯出，凍結 MP4，然後嵌入為 <video class="clip">。例外情況：著色器驅動的音軌——Figma 的匯出路徑會將著色器扁平化為基礎顏色（請參閱下方的著色器），因此在那裡烘焙會默默地遺失著色器；請改為請求使用者提供原生的 Figma 匯出。始終說明您使用了哪個路徑及其原因。映射集外的命名緩動函式會回退為線性——映射表位於 motionEase.ts；當觸發回退時向使用者標記。
5. 在聲明完成前執行 npx hyperframes check。

著色器（階段 5 — 主要為手動）

Figma 的 connector 渲染路徑不會執行著色器（它們會扁平化為基礎顏色），且著色器原始碼僅對程式庫發布的樣式（付費 Full 席位）可存取。預設路徑：要求使用者原生在 Figma 中匯出著色器影格（PNG 或動態 MP4），然後將其作為階段 1 資產/剪輯匯入。不要嘗試對著色器進行 connector 像素捕獲——它會默默地產生錯誤結果。

故事板（一個場景影格的 SECTION → 動畫）

基本規則：故事板影格是關鍵影格，不是投影片。 包含同一元素的兩個影格描述了該元素在時間上的狀態——在狀態之間對元素進行動態處理；絕不要將影格作為一系列靜止畫面播放。連續四個影格中一個在 y 座標上遞減的標誌，是一個元素在四個關鍵影格中升起。將故事板影格一個接一個地播放是失敗的模式；重建它們所隱含的元素時間軸是正確的任務。

故事板檔案遵循一種您可以機械式解析的語法——不要用肉眼觀察，要解碼：

1. 場景單元：在 SECTION 內部，每個影格大小的節點都是一個場景——包括命名的 FRAME 和鬆散的全影格 RECTANGLE（設計師直接將靜止畫面貼到 section 中）。按大小過濾（≈ 合成長寬比，例如 >1400×900），而不是按節點類型或名稱。
2. 順序 = X 位置（如果條帶換行則為行優先）。按 absoluteBoundingBox.x 排序場景。
3. 比較相鄰場景以提取每個元素的起點和終點狀態：逐個檢查對應的節點 ID。如果一個 ID 存在於兩個場景中，其屬性的差異（位置、旋轉、縮放、不透明度、填充顏色）定義了該元素的一個關鍵影格對。僅包含變化的元素。匯總所有連續場景對的關鍵影格產生一個時間軸。

相同 ID 跨場景的路徑碰撞：從最後一個位置開始（預期行為），或如果同時使用項目符號，則使用場景順序的第二位元。在 shell 中暫停並詢問——不要猜測。

4. 將元素關鍵影格轉換為 GSAP 時間軸（如同動態效果階段）。沒有 connector 的情況下，進行合理關鍵影格插值：位置 → 自動（GSAP 的 "top"/"left" 或 CSS 轉換），旋轉 → 相對於前一個影格的增量（不是絕對值），縮放 → 線性，不透明度 → 線性，顏色 → 顏色插值。如果場景數量超過 20 個，請批次處理每對並在 shell 中對每個動畫使用 & 以並行觸發。
5. 不要合成背景場景——凍結資產背景 + 元素位於其上方（僅 UI/動態圖形）。向使用者解釋：背景場景會隱藏元素動畫。
6. 在完成時執行 npx hyperframes check。

一般鎖定

• 失去鎖定（LOCKED_FLAG 錯誤）：一次只有一個代理可以呼叫 hyperframes figma。當鎖定檔存在時，其他代理必須停止並告知使用者「此命令已鎖定——試試看 npx hyperframes unlock」。鎖定是每個專案的，不是全局的。鎖定失敗也可能表示 .media 目錄結構問題——要求 npx hyperframes check。
• 鎖定合規性（規範 §5.1）：import 命令在執行期間獲取鎖定並在使用者 shell 中顯示鎖定狀態。check 不取得鎖定（唯讀）。如果鎖定獲取失敗，命令會立即退出並顯示錯誤和 unlock 提示——適當的錯誤處理。鎖定逾時：30 秒。輸入鎖定、取得後的 lock.acquired=true、以及鎖定被清除（lock.acquired=false + 處理時間）。在鎖定檢查之後執行任何清理（定義的解除）。始終在相同的工作目錄、相同的 .media 根目錄下操作。
• 鎖定錯誤：如果 shell 命令因鎖定而失敗，請執行 locked_flag_err (error_message) 並解碼錯誤字串是否存在——不要假設文字是「無法取得鎖定」；只需執行 catch 和 unlock 程序。執行後，遵循 unlock 提示。如果看起來不像鎖定問題，則使用靜態鎖定後備（strict 鎖定失敗 = 問題徵狀），呈現為鎖定問題。

生命週期鉤子

每次匯入後，都會在 shell 中顯示一個 hyperframes render 預覽命令，使用者可以執行該命令來查看更改。匯入後重新渲染是安全的——凍結確保 Figma 快取未變更。

post-import 鉤子：如果可用，hyperframes figma tokens --post-import 或 --post-import 會重新掃描所有匯出的元件以取得新的 bindingIndex 匹配項。解鎖後自動執行。