Design System Versioning & SemVer

Design Systems & Engineering • Product Strategy & Growth

Design system versioning helps teams identify releases and understand what changes when they upgrade a shared system. Semantic Versioning (SemVer) is one scheme for versioning software packages based on changes to a declared public API.

What counts as the public API?

Document which component exports, props, supported behaviors, and token names consumers can rely on. This is the compatibility contract for the package. Decide whether particular visual behavior is part of that contract and describe other visible changes in the release notes.

Design files and code can have different release schedules. Map a design library update to its matching code release when their changes are meant to be used together, and tell teams where to check compatibility.

Major, minor, and patch examples

For a stable package at 2.4.1, treat each row as a separate release example.

Change Next version Why
Fix a dialog bug so focus returns to the trigger as documented 2.4.2 Backward-compatible bug fix
Add an optional wide dialog variant and keep the current default 2.5.0 Backward-compatible addition
Remove a documented dialog prop 3.0.0 Breaking change to the public API

A token color update does not automatically determine the version bump. Check the compatibility contract first. A change that breaks a declared guarantee needs a major bump even if it only changes a value. Communicate visible changes in any release. For example, removing a documented token name is different from correcting its value to match the documented design.

How do you plan a breaking change?

If you are renaming a public prop, add the replacement while keeping the old prop working. Mark the old one deprecated in a minor release and explain how to migrate. Agree on the deprecation window and check representative products before removing it in a major release.

Publish migration notes with the affected consumers, a before-and-after example, and any manual checks. For a shared dialog, include a keyboard test in a real flow. For a prop rename, show the replacement prop and explain when teams can remove the old one from their code.

Sources