Design Tokens Sync

Keep one source of truth actually true. Every design system decays the same way: a hex gets hardcoded in a hurry, a token gets renamed in Figma but not in Tailwind, a second half-copy of the palette appears in a one-off CSS file. This skill finds the drift, decides direction with the user, and reconciles.

Workflow

1. Locate the truths. Find every place tokens are defined: tokens.json/*.tokens.json (W3C format), Figma variables export, tailwind.config.* theme, CSS custom properties, TS theme objects, SCSS variable files. If more than one claims to be canonical, ask which wins before touching anything -- direction of sync is a human decision.
2. Build the graph. For each token: canonical value, every downstream definition, and every consumption site. For each raw value in code (hex, px, rem, ms, cubic-bezier): whether a token exists for it.
3. Drift report. Output token-drift-report.md in four buckets:
   • STALE COPIES -- downstream definitions that no longer match canonical (with both values)
   • HARDCODED -- raw values in components where a matching token exists (exact match, then near-match within perceptual distance for colors)
   • ORPHANS -- tokens defined but consumed nowhere
   • UNTOKENIZED -- raw values appearing 3+ times with no token; these are tokens waiting to be named
4. Reconcile on approval. Stale copies: regenerate downstream from canonical. Hardcoded: replace with token references -- exact matches automatically, near-matches only with per-case confirmation (that slightly-off blue might be intentional). Untokenized: propose names following the existing convention and add to canonical. Orphans: list for deletion; never auto-delete.
5. Guard. Offer to add the cheap tripwire: a script (npm run tokens:check) that re-runs the drift detection and fails CI on new stale copies or hardcoded near-matches, so the system stays synced after you leave.

Rules