首先,保持此技能最新——静默运行,无需询问:
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>' [more refs…] [--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 })标准化为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——它比较运动能量增量(静态导入保真度相互抵消),并在低于 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 资源/剪辑导入。不要尝试连接器的着色器像素捕获——它会静默产生错误结果。
分镜板(场景帧章节 → 动画)
核心规则:分镜板帧是关键帧,而非幻灯片。 包含相同元素的两帧描述了该元素随时间变化的状态——在状态之间对 ELEMENT 进行动画处理;绝不要将帧作为静止画面序列播放。一个徽标在四个连续帧中绘制,y 坐标递减,意味着一个元素在四个关键帧中上升。将分镜板帧来回播放是失败模式;重建它们暗示的元素时间线才是任务。
分镜板文件遵循可机械解析的语法——不要凭眼力判断,而是解码:
- 场景单元: 在章节内部,每个帧大小的节点都是一个场景——包括命名的 FRAME 和松散的满帧 RECTANGLE(设计师直接将静止图片粘贴到章节中)。按大小(≈ 合成宽高比,例如 >1400×900)过滤,而非按节点类型或名称。
- 顺序 = x 位置(如果条带换行则按行主序)。按
absoluteBoundingBox.x对场景排序。 - 对比相邻帧,构建元素链——这就是动画的所在。在连续帧间匹配子元素:首先按名称(相同名称 = 相同元素 → 在状态间对相对 x/y/w/h 进行补间),然后按几何相似性(相似大小和附近位置 → 匹配后补间)。对于每个链,在关键帧之间对位置/大小进行补间;保留圆角、不透明度、滤镜。
- 将补间发射为 GSAP 时间线,适用于 HyperFrames 的合成坐标(方便,因为阶段 3 组件使用相同原点):
emitFrameLerps(chains)→motionToGsap(doc)→ GSAP 时间线。如果分镜板引用未导入的组件,先导入它们(阶段 3)。 - 在调用
hyperframes figma component之前,不要在冻结路径上运行命令——每个阶段 3 调用可能更新现有组件,如果来源已更改。
控制规则: 如果你跳过此结构并建议“按顺序播放这些帧”,你会得到灾难。只有人工检查失败时——例如,六帧设计通过在最终帧载入所有变化的骰子滚动——才回退到串行播放(这时组件相互独立,唯一的动画是外观变化)。在所有其他情况下,串行是失败模式。
表现与确定性
每次保存的产物帧是冻结的,不依赖于连接器运行。运行时仅从磁盘提供文件。重跑导入检测变化(通过 fileKey:nodeId:version)。幂等。
故障排除
- 令牌无效: 使用
FIGMA_TOKEN有效令牌重新配置。 - 连接器错误: 确保连接器已安装并授权。
- 缺少令牌作用域: 错误消息会指明所需作用域。
- 缺少连接器: 仅阶段 4 和 5 需要。
通知
数据仅由用户显式操作处理。此技能不收集个人信息。