Skip to content
UX Atlas
Plate SYS·006 · Design systemGrid D3 · Rev. 2026-09-14

Versioning and Deprecation

How the system changes without breaking the products built on it.

Design systemCraft conventionAdvanced

Definition

Versioning communicates the nature of a change; deprecation is the process of retiring something with enough notice and support that consumers can migrate. Both are what allow a system to evolve at all.

Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.

On this plate
  1. 1Definition
  2. 2What counts as breaking
  3. 3A deprecation that works
  4. 4Semantic versioning, applied to a design system
  5. 5Shipping change without spending trust
  6. 6Local chart
  7. 7Continue from here

Reach for this when

  • Changing anything consumed by other teams.
  • Retiring a component or token.
  • Planning a major version.

Common mistakes

  • Deprecating before a replacement exists.
  • Breaking changes shipped in minor versions.
  • No migration tooling.
  • Visual changes treated as non-breaking.

What counts as breaking

  • Removing or renaming a prop, a token or a component.
  • Changing default behaviour, which is breaking even when the API is unchanged.
  • Visual changes large enough to alter layout, since consumers build around dimensions.
  • Changing keyboard behaviour or accessible names, which breaks tests and user habits.

A deprecation that works

  1. 1

    Announce with a reason

    Say what is being retired, why, and what replaces it.

  2. 2

    Ship the replacement first

    Never deprecate before the alternative exists and is documented.

  3. 3

    Warn in place

    Console warnings in development, and a notice on the documentation page.

  4. 4

    Provide migration tooling

    A codemod, or at minimum a precise before-and-after guide.

  5. 5

    Give a real notice period

    Long enough for teams to fit it into a planning cycle, and state the removal date.

  6. 6

    Remove

    In a major version, not a minor one.

Semantic versioning, applied to a design system

Standard semver says nothing about pixels, so the visual cases are where teams improvise. These are the defaults worth agreeing in advance.

ChangeReleaseAlso required
New component or new variantMinorDocumentation published with the release, not after it.
New optional prop, default matching current behaviourMinorThe default stated explicitly in the notes.
Fix with no visual or API changePatchNothing beyond the changelog line.
Token value changedMajor if it moves layout or contrast, minor otherwiseBefore and after screenshots in the release notes.
Prop removed or renamedMajorA codemod, and a deprecation shipped at least one minor earlier.
Default behaviour changedMajorAn opt-out kept for at least one major version.
Accessible name or keyboard behaviour changedMajorA direct notice to teams whose tests assert on it.

Shipping change without spending trust

Do

  • Run the old and the new side by side for at least one minor version.
  • Put the removal date in the runtime warning, not only in the changelog.
  • Batch breaking changes into a planned major rather than dripping them out.
  • Write release notes that answer the consumer's actual question: what do I have to do.

Do not

  • Do not deprecate by deleting the documentation page. The component is still in production.
  • Do not release a major without a migration guide that works for someone who did not write it.
  • Do not fix a defect by changing a default. Fix it behind a flag and switch the default at the next major.
  • Do not version tokens and components separately unless you are prepared to publish and maintain the compatibility matrix.

Local chart

SYS·006 · Region VI · Grid D3

This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.

Loss AversionBIAS·002 · PRINCIPLES BEHIND THISStatus Quo BiasBIAS·005 · PRINCIPLES BEHIND THISChromaticTOOL·041 · OFTEN USED WITHMigrating Product Teams onto a Design SystemCASE·003 · PRACTICAL EXAMPLEDeprecationTERM·089 · SHORT DEFINITIONFeature FlagTERM·099 · SHORT DEFINITIONSemantic VersioningTERM·090 · SHORT DEFINITIONSingle Source of TruthTERM·087 · SHORT DEFINITIONComponent API DesignSYS·002 · RELATED CONCEPTDesign System AdoptionSYS·005 · RELATED CONCEPTDesign System DocumentationSYS·003 · RELATED CONCEPTDesign System GovernanceSYS·004 · RELATED CONCEPT

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Principles behind this

The reasoning this solution is an application of.

Often used with

These usually appear in the same screen or the same decision.

Practical example

A worked decision where this was the deciding factor.

Short definition

The one-paragraph version, for when that is all you need.

Related concept

Connected closely enough to change how you apply this.