按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
component-properties-figma — define a component's API + instantiate it
Two related jobs:
- Author the component's property API — add/edit/delete
TEXT,BOOLEAN,INSTANCE_SWAP, and
VARIANT properties so the component exposes the right knobs (the Figma equivalent of a React component's props).
- Use the component — create an instance and set its properties (label text, boolean toggles,
variant selection, swapped sub-instances).
Skill boundaries
- `use_figma` rules — load the official `figma-use` skill first; it is the full Figma Plugin API reference. Essentials these scripts rely on: plain JS with top-level
await+return(no IIFE, nofigma.closePlugin();console.logis not returned), inputs inlined asconstat the top of each script, colors in 0–1 range, load fonts before any text op,await figma.getNodeByIdAsync(...), and atomic errors (a failed script applies nothing — read the error, fix, retry). - Reading a component's existing property definitions / state machine →
use analyze-component-set-figma or deep-component-figma.
- These are design-system authoring writes the native MCP's
get_design_context/
get_metadata (read-only) do not cover.
Property types
| Type | What it controls | defaultValue | Notes |
|---|---|---|---|
TEXT | A text-layer string override | "Label" | Bind in UI to a text node's characters |
BOOLEAN | Show/hide a layer | true/false | Bind to a layer's visibility |
INSTANCE_SWAP | Which sub-component fills a slot | a component key | Pass preferredValues to populate the picker |
VARIANT | A variant axis (Size, State…) | one option string | Only meaningful on a COMPONENT_SET |
Workflow — authoring properties
- Target the COMPONENT_SET (or standalone COMPONENT). You cannot add properties to an
individual variant — the script errors and tells you to use the parent set.
- Add with `scripts/add-property.js` (
use_figma,
skillNames: "component-properties-figma"). Set NODE_ID, PROPERTY_NAME, PROPERTY_TYPE, DEFAULT_VALUE. addComponentProperty returns a name with a #id suffix — capture it.
- Edit / delete by reusing the same script's
editComponentProperty(name, {...})/
deleteComponentProperty(name) calls (commented variants are in the script). Use the suffixed name returned at creation for edits/deletes of non-variant props.
- Verify by re-reading
node.componentPropertyDefinitions(the script returns it).
Workflow — instantiate + set instance properties
- Get a component identity. A published library
componentKey(preferred) and/or a local
nodeId. Pass both when you have them — the script tries the library import first, then the local node.
- Run `scripts/instantiate-and-set.js`. Set
COMPONENT_KEY/
COMPONENT_ID, optional VARIANT (e.g. { Size: "md", State: "default" }), OVERRIDES, POSITION, and PARENT_ID.
- Set properties on an existing instance with the same script's
setPropertiespath — it loads
the main component, then matches plain names and Name#id-suffixed names automatically.
Notes
- Instance property keys carry `#nodeId` suffixes for TEXT/BOOLEAN/INSTANCE_SWAP
("Label#12:3"); VARIANT props use the bare name. The instantiate script resolves both, so you can pass the human name (Label) and it finds the suffixed key.
- Direct text editing of an instance's text layer fails silently — always go through
setProperties / instance properties, never set .characters on a nested instance text node.
componentKeyonly works for published components. For local/unpublished ones usenodeId.
