/cc-figma-tokens

name: cc-figma-tokens
description: "Build or update Figma variable collections (Primitives and Semantic) from component-contracts token files. Use when the user wants to sync their design token definitions into Figma as native variables — e.g. 'build the token library', 'sync tokens to Figma', 'create Figma variables from tokens', 'update the variable collections'. This skill is a PREREQUISITE for cc-figma-component — tokens must exist in Figma before components can be built. Requires the figma-use and figma-generate-library skills."

cc-figma-tokens — Component Contracts Token Skill

Build Figma variable collections from component-contracts token files. This skill creates the Primitive and Semantic variable collections that all components bind to.

**Prerequisites — load these skills first:**

• `figma-use` — Plugin API syntax rules (mandatory before every `use_figma` call)
• `figma-generate-library` — Design system workflow and variable creation patterns

**Always pass `skillNames: "cc-figma-tokens"` when calling `use_figma` as part of this skill.**

---

1. Configuration

Before anything else, read `.component-contracts` from the project root. This file contains all required configuration. Never output `FIGMA_ACCESS_TOKEN` in any response.

FIGMA_ACCESS_TOKEN=...       # never output this value
FIGMA_FILE_KEY=...           # use for all use_figma calls
TOKENS_DIR=...               # root directory of token files
CONTRACTS_DIR=...            # root directory of contract files

If `.component-contracts` is missing, tell the user to copy `.component-contracts.example` and fill in their values before proceeding.

---

2. Token File Structure

Component-contracts uses W3C DTCG token format organized in two tiers:

{TOKENS_DIR}/
  primitive/
    color.tokens.json
    motion.tokens.json
    shape.tokens.json
    space.tokens.json
    typography.tokens.json
  semantic/
    semantic.tokens.json

**Tier 1 — Primitives**: Raw values. Named with scale suffixes (`color/blue/500`, `space/4`). No aliases. Single mode: `Value`.

**Tier 2 — Semantic**: Aliases into Primitives. Named with roles (`brand/500`, `surface/default`, `text/primary`). Single mode: `Value`.

Read all token files before creating anything in Figma. Build a complete in-memory map of all tokens and their values/aliases before making any `use_figma` calls.

---

3. Figma Variable Architecture

Collections

Create exactly two collections in this order:

| Collection | Modes | Purpose | |-----------|-------|---------| | `Primitives` | `Value` | Raw token values — never bound directly to components | | `Semantic` | `Value` | Aliases into Primitives — this is what components bind to |

Variable naming

Use `/` as the group separator, matching W3C DTCG path structure:

Primitives:  color/blue/500, space/4, radius/md
Semantic:    brand/500, surface/default, text/primary, focus/default

Variable scopes

**NEVER use `ALL_SCOPES`.** Assign scopes based on the token's semantic role:

| Token role | Scope | |-----------|-------| | Color — background/fill | `FRAME_FILL`, `SHAPE_FILL` | | Color — text | `TEXT_FILL` | | Color — border/stroke | `STROKE_COLOR` | | Color — focus ring | `FRAME_FILL`, `SHAPE_FILL`, `STROKE_COLOR` | | Spacing — padding, gap | `GAP` | | Spacing — border width | `STROKE_WIDTH` | | Border radius | `CORNER_RADIUS` | | Typography — font size | `FONT_SIZE` | | Typography — font weight | `FONT_WEIGHT` | | Typography — line height | `LINE_HEIGHT` | | Primitives (all) | `[]` — hidden from property panels |

> **Note:** `HORIZONTAL_PADDING` and `VERTICAL_PADDING` are NOT valid `VariableScope` enum values in the Figma Plugin API. Use `GAP` only for all spacing variables.

Code syntax

Every variable MUST have WEB code syntax set. Use the `var()` wrapper with the CSS custom property name:

Primitive color/blue/500  →  var(--ds-color-blue-500)
Semantic brand/500        →  var(--ds-brand-500)
Semantic surface/default  →  var(--ds-surface-default)

CSS naming convention: `--ds-{path-with-dashes}` where `/` becomes `-`.

ANDROID and iOS do NOT use a `var()` wrapper.

---

4. Execution Modes

**Default (fast):** Present the Phase 0 plan and await approval, then run Phases 1–4 sequentially without stopping. This is the default for all runs.

**Debug mode:** Stop after each phase and await explicit approval before proceeding. Use when diagnosing issues or validating intermediate output. Activate by including "debug mode" in your prompt.

---

5. Workflow

Batching requirement (critical for performance)

**Create ALL variables in a single `use_figma` call per collection.** Never create variables one at a time or category by category.

• One `use_figma` call creates the Primitives collection + all variables
• One `use_figma` call creates the Semantic collection + all aliases
• Do NOT write intermediate state files between variables
• Do NOT validate between individual variables
• Validate ONCE after the entire collection is created

Token creation is deterministic and low-risk. The state ledger and intermediate file-writing pattern from `figma-generate-library` is NOT appropriate here — skip it entirely. Read all token files first, build the complete variable map in memory, then execute in one call per collection.

If a collection exceeds ~80 variables and must be split across two calls, split by category (e.g. color in one call, everything else in another) — never by individual variable.

---

Phase 0 — Inspect (read-only)

Before creating anything:

1. Read all token files from `TOKENS_DIR` 2. Inspect the Figma file — check for existing variable collections named `Primitives` or `Semantic` 3. If collections exist, check whether this is a create or update operation 4. Present a summary to the user: token counts per tier, existing vs. new collections, any conflicts 5. **Await explicit user approval before proceeding**

Phase 1 — Primitives collection

1. Re