Communitygithub.com

1999AZZAR/designer-mcp

HyperFrames 合成协议——构建一个可渲染项目。用于合成结构、`data-*` 时间属性、`class="clip"`、轨道、子合成、变量、框架拥有的媒体播放、确定性渲染规则和验证。在编写合成 HTML 之前阅读。

designer-mcp 是什么?

这是一个面向 AI 代理的 HyperFrames 核心技术规定。它定义了如何构建一个 HTML 合成视频项目:通过 `data-*` 属性声明每个 DOM 元素的时间线,框架控制媒体播放和渲染,并保证结果的可寻性和确定性。该技能详细列出了与 GSAP 动画的冲突规则(例如,避免 CSS 的 `transform` 与 GSAP 的 `x`/`y` 同时使用)、如何避免常见的 lint 错误(如 `media_crossorigin_breaks_preview` 和 `gsap_css_transform_conflict`),以及如何正确编写独立合成或子合成文件。它还涵盖了轨道和片段管理、变量声明、`<video>`/`<audio>` 媒体的放置规则,以及通过 `npx hyperframes timeline` 查看项目时间线的验证工作流程。明确支持命令行工具 (CLI)、Studio 集成以及 Tailwind v4 等框架,是确保 AI 代理准确理解 HyperFrames 架构、避免因错误写法导致渲染失败或静默错误的重要参考。

兼容平台~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 核心

Agent 陷阱(请先阅读):

  • 使用 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 模式、阶段时间。在 Linux 上,screenshot + software gpu 是慢路径。

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。

一个暂停的时间线

每个合成在 window.__timelines["<id>"] 处注册恰好一个 gsap.timeline({ paused: true })(键 = 根元素的 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 通过(0 个发现,涵盖 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.

相关技能