Figma Design Token Rewrite

The problem

The existing legacy token libraries were the product of years of uncoordinated growth. Tokens used Title Case naming with emoji prefixes, had no codeSyntax.WEB values (meaning Figma's developer tools returned nothing useful), and were structured as flat primitive dumps with no semantic layer. Components were bound directly to color primitives, bypassing any semantic aliasing — so a brand color change required hundreds of manual rebinds across thousands of nodes.

By the time the audit ran, the two libraries had accumulated 262 and 268 tokens respectively — nearly 3x the industry standard for an enterprise system of this scale. 6,209 variable bindings in one library were outright broken, pointing to deleted primitives with no path to resolution. The system had 12 external library dependencies in one file and 6 in the other, creating circular reference risks. Production CSS had two broken custom properties shipping to users — broken since a previous refactor that was never completed.

What was done

The migration was executed in phases using a combination of custom MCP-driven Figma scripts and structured analysis.

1. Phase 1

   Audit and mapping

   Queried both libraries end-to-end via Figma MCP to produce a complete inventory of every variable, its collection, naming format, alias chain, codeSyntax.WEB status, and binding count. Cross-referenced against production CSS to identify what was actually in use versus what was dead weight.

2. Phase 2

   Naming and codeSyntax

   Renamed 168 variables from Title Case to lowercase kebab-case using slash-separated hierarchy (color/action/button-default, spacing/md, radius/pill). Set codeSyntax.WEB on all 179 variables, bringing coverage from 0% to 100%. All variables now return usable CSS custom property names from Figma's developer tools and MCP.

3. Phase 3

   Semantic layer

   Established a clean two-tier architecture — semantic Tokens collection aliasing into typed Primitives. Designers work only with semantic tokens (what a color is for, not what it is). Primitives are an implementation detail. Created 11 missing variables (5 colors, 6 radius tokens) to close gaps between the Figma system and production CSS needs.

4. Phase 4

   Token consolidation

   Reduced both libraries from ~265 tokens to 116 — the number that maps precisely to production CSS usage. Eliminated 3x spacing token bloat (30 → 10 t-shirt sizes), 6x typography token bloat (77 → 15 semantic typography tokens), and consolidated redundant color scales. Removed all 18 external library dependencies.

5. Phase 5

   Binding repair

   Resolved 6,209 broken variable bindings by building an automated rebinding script that mapped deleted primitive IDs to their correct Tokens collection replacements. What would have taken 40–80 hours of manual Figma work took under 4 hours to script and 30 minutes to run.

6. Phase 6

   CSS export pipeline

   Built a Node.js script (generate-tokens-css.mjs) that pulls the Tokens collection via the Figma Variables API, resolves all alias chains to raw values, and writes three output formats: CSS custom properties (:root { ... }), a JSON token map for tooling, and a W3C DTCG-compliant JSON file for cross-platform use. Achieved 96.3% parity between the Figma export and the live production CSS theme.

Numbers

Project artifacts

Token outputs generated from the same source include CSS custom properties and a W3C token JSON map. The previews below show representative values from that artifact set.

Business value