首先，请确保此 skill 保持最新——运行前必须先获得用户确认： npx hyperframes skills update figma。所有内容均为最新版本时，该命令会快速执行一次无操作；否则，在你依赖它们之前，它会刷新此 skill 及其依赖的核心领域 skills。

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）与 agent 驱动的时间线组装结合起来——无需连接器。现有冻结资产、清单记录和绑定不受路由更改影响——这种拆分仅改变下一次导入使用的凭据。

身份验证——两类凭据，各有作用域

预检——首次调用 CLI 前，检查是否存在令牌：shell 环境（[ -n "$FIGMA_TOKEN" ]）或项目的 .env（CLI 会自动加载它——.env 中存在相应条目即视为已配置）。如果两处都没有，不得仅为获取错误而运行命令——先引导用户完成一次性设置，然后停止并等待：

1. figma.com/settings → 安全 → 个人访问令牌 → 生成新令牌。
2. 权限范围——此集成始终只需要只读权限（从不写入 Figma）：File content: Read-only + File metadata: Read-only。如果要在非企业版方案上运行 tokens，请添加 Library content: Read-only——已发布样式回退会调用 /v1/files/:key/styles，缺少该权限时会返回 403s（这是旧版设置说明中遗漏的权限范围）。品牌变量可选择添加 Variables: Read-only——仅限企业版；如果没有该权限，tokens 会自动降级为使用已发布样式（这是预期行为，并非错误——请说明这一点）。现在，403 错误会指出缺少的确切权限范围；遇到 429s 时会自动重试（按分钟限流，并遵循 Retry-After）。
3. 让用户将 FIGMA_TOKEN 设置在其 shell 配置文件或项目 .env 中；不得要求用户将令牌粘贴到对话中。

在引导配置时，还要一次性说明以下预期：每次导入都会落地为一个记录了来源信息的本地固化文件——渲染过程从不调用 Figma，重新运行命令只会重新导入 Figma 中发生变化的内容，而且一个令牌即可用于其 Figma 账户可查看的所有文件中的资产、品牌令牌和组件。

• 阶段 4–5（动效/着色器）：使用兼容的 Figma 连接器，其授权独立于令牌。如果连接器不可用或未经身份验证，请用户连接它或提供原生导出，然后停止。
• 准确说明失败阶段需要哪种凭据——不得将这种拆分描述为故障。
• 流程中途出现 BAD_TOKEN（401）→ 令牌已过期/被撤销；重新生成令牌。FORBIDDEN（403）→ 消息会指出确切缺失的作用域（例如，样式回退需要 library_content:read）——添加该作用域；否则就是该账号看不到此文件。REQUIRES_ENTERPRISE（变量请求返回 403）→ 这不是失败：样式回退已经执行。RATE_LIMITED（429）→ 客户端已经进行了退避重试（这适用于每一次读取——资产、设计令牌、样式、节点树、版本——重试逻辑位于共享请求路径中；遵循 Retry-After，上限为 60s）；如果仍出现此错误，请等待一分钟，或每次调用导入较少的节点。

限流注意事项（规范 §2.1）：连接器配额因 Figma 方案而异——批量发起父帧请求，除非用户要求，否则跳过验证截图，并缓存原始响应，使重新推导无需再次调用。REST 按分钟限流（10+/min，按端点分桶）——适合大批量使用；遇到 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 "<what it is>"（其值会成为索引行和 <img alt>）；对于有名称的品牌标志，再添加 --entity "<name>"，以便媒体使用功能稍后通过 resolve --entity 找到它们（实体命中会同时匹配图像和图标）。

在一次请求中批量处理多个节点——传入同一文件的多个引用（以空格分隔或用逗号连接）：hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。所有节点都会在一次 /v1/images 调用中渲染；这是 Figma 自身应对每分钟速率限制的方式——提取一整帧所需的资产时，应优先使用这种方式，而不是执行 N 条单独命令。--description/--entity 会应用于批次中的每个节点，因此应将用途相同的节点放在同一批次。遇到 429s 也一律会自动退避重试。

令牌（阶段 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 调用点，因此在开始和结束时触发 skill 信标（匿名、以用户同意为前提、始终不会失败）：开始时使用 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 中的纯函数辅助工具；否则请求原生导出：

1. 通过一次递归请求获取父画框的动效上下文，而不是为每个元素分别发起请求。将原始 JSON 保存在项目旁（.media/figma-cache/），这样重新转换无需额外开销。
2. 使用 @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，不得猜测。失败表示需要重新检查转换，而不是重新检查阈值。

3. motionToGsap(doc) → emitTimelineScript(spec) → 在 GSAP + CustomEase CDN 标签之后，以 <script> 形式注入。生成的时间线处于暂停状态且时长有限，并使用字面量键注册到 window.__timelines。
4. 无法转换的轨道（由着色器驱动、不支持的属性、复杂蒙版） → 通过连接器导出，冻结该 MP4，再将其作为 <video class="clip"> 嵌入。例外：着色器驱动的轨道 — Figma 的导出路径会将着色器展平为基础颜色（见下方“着色器”），因此通过该路径烘焙会悄然丢失着色器；应改为请求用户提供 Figma 原生导出。必须始终说明使用了哪条路径以及原因。不在映射集合内的命名缓动会回退为线性缓动 — 映射表位于 motionEase.ts；触发回退时应向用户说明。
5. 在宣布完成前运行 npx hyperframes check。

