token-crosswalk-builder

Build a three-way token crosswalk mapping new DTCG tokens to old Figma variables and code identifiers.

77|11|Updated Jun 2, 2026
One-click install
npx skills add https://github.com/jrpease/throughline --skill token-crosswalk-builder-jrpease
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: token-crosswalk-builder
Source: https://github.com/jrpease/throughline/tree/main/skills/token-crosswalk-builder
Command: npx skills add https://github.com/jrpease/throughline --skill token-crosswalk-builder-jrpease

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Retrofitting a design system onto a mature codebase requires knowing exactly how every new design token relates to the old Figma variables and legacy code identifiers it replaces. Doing this mapping by hand is error-prone and leaves no verifiable record, so drift between Figma and code goes undetected. ## Core Features & Use Cases - Crosswalk generation: Writes crosswalk.json, a persistent three-way map of new token, old Figma variable, and old code identifiers, with per-row status classification (aligned, renamed, drift-fix, added, mapped-nearest). - CI validation gate: Installs zero-dependency validation scripts and wires a tokens:validate npm script that must pass N/N before proceeding. - Reverse index: Generates crosswalk.reverse.json (codeToken to newToken) to semi-automate SCSS and Tailwind swaps during the code retrofit. - Use Case: A team migrating a legacy product to a new token system uses this Skill to map $primary-red and Colors.primaryRed to the new color.text.primary token, then gates every pull request on the validator so the mapping never drifts. ## Quick Start Ask the agent to build the token crosswalk for the brownfield retrofit and wire the tokens:validate CI gate.

Frequently Asked Questions about token-crosswalk-builder

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I map old design tokens to new ones during a design system migration?

Build a crosswalk.json file with one row per new token recording its resolved value, tier, old Figma variable, and old code identifiers. Each row gets a status such as aligned, renamed, drift-fix, added, or mapped-nearest based on how the old and new values relate.

How do I validate design tokens in CI?

Install the validate-crosswalk.mjs script and add a tokens:validate npm script that checks every crosswalk row's resolved value against the DTCG tokens.json source. The gate must report N/N matches before the retrofit proceeds, and failures are fixed at the token source, never by editing generated files.

What is a token crosswalk in a design system retrofit?

A token crosswalk is a persistent three-way map between each new design token, the old Figma variable it replaces, and the old code identifiers like SCSS variables or Tailwind classes. It drives the code retrofit and serves as the contract a CI validator enforces.

Can I build the crosswalk without running a design system audit first?

Yes. If the audit manifest section is null, the Skill asks you directly for the old-to-new mapping inputs and proceeds. Running design-system-audit first is recommended because it pre-fills the code surface and Figma inventory used to seed the rows.

When should I not use the token crosswalk approach?

Skip it for greenfield builds with no legacy tokens to map, since there are no old Figma variables or code identifiers to reconcile. It is also not the cleanup phase: old tokens are only removed later, after the token-removal guard confirms zero remaining references.