⚠ 合約狀態:尚未移植至 Remotion
此堆疊的輸出框架為 Remotion + React (
/hyperframes-core)。本技能仍描述已淘汰的 HTML +data-*+ 暫停 GSAP 時間軸管道,其捆綁腳本仍會以該合約發出index.html。在移植完成前:
- 請勿執行
npx hyperframes <anything>——該 CLI 已淘汰。/hyperframes-cli會將所有舊指令對應至其 Remotion 等效指令。- 請勿將其
data-*標記或 GSAP 時間軸程式碼複製到 Remotion 專案中。- 請從中汲取其工藝:故事形狀、剪輯節奏、視覺設計,以及關於螢幕上顯示內容的決策。該部分與框架無關,也是此技能仍保留的原因。
- 請透過
/hyperframes-core的合約來表達結果:<Composition>、<Sequence>以及從useCurrentFrame()衍生的值。當你必須為此進行變通時,請在你的摘要中說明,以便完成移植。
首先,保持此技能最新——靜默執行,無需詢問:
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 連接器(可選)用於動畫和著色器資料;若無連接器,則要求提供原生匯出。每個路徑都會將素材凍結在本機端,以確保渲染的可確定性。分鏡重建會組合 Phase-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 profile 或專案
.env中設定FIGMA_TOKEN;切勿要求他們將 token 貼到對話中。
在引導過程中,同時設定預期:每個匯入都以本機凍結檔案並記錄來源的形式落地——渲染絕不會呼叫 Figma,重新執行指令只會重新匯入 Figma 中已變更的內容,且一個 token 可用於其 Figma 帳戶能檢視的所有檔案中的素材、品牌代碼和元件。
- 階段 4–5(動畫/著色器): 需要一個相容的 Figma 連接器,其授權與 token 分開。若連接器不可用或未經認證,請要求使用者連接它或提供原生匯出,然後停止。
- 請明確指出失敗的階段需要哪個憑證——切勿將這種拆分描述為損壞。
BAD_TOKEN(401) 流程中 → token 已過期/撤銷;請重新產生。FORBIDDEN(403) → 訊息會指明確切遺漏的範圍(例如樣式備援的library_content:read)——請新增它,否則該檔案對該帳戶不可見。REQUIRES_ENTERPRISE(403 on variables) → 不是失敗:樣式備援已執行。RATE_LIMITED(429) → 用戶端已使用退避重試(這適用於所有讀取——素材、token、樣式、節點樹、版本——重試存在於共享請求路徑中;Retry-After會被遵守,上限為 60 秒);若仍出現,請等待一分鐘或每次呼叫匯入較少節點。
速率限制意識(規範 §2.1): 連接器配額因 Figma 方案而異——批次處理父影格請求、跳過驗證截圖(除非要求),並快取原始回應,以便重新推導不會花費第二次呼叫。REST 基於每分鐘限制(每分鐘 10+ 次,按端點存儲桶)——可大量使用,遇到 429 時後退。
路由
使用 parseFigmaRef(URL、fileKey:nodeId、純 fileKey)解析使用者的 figma 連結。然後根據意圖:
- "使用這個圖層 / 標誌 / 圖片" → 素材(CLI)
- "提取我的品牌 / 顏色 / token" → Tokens(CLI)
- "從此影格建構場景" → 元件(CLI)
- "匯入此動畫 / 動作" → 動畫(連接器可用時,見下文)
- 分鏡區段 / 場景影格的影片膠卷 → 分鏡(下文)
- 著色器填色/效果 → 著色器(下文)
為使用者說明每個步驟——在每個指令前,說明你即將從 Figma 提取什麼;之後,說明素材落地位置(凍結路徑 / 側車檔案 / 元件目錄)、合成中有何變化,以及下一步立即動作(預覽、新增列印變數、重新匯入以連結綁定)。使用者不應該需要問"成功了嗎?"或"然後呢?"。
素材(階段 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 "<name>",以便媒體使用 resolve --entity 稍後能找到它們(實體命中會跨圖片/圖示匹配)。
批次處理多個節點於一個請求中——傳遞多個相同檔案的 refs(空格分隔或逗號連接):hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。所有節點會在單一 /v1/images 呼叫中渲染,這是 figma 自身對每分鐘速率限制的解決方案——在提取整個影格的全部素材時,優先於 N 個單獨指令。--description/--entity 會套用至批次中的每個節點,因此請將具有相同用途的節點分組。429 也會使用退避自動重試。
Tokens(階段 2 — CLI)
hyperframes figma tokens <fileKey>
將變數匯入為合成品牌變數項目 + figma-tokens.json 側車檔案 + 綁定索引記錄(.media/figma-bindings.jsonl)。變數在上游受 Enterprise 限制:在其他方案上,指令會降級為已發布樣式中繼資料(值在元件匯入時解析)。將列印的項目新增至合成的 data-composition-variables。
當需要時,請在元件之前匯入 tokens——這能讓元件顏色連結到品牌變數,而不是烘焙重複項。
非 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 連接器的 tokens——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>/。向量/布林運算會透過 Phase-1 匯出自動點陣化。綁定傳遞(規範 §7.1,僅精確 ID——絕不進行值匹配):
- 靜態保真度自我檢查(對主要內容為強制性):匯入後,渲染片段並與 figma 自身的像素進行比較——
figma asset <same node> --format png是基準真相。文字是已知的漂移軸:比其行高短的 figma 文字框具有垂直修剪邊界(映射器會為這些情況發出text-box-trim;沒有它的實測漂移在 70px 字體上約為 6px)。如果比較顯示映射器未涵蓋的漂移,請回報——不要默默地手動調整片段。 - 填充綁定至已匯入的 token →
var(--slug, #literal)——品牌重新整理會傳播。 - 綁定至未知的 token → 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 API。當相容的連接器可用時,使用它並將其輸出傳遞給 @hyperframes/core/figma 中的純輔助函式;否則要求提供原生匯出:
- 在一個遞迴請求中檢索父影格的動畫上下文,而不是每個元素一個請求。將原始 JSON 儲存在專案旁(
.media/figma-cache/),以便重新翻譯無需成本。 - 使用
@hyperframes/core/figma中的motionContextToDocs(rawResponse, { selectorFor, repeat })標準化為MotionDoc——絕不手動轉錄關鍵影格編號。該輔助函式機械地編碼了經過實戰測試的解碼規則:它解析 motion.dev 片段(可靠的編碼——CSS 片段會拉伸持續時間且可能不一致;它們會被忽略),剝離循環包裝的尾部關鍵影格(時間 ≈0.9999→1 的子毫秒片段是循環的即時重置,而非作者的動畫——包裝由repeat重新啟動實現),並原樣保留貝塞爾緩動。selectorFor必須回傳 Phase-3 元件匯入的 ID——不要從節點名稱推導選擇器。 2b. 在宣告完成前,必須根據基準真相進行驗證:透過可用的連接器匯出同組的根影格,並執行node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y——它比較運動能量差異(靜態匯入保真度會抵消),若低於 15dB 最小運動 PSNR 則失敗(校準過:忠實 ≈ 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 或 Motion MP4),然後將其作為 Phase-1 素材/片段匯入。不要嘗試對著色器進行連接器像素捕捉——它會悄悄產生錯誤的結果。
分鏡(場景影格的區段 → 動畫)
基本規則:分鏡影格是關鍵影格,而非幻燈片。 包含相同元素的兩個影格描述了該元素隨時間的狀態——在狀態之間為 ELEMENT 製作動畫;從不將連續影格視為無關的步驟。CLI 提供:hyperframes figma storyboard <fileKey>——它會匯入影格作為 Phase-1 素材(凍結),然後產生一個用於動畫的 MotionDoc 草稿,你可以使用上述規則進行完善。
在所有匯入完成後,執行健全性檢查:
npx hyperframes check——它會驗證凍結素材的完整性、綁定索引,以及合成的結構完整性。在將其標記為完成前,先執行此操作。