⚠ 合同状态:尚未移植到 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 | 静态资源 | REST | hyperframes figma asset |
| 2 | 品牌令牌/样式 | REST | hyperframes figma tokens |
| 3 | 组件 → HTML | REST | hyperframes figma component |
| 4 | 运动 → GSAP | 连接器(可用时) | 使用其运动上下文 |
| 5 | 着色器 | 连接器/手动导出 | 使用它或原生导出 |
在任何可能的地方使用 REST(可批量使用,无头化)。可选的兼容 Figma 连接器用于运动和着色器数据;如果没有,要求用户提供原生导出。每条路径都会冻结本地资产,以使渲染保持确定性。故事板重建将阶段 1 资源导出 (REST) 与代理驱动的时间线组装组合在一起——无需连接器。现有的冻结资产、清单记录和绑定不受路由更改影响——划分仅更改下一个导入使用的凭据。
认证——两个凭据,作用域限定
预检查——在首次 CLI 调用之前,检查令牌是否存在:Shell 环境 ([ -n "$FIGMA_TOKEN" ]) 或项目 .env(CLI 自动加载——.env 条目计为已配置)。如果两者都不存在,则不要运行命令以收集错误——先引导用户完成一次性设置,然后停止并等待:
- figma.com/settings → 安全 → 个人访问令牌 → 生成新令牌。
- 作用域——此集成始终只需要只读权限(它从不写入 Figma):文件内容:只读 + 文件元数据:只读。如果你将在非 Enterprise 计划上运行
tokens,请添加库内容:只读——已发布样式的回退会命中/v1/files/:key/styles,如果没有此作用域(旧的设置文本遗漏了此作用域),则会返回 403。可选地,变量:只读用于品牌变量——仅限 Enterprise;如果没有,tokens会自动降级为已发布样式(预期行为,不是错误——请说明)。403 现在会指明确切缺少的作用域;429 会自动重试(每分钟限制,遵守Retry-After)。 - 让用户在她们的 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 中的纯辅助函数;否则要求用户提供原生导出:
- 在一次递归请求中检索父帧的运动上下文,而不是每个元素一次请求。将原始 JSON 保存到项目旁边 (
.media/figma-cache/),以便重新翻译是免费的。 - 使用
@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 表示检查翻译,而不是阈值。 motionToGsap(doc)→emitTimelineScript(spec)→ 在 GSAP + CustomEase CDN 标签之后注入为<script>。暂停、有限、使用字面键注册在window.__timelines上。- 不可翻译的轨道(着色器驱动、不支持的属性、复杂遮罩)→ 通过连接器导出,冻结 MP4,然后将其嵌入为
<video class="clip">。例外:着色器驱动轨道——Figma 的导出路径将着色器展开为基本颜色(参见下面的着色器),因此在那里烘焙会静默丢失着色器;要求用户改为进行原生 Figma 导出。始终说明你使用了哪个路径以及原因。映射集之外的命名缓动回退为线性——映射表存在于motionEase.ts中;当它触发时向用户标记回退。 - 在称为完成之前运行
npx hyperframes check。
着色器(阶段 5 — 主要是手动的)
Figma 的连接器渲染路径不执行着色器(它们展开为基本颜色),并且着色器源代码仅对库发布的样式(付费 Full 席位)可达。默认路径:要求用户原生在 Figma 中导出着色器帧(PNG 或运动 MP4),然后将其作为阶段 1 资源/视频片段导入。不要尝试连接器像素捕获着色器——它会静默产生错误的结果。
故事板(场景帧的章节 → 动画)
基本规则:故事板帧是关键帧,而不是幻灯片。 包含相同元素的两个帧描述了该元素随时间变化的状态——在状态之间为元素设置动画;绝不