首先，保持此技能新鲜——静默运行，无需询问：
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 → Security → Personal access tokens → 生成新令牌。
- 作用域——只读是所有此集成所需的内容（它从不写入 Figma）：File content: Read-only + File metadata: Read-only。如果您要在非企业计划上运行
tokens，请添加 Library content: Read-only——已发布样式回退会命中/v1/files/:key/styles，没有该作用域会返回 403（旧版设置文本省略了该作用域）。可选地添加 Variables: Read-only 用于品牌变量——仅限企业版；没有它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 链接。然后根据意图：
- “使用这个图层 / 标志 / 图像” → 资源（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（可缩放、可动画化），对于栅格保真度使用带 --scale 2 的 PNG。始终传递 --description "<是什么>"（它将成为索引行 + <img alt>）；对于命名的品牌标记添加 --entity "<名称>"，以便媒体使用的 resolve --entity 稍后能找到它们（实体匹配命中跨图像/图标）。
在 ONE 请求中批量处理许多节点——传递同一文件的多个引用（空格分隔或逗号连接）：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——它比较运动能量增量（静态导入保真度抵消），如果最小运动 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 的连接器渲染路径不执行着色器（它们会展平为基本颜色），并且着色器源代码仅对库发布的样式（付费完整席位）可访问。默认路径：要求用户在 Figma 中原生导出色着器帧（PNG 或 Motion MP4），然后将其作为阶段 1 资源/剪辑导入。不要尝试连接器像素捕获着色器——它会静默产生错误结果。
故事板（场景帧的 SECTION → 动画）
首要规则：故事板帧是关键帧，不是幻灯片。 包含同一元素的两个帧描述了该元素随时间变化的状态——在状态之间动画化该 ELEMENT；永远不要将帧作为静态图片序列播放。在四个连续帧中以递减 y 值绘制的标志是通过四个关键帧上升的 ONE 元素。连续回放故事板帧是失败模式；重建它们所隐含的元素时间线才是工作。
故事板文件遵循您可以机械解析的语法——不要目测，而是解码：
- 场景单元：在 SECTION 内部，每个帧大小的节点都是一个场景——既包括命名的 FRAME，也包括松散的满帧 RECTANGLE（设计师直接将静态图片粘贴到章节中）。按大小（≈ 合成宽高比，例如 >1400×900）过滤，而不是按节点类型或名称。
- 顺序 = x 位置（如果条带换行则为行优先）。按
absoluteBoundingBox.x对场景排序。 - 将相邻帧差异化为元素链——这就是动画所在。跨连续帧匹配子元素：首先按名称（相同名称 = 相同元素 → 在其相对 x/y/w/h 之间补间状态变化），然后按几何相似度（相似大小 + 附近中心——距离 ≤ ε）作为容错回退。给定元素链，源自相同根组件的子元素使用阶段 4 的运动管道自动转换为 GSAP（每个帧对生成一个关键帧）。
- 元素链 → GSAP 时间线：每个链是一个
gsap.to(element, { keyframes: [...] })。关键帧属性：{ x, y, width, height, scaleX?, scaleY?, rotation?, opacity? }——精确 Figma 值。每帧持续时间为相继承故事的frameDuration（默认 1/30）。缓动？故事板没有显式缓动——默认为"power1.out"（不同于连接器运动，后者保留 figma 的缓动曲线——与用户确认：“我会为场景添加默认缓出；是否需要不同的感觉？”）。将生成的时间线注入为阶段 4 脚本。 - 资源重建：同时，通过阶段 1 管道提取每个场景帧内所有子节点的资源（批处理每个场景一次——
hyperframes figma asset每次调用可以处理一个帧的所有节点）。将这些资源注册到合成清单中，以便时间线可以引用它们。 - 在声明完成之前运行
npx hyperframes check。