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.
Something that worked yesterday breaks or looks different without anyone touching it.
e.g. a prop renamed, a default changedNew and backward compatible, including anything newly marked as deprecated.
e.g. a new component, a deprecation warningA backward compatible fix that restores what the docs promise.
e.g. a focus ring back to 2 pxMAJOR.MINOR.PATCH · API = names + defaults + layout + behaviour · 0.y.z: anything may change
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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: ..."
- Atomic DesignBrad FrostBook · 2016 (Amazon)
- Semantic Versioning 2.0.0 (external site)
- Keep a Changelog 1.1.0 (external site)
- Atomic Design, chapter 5: Maintaining design systemsBrad Frost (external site)
"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.