Rolling out a breaking change to a shared Button

WHAT THIS TESTS This evaluates how you handle a change with a large blast radius. The Button is everywhere, so process and communication matter as much as the code.

A GOOD ANSWER COVERS Treat it as a major version under semver. Where feasible, make the change additive first: introduce the new API alongside the old one, mark the old props or variants as deprecated with console warnings or type-level hints, and define a clear sunset window. Provide a codemod so most consumers can auto-migrate, plus a written migration guide with before-and-after examples. Communicate early and through multiple channels: a changelog entry, a heads-up before release, office hours or a support channel, and a tracking dashboard showing who is still on the old version. Only remove the deprecated API in the next major once adoption is high.

COMMON WRONG ANSWERS Shipping the change as a minor or patch. Deleting the old prop in the same release as the new one with no overlap. Assuming a single announcement equals communication. Ignoring downstream CI breakage and version pinning.

LIKELY FOLLOW-UPS How do you handle a team that cannot upgrade in time? How do you measure adoption? Would you ever ship a parallel component name instead of a breaking change?

ONE CONCRETE EXAMPLE The Button changes from a boolean primary prop to a variant string. In version 4.0.0 you support both, with primary triggering a deprecation warning that maps to variant equals primary. You publish a codemod and migration guide and announce two weeks ahead. A dashboard tracks remaining usage of the old prop. After consumers migrate, version 5.0.0 removes the boolean prop cleanly.