插件安装: 在运行设置或更新命令之前,如果此技能位于 HyperFrames 插件内部,请遵循插件安装规则。独立安装保留下面的更新说明。
首先,保持此技能为最新版本 — 在运行之前与用户确认:
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):文件内容:只读 + 文件元数据:只读。如果您将在非企业计划上运行
tokens,请添加库内容:只读 — 已发布样式的回退会命中/v1/files/:key/styles,如果没有此范围则会返回 403(旧版设置文本遗漏的范围)。可选地添加变量:只读以获取品牌变量 — 仅限企业版;没有它,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(URL、fileKey:nodeId、裸 fileKey)解析用户的 figma 链接。然后按意图:
- "使用这个图层 / Logo / 图像" → 资产 (CLI)
- "提取我的品牌 / 颜色 / 令牌" → 令牌 (CLI)
- "从此帧构建场景" → 组件 (CLI)
- "导入此动画" → 动画(连接器可用时,见下文)
- 分镜板章节 / 场景帧的序列 → 分镜板(下文)
- 着色器填充/效果 → 着色器(下文)
为用户说明每一步 — 在每个命令之前说明您要从 Figma 提取什么;之后,说明工件落在哪里(冻结路径 / sidecar / 组件目录),合成了哪些更改,以及下一步立即行动(预览、添加打印的变量、重新导入以链接绑定)。用户永远不必问“它工作了吗?”或“现在怎么办?”。
资产 (阶段 1 — CLI)
hyperframes figma asset '<url-or-fileKey:nodeId>' [更多引用…] [--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 "<名称>",以便媒体使用解析 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 sidecar + 绑定索引记录(.media/figma-bindings.jsonl)。变量在上游受企业版限制:在其他计划上,该命令会降级为已发布样式的元数据(值在组件导入时解析)。将打印的条目添加到合成 data-composition-variables。
在需要组件之前导入令牌 — 这样可以让组件颜色链接到品牌变量,而不是烘焙副本。
非企业变量路径(经过现场测试): REST 变量受企业版限制,但兼容的连接器可能提供变量定义。当 tokens 报告 REQUIRES_ENTERPRISE 且连接器可用时,检索一次父场景的变量,将原始响应缓存到 .media/figma-cache/,并使用它来构建绑定索引。REST 节点树的 boundVariables 提供按属性划分的 VariableID;按节点和属性连接它们,然后写入 .media/figma-bindings.jsonl 行({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version})以及合成变量条目。下游的一切(组件 var() 解析、刷新、运行时 CSS 变量)都是已发布的机制。为用户标记它:“通过 Figma 连接器的令牌 — 企业计划直接从 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,打包为 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 })规范化为MotionDoc— 切勿手动转录关键帧编号。该帮助函数机械地编码了经过现场测试的解码规则:它解析 motion.dev 片段(可靠的编码 — CSS 片段会拉伸持续时间且可能不一致;因此忽略它们),剥离循环包裹尾部关键帧(时间 ≈0.9999→1 处的亚毫秒段是循环的即时重置,不是创作者的动画 — 包裹由repeat重启实现),并逐字保留贝塞尔缓动。selectorFor必须从阶段 3 组件导入返回 id — 不要从节点名称派生选择器。 2b. 在宣布完成之前根据真实依据进行验证 — 强制要求:通过可用连接器导出队列的根帧,并运行node <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y— 它比较运动能量增量(静态导入保真度相互抵消),如果最小运动 PSNR 低于 15dB 则失败(校准:忠实 ≈ 20+,差异 ≈ 5)。从渲染的实际卡片边缘测量--crop,不要猜测。失败意味着重新检查转换,而不是阈值。 motionToGsap(doc)→emitTimelineScript(spec)→ 在 GSAP + CustomEase CDN 标签之后注入为<script>。暂停、有限、使用文字键在window.__timelines上注册。- 不可转换的轨道(着色器驱动、不支持的属性、复杂遮罩)→ 通过连接器导出,冻结 MP4,然后将其嵌入为
<video class="clip">。例外:着色器驱动的轨道 — Figma 的导出路径会将着色器扁平化为基本颜色(请参阅下面的着色器),因此在那里烘焙会静默丢失着色器;请改为要求用户进行原生 Figma 导出。始终说明您使用了哪条路径以及原因。映射集之外的命名缓动会回退为线性 — 映射表位于motionEase.ts中;当触发时向用户标记该回退。 - 在宣布完成之前运行
npx hyperframes check。
着色器 (阶段 5 — 主要是手动的)
Figma 的连接器渲染路径不会执行着色器(它们会扁平化为基本颜色),并且着色器源代码仅对库已发布样式(付费完整席位)可达。默认路径:要求用户在 Figma 中原生导出着色器帧(PNG 或动画 MP4),然后将其作为阶段 1 资产/剪辑导入。不要尝试连接器像素捕获着色器 — 它会静默产生错误的结果。
分镜板 (场景帧的章节 → 动画)
核心规则:分镜板帧是关键帧,而不是幻灯片。 包含相同元素的两个帧描述了该元素在时间上的状态 — 在状态之间对元素进行动画处理;切勿将帧播放为静态图片序列。一个在四个连续帧中沿 y 轴下降绘制的 Logo 是一个通过四个关键帧上升的元素。接续播放分镜板帧是失败模式;重构它们隐含的元素时间线是任务。
分镜板文件遵循您可以机械解析的语法 — 不要用肉眼看,要解码:
- 场景单元:在章节内部,每个帧大小的节点都是一个场景 — 包括命名的 FRAME 和松散的整帧 RECTANGLE(设计者直接将静态图片粘贴到章节中)。按大小(≈ 合成宽高比,例如 >1400×900)过滤,而不是按节点类型或名称。
- 顺序 = x 位置(如果条带换行,则为行优先)。按
absoluteBoundingBox.x对场景排序。 - 差分相邻场景 — 对于每个元素,比较其在帧 A 和帧 B 之间的属性(
y/opacity/fill等)。如果未更改,绑定到一个关键帧。如果更改了,为目标帧生成一个关键帧。在帧 A 中添加到帧 B 的元素变为出现关键帧。从帧 A 中移除的元素变为消失关键帧。没有元素在两个帧中持续存在的情况下,顺序就是顺序:动画化到下一帧。 - 运动分段:场景之间的间隔由帧与帧间隙除以健康的速度基线(133 毫秒/帧 — 25 fps,分镜板帧速与所选帧相同)决定。但是阅读用户的意图:如果 x 位置跳跃很大(目标 x - 源 x > 帧宽 ×1.5),则插入一个暂停(动画等待)。
- 渲染:触发
figma component对所有不同的帧(即需要作为组件导入的唯一帧),然后使用@hyperframes/core/figma中的极简时间线构建器buildTimeline构建 GSAP 时间线:buildTimeline(components, keyframes, { frameDuration, gapStyle })。
针对非常常见的滑动场景(例如轮播)进行优化:一个移动在周期中包裹的元素队列。使用单一时间轴参数化循环,而不是为每个项目生成关键帧 — buildTimeline 可以为此接受 loop 选项。段落帧组成为时间轴段(暂定规范 §4.4)。
分镜板解码的一个警告:设计者经常以交错的方式放置重叠的状态 — 例如,一个元素在帧 1 和帧 3 中可见,但在帧 2 中消失。不要假设存在连续性。始终根据出现在帧 A 和帧 B 中的元素来构建关键帧,并让时间轴构建器处理空白状态。