Skip to content
Beta Multi-model support (OpenAI, Gemini, and more) launching soon.
RBA RBA Skills

design-system-sync

Installable Ships in design-to-code-builder — or copy the raw skill below.
Open Claude.ai

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

Design System Sync

Keep the codebase token layer in lockstep with the Figma design system. This skill reads the current Figma Variables via MCP, compares them against the checked-in token file, and produces a human-readable drift report and an updated token file ready to review and merge.

Usage

/design-system-sync <figma-url> [options]

Options:

Flag Values Default Description
--tokens file path auto-detect Current codebase token file
--out file path overwrites --tokens Where to write the updated token file
--modes comma-separated light Figma Variable modes to sync
--dry-run flag off Report drift without writing any files
--formats comma-separated same as current Also regenerate derived outputs (css, tailwind, scss)

Examples:

/design-system-sync https://figma.com/file/DS123/RBA-Design-System --dry-run
/design-system-sync https://figma.com/file/DS123/RBA-Design-System --modes light,dark --formats css,tailwind
/design-system-sync https://figma.com/file/DS123/RBA-Design-System --out tokens/tokens-updated.json

Phase 1 — Read Both Sources

1.1 Figma Variables (source of truth)

Call get_variable_defs for the Figma file URL. Build a flat map:

figmaTokens: Map<path, { value, type, modes, description }>

where path is the DTCG dot-path translation of the Figma /-separated variable name.

1.2 Codebase token file

Read the token file at --tokens or auto-detect:

tokens/tokens.json
src/tokens/tokens.json
design-tokens/tokens.json

Build a parallel flat map:

codeTokens: Map<path, { $value, $type, $description }>

If no token file is found, treat the codebase as starting from zero tokens. All Figma Variables become "added" tokens, and the sync becomes a first-time extraction.

Phase 2 — Compute the Diff

Compare figmaTokens against codeTokens:

2.1 Added tokens

figmaTokens has the path; codeTokens does not.

Possible causes:

  • New component added to the design system
  • Token renamed in Figma (both an "added" and a "removed" entry)
  • New mode (e.g. new brand theme) introduced in Figma

2.2 Removed tokens

codeTokens has the path; figmaTokens does not.

Risk assessment:

  • Search the codebase for CSS custom property usages: Grep("var(--<property-name>)")
  • If any component references the removed token, flag as breaking change
  • If unused in code, flag as safe removal

2.3 Changed values

Both maps have the path; values differ.

Sub-categories:

  • Color value changed — re-run contrast check for all pairs involving this token
  • Dimension value changed — note spacing/sizing impact; not automatically a regression
  • Token type changed — flag for manual review (e.g. color → dimension is almost certainly wrong)
  • Reference changed — token used to alias color.blue.500, now aliases color.blue.600

2.4 Changed descriptions only

$value and $type unchanged; $description updated. Low risk — apply automatically.

Phase 3 — Contrast Regression Check

For every changed color token, identify the contrast pairs it participates in (using the pair convention from design-token-extract). Re-compute contrast ratios for the new values.

Report:

## Contrast Impact of Changed Tokens

| Token changed | Was | Now | Affected pair | Old ratio | New ratio | Gate | Result |
|---|---|---|---|---|---|---|---|
| color.interactive.primary | #0057B8 | #0063CC | on-interactive-primary | 6.1:1 | 5.6:1 | 4.5:1 | PASS |
| color.feedback.warning | #FFAA00 | #FFCC00 | on-feedback-warning | 4.6:1 | 3.1:1 | 4.5:1 | FAIL — REGRESSION |

A FAIL entry is a contrast regression introduced by the Figma change. Flag these explicitly to the design team before accepting the sync.

Phase 4 — Build the Updated Token File

Apply the diff to generate the updated tokens.json:

  1. Merge added tokens into the DTCG structure
  2. Remove tokens flagged as "safe removal" (no code usages) — comment removals that ARE in use
  3. Update changed values
  4. Preserve $description values that were manually enriched in code (not overwrite)
  5. Add auto-generated sync metadata to the file header:
{
  "$metadata": {
    "generatedBy": "design-system-sync",
    "figmaFile": "<url>",
    "syncedAt": "<ISO timestamp>",
    "modesExported": ["light", "dark"]
  },
  "color": { ... }
}

If --dry-run is set, skip writing files. Print the diff only.

Phase 5 — Regenerate Derived Formats (if --formats)

If --formats is provided, regenerate the specified outputs using the same logic as design-token-extract Phase 5. Write alongside the updated .tokens.json.

Phase 6 — Drift Report

## Design System Sync Report

**Figma source:** <url>
**Codebase token file:** <path>
**Modes synced:** Light, Dark
**Sync date:** <ISO date>

---

### Summary

| Change type | Count |
|-------------|-------|
| Added | N |
| Removed (safe) | N |
| Removed (breaking — in use) | N |
| Value changed | N |
| Description only | N |
| **Total changes** | N |

---

### Added Tokens

- `color.feedback.info` (#1D7FBF) — new semantic token for informational states
- `spacing.component.gap-lg` (2rem) — new gap token for large layout variants

---

### Removed Tokens (Breaking — review before accepting)

| Token | Current value | Used in | Action |
|---|---|---|---|
| `color.interactive.secondary-alt` | #8B5CF6 | Button.module.css, Card.tsx | **Do not remove yet — update usages first** |

---

### Changed Values

| Token | Old value | New value | Contrast impact |
|---|---|---|---|
| `color.feedback.warning` | #FFAA00 | #FFCC00 | REGRESSION — 4.6:1 → 3.1:1 on white (see above) |
| `spacing.4` | 1rem | 1.25rem | No contrast impact |

---

### Contrast Regressions — MUST RESOLVE

1. `color.feedback.warning` — new value #FFCC00 on white (#ffffff) = 3.1:1. Fails 4.5:1 AA gate.
   Recommendation: restore #FFAA00 or use a darker warning variant for text.

---

### Files written

- tokens/tokens.json (updated)  [skipped in --dry-run]
- tokens/tokens.css (regenerated)  [if --formats css]

---

### Next steps

1. Review breaking removals with the design team before accepting the sync.
2. Resolve the 1 contrast regression before merging.
3. Run /component-a11y-gate on any component referencing changed tokens.
4. Commit tokens/tokens.json and regenerated outputs together in a single PR.
Technical details
Plugin
design-to-code-builder
Author
Dakota Smith
Skill name
design-system-sync
Maturity
experimental
Security review
No security review
Owners
  • engineering
  • design
Argument hint
<figma-url> [--tokens <path>] [--out <path>] [--modes light,dark] [--dry-run]
Allowed tools
  • Read
  • Write
  • Edit
  • Glob
  • Grep
  • mcp__figma-dev-mode-mcp-server__get_variable_defs
  • mcp__figma-dev-mode-mcp-server__get_metadata
  • Bash(git diff *)
  • Bash(git log *)
  • Bash(node *)
Source
plugins/design-to-code-builder/skills/design-system-sync/SKILL.md

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.