企业官网建设流程全解析

HyperFrames Figma Motion转GSAP实战：把设计稿动画变成可Seek时间轴

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames 是一个「写 HTML、渲染视频」的开源视频引擎，它的 Figma 集成可以把Figma Motion 时间轴自动翻译成 GSAP 动画，生成可逐帧 Seek 的确定性时间轴——设计师在 Figma 里做好的关键帧、缓动和循环，无需手抄数值，直接变成可渲染、可预览、可微调的真实动画。

为什么设计稿动画要变成「可 Seek」的时间轴？

传统工作流里，Figma Motion 只是「播放给你看」：你在设计工具里欣赏完，动画数值就锁在工具内部了。要落到视频渲染引擎，只能靠人肉抄关键帧——抄错一个时长，整段节奏全乱。

HyperFrames 的渲染器是逐帧 Seek的：它不连续播放，而是把播放头直接跳到第 N 帧去截图。这就要求动画必须满足三个条件：

• 时间轴是有限时长的（不能无限循环）
• 初始状态是确定的（用fromTo()显式声明起点）
• 缓动曲线是可复现的（贝塞尔值原样保留，而不是靠「看起来差不多」）

满足这三点，无论渲染器跳到哪一帧，画面都和你设计时看到的一模一样。

转换管线三步走：Connector → MotionDoc → GSAP

整个转换由 HyperFrames 的/figma技能驱动，核心逻辑封装在 packages/core/src/figma/ 模块中。

第 1 步：拉取 Motion 上下文

Figma 的 REST API 不提供动效数据，所以这一步需要一个兼容的 Figma Connector（一次 OAuth 授权即可）。Agent 会对父级 Frame 发起一次递归请求，拿到整棵树的动效上下文，原始 JSON 缓存在.media/figma-cache/，之后重跑转换不再消耗配额。

第 2 步：规范化为 MotionDoc

这是管线里最关键的一环，由 motionContextToDocs.ts 机械执行，规则经过大量实测校准：

• 解析 motion.dev 片段的编码（CSS 片段会拉伸时长、不可靠，直接忽略）
• 剔除「循环回卷」尾部关键帧——0.9999→1 的亚毫秒段是循环瞬间重置，不是真实动画，循环次数由repeat字段表达
• 贝塞尔缓动原样保留，由 motionEase.ts 映射表处理，映射不到的命名缓动降级为 linear 并明确告知你

第 3 步：生成 GSAP 时间轴并注册

motionToGsap.ts 把每条轨道编译成 GSAP tween，emitTimelineScript.ts 输出成一段<script>，注入到页面里。生成的时间轴长这样：

const timeline = gsap.timeline({ paused: true }); // 关键帧由 MotionDoc 机械编译，位置显式、起点确定 window.__timelines["figma-xxx"] = timeline;

注意paused: true和window.__timelines注册——这是 HyperFrames 识别时间轴的契约，注册键必须与页面上data-composition-id完全一致。

转完怎么验证：用「运动能量差」做客观质检

最坑的失败模式是「看起来对，其实错」——浏览器里连续播放正常，逐帧 Seek 就穿帮。HyperFrames 内置了一个客观质检脚本 verify-motion.mjs：

node skills/figma/scripts/verify-motion.mjs \ --reference figma-export.mp4 --render out.mp4 --crop 800x600+60+80

它的思路很巧妙：对 Figma 官方导出视频和 HyperFrames 渲染视频分别做相邻帧差分（PSNR），静态画面的字体、边缘差异会在差分中相互抵消，剩下的分数纯粹反映编排质量——轨迹、时长、缓动是否一致。实测校准数据：忠实转换得分约 20dB+，走样的转换只有 5dB 左右，所以默认阈值设为15dB，低于它就必须回头检查翻译而不是调阈值。

四个高频坑位清单 🎯

另外，转换完成后跑一遍npx hyperframes check再验收——这一步在技能流程里是强制的。

关键文件位置速查 📁

想深入源码或文档，以下是本次转换链路上的核心入口：

• Figma 集成总览：docs/guides/figma.mdx
• 设计稿入项目的方法论（图片归图片、HTML 归 HTML）：docs/guides/design-tools.mdx
• GSAP 时间轴的完整契约与规则：docs/guides/gsap-animation.mdx
• /figma技能说明书（含 Motion 四阶段流程）：skills/figma/SKILL.md
• 动效类型定义：packages/core/src/figma/types.ts
• 时间轴校验脚本：skills/figma/scripts/verify-motion.mjs

上手只需两步

1. 把仓库克隆到本地（需要 clone 时仓库地址是 https://gitcode.com/GitHub_Trending/hy/hyperframes），配置好 Figma Token；
2. 把你的 Figma 链接和诉求丢给 Agent：「把这个 Frame 的 Motion 时间轴转成 GSAP」。

之后所有脏活——拉取、规范化、编译、质检——都由管线机械完成。你只需要看两样东西：Agent 报告的走哪条翻译路径，以及verify-motion的分数是否过线。设计稿动画从此不再是「截图级的演示」，而是一条真正属于你、可 Seek、可渲染的 GSAP 时间轴。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes