component-properties-figma

component-properties-figma — 定义组件的 API 并创建其实例

两个相关任务：

1. 编写组件的属性 API — 添加、编辑或删除 TEXT、BOOLEAN、INSTANCE_SWAP 和 VARIANT 属性，让组件提供恰当的可调选项（相当于 Figma 中 React 组件的 props）。
2. 使用组件 — 创建实例并设置其属性（标签文本、布尔开关、变体选择、替换子实例）。

技能边界

• use_figma 规则 — 首先加载官方的 figma-use 技能；它是完整的 Figma Plugin API 参考。这些脚本依赖的要点：使用普通 JS，支持顶层 await 和 return（不使用 IIFE，也不调用 figma.closePlugin()；console.log 不会作为返回值返回）；在每个脚本顶部将输入内联为 const；颜色范围为 0–1；执行任何文本操作前先加载字体；使用 await figma.getNodeByIdAsync(...)；以及原子错误（脚本失败时不会应用任何更改 — 读取错误、修正后重试）。
• 读取组件现有属性定义／状态机 → 使用 analyze-component-set-figma 或 deep-component-figma。
• 这些是设计系统编写操作，原生 MCP 的 get_design_context／ get_metadata（只读）无法完成。

属性类型

类型	控制内容	defaultValue	备注
TEXT	文本图层字符串覆盖值	"Label"	在 UI 中绑定到文本节点的字符
BOOLEAN	显示／隐藏图层	true／false	绑定到图层的可见性
INSTANCE_SWAP	填充插槽的子组件	组件 key	传入 preferredValues 以填充选择器
VARIANT	变体轴（Size、State…）	一个选项字符串	仅适用于 COMPONENT_SET

工作流 — 编写属性

1. 指定 COMPONENT_SET（或独立的 COMPONENT）作为目标。 你不能向单个变体添加属性 — 脚本会报错并提示你使用父级集合。
2. 使用 scripts/add-property.js 添加（use_figma， skillNames: "component-properties-figma"）。设置 NODE_ID、PROPERTY_NAME、PROPERTY_TYPE、 DEFAULT_VALUE。addComponentProperty 会返回带 #id 后缀的名称 — 请记录下来。
3. 通过重复使用同一脚本中的 editComponentProperty(name, {...})／ deleteComponentProperty(name) 调用来编辑／删除（脚本中提供了注释掉的示例）。编辑／删除非变体属性时，请使用创建时返回的带后缀名称。
4. 验证：重新读取 node.componentPropertyDefinitions（脚本会返回该值）。

工作流 — 创建实例并设置实例属性

1. 获取组件标识。 已发布库中的 componentKey（首选）和／或本地 nodeId。如果两者都有，请同时传入 — 脚本会先尝试导入库组件，再尝试本地节点。
2. 运行 scripts/instantiate-and-set.js。设置 COMPONENT_KEY／ COMPONENT_ID，可选的 VARIANT（例如 { Size: "md", State: "default" }）、OVERRIDES、 POSITION 和 PARENT_ID。
3. 使用同一脚本的 setProperties 路径设置现有实例的属性 — 脚本会加载主组件，然后自动匹配普通名称和带 Name#id 后缀的名称。

备注

• 实例属性键带有 #nodeId 后缀，适用于 TEXT／BOOLEAN／INSTANCE_SWAP （"Label#12:3"）；VARIANT 属性则使用不带后缀的名称。创建实例的脚本会自动解析两种形式，因此你可以传入易读名称（Label），脚本会找到带后缀的键。
• 直接编辑实例的文本图层会无声失败 — 始终通过 setProperties／实例属性操作，不要对嵌套实例文本节点设置 .characters。
• componentKey 仅适用于已发布组件。对于本地／未发布组件，请使用 nodeId。