Marcus Andrey Study
Ler em português Library

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.primary becomes color.action.primary.
  • A component removed: Banner is replaced by Notice.
  • A property renamed or its values changed: type="error" becomes tone="danger".
  • A default changed: Button was md, now sm.
  • 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

  1. 3.2.0February
    The replacement shipsNew Notice component, with a tone property. Banner still works as before.
  2. 3.4.0April
    Deprecated, not removedBanner marked deprecated in code, Figma and the docs. A console warning in development names the replacement and links the migration guide.
  3. 3.4 → 3.9April to September
    Migration windowA codemod rewrites most uses. The system team pairs with the two teams that use it most. Adoption dashboard counts what's left.
  4. 4.0.0October
    Removed, in a major releaseBanner deleted, listed under "Breaking changes" in the changelog with the one-line fix. 3.x gets security fixes for six more months.
A deprecation in Harbour, from replacement to removal. The rule comes from Semantic Versioning: deprecate in a minor release, remove only in a major one, and leave at least one minor release in between. The months are this example's choice, not a standard.Diagram: Marcus Andrey, CC BY 4.0. Versioning rule from semver.org 2.0.0.

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 $deprecated property that can be true or 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

  • Banner removed. Use Notice: <Banner type="error"> becomes <Notice tone="danger">. Run npx @harbour/codemods banner-to-notice. Deprecated since 3.4.0.
  • Token color.primary removed. Use color.action.primary (same value). Deprecated since 3.4.0.

Changed

  • Button focus 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.
A changelog entry for a major release, written for the person who has to upgrade. Each breaking change says what was removed, what to use instead, how to do it and since when it was announced.Example: Marcus Andrey, CC BY 4.0. Harbour is a fictional system.

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)

  1. Pick one component or token in your system you'd love to remove.
  2. Write its deprecation notice in two sentences: what replaces it, and when it goes.
  3. 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

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Versioning and releases · Measuring adoption · Contribution models · Tokens from Figma to code · A roadmap for the system · Deprecation lifecycle

Saved only on this device.

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