figma_variant_set
Build or update a Figma component set as a property matrix in one undoable transaction: combine components, add variants, or rename properties, with dry-run validation before writing.
Instructions
Author a COMPONENT_SET as a property matrix in ONE transaction. action "combine" turns standalone COMPONENTs into a new set (names are replaced by the requested variant names), "add" clones an existing variant with a new property combination, and "edit" renames one variant in place. The dry run (default) validates the whole matrix: every variant has the same property names, no combination is duplicated, the destination is not an INSTANCE, another set or a COMPONENT definition, and a combine destination is not inside one of its own variants. It returns per-component and per-set fingerprints plus the destination layout, so a changed document is refused before writing. Apply with the returned planId and expectedFingerprints; it is one undo transaction. After writing, component names are read back as variantProperties and the set matrix is verified — a Figma that did not accept the name is rolled back, not reported as a success; if the undo itself fails, the error says ROLLBACK FAILED. Components already in a set are refused by combine; components inside an INSTANCE are refused. A combine destination inside a COMPONENT is refused because Figma will not reparent a component into a component definition; add and edit still operate on an existing set.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"action": "<action>"
},
"name": "figma_variant_set"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | combine: the new COMPONENT_SET name | |
| index | No | add: insertion index inside the set; omitted appends | |
| action | Yes | combine: standalone COMPONENTs -> new COMPONENT_SET | add: clone a variant with new properties | edit: rename one variant's properties | |
| dryRun | No | TRUE (default): validate and fingerprint only. FALSE: apply in one undo transaction. | |
| planId | No | The planId returned by figma_variant_set; if supplied on apply, a different request is refused before it is sent | |
| fileKey | No | Which connected Figma file to use: its fileKey (figma_whoami) or, when omitted, the only connected file. Required once more than one file is connected; figma_ping lists them. | |
| parentId | No | combine: where to create the set. Omit when all components already share a parent | |
| sourceId | No | add: the existing variant to clone | |
| parentKey | No | combine: stable key of the destination, resolved on the current page | |
| sourceKey | No | add: stable key of the variant to clone, resolved on the current page | |
| variantId | No | edit: the variant to rename | |
| components | No | combine: the components and the variant properties each one should represent | |
| properties | No | add/edit: the new variant's complete property map | |
| variantKey | No | edit: stable key of the variant to rename, resolved on the current page | |
| expectedFingerprints | No | Required on apply: nodeId -> fingerprint from the dry run, covering every component, the set and its destination layout. |