Evaluating the version and handling breaking change how.
Disruptive changes are not prohibited, but they must be communicated in advance, have a clear roadmap, and not surprise the team using the system.
Baseline standards set versions semantically, known as SemVer (denoted MAJOR.MINOR.PATCH): breaking changes increase the major number, adding backward-compatible features increases the minor number, and fixing minor bugs increases the patch number. Breaking changes are not prohibited but must be communicated in advance with a long enough downtime window for teams to adapt. Special attention should be paid to visual breaking changes, such as color or spacing alterations that misalign the interface even if the programming interface remains unchanged, as these are often mistaken for minor changes.
- need to coordinate simultaneous updates for multiple products (common versioning)
- teams upgrading independently (iterating by component)
- A wide community needs a long window to stop using before removal.
- change colors or spacing and consider it a minor update, overlooking visual disruption
- remove old components without prior notice
Disruptive changes, or breaking changes (changes that break the old usage), are an unavoidable part of the lifecycle of any growing design system. The issue is not whether to change, but how to change so that teams using the system are not caught off guard and have enough time to transition.
Baseline: set versions according to semantics
The most widely used standard is SemVer, or Semantic Versioning (setting versions semantically), denoted by MAJOR.MINOR.PATCH. These three numbers are not decorative; each number conveys a commitment to the system's users.
- MAJOR: increases when there are disruptive changes, meaning users must adjust their code or design to continue using it.
- MINOR: increases when new features are added but remain backward compatible, meaning they do not break what is currently running.
- PATCH: Used only for bug fixes that do not change behavior or interface.
The practical meaning of this convention is: when another team sees a large number jump, they immediately know to read the changelog and double-check before upgrading. If they only see the middle or final number increase, they can upgrade with more confidence.
Visual breaking: often overlooked.
Breaking the API is relatively easy to detect because the code will report an error. More dangerous is breaking the visual: changing color token values, spacing, or font size can cause the interface of another team to deviate from the original design, even if no line of code reports an error.
A change is a breaking change if it alters anything that users rely on, even if the programming interface remains unchanged.
Nathan Curtis, Visual Breaking Change in Design Systems, EightShapes
Before each change of tokens or shared styles, you need to ask: will this change make any screen of another team look different? If so, that is a visual break and must be labeled MAJOR, not PATCH.
Discontinued windows: the process cannot be omitted.
To stop using, or deprecation (announcing that a feature will be removed in the future), requires two elements: clear communication and a long enough timeframe for teams to transition. Sudden removal without prior notice is the most common reason teams lose trust in the design system.
Long window, for example 18 months like Salesforce: suitable when there are many discrete teams that are hard to gather for an upgrade at the same time, or when products have long and inflexible release cycles.
Short window, for example 3 to 6 months like Financial Times' Origami: suitable when the community is small, close-knit, and has a habit of frequent upgrades. A shorter window helps the system escape technical debt more quickly.
It's best to let the new coexist with the old for a while before officially launching the major version. Morningstar once kept both the old and new component versions running in parallel for six months before releasing version 2.0.0, allowing teams to revert if necessary.
Evaluating generally or by each component.
This is a decision that needs to be finalized early in the management setup phase.
- Versioning for the entire library: A single version represents the entire system. It is easy to coordinate when teams need to upgrade simultaneously. The downside is that if only one component changes, the entire library still needs to increase its version number.
- Versioning by component: Each component has its own independent version. Teams know exactly which component has broken and can selectively upgrade. The downside is that it is more complex to track and coordinate.
Choose a direction based on how the teams actually work together, not based on which theory sounds better.
Common mistakes when governing versions
- Changing color tokens or spacing and then numbering PATCH because the programming interface remains unchanged, ignoring visual disruption.
- Removing old components without prior notice causes teams to break down en masse.
- There is no change log; other teams do not know what has changed in the new version and whether adjustments are needed.
- Stuffing too many disruptive changes into a MINOR version to avoid a MAJOR version, resulting in the MINOR version surprising users.
- Consolidate scattered changes across many small versions instead of gathering them and triggering a MAJOR version with a clear timeline.
The viewpoint of Sinh Vũ
In Sinh Vũ's A3 process, versioning and change logs come with tokens according to the neutral DTCG JSON standard (Design Token Community Group, a common token format across tools). This structure means that a change at the token level can ripple throughout the entire system if version discipline is lacking; this is where visual breakdowns occur most frequently and least expected.
Sinh Vũ establishes a stop window and approval process so that every disruptive change is reported in advance and has a fallback option. The specific release cadence and the length of the window should be finalized during the initial governance setup, as the correct numbers depend on the number of teams sharing and their level of closeness, with no default numbers applicable to all organizations.
Decision checklist
Topic: Evaluating versions and handling breaking changes in the design system. Sinh Vũ guide, sinhvu.com
Select each item you find appropriate, then print or save as PDF to take with you.
If you have marked most of the signs above, this is the time to discuss in more detail. Sinh Vũ can help you review and propose a direction.
References
Semantic Versioning 2.0.0 (semver.org). Nathan Curtis, Versioning Design Systems, Releasing Design Systems, and Visual Breaking Change in Design Systems (EightShapes). Practical experience from Sinh Vũ Studio.
Frequently asked questions
How long in advance should we notify before removing an old component?
There is no fixed number; it depends on the number of teams sharing and the closeness of that community. Salesforce allows for an 18-month window because there are many disparate teams that are hard to elevate simultaneously. Financial Times' Origami compresses to 3 to 6 months due to a small and close community that can upgrade quickly. You should finalize this number while setting up governance, not wait until you need to dismantle it to discuss.
Is changing the color token a breaking change?
Yes, if the changes cause the interface of another team to deviate from the original design. This is called visual disruption, which is different from breaking programming interfaces. A common mistake is changing colors or spacing and then labeling it as a minor version because the programming interface remains unchanged, but the display results of the other team may still be disrupted. Both dimensions must be evaluated before deciding on versioning.
You should version the library as a whole or by each component?
It is easier to coordinate updates across multiple products simultaneously when done collectively. When done separately by component, teams can upgrade independently and know which components are breaking. There is no one right way; choose based on how teams actually work together, not based on theory.