Marcus Andrey Study
Ler em português Library

Design Systems · Step 5 · 6 min read

Versioning and releases

A design system is something other teams depend on, so every change is a change to their product. How Semantic Versioning works and what counts as breaking for a design system, how to keep the Figma library and the code package on one number, how to write a changelog people read, and a release rhythm teams can plan around.

A version number is a message to every team that uses the system: how careful do you need to be with this update? A patch says "take it, nothing you rely on changes". A major says "set time aside". When a system's numbers tell the truth, teams update often and fixes reach users. When they don't, teams stop updating, and the system splits into as many versions as there are products.

What you'll be able to do after reading:

  • Explain MAJOR, MINOR and PATCH in plain words
  • Decide which kind of change a design system change is, including the ones that look harmless
  • Keep the Figma library and the code on one version
  • Write a changelog and release notes people act on

1. Three numbers, three promises

Semantic Versioning, the convention most code packages follow, gives a version three numbers, MAJOR.MINOR.PATCH, and says to increase (Semantic Versioning 2.0.0):

  • MAJOR "when you make incompatible API changes"
  • MINOR "when you add functionality in a backward compatible manner"
  • PATCH "when you make backward compatible bug fixes"

Two more rules matter for design systems. Version 0.y.z "is for initial development. Anything MAY change at any time", so a system that's still finding its shape can say so honestly. And deprecation is a minor release: the minor number "MUST be incremented if any public API functionality is marked as deprecated", and the spec's FAQ asks for "at least one minor release that contains the deprecation" before the major that removes it (Semantic Versioning 2.0.0). How to run that deprecation well is in Deprecation and breaking changes.


2. What "breaking" means for a design system

Change to HarbourBumpWhy
The focus ring on Text field was 1 px, the spec says 2 px; fixedPATCH 2.3.0 → 2.3.1A bug fix. Nothing anyone relies on changes
New size="compact" on Button, for the staff consoleMINOR 2.3.1 → 2.4.0New, optional. Old screens keep working
color.brand.blue marked deprecated, replaced by color.action.primaryMINOR 2.4.0 → 2.5.0SemVer says deprecations go in a minor, before removal
color.brand.blue removed; Button kind renamed variantMAJOR 2.5.0 → 3.0.0Breaks anyone still using the old names
The default Button changes from secondary to primary lookMAJORNo name changed, but every screen that used the default now looks different
Semantic Versioning applied to a design system. The test for each row is the same: will something that worked yesterday break, or look different, without anyone touching it? The last row is the one teams miss: a change of default is a breaking change even when the API is identical.Rules from Semantic Versioning 2.0.0; the Harbour changes are made up for this course.

For a code library, the API is the functions and their arguments. For a design system, the API is wider: anything a product relies on without thinking about it. That includes:

  • Names: components, props, option values, tokens, CSS custom properties, Figma property names.
  • Defaults: what a component looks like and does when nobody sets anything.
  • Layout: a Button that grows 4 px taller can push a form below the fold on every screen that uses it.
  • Behaviour: a Dialog that now closes on outside click changes what users can lose.

So the test is not "did the API change?" but "will something that worked yesterday break, or look different, without anyone touching it?" If yes, it's a major, even when the code diff is one line. Visual tests in Storybook (Storybook and living documentation) are how you find out before release.


3. One number for Figma and code

Figma's publish flow asks for a description, not a version number: each publish gets the description you write, which people see when they accept the update and in the file's version history (Figma, Publish a library). The code package does have a number. Harbour joins them:

  • The package @tidewater/harbour is versioned with SemVer.
  • The library publish that matches it starts its description with the same number: "3.0.0: Button kind is now variant…".
  • The cover page of each library file shows the current version (see Building a Figma library).

Then a designer and a developer can say "we're on 3.0" and mean the same thing. Remember that subscribers choose when to accept a library update, so the design side lags too. The number tells them how carefully to accept it.


4. A changelog people read

Harbour changelog

Follows Semantic Versioning · Figma library and @tidewater/harbour share one number

Unreleasedin review

Added

  • Sailing card: status slot for delays and cancellations

3.0.06 Oct 2026Breaking

Removed

  • color.brand.blue, deprecated in 2.5.0. Use color.action.primary

Changed

  • Button: kind is now variant, in code and in the Figma component, in the same release

How to upgrade

  • Migration guide, about 20 minutes per product. Office hours on Thursday

2.5.01 Sep 2026

Deprecated

  • color.brand.blue. Removal planned for 3.0.0

Added

  • Dark mode for Dialog and Select

2.4.04 Aug 2026

Added

  • Button: size="compact", for the staff console

Fixed

  • Text field: focus ring back to 2 px
A filled-in changelog for Harbour, newest first, grouped by type of change. One number for design and code means a designer and a developer can say "we're on 3.0" and mean the same thing. The breaking release says what was removed, what to use instead and how long the upgrade takes.Format after Keep a Changelog 1.1.0; the releases are made up.

Keep a Changelog defines a changelog as "a curated, chronologically ordered list of notable changes for each version", and its principles fit design systems well: "Changelogs are for humans, not machines", "The latest version comes first", and changes grouped as Added, Changed, Deprecated, Removed, Fixed and Security, with an Unreleased section at the top for what's coming (Keep a Changelog 1.1.0).

For a design system, add three things to every major:

  1. What to use instead of anything removed.
  2. How long the upgrade takes, measured on one real product.
  3. Where to get help: a migration guide, office hours, a channel.

Write for the designer who's busy and the developer who's tired. "Fixed focus ring" is a commit message. "Text field: focus ring back to 2 px" is a changelog line.


5. A release rhythm

  • A fixed cadence for minors, every two or four weeks, so teams know when to look.
  • Patches when needed, especially for accessibility bugs, which shouldn't wait.
  • Majors rarely, and announced early: at least one minor with the deprecations first, and a date.
  • The same day for design and code. A library publish before the package ships means designers draw things developers can't build yet, and the reverse.
  • Support more than the latest major for a while, and say for how long. Nobody upgrades the week a major lands.

6. Common mistakes

  • Calling a visual change a patch because "the API didn't change".
  • Removing something with no deprecated release before it.
  • Publishing the Figma library on a different rhythm from the code.
  • Changelogs written from commit messages.
  • Majors so frequent that teams stop upgrading.
  • A system stuck at 0.y.z for years, so nothing is ever promised.

7. Vocabulary

Term Meaning
Semantic Versioning (SemVer) MAJOR.MINOR.PATCH, where each number says what kind of change it is
Breaking change A change that makes something that worked stop working, or look different, without anyone touching it
Deprecation Marking something as going away, while it still works
Changelog A list of notable changes per version, newest first
Release notes The message for one release: what changed, who needs to act, how
Migration guide Step-by-step instructions to move from one major to the next

8. Try it (no tools needed)

  1. Write down the last five changes your team made to its components or styles.
  2. For each, ask: would anything that worked yesterday break or look different without anyone touching it?
  3. Give each one a number: patch, minor or major. Then write one changelog line for each, for a busy reader.

Reflection questions: Which of the five would you have called a patch before this lesson? Does anyone in your team know which version of the system their product is on?


9. If you already practise

  • Add the version to the cover page of every library file and to every publish description.
  • Run visual tests before every release and attach the diff to the release review.
  • Measure how long the last major took one team to adopt, and put that number in the next one's notes.
  • Track how many products are on the latest major: it's one of the adoption measures in Measuring adoption.

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.

Deprecation and breaking changes · Storybook and living documentation · Building a Figma library · Contribution models · Motion in design system governance · Semantic versioning for design systems

Saved only on this device.

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