---
chain-id: 8
name: Figma write-back (Code → Figma)
path: B
status: live
prompts: [15]
inputs: output/tokens.css (source of truth) + Figma file via MCP (write access)
outputs: Figma library variables updated to match tokens.css
documented-in: Ch19 — Code → Figma · Ch15 — Figma + AI Foundation
---

# Chain 8 — Figma Write-Back

Synchronises a Figma variable library to match `output/tokens.css`. Code is the source of truth — this chain updates Figma to match code, the opposite direction of Chain 2.

**When to use:**
- Engineering shipped a token change (new value, renamed token) that is not yet reflected in the Figma file
- A BYOC update changed palette values in code; Figma still has old values
- A new archetype token was added in code; the Figma variable library needs it
- A quarterly sync to keep Figma and code aligned

**This chain does NOT:**
- Update component structure, layer names, or auto-layout in Figma
- Create new Figma components or variants
- Push design changes from Figma to code (that is Chain 2)

**Expected runtime:** 20–40 minutes depending on variable count and scope.

**Prerequisites:**
- Claude Desktop with Figma Dev Mode MCP installed and write access confirmed
- `output/tokens.css` current and reviewed
- Figma Professional plan or above (variable write access requires it)

---

## Step table

| Step | Prompt / action | What lands | Checkpoint |
|---|---|---|---|
| 0a (optional) | `27-mapping-report.md` | Three-section mapping report: Direct Matches / Partial Matches / Figma Assembly Spec | Designer reviews and decides what to action |
| 0b | Confirm MCP write access to Figma | Write calls succeed in test | Send one test write and confirm |
| 1 | `15-figma-write-back.md` | Figma variable library updated | Open Figma, spot-check 10 values against tokens.css |
| 2 | (post-run) Verify component connections | No broken variable links in Figma | Check Components page for missing variable warnings |

**Step 0a is the planning artifact.** When Figma has gaps you don't yet have visibility into (which components are in code but not Figma? which have drifted?), run [Prompt 27 — Component mapping report](../prompts/27-mapping-report.md) first. Designer reviews the report; you and the designer agree on what to add, change, or leave alone; THEN Chain 8 executes the agreed changes via Step 1. Skip this step only when you already know the scope (e.g., a routine quarterly token sync where the mapping is unchanged from last time).

---

## Step-by-step walkthrough

### Step 0 — Confirm write access

Before running Prompt 15, confirm that MCP write access is working:

1. In Claude Desktop: connect to the Figma MCP and navigate to your file
2. Ask Claude: "Read all variable collections in this Figma file and list them." Confirm the collections are visible.
3. Ask Claude: "Update the value of [any non-critical variable] to [its current value] as a write test." If the write succeeds, proceed. If it fails, resolve MCP write permissions before continuing.

Common write access failures:
- Figma Starter plan: variables are read-only. Upgrade to Professional for write access.
- MCP not in write mode: confirm the MCP server is configured with `figma:write` scope, not read-only.

---

### Step 1 — Run the write-back (Prompt 15)

**What to paste:**
1. `output/tokens.css` — the canonical token source
2. `specs/[archetype].spec.md` — for context on token naming and structure

**Choose your scope (Prompt 15 asks this before making changes):**

| Scope | What changes | Risk level |
|---|---|---|
| A — Values only | Updates hex/rgba/size values where Figma differs from tokens.css | Low — no renames |
| B — Names + values | Renames variables to match CSS token names + updates values | High — breaks component connections to renamed variables |
| C — Add missing only | Adds variables that exist in tokens.css but not in Figma | Low — additive only |
| D — Full sync | Applies A + B + C | High — most comprehensive, most disruptive |

**Recommended starting scope:** A (values only). After confirming values are correct, run scope C to add any missing variables. Avoid scope B and D unless rebuilding the Figma library from scratch.

**What the prompt does before making changes:**
Prompt 15 generates a reconciliation table showing every variable in Figma vs. every token in tokens.css — MATCH, DIFF, MISSING, or ORPHAN — and pauses for your confirmation before writing anything. Review this table carefully.

**What to check at the checkpoint:**
- DIFF rows: confirm the new value in tokens.css is intentional (not a typo or accidental change)
- MISSING rows: confirm these tokens should be added to Figma (some tokens are code-only and do not need a Figma equivalent)
- ORPHAN rows: decide for each — delete, keep, or document. Do not delete without confirming no components reference that variable.

---

### Step 2 — Verify component connections

After Prompt 15 completes, open the Figma file:

1. Go to Assets panel → Local variables. Spot-check 10 values against `output/tokens.css`. Values must match exactly.
2. Go to the Components page (if your Figma file has one). Look for any components showing "missing variable" warnings in the right-side panel. These indicate a variable was renamed (scope B/D) and the component connection broke.
3. For each broken connection: re-apply the variable by selecting the affected layer and choosing the new variable name from the variable picker.

If scope A was used (values only), there should be zero broken connections. Broken connections only occur with scope B or D (renames).

---

## When to use — decision guide

| Situation | Use this chain? | Notes |
|---|---|---|
| Token value changed in code | Yes — scope A | Fast, safe, no renames |
| Token renamed in code | Yes — scope B | Warn team: component reconnection required |
| New token added in code | Yes — scope C | Additive only, no risk |
| Designer changed Figma, need code to match | No — use Chain 2 | Chain 2 is Figma → code |
| Component added in code, not in Figma | Not this chain | Prompt 15 handles variables only; component creation is manual |

---

## Cadence

Run this chain:
- After every sprint that includes token changes
- After any BYOC update that changes palette values
- After a quarterly token audit (Chain 4) resolves Category A drift

Keep `output/chain-state.md` updated with each run. The state log is how future sessions know what version of tokens.css was last synced to Figma.

---

*Chain 8 · Figma Write-Back · Design Systems That Build Themselves · © 2026 Ishdeep S Sahni*