figma-analyze-component-set

figma-analyze-component-set — 变体状态机 → CSS

将 Figma COMPONENT_SET（包含某个组件所有变体的紫色虚线容器）转换为代码生成蓝图：哪些属性轴属于状态，哪些属于尺寸；每种状态如何映射到 CSS 伪类或 ARIA 属性；以及每种状态在默认变体基础上应用的最小视觉差异。这是连接“Figma 中有 12 个按钮变体”和“生成一条 .btn 规则，再添加 :hover/:disabled 覆盖规则”的桥梁。

技能边界

• use_figma 规则 — 首先加载官方 figma-use 技能；它是完整的 Figma Plugin API 参考。这些脚本依赖的要点：使用带顶层 await 和 return 的纯 JS（不要用 IIFE，也不要用 figma.closePlugin()；console.log 不会作为返回值返回）；在每个脚本顶部以内联方式定义输入 const；颜色取值范围为 0–1；执行任何文本操作前先加载字体；使用 await figma.getNodeByIdAsync(...)；以及原子错误（脚本执行失败时不会应用任何更改——读取错误、修复后重试）。
• 完整递归树（不限深度，包含交互响应和实例引用）→ 使用 figma-deep-component。
• 将变体重新整理为带标签的网格 → 使用 figma-arrange-component-set。
• 添加/移除属性本身 → 使用 figma-component-properties。
• 这是一项设计系统代码生成能力，原生 MCP 的 get_design_context / get_metadata 不提供此功能——它们返回原始结构，而不是变体→CSS 状态机。

工作流

1. 获取 COMPONENT_SET ID。 从用户的选择（figma_get_selection）、搜索结果或用户粘贴的节点 ID 中获取。它必须是集合，而不是单个变体——脚本会验证类型。
2. 通过 use_figma 运行 scripts/analyze-component-set.js（skillNames: "figma-analyze-component-set"）。先在顶部设置 const COMPONENT_SET_ID。
3. 读取结果。 返回的数据包括 variantAxes（各属性轴及其选项）、componentProps（非变体 TEXT/BOOLEAN/INSTANCE_SWAP 属性 → 代码属性）、包含 cssMapping（状态名称 → CSS 选择器）和 defaultSignature 的 stateMachine，以及每个变体的 diffFromDefault。
4. 生成代码。 根据 defaultSignature 实现默认变体，然后为每个 cssMapping 条目添加一条规则，仅应用该变体的 diffFromDefault。将 componentProps 映射为框架属性：BOOLEAN→boolean，TEXT→string，INSTANCE_SWAP→ReactNode/slot，VARIANT→union。
5. 验证。 交叉检查 stateMachine.states 中的每种状态是否都已添加 CSS 规则，并确认差异中的令牌名称（例如 Color/Brand/Primary）能解析到已导出的令牌。

状态如何映射到 CSS

脚本会将状态轴的值（不区分大小写）规范化为选择器：

变体值	CSS / ARIA 选择器
default	（基础规则，无选择器）
hover	:hover
focus / focused / focus-visible	:focus-visible
active / pressed	:active
disabled	:disabled, [aria-disabled="true"]
error / invalid	[aria-invalid="true"]
selected	[aria-selected="true"]
checked	:checked
loading	[aria-busy="true"]
open / closed	`[aria-expanded="true"
filled	.has-value

说明

• 差异以默认变体为基准计算，因此某个状态的 diffFromDefault 只列出发生变化的属性（填充令牌、描边、文本颜色、不透明度、效果、子项可见性）。只将这些属性作为覆盖规则输出——不要重新指定未变化的属性。
• 脚本会在可用时将 boundVariables（填充/描边）解析为令牌名称，否则回退到原始十六进制值。生成代码时优先使用令牌名称。
• 属性轴检测采用启发式规则：名称为 state/status/interaction 的属性轴会被视为状态轴；size/scale 会被视为尺寸轴。如果集合中的属性轴使用了其他名称，cssMapping 可能为空——请读取 variantAxes 并自行映射状态。