用途
figma 技能用于将用户的 Figma 工作内容导入 HyperFrames 合成。按设计规范的能力拆分，分为五个阶段：静态资源、品牌 token/样式、组件转 HTML、动效转 GSAP、着色器。此外还涵盖将 storyboard 区段（一组场景帧）重建为动画。
主要能力
- 阶段 1 静态资源：通过 REST 渲染，对 SVG 做清洗，冻结到
.media/images/下，追加带来源信息的 manifest，重新生成.media/index.md，并输出<img>片段。支持--format svg|png|jpg|pdf、--scale、--description、--entity参数；可一次请求批量导入同一文件的多个节点。 - 阶段 2 品牌 token/样式：
hyperframes figma tokens <fileKey>将变量导入为合成品牌变量条目，并生成figma-tokens.json副文件与绑定索引记录。变量在企业版上游受控；非企业版降级为已发布样式元数据。建议在导入组件前先导入 token，以便组件颜色链接到品牌变量。 - 阶段 3 组件转 HTML：
hyperframes figma component '<url-or-fileKey:nodeId>'把节点树转换为精确 Figma 几何的可编辑 HTML，打包为compositions/components/<name>/下的注册项。矢量/布尔运算会自动光栅化。绑定过程仅按精确 ID 匹配，不做值匹配；绑定到已导入 token 的填充变为var(--slug, #literal)；未知 token 则使用字面值并加data-figma-unresolved标记。含强制性的静态保真自检，用 Figma 自身像素作为基准对比。 - 阶段 4 动效转 GSAP：无 REST 等价方案。在兼容 Figma 连接器可用时，递归获取父帧的动效上下文，保存原始 JSON 到
.media/figma-cache/，再用@hyperframes/core/figma中的motionContextToDocs归一化为 MotionDocs，避免手工转录关键帧数值。之后motionToGsap(doc)→emitTimelineScript(spec)注入为脚本。含强制性的真值校验脚本verify-motion.mjs（要求 motion-PSNR 不低于 15dB）。 - 阶段 5 着色器：Figma 连接器渲染路径不执行着色器（会压平为基础色），着色器源码仅对已发布库样式可达。默认路径是请用户在 Figma 中原生导出着色器帧，再作为阶段 1 资源导入。
- Storyboard 重建：storyboard 帧是关键帧而非幻灯片。需解析区段语法：场景单元按尺寸筛选（约 >1400×900），顺序按
absoluteBoundingBox.x，相邻帧做元素链比对（先按名称，再按几何相似度），每个链导出一个资源。文本节点为导演注释，映射为转场。若所有帧描绘同一产品 UI 的连续状态，则升级为重建应用界面而非元素链。
使用方式
- 认证：两套凭证。REST 使用
FIGMA_TOKEN（shell 环境变量或项目.env，CLI 自动加载）。令牌需只读权限：File content: Read-only、File metadata: Read-only；非企业版运行 tokens 时还需 Library content: Read-only；可选 Variables: Read-only（仅企业版）。不可让用户在对话中粘贴令牌。动效/着色器阶段需要兼容的 Figma 连接器，其授权独立于令牌。 - 保持更新：运行
npx hyperframes skills update figma（需先与用户确认）。 - 错误处理：BAD_TOKEN（401）需重新签发；FORBIDDEN（403）消息会指明缺失的具体权限范围；REQUIRES_ENTERPRISE（403）非失败，样式回退已自动执行；RATE_LIMITED（429）客户端已按 Retry-After 退避重试（上限 60 秒）。
- 速率限制：连接器配额随 Figma 方案而异；REST 按分钟计（每端点 10+/分钟）。建议批量请求、跳过非必要的验证截图、缓存原始响应。
- 动效/着色器/storyboard 阶段的信标：使用
npx hyperframes events --skill=figma-motion等命令（匿名、需同意、不会失败）。
适用场景
- 把 Figma 中的图层、logo、图像导入为渲染资源。
- 拉取品牌颜色/token 并在合成中复用，实现一处更新、全局换肤。
- 由某个帧构建场景组件。
- 导入动画/动效并转为 GSAP 时间线。
- 将 storyboard 的场景帧区段重建为动画。
- 处理着色器填充/效果（多为手动导出路径）。
限制
- 动效与着色器无 REST 等价，依赖可选的兼容 Figma 连接器或用户提供的原生导出。
- Figma 连接器渲染路径不执行着色器，连接器像素捕获着色器会静默产出错误结果。
- 变量导入在企业版上游受控，非企业版降级为已发布样式。
- 着色器源码仅对已发布库样式（需付费 Full 席位）可达。
- 批量导出大场景帧时，超过约 12 个 id 会触发渲染超时，需分块（约每次 4 个）并重试。
- 命名缓动若不在映射表内会回退为线性，需向用户标记。
- 若静态保真对比发现映射器未覆盖的漂移，应报告而非静默手动调整片段。
- 具体收费、价格未见资料明确提供。