How to kill a component (the right way)

Building a component is celebrated. Deprecating one is avoided. That asymmetry is how design systems end up with three button variants, two navigation patterns, and a legacy card that's been "going away" for nineteen months.

Deprecation is harder than creation. You need to know what you're replacing and why, who's using it, and how to get consumers to move without making their lives worse. You also have to accept that you shipped something that didn't hold up. Not a comfortable thing to formalize in a system that's supposed to be authoritative.

The cost of not doing it compounds though. Every deprecated component staying in the system is something new designers learn. Every old pattern that stays undocumented is something engineers reach for. Eventually you get a contribution that rebuilds the thing you quietly stopped using, because nobody said publicly that it was done.

Know what you're actually deprecating

The first question isn't how. It's whether. Before marking anything deprecated, understand what problem the original component was solving and whether that problem still exists.

Sometimes a component gets deprecated because the context it was built for no longer exists. The old card wasn't wrong; the product surface it was built for got redesigned. Deprecation in that case is clean. Clear successor, clear reason.

Sometimes a component gets deprecated because a better one was built. The challenge is making sure "better" is true across the full range of use cases, not just the common one. Legacy components hang around because of edge cases the new one doesn't handle. Deprecate without addressing those and you'll get custom implementations recreating the old behavior entirely outside the system.

Understand the real usage before you start. Most design systems don't have great tooling for this, which means actually going and asking. A Slack message to engineering asking "who's still using this?" works better than you'd expect.

Set the timeline based on who's doing the migration

The deprecation announcements I've seen go wrong follow the same pattern: a component gets marked deprecated, the timeline gets set based on system team capacity rather than the teams actually doing the migration, and when the deadline arrives and most teams haven't moved, it extends indefinitely. The "deprecated" badge becomes furniture.

Talk to those teams before setting the timeline. Find out what it actually takes to swap out the component in their codebase. If three teams each estimate a week of engineering work, a two-week window isn't realistic. Set a real timeline early, and people can plan for it.

Make the migration easy, or it won't happen

The main reason migrations stall: staying on the old thing is easier than moving. If your replacement has a different API, requires prop changes, and needs designers to update Figma files, that's a real project for a team with other work.

Write the migration for the common case. A codemod for the mechanical substitution takes a day and removes the biggest barrier for most teams. A Figma swap action handles the design files. A written guide covering the 90% case takes an afternoon. Be honest about the 10% where there's no clean equivalent.

Most system teams underinvest here because the migration feels like someone else's work. It isn't.

Document why it died

Once a component is deprecated, write down why. Not a changelog entry. Actual prose explaining what the component was, why it was replaced, what replaced it, and when it goes away.

Someone will find the old component in search results or a Stack Overflow post and consider using it. "Deprecated" by itself means nothing. They'll ask a colleague or just use it. "Deprecated, replaced by Card v2 in March 2026, removed in Q3 2026. Here's the migration guide." That gives them what they need in thirty seconds.

Ten minutes of writing prevents a lot of mistakes.

When to actually remove it

At some point, deprecated has to mean removed. A component you've committed to deprecating but can't bring yourself to delete is just a legacy component with different documentation.

Remove it when you've confirmed zero usage, not when a deadline passes on a calendar. Set a monitoring alert if your tooling supports it, or do a sweep before removal. When you hit zero, delete. Not archive.

A system where deprecated components never disappear teaches everyone that deprecation isn't real. That's hard to undo, and it makes every future deprecation harder to take seriously.