Semantic Versioning: How Version Numbers Show What a Design System Change Does
Learn how the MAJOR.MINOR.PATCH number tells designers and developers whether a design system update is safe to adopt.
In short
Semantic versioning uses a MAJOR.MINOR.PATCH number to tell designers and developers whether a design system update is safe to adopt.
12 min readFree
What you will learn
A design system is a shared set of reusable parts, rules, and visual choices that many product teams build with. Each time the team publishes a new release, people need a fast way to know what changed. Semantic Versioning, often shortened to SemVer, is a numbering habit that gives that answer. In this lesson you will learn what each of the three numbers means, how to sort a change into the right number, and how teams use those numbers to decide when to update.
Key words
- Design system
- A shared collection of reusable parts, usage rules, and visual decisions that product teams use to build their screens.
- Release
- One published, numbered version of the design system that people can install or use.
- Consumer
- Any team, product, or tool that uses the design system. A product team is a consumer.
- Version number
- A label such as 3.2.1 that tells people which release they are looking at.
- Interface
- The parts other people rely on, such as component names, settings, and token names.
- Prop
- A setting you give a component, such as its size or its type. Props are part of the interface.
- Token
- A named design decision, such as a color role called primary, stored under one name.
- Breaking change
- A change that forces consumers to edit their own work before they can use the new release.
- Backward compatible
- A change that keeps working with what people already built.
- Pin
- Lock a product to one exact version so it does not change until someone chooses.
- Range
- A rule that allows a group of versions, such as every release in the 1.x family.
- Pre-release
- A test version with a label added, such as beta, which signals that it is not finished.
What do the three numbers mean?
SemVer uses three numbers separated by dots, written as MAJOR.MINOR.PATCH. Each position has its own job. The numbers are read from left to right, and the further left a number is, the bigger the change it signals. The official SemVer rules describe the scheme as a way to tell consumers what kind of change a release contains.
MAJOR (the first number)
Goes up when a release contains breaking changes. Consumers may have to update their work before they can use it.
MINOR (the middle number)
Goes up when a release adds something new in a way that does not break existing work. A new component or a new variant is a typical example.
PATCH (the last number)
Goes up when a release only fixes mistakes. Work built on the earlier release should keep working as before.
Tip
Read the first number as a warning level. If it changed, check your work before you upgrade. If only the last number changed, the upgrade is usually low risk.
Once a version is published, its contents do not change. Any fix, even a small one, gets its own new number. This is why 3.2.1 always means the same thing, no matter when someone looks at it.
Why reset the lower numbers?
When a bigger number goes up, the smaller numbers to its right start again from zero. This tells readers that a fresh set of changes began at that level. Follow the steps below to see how it works.
- 1
Start with 1.4.2
This is the release your product uses today.
- 2
Add a breaking change
Because existing work must change, the first number goes up by one, from 1 to 2.
- 3
Reset the others
The middle and last numbers return to zero, so the new release is 2.0.0.
- 4
Compare with a new feature
If 1.4.2 had only gained a backward-compatible feature instead, the release would be 1.5.0, not 1.4.3. The middle number rises and the last number resets.
How do you sort a change into the right number?
The hard part of SemVer is not the numbers. It is deciding which number a change deserves. Start with one question: will a person who already uses the design system have to edit their work? If yes, the change is breaking. If no, ask whether the change adds something or only fixes something.
What are breaking changes?
In a design system, a breaking change is anything that makes existing use stop working or behave differently in a way that forces edits. These changes raise the MAJOR number.
Removing or renaming
Taking away a component, a prop, or a token, or giving it a new name. Renaming a color token is a breaking change because every screen that uses the old name must be edited.
Changing behavior or the interface
Changing how a component works or how people interact with it, such as its keyboard pattern. Changing a prop's type from optional to required is also in this group.
Changing a default
Making a component act differently out of the box, even when nobody removed anything. People who relied on the old default are affected.
Some teams use a gentler route first. A feature that will be removed later can be marked as deprecated, which means it still works but should not be used. Marking something as deprecated is a change that raises the MINOR number. The actual removal waits for the next MAJOR release. This gives consumers time to move over.
What are backward-compatible additions?
An addition is backward compatible when existing work keeps working exactly as before. These changes raise the MINOR number.
New component
A new part, such as a tooltip, that teams can choose to use. Pages that do not use it do not change.
New variant
A new style of an existing component, such as a quieter ghost button. Old buttons still look and act the same.
New optional prop
A new setting that is off unless someone turns it on, and whose default keeps the old behavior.
New token
A new named decision, such as a color for info messages. Existing tokens stay as they were.
Tip
Ask whether an addition would change anything on a screen that does not use it. If the answer is no, the change is probably a MINOR update.
Fixes
A fix corrects something that was wrong, and the rest of the system still works the same way. Fixes raise the PATCH number. Examples include a misaligned icon that now sits centered, or a text color that failed contrast checks and now passes. A color contrast fix is still a fix, as long as people's existing work keeps working and nothing they depend on is removed.
Using version numbers to decide when to upgrade
Version numbers are a shortcut. They let a team estimate the risk of an update before reading every line of change. Teams also control which versions their products accept, and they can choose how strict that control is.
Reading a version bump to judge risk
A version bump means the jump from one number to a new one. Official guidance says that a higher number signals a bigger kind of change, so a team can rank updates by how careful it must be.
Patch bump
Low risk. Expect corrected mistakes and no new work to check.
Minor bump
Low risk to existing work. Read the new additions so you know what is available.
Major bump
Higher risk. Set aside time to update your work, and read the migration notes first.
Some teams go further and let each part of the system follow its own version path, with component-level versions instead of one number for the whole library. A single breaking component can raise the number for the whole library, so teams often plan carefully before releasing one.
Pinning versions and using ranges
Developers often describe how much freedom a product has to take new releases. The common ways are an exact pin, a tilde range, and a caret range. You will see these in product settings, so it helps to know what they allow. The examples below use the npm notation that many teams follow.
Exact pin, such as 1.4.2
Allows only that one version. Nothing changes until someone edits the setting.
Tilde range, such as ~1.4.2
Allows the same MAJOR and MINOR numbers with newer patches. It accepts fixes but not new additions. Use it when a team wants only corrections.
Caret range, such as ^1.4.0
Allows any release from 1.4.0 up to, but not including, 2.0.0. It accepts minor additions and patches, but it blocks breaking major changes. It is the most common default.
Pre-1.0 versions need care. A version that starts with zero is a sign of early work, and the SemVer rules say anything may change in that stage. For a 0.x design system, a caret range is narrower. It only allows updates within the same minor number.
Tip
If your team is new to the system, start with a caret range on a stable 1.x or higher release. Switch to an exact pin only for a specific reason you can explain to others.
Check your understanding
Try these two short scenarios. Each one needs the ideas from this lesson.
Quick check
Your design system's Modal currently closes when someone clicks outside it. The team changes it so it stays open on an outside click, unless a new optional prop called dismissOnOutsideClick is turned on. The current version is 2.5.3. What should the next version be?
Quick check
A product uses a Card component with the range ^2.4.0. Later the design system publishes 2.4.1, then 2.7.0, then 3.0.0. Which releases will the range accept without the team changing its setting?
Common mistakes to avoid
Treating a rename as small
A new name for a token or prop feels tidy, but it breaks every place that used the old name. It belongs in a MAJOR release.
Bumping the wrong number for a new variant
A new variant adds choice without breaking old choices, so it is a MINOR change, not a PATCH.
Forgetting that behavior counts
A change that keeps every name but alters what a component does can still break users. Check behavior and defaults, not only names.
Tip
When you are unsure, write one sentence describing what a user of the old version must do after the change. If they must do something, the change is probably breaking.
Key takeaways
SemVer gives every release a MAJOR.MINOR.PATCH number. MAJOR signals breaking changes that need work from consumers. MINOR signals backward-compatible additions, and PATCH signals backward-compatible fixes. When a bigger number rises, the smaller numbers reset to zero. Teams use these numbers to judge risk, to choose between exact pins and ranges, and to read pre-release labels as signs of unfinished work. Your job as a designer is to sort each change honestly, because the number is only useful when it is correct.
Sources
- Semantic Versioning 2.0.0 specification (semver.org)
- Semantic Versioning 2.0.0 full text (semver.org spec file)
- Kolibri Design System, Release process
- Supernova, How to Version Design Systems: 8 Real-World Examples
- UXPin, Component Versioning vs. Design System Versioning
- Steve Kinney, Versioning and Release Management
- EightShapes, Versioning Design Systems (Medium)
- npm documentation, semver ranges
- Rush Stack, SemVer concepts (version ranges)
- npm Version Range Cheat Sheet (Dev Toolbox)
- OpenReplay, Semantic Versioning Explained
- GitWatchman, Semantic Versioning Best Practices
- DEV Community, Design Token Architecture for Scalable Theming
Last updated on 17 November 2026
Related lessons
- Design systemsVersion Control: Track Every Design System Change and Undo Mistakes Safely
- AI engineeringSemantic Search
- Design systemsContribution Guidelines: How Anyone Proposes and Ships a Design System Change
- Design systemsPR Templates: The Pre-Filled Form That Makes Every Design System Change Easy to Review
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.