插件安装: 在运行设置或更新命令前,当此技能位于 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 连接器对于动画和着色器数据是可选的;如果没有,则要求用户提供原生导出。每条路径都会在本地冻结资源,确保渲染确定性。故事板重构结合了第一阶段资源导出(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>'
节点树 → 可编辑 HTML,精确匹配 Figma 几何尺寸,打包为 compositions/components/<name>/ 下的注册表项。矢量/布尔运算通过第一阶段导出自动栅格化。绑定传递(规格 §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必须返回第三阶段组件导入的 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),然后作为第一阶段资源/片段导入。不要尝试对着色器进行连接器像素捕获 — 它会静默产生错误结果。
故事板(场景帧章节 → 动画)
核心规则:故事板帧是关键帧,不是幻灯片。 包含同一元素的连续两帧描述了该元素随时间变化的状态 — 为 ELEMENT 在状态之间制作动画;切勿将帧作为静止序列播放。一个标志在四个连续帧中 y 坐标递减,这是同一个元素穿过四个关键帧向上移动。将故事板帧连续播放是错误模式;重构它们暗示的元素时间线才是正确任务。
故事板文件遵循一种可机械解析的语法 — 不要肉眼查看,而是解码:
- 场景单元:在 SECTION 内部,每个帧大小的节点都是一个场景 — 包括命名的 FRAME 和松散的满画幅 RECTANGLE(设计师将静态图像直接粘贴到章节中)。按大小过滤(≈ 合成宽高比,例如 >1400×900),而不是按节点类型或名称。
- 顺序 = x 位置(如果条带换行则为行优先)。按
absoluteBoundingBox.x对场景排序。 - 比较相邻场景:对于场景 N 和 N+1,分别以每种元素为单位差集。添加的元素 → 出现关键帧(
opacity: 0→opacity: 1)。移除的元素 → 消失关键帧(opacity: 1→opacity: 0)。在两个场景中都存在但几何形状或属性不同的元素 → 演变关键帧。从场景 N+1 到 N+2 重复此过程,以此类推。 - 构建时间线:
emitTimelineScript为元素对{state: {opacity, transform, filter, …}, duration: inter-scene gap / framesPerSecond}创建一个 GSAP 时间线。如果用户提供了帧率,使用它;否则假设为 24fps(然后询问用户)。如果在场景间未显式指定,使用相等分配duration。 - 验证: 运行
hyperframes check以确保正确的层叠和 z 顺序。永远不要将故事情节转换为视频编码的幻灯片式序列。
将此技能与 @hyperframes/core/figma 辅助函数结合使用,以获得可靠的 Figma 数据解码、绑定索引管理和动画翻译。