Communitygithub.com

1999AZZAR/designer-mcp

HyperFrames 合成合約 — 構建一個可渲染的專案。用於合成結構、`data-*` 時間屬性、`class="clip"`、軌道、子合成、變數、框架擁有的媒體播放、確定性渲染規則及驗證。在撰寫合成 HTML 前請先閱讀。

designer-mcp 是什麼?

此技能定義了 HyperFrames 合成合約,提供了一個全面的技術指南,說明如何構建一個可渲染的 HyperFrames 專案。它解釋了合成的基礎結構,包括獨立與子合成兩種根形式、使用 GSAP 時間軸的時序控制、`data-*` 屬性、`class="clip"` 元素,以及變數與媒體播放功能。此指南強調了避免常見錯誤的關鍵點,例如 CSS 與 GSAP 變換屬性間的衝突、錯誤的時間軸註冊,以及 lint 工具會強制執行的特定規則(如 `gsap_css_transform_conflict` 與 `media_crossorigin_breaks_preview`)。對於開發者和 AI 代理使用者而言,此技能確保了構建確定性、可定位、無錯誤的影片渲染,遵循 HyperFrames 在各種執行環境(如 Claude Code、Cursor、Codex)中的嚴格架構與最佳實務。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1999AZZAR/designer-mcp/tree/HEAD/skills/video/engine/hyperframes-core

在你喜歡的 AI 中提問

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

說明文件

HyperFrames 核心

代理陷阱(請先閱讀):

  • 使用 flex/inset 居中,不要在後續使用 GSAP x/y 操作的節點上使用 CSS transform: translate(-50%,-50%)。Lint 規則:gsap_css_transform_conflict。請改用 fromTo 或 xPercent/yPercent。
  • 不要添加場景退出的 tl.set(..., {visibility:"hidden"})。執行環境已經會隱藏計時的片段。內部節點的透明度淡入(或 .clip 上的 opacity)就足夠了。字幕的強制隱藏是另一條規則。
  • window.__timelines["id"] 必須與根元素的 data-composition-id 匹配。
  • 在 render 之後,讀取摘要的第二行:beginframe 與 screenshot、GPU 模式、階段時序。screenshot + software gpu(在 Linux 上)是較慢的路徑。

HyperFrames 從 HTML 渲染影片。一個合成是一個 HTML 檔案,其 DOM 使用 data-* 屬性宣告時序,其動畫執行環境是可定位的,且其媒體播放由框架擁有。

此技能是技術合約 — 如何構建一個 hyperframes 專案。以下內容是構建指南;每個主題的詳細資訊位於 references/(接下來索引),請按需閱讀。流程文件(簡報、故事板、審查、製作、調度、幀處理)位於 /hyperframes → references/。其他關注點位於同領域技能中 — hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力圖解釋了每個技能涵蓋的內容。

參考資料

檔案閱讀它以…
references/minimal-composition.md從最小的可渲染合成骨架開始
references/composition-patterns.md選擇整體式 vs 模組化;結構化一個模組化 index.html;選擇一個子合成原型
references/data-attributes.md查詢任何 data-*(根 / 片段 / 子合成宿主 / 舊版別名);使用 class="clip"
references/tracks-and-clips.md理解 data-track-index 的作用(以及不作用)、z-index、相對於另一個片段的時間定位;使用 npx hyperframes timeline 列出每個軌道和片段
references/creator-editing-recipes.md複製可靠的剪下/修剪/重新排序/重新計時/凍結/攝影機/遮罩/交叉淡入淡出/音訊編輯食譜及其限制
references/sub-compositions.md連接一個子合成(宿主屬性、<template>、每個實例的變數)並在其內部執行動畫
references/variables-and-media.md宣告變數;放置 <video>/<audio>,設定音量,修剪
references/determinism-rules.md構建一個可定位的時間軸;確定性禁止事項;版面 / 文字適應
references/full-screen-motion.md使用共享背景撰寫全幀動畫
references/tailwind.md在 Tailwind v4 專案中工作(init --tailwind;執行環境合約與 Studio 的 v3 不同)

有關動畫執行環境的細節(GSAP API、Lottie、Three.js 等),請前往 hyperframes-animation → adapters/<runtime>.md。

構建一個合成

