figma-component-properties

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

两个相关任务：

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

技能范围

• use_figma 规则 — 首先加载官方 figma-use 技能；它是完整的 Figma Plugin API 参考。这些脚本依赖的要点：使用带顶层 await 和 return 的纯 JS（不要使用 IIFE 或 figma.closePlugin()；console.log 不会作为返回值返回），在每个脚本顶部以内联 const 定义输入，颜色值范围为 0–1，在进行任何文本操作前加载字体，使用 await figma.getNodeByIdAsync(...)，并遵守原子错误规则（脚本失败时不会应用任何更改——读取错误、修复后重试）。
• 读取组件现有属性定义／状态机 → 使用 figma-analyze-component-set 或 figma-deep-component。
• 这些是设计系统编写操作，原生 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: "figma-component-properties"）。设置 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。