Book a call

WritingGovernancePart 3 of 4 in Running it day to day

Design system versioning: semantic versions, breaking changes and deprecation

Nothing in the code broke, but three products did. Design system releases can break screens through a padding tweak as easily as a renamed prop. How to number versions, decide what's breaking, and retire things without surprising anyone.

On this pageWhy design systems break products
  1. Why design systems break products
  2. Semantic versioning, in plain words
  3. What counts as a breaking change
  4. Release cadence
  5. Deprecation: retiring things gracefully
  6. Migrations: make switching cheap
  7. Supporting old versions
  8. The short version
  9. Frequently asked questions
  10. Further reading

The short answer

Version a design system with semantic versioning (major.minor.patch): patch for fixes that are safe to take, minor for new things that change nothing existing, and major for anything that could make a product look wrong or stop working. In a design system, that includes visual changes, like padding that no longer fits a table row, not just renamed props. Retire old parts by deprecating them first, with a replacement, a migration guide and a notice period, and remove them only in the next major release.

  • Decide in advance which visual changes count as breaking, and write it down.
  • Announce breaking changes at least one release cycle ahead, ideally four to eight weeks.
  • Track who still uses deprecated parts, and offer a codemod where the change is mechanical.

Why design systems break products

An illustration: the Friday padding change

The situation

The system team gives buttons slightly more rounded corners and a little more padding. It's a small visual tweak, shipped on a Friday as a minor release.

What goes wrong

On Monday three teams report broken screens: buttons no longer fit in table rows, a toolbar wraps onto two lines, and a checkout button pushes the price off small phones.

What should have happened

A layout-affecting size change is a major release: announced ahead, with before-and-after screenshots, a beta period and a checklist for teams.

Nothing in the code "broke". But the products did. Nathan Curtis wrote a whole article about exactly this: changes to colour, size and spacing can break a product as surely as a change to an API.

Semantic versioning, in plain words

Most design systems label releases with a three-part number like 4.2.1, following the Semantic Versioning convention. Each number tells teams how careful they need to be when updating.

Which number changesWhat it means for teamsDesign system examples
Major · 4 → 5"Careful: check or change your work."A component renamed or removed; a token removed; button sizes changed in a way that affects layouts; a prop renamed.
Minor · 4.2 → 4.3"New things added; nothing you use should change."A new component, a new variant, a new icon, a new optional prop.
Patch · 4.2.1 → 4.2.2"Fixes only. Safe to update."A bug fix; an accessibility fix that doesn't change size or layout; a docs correction.

What counts as a breaking change

Code-level breaking changes are well understood: removing a component, renaming or removing a prop, changing a default. Design systems add a second category, which is where most surprises come from.

CODE BREAKING CHANGES
  • A component, prop or token removed or renamed
  • A prop's default value changed
  • An event or callback changed shape
  • A dependency's major version raised (framework, peer libraries)
VISUAL BREAKING CHANGES
  • Size, padding or height changed in a way that affects layout
  • Typography metrics changed (line height, font, size)
  • A colour change that alters meaning, not just shade
  • A component's outside margin added or removed

Write your own rule list and publish it. A common, workable rule: if a change can move anything around it, it's major. A colour that gets slightly darker inside a fixed space is a minor change, announced. A button that gets 4px taller is major.

New word

A breaking change is any update that could make something stop working or look wrong in a product, so teams need to check or change their own work before taking it.

Release cadence

Predictable timing is itself a form of communication. When teams know releases come every other Tuesday and breaking changes are announced at least a release cycle ahead, they can plan.

WhatWhen
Minor and patch releasesOn a regular release day, early in the working week, never late on a Friday
Breaking change: first noticeAt least one full release cycle before, ideally 4–8 weeks, with the migration guide ready
Breaking change: remindersOne week before, and on release day
Major releasesRarely, and bundled: two or three a year beats one a month
Critical fixesImmediately, as a patch

Bundling matters. Every major release asks every team to stop and check their screens. Group breaking changes into a few planned majors a year, and use the time between them to deprecate.

Deprecation: retiring things gracefully

Sooner or later you'll replace a component. Doing it suddenly breaks things; never doing it leaves two ways to do the same job forever. The healthy middle path:

Mark it deprecatedIt still works; docs, Figma and a code warning say "use the new one"
→
Give a way to switchA migration guide; a codemod where the change is mechanical
→
Track remaining useA live count of uses per product, shared with champions
→
Remove in a majorAfter the notice period everyone knew about
Four steps from "please stop using this" to removal. The notice period is announced when the part is deprecated, not when it's removed.

Use the DTCG format's $deprecated property for tokens, a lifecycle label on documentation pages, and a console warning in development builds for components. Make sure the deprecation shows up wherever people meet the old part.

Migrations: make switching cheap

  • A migration guide with before-and-after code and screenshots for every breaking change.
  • A codemod: a script that rewrites code automatically for mechanical changes like renamed props.
  • A visual diff of affected components, so teams know what to check.
  • Extra office hours in the weeks around a major release.
  • A beta of the major version, so a couple of pilot teams can try it first.

An illustration: renaming a prop across 600 uses

The change

Button's kind prop is renamed to variant, so every component in the library uses the same word.

The risk

About 600 uses across seven products. A rename posted once in a busy channel will be missed.

How it ships

variant is added in a minor release alongside kind; kind is deprecated with a codemod; it's removed in the next major, with reminders and extra office hours.

That pattern, add the new thing in a minor, deprecate the old, remove in a major, turns most breaking changes into routine maintenance.

Supporting old versions

Decide how long a major version is supported after the next one ships. A common policy: the previous major gets critical fixes and security updates for six to twelve months; older versions get nothing. Publish the policy and track version spread: how many products are on each major. If many products are stuck on old versions, your majors are too frequent or too expensive to adopt.

The short version

  • Use semantic versioning: patch for fixes, minor for additions, major for anything that can break a product.
  • Visual changes that move layouts are breaking. Write your rules down.
  • Bundle breaking changes into a few planned majors; announce them four to eight weeks ahead.
  • Add the new in a minor, deprecate the old, remove in a major, with guides and codemods.
  • Publish a support policy for old versions and track version spread.

Frequently asked questions

Should design and code share one version number?

It helps if they release together. Many teams version the code package and tag the Figma library release with the same number, so "4.6" means the same thing in both.

Is a colour change a breaking change?

Usually not, if it keeps the same meaning and passes contrast. It becomes breaking if it changes meaning (a warning becoming red) or affects layouts or images that depend on it. Announce it either way.

How long should a deprecation period be?

At least one major release cycle, typically two to six months, depending on how many uses there are and whether a codemod exists.

How often should a design system ship a major version?

Rarely: one to three times a year is common. Each major asks every team to check their work, so bundle breaking changes.

What's a codemod?

A script that rewrites code automatically, for example changing every kind= to variant=. It turns a migration from hours of manual work into one command.

Further reading