kinyias/hyperframes-templates

插件安装： 在运行 setup 或 freshness 命令之前，如果此技能位于 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 连接器对于动态效果和着色器数据是可选的；如果没有，则要求原生导出。每条路径都会在本地冻结资产，使渲染保持确定性。故事板重建将阶段 1 资产导出（REST）与代理驱动的时间线组装相结合——无需连接器。现有冻结资产、清单记录和绑定不受路由更改影响——拆分仅改变下一次导入使用的凭据。

认证——两个凭据，按范围划分

预检——在首次 CLI 调用之前，检查令牌是否存在：shell 环境变量（[ -n "$FIGMA_TOKEN" ]）或项目 .env（CLI 自动加载——.env 条目算作已配置）。如果两者都不存在，不要运行命令来捕获错误——首先引导用户完成一次性设置，然后停止并等待：

1. figma.com/settings → 安全 → 个人访问令牌 → 生成新令牌。
2. 范围——此集成始终只需要只读权限（它从不写入 Figma）：文件内容：只读 + 文件元数据：只读。如果您将在非 Enterprise 计划上运行 tokens，请添加库内容：只读——已发布样式的回退会命中 /v1/files/:key/styles，如果没有此范围会返回 403（旧版设置文本遗漏的范围）。可选地添加变量：只读用于品牌变量——仅限 Enterprise；没有它会自动降级为已发布样式（预期行为，非错误——请说明）。403 现在会明确指出缺失的范围；429 会自动重试（每分钟限制，遵循 Retry-After 头部）。
3. 让用户在 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 提取什么；之后，说明工件放置的位置（冻结路径 / sidecar / 组件目录）、合成中更改的内容以及下一步操作（预览、添加打印变量、重新导入以链接绑定）。用户永远不应该问"它工作了吗？"或"现在怎么办？"。

资产（阶段 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（可缩放、可动画化）；对于光栅保真度，使用 --scale 2 的 PNG。始终传递 --description "<它是什么>"（它将成为索引行 + <img alt>）；为命名的品牌标记添加 --entity "<名称>"，以便稍后 media-use 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 sidecar + 绑定索引记录（.media/figma-bindings.jsonl）导入。变量在上游受 Enterprise 限制：在其他计划上，命令会降级为已发布样式的元数据（值在组件导入时解析）。将打印的条目添加到合成的 data-composition-variables 中。

当同时需要令牌和组件时，先导入令牌——这样可以让组件颜色链接到品牌变量，而不是烘焙副本。

