Marcus Andrey Study
Ler em português Library

Framework · Design systems · 3 min read

Semantic versioning for design systems

MAJOR.MINOR.PATCH applied to a design system, where the API includes names, defaults, layout and behaviour, so every release number tells product teams how carefully to update.

4MAJOR

Something that worked yesterday breaks or looks different without anyone touching it.

e.g. a prop renamed, a default changed
.5MINOR

New and backward compatible, including anything newly marked as deprecated.

e.g. a new component, a deprecation warning
.1PATCH

A backward compatible fix that restores what the docs promise.

e.g. a focus ring back to 2 px

MAJOR.MINOR.PATCH · API = names + defaults + layout + behaviour · 0.y.z: anything may change

Each number tells product teams how carefully to update; for a design system the API is anything a product relies on without thinking about it.

Use it when

  • You're about to release and someone says "it's only a visual tweak, call it a patch".
  • Teams have stopped updating because they can't tell a safe release from a risky one.
  • The Figma library and the code package have drifted onto different numbers.

How to use it

  1. Write down what counts as API. For a design system that's names (components, props, option values, tokens, CSS custom properties, Figma property names), defaults, layout and behaviour. Put the list in the docs. Output: a short "our public API" section.
  2. Classify every change with one question. Will something that worked yesterday break or look different without anyone touching it? Yes is MAJOR. A new, compatible feature or a new deprecation is MINOR. A compatible fix is PATCH. Output: a label on every merged change.
  3. Deprecate in a minor, remove in a major. Semantic Versioning asks for at least one minor release that contains the deprecation before the major that removes it. Output: no removal without a deprecated release before it.
  4. Give Figma and code one number. Version the package, start the matching library publish description with the same number, and show the current version on each library cover page. Output: "we're on 3.0" means the same thing to design and engineering.
  5. Write the changelog for people. Newest first, grouped as Added, Changed, Deprecated, Removed, Fixed and Security. For a major, add what to use instead, how long the upgrade takes on one real product, and where to get help. Output: release notes a busy designer can act on.
  6. Keep a rhythm teams can plan around. Minors on a fixed cadence, patches when needed (accessibility fixes shouldn't wait), majors rarely and announced early, design and code on the same day. Output: a release calendar in the docs.

Worked example

Harbour is on 3.4.0. Five changes are waiting for the next release at Tidewater:

Change Breaks or looks different without anyone touching it? Bump
Text field focus ring back to 2 px after a regression No, it restores the documented look PATCH
New Notice component No, nothing existing changes MINOR
Banner marked deprecated, warning names Notice No, it still works MINOR
Button padding grows, so it is 4 px taller Yes, forms reflow on every screen MAJOR
Button prop kind renamed to variant Yes, builds fail MAJOR

The first three ship together as 3.5.0. The two Button changes wait for 4.0.0, announced with a date and a migration guide.

Watch out for

  • Calling a visual change a patch. "The API didn't change" is the wrong test. Layout and defaults are API.
  • Majors so frequent that teams stop upgrading. Batch breaking changes on a known rhythm instead.
  • Staying at 0.y.z for years. Version 0 means "anything may change at any time", so nothing is ever promised.
  • Changelogs copied from commit messages. "Fixed focus ring" is a commit. "Text field: focus ring back to 2 px" is a changelog line.

Template

Copy this into the release checklist and fill it before you pick the number.

Current version: ... 
Changes in this release:
  - ...  | breaks or looks different without anyone touching it? yes / no | MAJOR / MINOR / PATCH
  - ...
New version: highest bump wins = ...

Release notes (newest first)
## [x.y.z] - YYYY-MM-DD
### Added       ...
### Changed     ...
### Deprecated  ... (use ... instead, removed in ...)
### Removed     ... (use ... instead)
### Fixed       ...
### Security    ...
Who is affected: ...
Upgrade time on one real product: ...
Help: migration guide ... / office hours ... / channel ...

Figma publish description starts with: "x.y.z: ..."
Source
Semantic Versioning 2.0.0 (Tom Preston-Werner). Keep a Changelog 1.1.0 (Olivier Lacan)

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

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