首先,保持此技能新鲜——运行前与用户确认:
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 解析用户的 figma 链接(URL、fileKey:nodeId、裸 fileKey)。然后按意图:
- "使用此图层/徽标/图像" → 资源(CLI)
- "提取我的品牌/颜色/令牌" → 令牌(CLI)
- "从此帧构建场景" → 组件(CLI)
- "导入此动画/运动" → 动画(连接器可用时,如下)
- 分镜片段/场景帧的胶片条 → 分镜(如下)
- 着色器填充/效果 → 着色器(如下)
为用户叙述每一步——在每个命令前说明要从 Figma 拉取什么;之后说明产物落在了哪里(冻结路径/侧车/组件目录),合成中发生了什么变化,以及下一步立即操作(预览、添加打印变量、重新导入以链接绑定)。用户永远不必问“成功了吗?”或“然后呢?”
资源(阶段 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 具有幂等性。对于矢量/徽标优先使用 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 侧车 + 绑定索引记录(.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,打包为 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 })标准化为MotionDoc——永远不要手动转录关键帧编号。辅助函数以机械方式编码现场测试的解码规则:它解析 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——它比较运动能量增量(静态导入保真度抵消),低于 15dB 最小运动 PSNR 则失败(校准:忠实≈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 的连接器渲染路径不执行着色器(它们展平为基本颜色),并且着色器源代码仅对库发布的样式(付费完整席位)可访问。默认路径:要求用户在 Figma 中原生导出着色器帧(PNG 或动画 MP4),然后将其作为阶段1资源/剪辑导入。不要尝试连接器像素捕获着色器——它会静默产生错误结果。
分镜(场景帧的一段→动画)
核心规则:分镜帧是关键帧,不是幻灯片。 包含相同元素的两个帧描述了该元素随时间变化的状态——在状态之间对元素进行动画;永远不要将帧作为静态序列播放。在四个连续帧中 y 下降绘制的徽标是一个元素上升通过四个关键帧。逐个播放分镜帧是失败模式;重构它们暗示的元素时间线才是工作。
分镜文件遵循您可以机械解析的语法——不要用眼看,要解码:
- 场景单元:在 SECTION 内部,每个帧大小的节点是一个场景——包括命名的 FRAME 和 松散的满帧 RECTANGLE(设计人员将静态图像直接粘贴到片段中)。按大小(≈合成宽高比,例如 >1400×900)过滤,而不是按节点类型或名称。
- 顺序 = x 位置(如果条带环绕则按行优先)。按
absoluteBoundingBox.x对场景排序。 - 将相邻帧差异化为元素链——这是动画的所在。匹配连续帧间的子节点:首先按名称(相同名称=相同元素→在状态间补间其相对 x/y/w/h),然后按几何相似性(相似尺寸和位置⇒相同元素;若名称不匹配,备选匹配)。
- 为每个链构建关键帧列表:对于名称链
logo跨越帧 1→4→7→10:{0%: pos1, 30%: pos2, 60%: pos3, 100%: pos4}。百分比 =(帧_索引 / 总帧数)* 100。 - 为每个链发射 GSAP 从/到/关键帧块——永远不要为链生成单独的补间;始终合并为一个单一元素的关键帧补间。
- 处理不匹配的元素:在场景中开始和结束的元素(在序列中途出现/消失)→ 出现为 'from'(opacity:0)、消失为 'to'(opacity:0)。
- 设置总持续时间:2-5 秒每场景,或让用户指定。
- 不要发出屏幕旋转/缩放——分镜是空间布局;相机运动是错误的。
- 验证:发出后,要求用户预览。如果动画看起来不连贯(元素跳跃而非平滑),检查名称匹配何处失败(常见原因:Figma 添加了尾随空格、不同的大小写、图层 > 8 层深被折叠为 "Group N")。
上下文锚定(spec §2.2.1):分镜阶段以 1:1 的时间比例编号帧——10 个场景帧 = 10 个关键帧,间隔均匀。
错误恢复和保持新鲜
在每次与 Figma 相关的调用之前运行 npx hyperframes skills update figma(这应发生在前缀提示中)。如果 CLI 或可用连接器的版本命令返回过时状态("status":"outdated"),建议用户运行 npx hyperframes update。
恢复:如果资源/令牌/组件导入在过程中途失败(403、500、超时),说出来并建议:
- 对于速率限制:"等待 60 秒,然后重试——将请求分组到更少的批量中"
- 对于权限:"在 figma.com/settings/access 检查您的令牌作用域——此操作需要 file_content:read"
- 对于连接器超时:"您的 Figma 连接器未响应。将其保持打开状态,然后重试"
内务和从属技能
此技能在下面记录自己的图式,并从这些核心技能继承其安装/更新提示(npx hyperframes skills update figma 获取它们):
hyperframes/core(渲染器、超时和资源管理)hyperframes/media(冻结导出资产的清单)
所有阶段共享一个冻结的依赖文件和配置清单:compositions/components/ 下每个组件的 figma-meta.jsonl(资产版本、原始文件密钥、节点 ID、最后导入时间)。始终在项目根目录运行所有 CLI 命令。从 Figma 导入的所有内容在合成之间立即共享——标记元素是可引入的,无需重新导入。