setup-design-tokens-figma — atomic token-system bootstrap

Create a variable collection + modes + all variables in a single use_figma call. This is the fastest way to stand up a new token system (or a new collection within one). Because it runs as one atomic script, either everything is created or nothing is (failed scripts apply no changes).

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, no figma.closePlugin(); console.log is not returned), inputs inlined as const at 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).
• Incremental CRUD / batch edits to an existing system → manage-variables-figma.
• Sync from a code token file → import-tokens-figma.

Workflow

1. Agree the v1 scope. List the collection name, the modes (first one is the default), and the

full token set with per-mode values. Lock this before writing — it's much cheaper than editing afterward.

1. Fill the constants in scripts/setup-tokens.js: COLLECTION_NAME,

MODES, TOKENS (values keyed by mode name), and optional per-variable SCOPES.

1. Run via use_figma (skillNames: "setup-design-tokens-figma"). It returns

{ collectionId, modes, created, errors }.

1. Validate with get_variable_defs or the export-tokens-figma read script, then screenshot if

you also created swatches.

Notes

• Two-tier systems: create primitives (raw values) with this skill, then create semantic

tokens that alias them using import-tokens-figma (which has the alias pass) or manage-variables-figma. Keep primitives single-mode and put theming on the semantic layer.

• Set scopes: the default ALL_SCOPES clutters every property picker. Pass SCOPES for the

surfaces each token belongs to (FRAME_FILL/SHAPE_FILL for backgrounds, TEXT_FILL for text, GAP for spacing, CORNER_RADIUS for radii, WIDTH_HEIGHT for sizing).

• Keep one bootstrap per collection. Multiple collections = multiple runs.