兩種根形式(不可互換)

  • 獨立(頂層 index.html):根元素 <div data-composition-id="…"> 直接位於 <body> 中,沒有 <template> 包裝。包裝一個獨立的根元素會隱藏所有內容,且 lint 會拒絕它(standalone_composition_wrapped_in_template,錯誤)。
  • 子合成(透過 data-composition-src 載入):將根元素包裝在 <template> 中。這是建議寫入的形式:載入器也接受一個普通的完整文件並回退到其 <body>,但範例和工具預設使用模板形式。

⚠ 傳輸規則:對於模板化的子合成,組合器會丟棄檔案自身的 <head> <style>/<script>(packages/core/src/compiler/compositionAssembly.ts,hasTemplate 閘門),因此請將 <style>/<script> 放在模板內部。<link> 無論如何都會被提升。 ⚠ 宿主 ID 慣例:給予宿主插槽、內部模板和 window.__timelines["<id>"] 鍵相同的 id。支援不同的本地 ID(組合器會回退到檔案中的第一個根元素),但此不匹配是靜默的,因此除非有理由不這樣做,否則請保持它們一致。

檔案結構、宿主連接和預渲染檢查清單 → references/sub-compositions.md。

根元素必須設定大小(靜態版面錯誤)

獨立根元素的作者使用 width/height: 100%。畫布大小為 data-width/data-height。執行環境會將這些像素套用到合成根元素上。不要在 #root 上硬編碼 1920px/1080px。骨架 → references/minimal-composition.md。

一個暫停的時間軸

每個合成會註冊恰好一個 gsap.timeline({ paused: true }) 到 window.__timelines["<id>"](鍵 = 根元素的 data-composition-id)。支援在非同步回呼(document.fonts.ready)內部構建它;重要的是你只在構建完成後註冊。渲染長度是根元素的 data-duration,不是時間軸的長度:運行超過它的時間軸會被截斷,而提前結束的時間軸會保持其最後一幀。省略根元素的 data-duration 則長度會被推斷(時間軸、媒體視窗或轉接器)。你不需要 window.__timelines = window.__timelines || {}:執行環境在你的內嵌腳本運行前就建立了註冊表,並且 lint 不再要求它。不要手動將子時間軸嵌套到宿主中;執行環境會自動嵌套已註冊的子時間軸。完整合約(包括非 GSAP 執行環境)→ references/determinism-rules.md + hyperframes-animation/adapters/。

首次通過 lint 的陷阱(保證首次構建失敗)

lint 確實會捕獲的規則,但僅在事後。第一次就寫對它們:

  • 永遠不要將 CSS 初始 transform 與對相同屬性的 GSAP 補間動畫配對 — CSS 值和補間動畫的起始值會衝突,lint 會以 gsap_css_transform_conflict 拒絕它。使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在補間動畫內部設定初始狀態,而不是 CSS transform: translateX(-40px)。
  • 永遠不要在 <video>/<audio> 上放置 crossorigin。lint 會無條件地以 media_crossorigin_breaks_preview(錯誤)拒絕它,包括 canvas/WebGL/WebAudio 回讀。沒有抑制方法。
  • 永遠不要給 <video data-start> 一個同時帶有 data-start 的祖先。lint 會以 video_nested_in_timed_element(錯誤)拒絕它。為包裝器或影片設定時間,而不是兩者。
  • 每個 <audio> 都需要一個 id。lint 會以 media_missing_id 拒絕它,並且沒有 ID 的 <audio> 永遠不會被混音器拾取,因此渲染是靜音的。
  • 永遠不要使用 autoAlpha 或 visibility 對 .clip 進行補間動畫 — lint 會以 gsap_animates_clip_element 拒絕它。請對子元素執行動畫。
  • 一個命名的 CSS font-family 需要一個指向已傳送本地檔案的 @font-face,否則 lint 會觸發 font_family_without_font_face。
  • 子合成 #root 使用 width/height: 100%(或 inset: 0),而不是硬編碼的 1920px/1080px。畫布大小為 data-width/data-height。

Lint 錯誤也會關閉版面與對比度審計:check 接著會報告 0 sample(s) 和 0/0 text checks,這看起來像一個乾淨的檔案,但實際上什麼都沒運行。在信任這些數字之前,請先清除 lint 錯誤。

不可協商的規則(自動化閘可能遺漏的靜態錯誤)

