Communitygithub.com

MattiaIppoliti/tia-skills

將 Figma 內容匯入 HyperFrames 合成——渲染素材、品牌代碼、元件、分鏡區段→重建動畫(影格視為狀態,而非幻燈片)(REST/CLI),必要時透過連接器輔助動畫,以及從連接器或原生匯出取得著色器。

tia-skills 是什麼?

此技能可讓 AI 代理(如 Claude Code、Cursor、Codex)將 Figma 設計直接匯入 HyperFrames 合成工具中,支援靜態素材、品牌代碼、元件,以及透過 REST API 重建的分鏡動畫。必要時,可透過 Figma 連接器輔助匯入更複雜的動畫和著色器資料;若無連接器則回退至原生匯出。此技能遵守一份合約狀態警告,表明其輸出框架目前為 Remotion + React,而非舊有的 HTML/GSAP 管道;代理必須將創意決策(故事結構、剪輯節奏、視覺設計)轉化為 Remotion 的 `<Composition>` 和 `<Sequence>` 元件。此技能會自動將素材凍結在本機端,確保渲染的可重現性,並管理認證(Figma 個人存取權杖和連接器授權),同時處理速率限制和錯誤,提供流暢的開發者體驗。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/MattiaIppoliti/tia-skills/tree/HEAD/skills/video/figma

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

⚠ 合約狀態:尚未移植至 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靜態素材RESThyperframes figma asset
2品牌代碼/樣式RESThyperframes figma tokens
3元件 → HTMLRESThyperframes figma component
4動畫 → GSAP連接器(可用時)使用其動畫上下文
5著色器連接器 / 手動匯出使用它或原生匯出

REST 在可能的情況下使用(可大量使用、無頭模式)。相容的 Figma 連接器(可選)用於動畫和著色器資料;若無連接器,則要求提供原生匯出。每個路徑都會將素材凍結在本機端,以確保渲染的可確定性。分鏡重建會組合 Phase-1 素材匯出(REST)與代理驅動的時間軸組合——無需連接器。現有的凍結素材、清單記錄和綁定不受路由變更影響——此分類僅變更下一個匯入所使用的憑證。

認證——兩組憑證,範圍區分

預檢——在首次 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;切勿要求他們將 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 中的純輔助函式;否則要求提供原生匯出:

  1. 在一個遞迴請求中檢索父影格的動畫上下文,而不是每個元素一個請求。將原始 JSON 儲存在專案旁(.media/figma-cache/),以便重新翻譯無需成本。
  2. 使用 @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 表示需要重新檢查翻譯,而不是閾值。
  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 的連接器渲染路徑不會執行著色器(它們會扁平化為基本顏色),且著色器原始碼僅能透過已發布的文件庫樣式(付費完整席位)取得。預設路徑:要求使用者在 Figma 中原生匯出著色器影格(PNG 或 Motion MP4),然後將其作為 Phase-1 素材/片段匯入。不要嘗試對著色器進行連接器像素捕捉——它會悄悄產生錯誤的結果。

分鏡(場景影格的區段 → 動畫)

基本規則:分鏡影格是關鍵影格,而非幻燈片。 包含相同元素的兩個影格描述了該元素隨時間的狀態——在狀態之間為 ELEMENT 製作動畫;從不將連續影格視為無關的步驟。CLI 提供:hyperframes figma storyboard <fileKey>——它會匯入影格作為 Phase-1 素材(凍結),然後產生一個用於動畫的 MotionDoc 草稿,你可以使用上述規則進行完善。

在所有匯入完成後,執行健全性檢查: npx hyperframes check——它會驗證凍結素材的完整性、綁定索引,以及合成的結構完整性。在將其標記為完成前,先執行此操作。

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

MattiaIppoliti/tia-skills

The technique catalog: five velocity-matched SEAMS (zoom-through, INVERSE zoom-through, cut-the-curve, waterfall cut, rack-focus blur-cut) plus the two in-scene techniques — waterfall ENTRY (staggered arrival cascades for title cards / segment openers) and the nudge curve (slow-fast-slow three-phase group slides). Covers partial-travel (~12% of frame) velocity matching via mirrored power4 eases, the Z scale-sign rule, size-scaled blur (10px text / 18-20px full-frame), word-by-word staggered cuts, cascade pacing by element weight, and the 10/65/25 slide ratio. Read before authoring any transition, text-beat handoff, kinetic text entry, or group reposition. [depth, zoom, inverse-zoom, scale-sign, mirrored-zoom, rack-focus, pacing, velocity, cut-the-curve, waterfall, stagger, cascade, kinetic-text, title-card, segment-opener, nudge, slide, easing, group-motion, z-depth, motion-graphics, cinematic, transition, blur, directional-continuity]

MattiaIppoliti/tia-skills

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

MattiaIppoliti/tia-skills

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

MattiaIppoliti/tia-skills

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), or automation envelopes drawn on a track's volume or any effect parameter. Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

MattiaIppoliti/tia-skills

Drive the Remotion CLI development loop: scaffold, studio, type-check, compositions, still probes, single and batch render, bundle, Lambda and Cloud Run rendering, benchmark, versions, upgrade, and GPU checks. Also use when diagnosing a build or render failure, or when looking for a capability the retired HyperFrames CLI used to own.

MattiaIppoliti/tia-skills

The composition contract for building one renderable Remotion project. Use for project structure, `<Composition>` registration, `<Sequence>` timing, layer/track ordering, scene components, props and schemas, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition code.

相關技能