Your design system is used by 20 apps. How do you ship a breaking change to the Button API without blocking teams or forking the ecosystem?

First try to avoid the break. If you must break, ship a major version with a codemod, and support the old version for a while.

Avoid the break first:

• Add the new prop next to the old one.
• Map the old prop to the new behaviour internally.
• Log a deprecation warning in development only, with a link to the migration guide.

When the old API must go: remove it in a major version, with a clear changelog. Ship a codemod, which is a script that rewrites most call sites automatically. I run the codemod on a few real apps first. This shows how much is left for manual fixes.

Avoid apps stuck on old majors:

• Keep the previous major on security and critical fixes for a set window of time.
• Publish an adoption dashboard that shows which app is on which version.
• Before deciding, use usage analytics from scanning repos for imports. They show which props are actually used.

Mixed versions: two versions of the same component in one bundle are a risk in micro-frontend setups. So I keep tokens and CSS variables stable across majors. Then mixed versions still look consistent during the migration.