在此列出;完整原理請參閱連結的參考資料。不要違反:

  • 沒有渲染時時鐘 / 未播種的 Math.random / 網路 / 輸入狀態;沒有 repeat: -1(使用有限次數)。 → determinism-rules.md
  • 永遠不要在 .clip 元素上補間 display、visibility 或 autoAlpha。框架擁有片段的可見性,且 lint 會拒絕它(gsap_animates_clip_element)。請對子元素執行動畫。 → determinism-rules.md
  • 正文文字中沒有 <br>;被轉換的元素必須是區塊級 + 已設定大小;脈衝的絕對定位裝飾元素需要間距清除。 → determinism-rules.md
  • <video>/<audio> 是透過扁平文件查詢找到的,因此框架可以在任何嵌套深度(包括在子合成 <template> 或包裝器內部)查找並解碼它們。一個硬性限制:如果一個 <video data-start> 位於另一個也帶有 data-start 的普通元素內部,lint 會報錯,且此失敗是真實的(錯誤的來源幀,然後片段在中途消失),因此將時間放在包裝器或影片上,而不是兩者。子合成宿主是豁免的:子合成內部的媒體可以正確渲染。另一個注意事項是時間軸,而非放置位置:子合成時間軸不能對宿主根元素執行動畫。 → variables-and-media.md
  • 在組合後的頁面中保持每個 id 唯一(為子合成 ID 加上合成 ID 前綴,例如 #<id>-hero),以便你自己的 #id CSS 和 getElementById 呼叫能正常解析。幀注入不再依賴於此:編譯器會為每個 video[src]/audio[src]/img[src] 蓋上文件唯一的 data-hf-render-id。使用 <source> 子元素而不是 src 屬性的媒體不會被蓋上標記,因此唯一 ID 在那種情況下仍然重要。 → composition-patterns.md
  • 在合成根元素上的全螢幕填充在正常渲染時是好的。它僅在分層合成路徑(HDR 內容,或使用著色器轉場的合成)上被丟棄,在該路徑中引擎會強制每個合成根元素透明,以便底層顯示出來。如果你的合成使用著色器轉場或 HDR 媒體,請將填充放在一個滿版出血的子元素上(position:absolute; inset:0)。 → composition-patterns.md

編輯現有合成

  • 首先閱讀檔案。保留不相關的時序、軌道、ID、變數、媒體路徑。
  • 要知道專案時間軸上有什麼(軌道、片段、開始、結束、播放的內容),運行 npx hyperframes timeline [--json],而不是閱讀 index.html 和每個子合成檔案。
  • 匹配現有的合成 ID 和時間軸鍵。
  • 添加片段:有意識地根據周圍的片段設定其 data-start/data-duration。data-track-index 是 Studio 的顯示通道,不是時序限制,因此它不需要是空的。
  • 在任何合成元素上的 data-hidden 會將其隱藏在預覽和渲染中,覆蓋其時間視窗;它是非破壞性/可逆的,並由 Studio 時間軸的眼睛圖示切換。
  • 添加子合成:在連接宿主之前,驗證其內部的 data-composition-id。

驗證

使用 hyperframes-cli 獲取命令細節

  • npx hyperframes check 通過(在 lint、執行環境、版面、動畫和對比度方面沒有發現問題)
  • 具有子合成的專案:npx hyperframes snapshot --at <midpoints> 並目視檢查每個幀
  • npx hyperframes preview --background 用於審查(使用者可以在 Studio 的時間軸中編輯任何內容,且伺服器在調用命令後仍然存活)
  • 僅在使用者批准後運行 npx hyperframes render

Individual skills in this repo

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

1999AZZAR/designer-mcp

SOTA animation and physics heuristic guide using motion.dev

1999AZZAR/designer-mcp

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

1999AZZAR/designer-mcp

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). 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`.

1999AZZAR/designer-mcp

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

1999AZZAR/designer-mcp

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1999AZZAR/designer-mcp

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

1999AZZAR/designer-mcp

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1999AZZAR/designer-mcp

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

1999AZZAR/designer-mcp

Use when building or editing a HyperFrames project that people open in Studio: how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

1999AZZAR/designer-mcp

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

1999AZZAR/designer-mcp

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

1999AZZAR/designer-mcp

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

1999AZZAR/designer-mcp

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.

相關技能