Component Deprecation & Migration Workflows

Design systems must evolve as products grow. Old components eventually become obsolete, inefficient, or inaccessible. However, suddenly deleting a component from the library will break dozens of production feature branches.

A healthy deprecation lifecycle follows a predictable sunset timeline:

1. Notice & Warning: Mark the component as @deprecated in code with console warnings pointing to the replacement. Add visual flags in Figma.
2. Automated Codemods: Provide automated migration scripts (AST codemods) that transform old component imports and prop signatures to the new component automatically.
3. Grace Period: Maintain the deprecated component for at least one major release cycle (e.g., 6 months).
4. Removal: Safely remove the component in the next major SemVer release (v3.0.0) once adoption of the replacement reaches 100%.