Automating a breaking design token rename

WHAT THIS TESTS Whether you can use codemods and deprecation aliases to turn a painful breaking rename into a low-effort, staged migration.

A GOOD ANSWER COVERS Two complementary tactics. First, an alias for backward compatibility: for a transition release, keep the old token name as an alias that points to the new value and emits a deprecation warning, so existing consumers keep working without immediate edits. Second, a codemod that does the actual migration: a script using jscodeshift for JS and prop usages and a CSS-aware transform or PostCSS for stylesheet references, rewriting every occurrence of the old token to the new name across a repo. Publish the codemod and a clear command consuming teams run. Document the change in the changelog and migration guide with before and after examples. Remove the alias only in a later major, after telemetry shows usage has dropped. Optionally offer to open migration PRs for the largest consumers.

COMMON WRONG ANSWERS Renaming hard in one release with no alias and no codemod, breaking everyone at once. Expecting teams to find-and-replace by hand, which misses dynamic references and template strings. No deprecation window. Removing the alias too soon. Forgetting that tokens appear in CSS, JS, and component props, not just one place.

LIKELY FOLLOW-UPS How do you write a codemod that catches CSS and JS usages? How long should the alias live? How do you measure remaining old-token usage before removing the alias? How do you handle dynamically constructed token names?

ONE CONCRETE EXAMPLE You ship the new color-brand-default and keep color-primary as an alias to it for v5, with a dev warning. You publish a codemod consumers run that rewrites color-primary to color-brand-default in their CSS and JSX. After usage telemetry shows the old name is nearly gone, you remove the alias in v6.