Marcus Andrey Study
Ler em português Library

Framework · Design systems · 3 min read

Deprecation lifecycle

Five stages for taking a component, token or property out of a design system (decide, deprecate in a minor, help people move, remove in a major, support the old major for a while), so nothing disappears by surprise.

  1. 1Decide

    Check what breaks, name the replacement, write the notice.

    "Use Notice. Banner goes in 4.0."
  2. 2Deprecate

    A minor release marks it in code, tokens, Figma and docs.

    Still there, still working
  3. 3Migrate

    Guide, codemod and pairing, for as long as the slowest team needs.

    Watch uses remaining go down
  4. 4Remove

    Only in a major, with a changelog entry people can act on.

    What, instead, how, since when
  5. 5Support

    Fixes for the old major for a stated period.

    Nobody upgrades the first week
Deprecate in a minor, remove in a major, and fit the window between them to the slowest team's release cycle.

Use it when

  • A component should never have shipped (a banner nobody can make accessible) and you want it gone.
  • A token or prop needs a new name, and the old one is used across many products.
  • Someone proposes deleting something in a minor release because "nobody uses it".

How to use it

  1. Decide and name the replacement. Check the change with one question: will someone's screen change, or their build fail, when they update? Then write what replaces the old thing, or why nothing does. Output: a two-sentence deprecation notice: what replaces it, and when it goes.
  2. Deprecate in a minor, everywhere people look. A console warning in code that names the replacement and links the guide; $deprecated on tokens; in Figma a "Deprecated" page, a name prefix and an updated description; a status label and removal date on the doc page. Output: a minor release with the deprecation marked in code, Figma and docs.
  3. Make the move cheap. A migration guide with before and after, in code and in Figma. A codemod when the change is mechanical, like a rename. Pairing with the teams that use the old thing most; the adoption numbers tell you who they are. Output: a guide, a codemod if possible, and a list of teams to help.
  4. Set the window by the slowest team. The removal date has to fit the longest release cycle among the products that use it. Track "deprecated uses remaining" per product so you can see it go down. Output: a removal date and a count to watch.
  5. Remove only in a major. Batch breaking changes on a known rhythm. The changelog entry answers what went, what to use instead, how to move, since when it was announced, and who is affected. Output: a major release with a "Removed" section people can act on.
  6. Support the old major for a while. Security and accessibility fixes for the previous major after the new one ships, for a stated period. Output: a support end date in the docs.

Worked example

Harbour's Banner can't be made accessible without breaking how teams use it, so it's replaced by Notice. Tidewater's staff console ships every six weeks, the slowest of the products.

Stage Release What happens
Decide Notice: "Use Notice. Banner is removed in Harbour 4.0.0."
Deprecate 3.5.0 (minor) Console warning, Figma "Deprecated" page, status label on the doc page
Migrate 3.5 to 3.8 Migration guide, a codemod for type to tone, pairing with the console team
Remove 4.0.0 (major) Changelog: removed, use Notice, link to guide, announced in 3.5.0, affects all products using Banner
Support 3.x Security fixes for 3.x for a stated period after 4.0.0

The window covers at least two staff console releases, so the console team can move without an emergency.

Watch out for

  • Removing in a minor. "Nobody uses it" is almost always wrong. Somebody does.
  • Deprecating in code only. Designers keep handing off the old component if Figma doesn't say it's going.
  • "Deprecated" with no replacement. A notice that doesn't name what to use instead is a chore assigned to every team.
  • One huge major. Too many breaking changes in one release, and nobody can afford to adopt it.

Template

Copy this into the deprecation issue, then reuse the notice and the changelog lines.

What is deprecated: ...           (component / token / prop / value)
Why: ...
Replacement: ...                  (or: none, because ...)
Will someone's screen change or build fail on update? yes / no

Deprecated in: x.y.0 (minor)      Removal planned in: x+1.0.0 (major), date ...
Slowest affected release cycle: ... -> window of at least ...

Marked in:
[ ] Code: console warning naming the replacement and the guide
[ ] Tokens: "$deprecated": "Use ... Removed in ..."
[ ] Figma: "Deprecated" page, name prefix, description updated
[ ] Docs: status label and removal date

Help: migration guide ... / codemod ... / teams to pair with ...
Deprecated uses remaining: product A ..., product B ...

Changelog (removal):
### Removed
- ...: use ... instead. Guide: ... Announced in x.y.0. Affects: ...
Source
Semantic Versioning 2.0.0, FAQ on deprecation (Tom Preston-Werner). Component lifecycle: U.S. Web Design System. $deprecated property: Design Tokens Community Group, Format Module 2025.10
Where to find it
Design Systems in Practice: Deprecation and breaking changes › Deprecate first, remove later

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close