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.
- 1Decide
Check what breaks, name the replacement, write the notice.
"Use Notice. Banner goes in 4.0." - 2Deprecate
A minor release marks it in code, tokens, Figma and docs.
Still there, still working - 3Migrate
Guide, codemod and pairing, for as long as the slowest team needs.
Watch uses remaining go down - 4Remove
Only in a major, with a changelog entry people can act on.
What, instead, how, since when - 5Support
Fixes for the old major for a stated period.
Nobody upgrades the first week
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
- 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.
- Deprecate in a minor, everywhere people look. A console warning in code that names the replacement and links the guide;
$deprecatedon 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. - 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.
- 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.
- 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.
- 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: ...
- Atomic DesignBrad FrostBook · 2016 (Amazon)
- Design That ScalesDan MallBook · 2023 (Amazon)
- How should I handle deprecating functionality?SemVer FAQ (external site)
- Component lifecycleUSWDS (external site)
- Design Tokens Format Module 2025.10DTCG (external site)
- Keep a Changelog 1.1.0 (external site)
"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.