用途
component-properties-figma 面向 Figma 设计系统的组件作者，处理两件相关的工作：
- 编写组件的属性 API：添加、编辑、删除 TEXT、BOOLEAN、INSTANCE_SWAP 和 VARIANT 属性，让组件暴露出正确的可调参数（相当于 React 组件的 props）。
- 使用组件：创建组件实例并设置其属性，包括标签文本、布尔开关、变体选择以及替换的子实例。
该技能属于设计系统编写类的写入操作，原生 MCP 的 get_design_context / get_metadata（只读）并不覆盖这些能力。
主要能力
属性类型
| 类型 | 控制内容 | defaultValue | 说明 |
|---|---|---|---|
| TEXT | 文本图层的字符串覆盖 | "Label" | 在 UI 中绑定到文本节点的 characters |
| BOOLEAN | 显示/隐藏图层 | true/false | 绑定到图层的可见性 |
| INSTANCE_SWAP | 由哪个子组件填充插槽 | 一个组件 key | 传入 preferredValues 以填充选择器 |
| VARIANT | 一个变体轴（Size、State 等） | 一个选项字符串 | 仅在 COMPONENT_SET 上有意义 |
编写属性的工作流
- 目标对象是 COMPONENT_SET（或独立的 COMPONENT）。不能给单个变体添加属性——脚本会报错并提示使用父级 set。
- 使用 scripts/add-property.js（use_figma，skillNames: "component-properties-figma"）添加属性。设置 NODE_ID、PROPERTY_NAME、PROPERTY_TYPE、DEFAULT_VALUE。addComponentProperty 返回的名称带有 #id 后缀，需要捕获它。
- 编辑/删除时复用同一脚本的 editComponentProperty(name, {...}) / deleteComponentProperty(name) 调用（脚本中带有注释形式的变体）。对非变体属性进行编辑/删除时，使用创建时返回的带后缀名称。
- 通过重新读取 node.componentPropertyDefinitions 进行验证（脚本会返回它）。
实例化并设置实例属性的工作流
- 获取组件身份。优先使用已发布库的 componentKey，和/或本地 nodeId。两者都有时都传入——脚本会先尝试库导入，再尝试本地节点。
- 运行 scripts/instantiate-and-set.js。设置 COMPONENT_KEY / COMPONENT_ID、可选的 VARIANT（例如 { Size: "md", State: "default" }）、OVERRIDES、POSITION 和 PARENT_ID。
- 对已有实例设置属性时使用同一脚本的 setProperties 路径——它会加载主组件，然后自动匹配普通名称和带 Name#id 后缀的名称。
使用方式与依赖
该技能依赖官方 figma-use 技能，需先加载它，它是完整的 Figma Plugin API 参考。这些脚本依赖的要点包括：使用带顶层 await + return 的普通 JS（不用 IIFE，不用 figma.closePlugin()；console.log 不会被返回）；输入以 const 内联在每个脚本顶部；颜色使用 0–1 范围；任何文本操作前先加载字体；使用 await figma.getNodeByIdAsync(...)；以及原子性错误（脚本失败时不应用任何更改——读取错误、修复、重试）。
适用场景
- 为设计系统组件定义和调整属性 API。
- 创建组件实例并批量设置文本、布尔、变体和实例替换属性。
- 需要写入组件属性定义，而只读 MCP 工具无法覆盖的场景。
限制与注意事项
- 不能给单个变体添加属性，必须针对 COMPONENT_SET 或独立 COMPONENT。
- 实例属性键对 TEXT/BOOLEAN/INSTANCE_SWAP 带有 #nodeId 后缀（如 "Label#12:3"）；VARIANT 属性使用裸名称。实例化脚本会解析两者，因此可以传入人类可读名称（Label），它会找到带后缀的键。
- 直接编辑实例文本图层的文本会静默失败——始终通过 setProperties / 实例属性，绝不要对嵌套实例文本节点设置 .characters。
- componentKey 仅适用于已发布的组件。对于本地/未发布的组件，使用 nodeId。
- 读取组件已有的属性定义 / 状态机请使用 analyze-component-set-figma 或 deep-component-figma。
暂未提供的信息
关于该技能的收费、价格、平台支持范围、具体效果指标等，资料中暂未提供。