# 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-

…