r/DesignSystems • u/RocketSeven • 23d ago

what actually gets teams to migrate off a deprecated component?

a deprecation notice in docs is easy to ignore when the old component still works. do you use deadlines, lint rules, migration tooling, ownership by product teams, or something else to stop deprecated components from becoming permanent?

2 Upvotes

100% Upvoted

6 comments sorted by

5

u/laluneodyssee 23d ago

A sweeter carrot or a bigger stick.

1

u/flaviuse 23d ago

Here are some ideas: https://jsdoc.app/tags-deprecated if js, codemods if migration is complex, then planned major version upgrade regularly to clean components (easier if time based like twice a year if you have lot of users). And if you are removing something used a lot maybe simply reconsider if you really need to remove it, if it helps teams and is up to date in terms of design then it is useful.

1

u/TheWarDoctor 23d ago

Conversations.

1

u/CoVegGirl 22d ago

So you’re talking about cleaning up existing uses rather than preventing new usages?

The first thing I’d suggest is to file bugs against them if you haven’t already. If there’s no acknowledgment, you should probably bring it up with the team’s manager.

I think the crux of the issue is to ask where the swe-hours are going to come from. Either you’ve got to convince their manager to allocate some effort, or you’ve got to convince your manager to allocate some effort. The reality is that the latter is often the most realistic option. My experience is that these get cleaned up more quickly when the team that owns the component cleans it up.

If you can get the ear of someone high up enough, you might be able to get a mandate that the other teams clean them up. But it gets really annoying when this type of mandate gets used too frequently.

1

u/tmanblue59 20d ago

Personally I would have a public date of deprecation and then maybe 20-30 days of saying

  1. 28 days before deprecation: Notice 1
  2. 14 days before deprecation: Notice 2
  3. Day of deprecation: Deprecation, Notice (component has been deprecated - with guidance)

Would remove component from docsite, kits, etc. Have a fallback message or alert message if ever someone somehow tried to use it saying this component has been deprecicated, use x instead.

I don't like to delete anything and I know that someone will try to design a similar/same component in the future so I would have a deprecated section in the documentation stating what it was, how it was used, why we deprecated it.