We thought we were replacing a component.
We had the technical case. The new component was more accessible, more performant, better aligned to the token architecture. Every objective measure said the old one should go. We scheduled the deprecation notice. We wrote the migration guide. We were ready.
Nobody argued accessibility. Nobody argued performance. Nobody argued consistency. They argued familiarity. The old component was the decision they had defended in a room we were not invited into, years before we arrived. It was theirs. Removing it was not a technical upgrade. It was a verdict on a decision they had owned.
That was the moment the obstacle became visible. We were not deprecating a component. We were asking a team to let go of something they had defended for years. Those are not the same conversation. We had prepared for one of them.
Deprecation is the most politically underestimated process in design system operations. It is treated as a technical lifecycle event. It functions, in most organizations, as a referendum on past decisions made by people who are still in the room. The technical merits of the replacement are rarely the deciding factor. The deciding factor is whether the team removing the component has enough trust and enough lead time to make the transition feel like a handoff rather than a seizure.
A deprecation that surprises people is not a deprecation. It is an ambush with a migration guide attached.
Why Deprecation Fails
Most design system deprecations fail for one of three reasons. None of them are technical.
Reason 1 — No Warning
The deprecation notice arrives at the same time as the deprecation. The team using the component finds out it is being removed at the moment it is already marked deprecated. They have no time to plan a migration, no time to raise concerns, and no reason to trust the next decision the design system team makes.
Speed is not a virtue in deprecation. Lead time is.
Reason 2 — No Migration Path
The component is deprecated. The replacement exists. The path from one to the other is not documented, not scoped, and not estimated. The consuming team is told what to stop using but not what doing so will actually cost them in sprint time, in engineering hours, in QA cycles. A deprecation without a migration guide is a problem statement without a solution.
Reason 3 — No Acknowledgment of What Is Being Asked
The design system team communicates the technical rationale. The accessibility improvements. The performance gains. The alignment to the new token architecture. All of which is true and none of which addresses the actual resistance. The team being asked to migrate is not resisting the new component. They are resisting the implication that the old one was wrong — and by extension, that the decision to use it was wrong. That is a different conversation. It requires acknowledgment, not documentation.
The Lifecycle Framework
Deprecation does not begin when you decide to remove something. It begins when you decide to introduce something. Every component that enters the system should enter with a defined lifecycle status — because the question of how it leaves the system should be considered before it arrives.
Four stages. Each with a defined meaning and a defined set of behaviors.
Stage 1 — Active
Recommended for all new usage. The component is maintained, documented, and supported. Teams can use it with confidence that it will not be removed without the full lifecycle process. Active status is the design system's endorsement. It should be earned before it is given. Document active components in Notion or Confluence — free tiers cover everything a component status registry requires.
Stage 2 — Caution
Use only with review. The component has known limitations — an accessibility gap, a token misalignment, a pattern conflict with something newer in the system. It is not removed. It is flagged. Teams can still use it, but they must acknowledge the flag and confirm the usage has been reviewed. In Figma, this is a component annotation in the library — a visible label on the component itself that signals caution before the designer reaches for it. The flag is not a verdict. It is a warning.
Stage 3 — Deprecated
No new usage. Existing usage is supported through the migration window. The replacement is available, documented, and the migration path is scoped. The deprecated status triggers the communication process — the notice to consuming teams, the migration guide, the timeline, the support commitment. Track deprecated components in GitHub alongside the codebase — a component status file in the repository gives engineering teams visibility in the environment they already work in, free for public repositories and standard for most organizations. This is the stage where lead time matters most. The longer the lead time, the lower the resistance.
Stage 4 — Retired
Removed. No longer in the system. No longer supported. The retirement date is announced at the start of the deprecated stage, not at the end of it. Teams know from the moment of deprecation exactly when the component disappears. The retirement is not a surprise. It is the conclusion of a communicated process that began months before it ends.
The lifecycle is not a bureaucratic framework. It is a trust architecture. Every stage is a signal to consuming teams that the design system team has thought about the consequences of its decisions before asking others to absorb them.
Three Rules for a Deprecation That Lands
Rule 1 — Announce Before You Deprecate
The deprecation notice is not the first communication. It is the third. The first is an informal heads-up to the teams most affected — a Slack message, a brief conversation, a signal that something is coming before it officially arrives. The second is the pre-deprecation review — an opportunity for consuming teams to raise concerns, flag dependencies, and confirm the migration timeline is realistic. The third is the formal deprecation notice with the full migration guide attached.
Three communications. One deprecation. The teams who feel consulted do not fight the process. They participate in it.
Rule 2 — Communicate Before You Deprecate
The migration guide is not a document. It is a walkthrough. Record the component, the migration steps, and the time estimate for a standard use case in a Loom video. An engineering lead who watches it before sprint planning arrives having already assessed the effort — and having already decided whether to raise it in the next cycle or the one after. A PDF in a Slack message is not a migration guide. It is documentation that will be opened the week the retirement date arrives and not before.
Rule 3 — Acknowledge What You Are Asking
Before the deprecation notice, one sentence: we know this component has been part of your workflow for a long time, and we want to make this transition as low-friction as possible. That sentence is not an apology. It is an acknowledgment that the design system team understands the difference between a technical lifecycle event and what it actually feels like to the team absorbing it.
The teams that argued familiarity were not being irrational. They were telling us something about how the deprecation had been framed. We had prepared the technical case. We had not prepared the human one.
The Quick Win: Audit Your Current Component Status
This week: open your component library and identify three components that should be in Caution status but are currently labeled Active. Not removed. Not deprecated. Just flagged.
For each one, add the Caution annotation in Figma and write one sentence explaining the known limitation. Share it with your engineering lead. Ask them: if we deprecated this in ninety days, what would that cost your team?
Their answer is your migration brief. The conversation is your deprecation process starting before anyone feels ambushed.
Deprecation that begins with a question is deprecation that ends with cooperation. Deprecation that begins with a notice ends with a war that delays the retirement by six months and costs everyone the trust it took two years to build.
The Argument
Deprecation is not a technical lifecycle event that happens to have political consequences. It is a political event that requires a technical process to execute cleanly. The teams that resist are not resisting the new component. They are resisting the way they found out about it. Build the lifecycle framework before you need it. Communicate before you deprecate. Acknowledge what you are asking before you ask it. The component will be retired. The relationship with the team does not have to be.
Disagree loudly. Inspire boldly.
And remind me — falsely if needed — that somewhere a deprecation notice was received with enthusiasm and a migration completed ahead of schedule.
What is the one component in your system that everyone knows should be deprecated — and nobody has started that conversation yet? 🤔
