Gradual design system adoption in legacy code

WHAT THIS TESTS This evaluates whether you can move a large legacy codebase onto a design system safely and incrementally, using automation to reduce manual toil.

A GOOD ANSWER COVERS Reject a big-bang rewrite. Enable coexistence so legacy and design-system components run side by side, then migrate in slices. Build codemods using AST tools like jscodeshift or Hypermod to mechanically convert common cases, for example swapping a legacy button for the system Button and mapping old props to new ones. Where styling is bespoke, provide token mappings so colors and spacing align. Add lint rules to create guardrails: flag usage of legacy components, forbid new bespoke implementations of things the system already provides, and warn on raw hex values instead of tokens. Prioritize by impact: migrate high-traffic screens and shared layouts first, where consistency and bug reduction pay off most. Track coverage over time so progress is visible and momentum is maintained, and pair tooling with short docs and support.

COMMON WRONG ANSWERS Proposing a full rewrite. Expecting teams to migrate manually with no tooling. No guardrails, so new code keeps adding legacy patterns. Migrating low-value areas first.

LIKELY FOLLOW-UPS What cases can a codemod not handle? How do you stop new code from regressing? How do you sequence which surfaces to migrate first?

ONE CONCRETE EXAMPLE A jscodeshift codemod rewrites every legacy OldButton into the system Button, mapping type equals submit to variant equals primary. A lint rule then errors on any new import of OldButton, preventing backsliding. The team migrates the checkout flow first because it is the highest-traffic surface, and a coverage dashboard climbs from 20 to 60 percent over a quarter.