Design Systems · Step 7 · 6 min read
Deprecation and breaking changes
How to change or remove something in a design system without breaking the products that use it. What counts as a breaking change, how Semantic Versioning orders deprecation and removal, and the warnings, migration help and changelog lines that get teams across.
Removing a component is a promise you broke, unless you said so early, said why, and helped people move. Every system has parts it should never have shipped: a banner nobody can make accessible, a token with a name that means nothing. Taking them out is healthy. Taking them out by surprise is how a system loses the trust it took years to earn.
What you'll be able to do after reading:
- Tell a breaking change from a safe one
- Use Semantic Versioning to plan a deprecation
- Write a deprecation notice and a migration path
- Write a changelog entry for the person who has to upgrade
1. What breaks
A breaking change is any change that makes someone's working product fail, or look or behave differently, without them choosing it. In code that's easy to see: a removed component, a renamed property, a prop that now needs a different value. In design it's quieter, and it counts too:
- A token removed or renamed:
color.primarybecomescolor.action.primary. - A component removed:
Banneris replaced byNotice. - A property renamed or its values changed:
type="error"becomestone="danger". - A default changed:
Buttonwasmd, nowsm. - A visual change people built around: padding that grew 4 px and now pushes a console table onto two lines.
Ask one question: will someone's screen change, or their build fail, when they update? If yes, treat it as breaking.
2. Versions that tell the truth
Semantic Versioning gives every release three numbers, MAJOR.MINOR.PATCH. You increase the major for incompatible API changes, the minor when you add functionality in a backward compatible way, and the patch for backward compatible bug fixes (semver.org).
Its FAQ also gives the order for removing something: update the documentation, then "issue a new minor release with the deprecation in place", and only remove it in a major release, with at least one minor release containing the deprecation in between (Semantic Versioning 2.0.0, FAQ).
For a design system the API includes the Figma library. Version the library and the code together, or at least announce them together, so "Harbour 4.0" means the same thing to a designer and to an engineer (see Versioning and releases).
3. Deprecate first, remove later
- 3.2.0FebruaryThe replacement shipsNew
Noticecomponent, with atoneproperty.Bannerstill works as before. - 3.4.0AprilDeprecated, not removed
Bannermarked deprecated in code, Figma and the docs. A console warning in development names the replacement and links the migration guide. - 3.4 → 3.9April to SeptemberMigration windowA codemod rewrites most uses. The system team pairs with the two teams that use it most. Adoption dashboard counts what's left.
- 4.0.0OctoberRemoved, in a major release
Bannerdeleted, listed under "Breaking changes" in the changelog with the one-line fix. 3.x gets security fixes for six more months.
Deprecated means: still there, still working, no longer recommended, and going away. The US Web Design System puts it precisely: a deprecated component is removed from active support, stays in the code base, gets no updates, and the team recommends removing it from your project; it is retired when it's deleted (USWDS, Component lifecycle).
Mark a deprecation everywhere people meet the thing:
- Code. A warning in the development console that names the replacement and links the guide. For tokens, the DTCG format has a
$deprecatedproperty that can betrueor a string with the reason (DTCG Format Module 2025.10):
"primary": {
"$type": "color",
"$value": "{color.blue.600}",
"$deprecated": "Use color.action.primary. Removed in Harbour 4.0.0."
}
- Figma. Move the component to a "Deprecated" page, prefix its name, and update its description with the replacement.
- Docs. A status label on the page, and the date it will go.
Brad Frost mentions Salesforce's Sass Deprecate tool, which flags patterns that are on their way out before they disappear (Atomic Design, chapter 5). The idea matters more than the tool: warn where people already look.
4. Help people move
A deprecation notice without help is a chore you've assigned to every product team. Make the move cheap:
- A migration guide: before and after, in code and in Figma, for each case.
- A codemod where the change is mechanical, like a property rename. It's a script that rewrites the code for people.
- Pairing with the teams that use the old thing most. The adoption numbers from Measuring adoption tell you who they are.
- A window long enough for the slowest team's release cycle. For the staff console, which ships every six weeks, that's at least two releases.
- Support for the old major for a while: security fixes for 3.x after 4.0 ships.
When IBM moved Carbon from v10 to v11, they renamed colour tokens to describe their use, gathered the packages under @carbon/react, and kept separate v10 and v11 Figma libraries so designers could switch when ready (Carbon, Migration guide). The pattern is the one to copy: the reason first, then the changes, then a path for each audience.
5. The changelog line
Harbour 4.0.013 October · major release
Breaking changes
Bannerremoved. UseNotice:<Banner type="error">becomes<Notice tone="danger">. Runnpx @harbour/codemods banner-to-notice. Deprecated since 3.4.0.- Token
color.primaryremoved. Usecolor.(same value). Deprecated since 3.4.0.action. primary
Changed
Buttonfocus ring is now 2 px with a 2 px offset in every mode, so it stays visible on dark surfaces.
Who is affected
- Booking app: 0 uses left. Staff console: 3 uses left in the check-in screens, migration paired for week 42.
Keep a Changelog starts from one principle: changelogs are for humans, not machines. It groups changes as Added, Changed, Deprecated, Removed, Fixed and Security (Keep a Changelog 1.1.0). For a design system, add a line on who is affected: the person reading wants to know if this is their problem.
A breaking change entry answers four questions: what went, what to use instead, how to move, and since when it was announced.
6. Common mistakes
- Removing something in a minor release because "nobody uses it" (somebody does).
- Deprecating in code but not in Figma, so designers keep handing off the old component.
- A notice that says "deprecated" without naming the replacement.
- Bundling many breaking changes into one huge major release nobody can afford to adopt.
- Changing a token's value quietly and calling it a patch.
7. Vocabulary
| Term | Meaning |
|---|---|
| Breaking change | A change that makes a working product fail or change without its team choosing it |
| Deprecated | Still there and working, no longer recommended, and scheduled to go |
| Retired, removed | Deleted from the system |
| Migration guide | Before-and-after instructions for moving from the old thing to the new |
| Codemod | A script that rewrites code automatically, for mechanical changes |
| Major, minor, patch | The three numbers of a version: breaking, new and compatible, fix |
8. Try it (no tools needed)
- Pick one component or token in your system you'd love to remove.
- Write its deprecation notice in two sentences: what replaces it, and when it goes.
- List the three teams that would be most affected, and what each would need from you.
Reflection questions: How would a product team find out today that something they use is going away? What's the longest release cycle among the products your system serves?
9. If you already practise
- Add a lint rule or build warning for deprecated tokens and components, so the count goes down on its own.
- Report "deprecated uses remaining" per product next to your adoption numbers.
- Batch breaking changes on a known rhythm, such as one major a year, so teams can plan for it.
Checklist
Learn more
- Semantic Versioning 2.0.0
- USWDS, Component lifecycle
- Design Tokens Community Group, Format Module 2025.10: the
$deprecatedproperty - IBM Carbon, Migration guide v10 to v11
- Keep a Changelog 1.1.0
Books, courses and videos to go deeper
- Atomic DesignBrad FrostBook · Brad Frost, 2016 (Amazon)
- Design That ScalesDan MallBook · Rosenfeld Media, 2023 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Versioning and releases · Measuring adoption · Contribution models · Tokens from Figma to code · A roadmap for the system · Deprecation lifecycle