ensure_collection
Creates a Figma variable collection by name and modes, or returns the existing one if it already matches, preventing duplicate collections.
Instructions
Idempotent VariableCollection creation — safe to retry.
Returns existing collection if one with the same name + identical mode list already exists, otherwise creates a new one. Spec §3.1.
Prefer this over create_collection — re-running with the same name + modes returns the existing collection instead of creating a duplicate.
Omit idempotency_key — the handler computes it canonically from (name, modes). Pass it only if you need strict concurrency-safety validation (LLMs should not try to compute SHA-256 inline; placeholder strings are rejected).
Returns {data: {collection_id, modes: [{modeId, name}], reused?: true}}.
Examples: ensure_collection({name: "Theme", modes: ["Light", "Dark"]})
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Collection name | |
| modes | Yes | Mode names (first becomes default) | |
| idempotency_key | No | Optional. Handler auto-computes canonically if omitted. Pass only if you need strict concurrency-safety validation against the SHA-256 formula in spec §3.1. |