analyze-component-set-figma

analyze-component-set-figma — 变体状态机 → 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(...)；以及原子错误（脚本失败时不会应用任何内容——读取错误、修复后重试）。
• 完整递归树（无限深度、交互、实例引用）→ 使用 deep-component-figma。
• 将变体重新整理为带标签的网格 → 使用 arrange-component-set-figma。
• 添加或移除属性本身 → 使用 component-properties-figma。
• 这是一种设计系统代码生成能力，原生 MCP 的 get_design_context / get_metadata 不提供此能力——它们返回原始结构，而不是变体→CSS 状态机。

工作流

1. 获取 COMPONENT_SET ID。 从用户的选择（figma_get_selection）、搜索结果或用户粘贴的节点 ID 获取。它必须是集合，而非单个变体——脚本会验证类型。
2. 运行 scripts/analyze-component-set.js，通过 use_figma 执行（skillNames: "analyze-component-set-figma"）。先在顶部设置 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 规则，并确认差异中的 token 名称（例如 Color/Brand/Primary）能解析为已导出的 token。

状态如何映射到 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 只会列出发生变化的属性（填充 token、描边、文本颜色、不透明度、效果、子元素可见性）。覆盖规则只需准确输出这些属性——不要重新指定未变化的属性。
• 脚本会在可用时将 boundVariables（填充/描边）解析为 token 名称，否则回退为原始十六进制值。生成代码时优先使用 token 名称。
• 轴检测采用启发式：名为 state/status/interaction 的轴会被识别为状态轴；size/scale 会被识别为尺寸轴。如果集合中的轴名称不同，cssMapping 可能为空——请读取 variantAxes 并自行映射状态。