着色器（阶段 5 — 以手动处理为主）

Figma 的连接器渲染路径不会执行着色器（而是将其展平为基础颜色），且仅可从已发布到库的样式中访问着色器源代码（需付费的完整席位）。默认路径：请用户在 Figma 中原生导出着色器画框（PNG 或动效 MP4），然后将其作为阶段 1 资产 / 剪辑导入。禁止尝试通过连接器捕获着色器像素 — 这会在不提示的情况下生成错误结果。

故事板（包含场景帧的一个 SECTION → 动画）

最重要的规则：故事板中的帧是关键帧，不是幻灯片。 包含同一元素的两个帧描述了该元素随时间变化的状态——应让这个元素在这些状态之间产生动画；禁止将这些帧作为一系列静帧播放。在连续四个帧中绘制且 y 坐标依次降低的徽标，是同一个元素经过四个关键帧逐渐上升。将故事板帧一个接一个连续播放是错误做法；真正的任务是重建这些帧所隐含的元素时间线。

故事板文件遵循一种可通过程序解析的语法 — 不得凭肉眼判断，要按语法解码：

1. 场景单元：在 SECTION 内，每个与画框等大的节点都是一个场景 — 既包括已命名的画框，_也包括_ 独立的整帧矩形（设计师会将静态画面直接粘贴到该分区中）。按尺寸筛选（≈ 合成画幅，例如 >1400×900），而不是按节点类型或名称筛选。
2. 顺序 = x 位置（帧条带换行时按行优先排序）。按 absoluteBoundingBox.x 对场景排序。
3. 对相邻帧进行差分以形成元素链 — 动画信息就蕴含其中。匹配连续帧之间的子节点：先按名称（名称相同 = 同一元素 → 在各状态之间补间其相对 x/y/w/h），再按几何相似度（尺寸相近 + 中心点接近 = 像素发生变化的同一逻辑元素 → 在补间几何属性的同时，让两份导出内容原位交叉淡化；适用于打字文本的渐进变化和变形状态）。未匹配的子节点在对应场景的节拍点进入/退出。帧背景填充按颜色轨道进行补间。每条链只导出一个资产（只有在像素确实不同时，才为每个状态各导出一个） — 禁止按帧逐一导出静态画面。
4. 静帧是后备方案，并非默认方案——仅用于无法拆解的画面（没有共享元素的扁平全画面截图）；这类画面采用下述动态分镜处理方式。
5. 导演注释：条带下方的 TEXT 节点表达运动意图，按横向范围的重叠关系与对应场景配对。它们描述的是 _如何_ 制作动画，并非屏幕上显示的文案。
6. 批量导出（元素或静帧）：GET /v1/images 接受逗号分隔的 ID，但大型场景画面在超过约 12 个 ID 时会触发 "Render timeout"——每次调用分为约 4 个，并安排重试。（每个场景调用一次会浪费速率配额；走单素材路径时，26 个场景 ≈ 52 次调用。）
7. 注释动词 → 转场（初始词汇表，遇到新情况时扩充）：

| 注释内容 | 操作 | | ------------------------------- | ----------------------------------------------------------------- | | EXPLOSION / BURST | 入场缩放约 1.5→1 + 淡入，power3.out | | SLIDES / SLIDE TO THE… / SCROLL | 从对应边缘定向滑入 | | MORPH / REVEALS | 交叉淡化——若运动发生在单个场景内部，则采用第 3 阶段导入 | | CYCLE THROUGH / EACH ONE | 延长停留——若元素在场景内部运动，则采用第 3 阶段导入 | | （无注释） | 交叉淡化 + 缓慢的 Ken-Burns 平移缩放 |

1. 静帧与组件的路由选择：描述_场景之间_运动的备注 → 在静帧上应用转场（见上文）。描述_场景内部_运动的备注（"文字行逐行显现"、"胶囊元素以动画方式进入"）→ 应对该帧执行第 3 阶段组件导入，按照备注为真实元素制作动画，而不是使用扁平的 PNG。先使用静帧完成动态分镜处理，再升级备注中特别指出的场景。
2. 一条 main 时间线统一编排所有内容（在绝对时间点设置各场景的 opacity/x/y）——动态分镜无需为每个场景创建子合成。
3. 升级处理——画面展示的是同一个产品 UI → 重建应用，而非拼接元素链。当所有画面都是同一应用屏幕的连续状态（注册流程、设置面板、播放器）时，元素链无法充分呈现它。将 UI 重建为可运行的 DOM——对发生状态变化的部分采用第 3 阶段组件导入，静态界面框架使用实际导出的像素（用代码实现状态变化，不变的部分冻结）——将每次画面变化视为要执行的交互，而非要应用的补间动画：光标进入、点击控件、状态响应、屏幕像真实导航一样推入或滑动。最终效果应像对可用应用进行的一段连续屏幕录制。这是核心规则在 UI 流程中的完整体现；静帧或元素链处理适用于不构成单一连贯应用的分镜。

确定性

禁止在合成中留下 Figma URL——先冻结。禁止输出 repeat: -1。时间线须暂停、有限，且使用字面量 window.__timelines 键。所有 Figma I/O 均在导入时完成；渲染时仅访问本地文件。