Communitygithub.com

MattiaIppoliti/tia-skills

将 Figma 内容导入 HyperFrames 合成——渲染资源、品牌令牌、组件、故事板章节→重构动画(帧作为状态而非幻灯片读取)(REST/CLI),在可用时使用连接器辅助运动,以及通过连接器或原生导出来使用着色器。当用户粘贴 figma.com 链接或要求将 Figma 设计、帧、Logo、品牌或动画导入视频/合成时使用。

tia-skills 是什么?

此技能可让你将 Figma 设计无缝导入 HyperFrames/Remotion 合成环境。它分五个阶段运作:渲染静态资源、提取品牌令牌和样式、将组件转换为 HTML、通过连接器辅助处理运动动画,以及管理着色器效果。该技能严格遵循使用 REST API 的“先读”认证方法,需要 `FIGMA_TOKEN` 环境变量,并指导用户通过 Figma 的个人访问令牌进行一次性设置。 一个关键特性是其通过冻结本地资产和记录来源来确保确定性渲染;后续运行仅重新导入 Figma 中发生更改的内容,避免不必要的 API 调用。该技能提供了一个强大的速率限制处理机制,包括自动重试和退避策略。对于运动和着色器阶段,它利用可选的 Figma 连接器,并在连接器不可用时回退到原生导出。一个显著的设计决策是将故事板帧视为关键帧而非幻灯片,为同一元素设置动画以在不同帧之间改变其状态,从而创建流畅的叙事。该技能通过 CLI 命令 `hyperframes 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 连接器用于运动和着色器数据;如果没有,要求用户提供原生导出。每条路径都会冻结本地资产,以使渲染保持确定性。故事板重建将阶段 1 资源导出 (REST) 与代理驱动的时间线组装组合在一起——无需连接器。现有的冻结资产、清单记录和绑定不受路由更改影响——划分仅更改下一个导入使用的凭据。

认证——两个凭据,作用域限定

预检查——在首次 CLI 调用之前,检查令牌是否存在: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 配置文件或项目 .env 中设置 FIGMA_TOKEN;切勿要求她们将令牌粘贴到对话中。

在引导过程中,同时一次性设定期望:每次导入都会落地为具有记录来源的本地冻结文件——渲染从不调用 Figma,重新运行命令仅重新导入 Figma 中更改的内容,并且一个令牌可用于其 Figma 帐户可以查看的每个文件中的资源、品牌令牌和组件。

  • 阶段 4–5(运动/着色器): 一个兼容的 Figma 连接器,具有与令牌分开的独立授权。如果它不可用或未认证,要求用户连接它或提供原生导出,然后停止。
  • 确切说明失败阶段所需的凭据——切勿将拆分描述为损坏。
  • BAD_TOKEN (401) 流程中 → 令牌已过期/撤销;重新生成。FORBIDDEN (403) → 消息指明缺少的确切作用域(例如样式回退的 library_content:read)——添加它,或者文件对帐户不可见。REQUIRES_ENTERPRISE(变量上的 403)→ 不是失败:样式回退已运行。RATE_LIMITED (429) → 客户端已使用退避重试(这适用于每次读取——资源、令牌、样式、节点树、版本——重试存在于共享请求路径中;Retry-After 已遵守,上限为 60 秒);如果仍然出现,请等待一分钟或每次调用导入更少的节点。

速率限制意识(规范 §2.1): 连接器配额因 Figma 计划而异——批处理父帧请求,除非要求,否则跳过验证截图,并缓存原始响应,以便重新派生不会花费第二次调用。REST 是每分钟限制(每分钟 10+ 次,按端点桶)——批量使用正常,在 429 上退避。

路由

使用 parseFigmaRef 解析用户的 figma 链接(URL、fileKey:nodeId、裸 fileKey)。然后根据意图:

  • “使用此图层 / Logo / 图像” → 资源 (CLI)
  • “拉取我的品牌 / 颜色 / 令牌” → 令牌 (CLI)
  • “从此帧构建场景” → 组件 (CLI)
  • “导入此动画 / 运动” → 运动(连接器可用时,如下)
  • 故事板章节 / 场景帧的胶片条 → 故事板(如下)
  • 着色器填充 / 效果 → 着色器(如下)

为用户叙述每一步——在每个命令之前,说明你即将从 Figma 拉取什么;之后,说明工件落在何处(冻结路径 / 侧车 / 组件目录)、合成中发生了什么变化以及接下来的立即操作(预览、添加打印变量、重新导入以链接绑定)。用户绝不应询问“它工作了吗?”或“现在怎么办?”。

资源(阶段 1 — CLI)

hyperframes figma asset '<url-or-fileKey:nodeId>' [more refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

通过 REST 渲染,清理 SVG,冻结在 .media/images/ 下,将来源附加到清单,重新生成 .media/index.md(共享媒体使用清单),打印一个 <img> 片段。每个 fileKey:nodeId:format:scale:version 幂等。对于矢量/Logo,首选 SVG(可缩放、可动画化);对于光栅保真度,使用 PNG --scale 2。始终传递 --description "<它是什么>"(它变成索引行 + <img alt>);为命名品牌标记添加 --entity "<name>",以便媒体使用 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 侧车 + 绑定索引记录 (.media/figma-bindings.jsonl) 导入。变量是上游 Enterprise 门控的:在其他计划上,该命令降级为已发布样式元数据(值在组件导入时解析)。将打印的条目添加到合成的 data-composition-variables。

当两者都需要时,在组件之前导入令牌——这允许组件颜色链接到品牌变量,而不是复制重复项。

非 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 连接器的令牌——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 文本框是垂直裁剪边界(映射器为此类情况生成 text-box-trim;没有它,测量的漂移在 70px 字体上约为 6px)。如果比较显示映射器未覆盖的漂移,请报告——不要静默手动调整片段。
  • 填充绑定到已导入的令牌 → var(--slug, #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 等效项。当兼容的连接器可用时,使用它并将其输出传递给 @hyperframes/core/figma 中的纯辅助函数;否则要求用户提供原生导出:

  1. 在一次递归请求中检索父帧的运动上下文,而不是每个元素一次请求。将原始 JSON 保存到项目旁边 (.media/figma-cache/),以便重新翻译是免费的。
  2. 使用 @hyperframes/core/figma 中的 motionContextToDocs(rawResponse, { selectorFor, repeat }) 规范化为 MotionDocs——切勿手动转录关键帧编号。辅助函数机械地编码了经过现场测试的解码规则:它解析 motion.dev 片段(可靠的编码——CSS 片段拉伸持续时间并且可能不一致;它们被忽略),剥离循环换行尾部关键帧(时间 ≈0.9999→1 处的亚毫秒段是循环的即时重置,非创作的运动——换行由 repeat 重启实现),并逐字保留贝塞尔缓动。selectorFor 必须返回来自阶段 3 组件导入的 id——不要从节点名称派生选择器。 2b. 在称为完成之前对照真实参考进行验证——强制:通过可用的连接器导出队列的根帧,并运行 node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y——它比较运动能量增量(静态导入保真度抵消)并且在最小运动 PSNR 低于 15dB 时失败(校准:忠实 ≈ 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 的连接器渲染路径不执行着色器(它们展开为基本颜色),并且着色器源代码仅对库发布的样式(付费 Full 席位)可达。默认路径:要求用户原生在 Figma 中导出着色器帧(PNG 或运动 MP4),然后将其作为阶段 1 资源/视频片段导入。不要尝试连接器像素捕获着色器——它会静默产生错误的结果。

故事板(场景帧的章节 → 动画)

基本规则:故事板帧是关键帧,而不是幻灯片。 包含相同元素的两个帧描述了该元素随时间变化的状态——在状态之间为元素设置动画;绝不

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.

相关技能