非 Enterprise 变量路径（经过实地测试）： REST 变量受 Enterprise 限制，但兼容的连接器可能提供变量定义。当 tokens 报告 REQUIRES_ENTERPRISE 且连接器可用时，检索父场景的变量一次，将原始响应缓存到 .media/figma-cache/，并使用它构建绑定索引。REST 节点树的 boundVariables 提供每个属性的 VariableID；按节点和属性连接它们，然后写入 .media/figma-bindings.jsonl 行（{kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<名称>", version}）以及合成变量条目。下游的所有内容（组件 var() 解析、刷新、运行时 CSS 变量）都是已交付的机制。向用户说明："通过 Figma 连接器的令牌——Enterprise 计划可以直接从 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/<名称>/ 下的注册表项。矢量/布尔运算通过阶段 1 导出自动栅格化。绑定传递（规范 §7.1，仅精确 ID——从不进行值匹配）：

• 静态保真度自检（对主要内容为强制要求）：导入后，渲染片段并与 figma 自身的像素进行比较——figma asset <同一节点> --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 中的纯辅助函数；否则要求原生导出：

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 <SKILL_DIR>/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 的连接器渲染路径不会执行着色器（它们扁平化为基色），并且着色器源代码仅对库发布的样式（付费 Full 席位）可访问。默认路径：要求用户原生导出 Figma 中的着色器帧（PNG 或动态 MP4），然后将其作为阶段 1 资产/剪辑导入。不要尝试连接器对着色器的像素捕获——它会静默产生错误的结果。

故事板（场景帧的 SECTION → 动画）

核心规则：故事板帧是关键帧，而非幻灯片。 包含相同元素的两个帧描述了该元素随时间的状态——在状态之间对元素进行动画；切勿将帧视为静止帧的顺序播放。一个徽标在连续的四个帧中绘制为递减的 y，是一个元素通过四个关键帧上升。背靠背播放故事板帧是失败模式；重建它们所隐含的元素时间线是任务。

故事板文件遵循您可以机械解析的语法——不要目测，解码：

1. 场景单元：在 SECTION 内部，每个帧大小的节点都是一个场景——包括命名的 FRAME 和松散的完整帧 RECTANGLE（设计人员直接将静止帧粘贴到章节中）。按大小过滤（≈ 合成宽高比，例如 >1400×900），而不是按节点类型或名称。
2. 顺序 = x 位置（如果条带换行，则按行优先）。按 absoluteBoundingBox.x 对场景排序。
3. 比较相邻场景并创建一个以元素标识为键的运动映射：
   • 出现在场景 N 但不在 N-1 中的节点 → {from: "idle"/*例如透明、缩小*/}（仅对于新出现——场景 N-1 中不存在的元素）
   • 出现在两者中的节点 → {from: {x, y, rotation, opacity, scaleX, scaleY, skewX, skewY}, to: {…差值}}——如果差值足够小（<5px），则可能为自动化建议合并状态
   • 未变化的节点设置为 {remain: "unchanged"}（自动化跳过——不创建 GSAP 关键帧）
4. 输出：hyperframes.gsap 片段，由场景间 TimelineMax（分阶段，按键控）和 TweenMax.set()（用于首个场景的基准状态）组成。

始终从帧中提取关键词并让用户描述高于姿态的节奏："这是一个统一的慢入效果吗？每个元素错开 50 毫秒？前两个场景同时设置品牌，其余内容动画化？"——从设计中读取意象，而不是从他们那里提取 CSS。

在处理故事板输入时，展示代码。展示 Inspector 元素和解码的帧关系——用户将他们的电影帧读作意图，所以通过逐步说明您将如何重构它来建立信任。

质量门（所有导入）

每个导出物都必须完成以下检查：

1. 令牌完整性：没有未解决的数据 - figma - 未解析标志。
2. 组件映射：矢量和文本锚点匹配 figma 的像素位置（通过与生产阶段 1 资产输出进行比较）。

在阶段 1 CLI 模式下，如果用户请求 sync（--sync），则执行此操作：

hyperframes figma check

在连接器模式下，在最终确定合成之前，提示用户运行 npx hyperframes check。

如果保真度检查失败：不要重写组件 HTML 来解决它。相反，更新映射器逻辑（如果问题是可推广的），然后重新导入。在差异明确是 figma 的渲染（例如，特定的辐射渐变）之前，切勿对 figma 的渲染进行像素校正——在这种情况下，从阶段 1 导出的光栅化图像是基准真实值，请使用它。

平台兼容性

此技能首先在 macOS CLI（Node 18+，hyperframes CLI）上测试。Windows 需要 Git Bash 或 WSL 用于路径和 npx hyperframes。CI/CD 可以使用 hyperframes 配方，但所有令牌都必须通过环境变量设置，而不是交互式设置。对 --sync 使用 hyperframes figma check --strict 以在 CI 失败时非零退出，如果资产不一致。

使用示例

用户： "拉入这个 Frame：https://www.figma.com/file/abc123/Design?node-id=456%3A789" 代理： 正在通过 REST 提取 Stage 1 资产，冻结，输出 <img alt="Frame 名称">。如果您需要品牌令牌或组件，请告诉我。

用户： "使用我的 acme 品牌颜色" 代理： 正在从 CXF2 提取令牌。我们需要 library_content:read 范围为基础样式——您可以在 figma 令牌设置中启用它。之后，令牌将保真适用于组件。