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 Harbour | Bump | Why |
|---|---|---|
| The focus ring on Text field was 1 px, the spec says 2 px; fixed | PATCH 2.3.0 → 2.3.1 | A bug fix. Nothing anyone relies on changes |
New size="compact" on Button, for the staff console | MINOR 2.3.1 → 2.4.0 | New, optional. Old screens keep working |
color. marked deprecated, replaced by color. | MINOR 2.4.0 → 2.5.0 | SemVer says deprecations go in a minor, before removal |
color. removed; Button kind renamed variant | MAJOR 2.5.0 → 3.0.0 | Breaks anyone still using the old names |
| The default Button changes from secondary to primary look | MAJOR | No name changed, but every screen that used the default now looks different |
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/harbouris versioned with SemVer. - The library publish that matches it starts its description with the same number: "3.0.0: Button
kindis nowvariant…". - 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 numberUnreleasedin review
3.0.06 Oct 2026Breaking
2.5.01 Sep 2026
2.4.04 Aug 2026
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:
- What to use instead of anything removed.
- How long the upgrade takes, measured on one real product.
- 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)
- Write down the last five changes your team made to its components or styles.
- For each, ask: would anything that worked yesterday break or look different without anyone touching it?
- 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
- Semantic Versioning 2.0.0
- Olivier Lacan, Keep a Changelog 1.1.0
- Figma Help Center: Publish a library (checked November 2026)
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.
Related
Deprecation and breaking changes · Storybook and living documentation · Building a Figma library · Contribution models · Motion in design system governance · Semantic versioning for design systems