As a system changes, adopters will want to take advantage of what’s new.

“Let’s update the old Card with a new, shiny Card,” they say. Or, dangerously, “Let’s put this newer Button in the page with all those older ones.”

Trouble arises when change is poorly communicated or its impacts ill-defined. Developers compare a proposed design to system code, identity what needs to be swapped or added, and carefully install or upgrade what’s needed. They are also usually mindful of breaking change in dependencies.

Are designers as sensitive to changes when working in a tool like Sketch? Not as much. They replace this with that. A new Button goes here, unaware that older buttons are used elsewhere in that or other pages. Designers flow updates swiftly, indicating neither the component’s version nor annotating an upgrade compared to what’s coded today. Friction ensues:

“I add a new system feature to my design. Yet the developer says we can’t use it.”
Designer on a product team

“The designer sprays style and component upgrades across a new feature, completely unaware of the upgrade costs it triggers across our whole app.”
Developer on the same product team

Designers want the latest. Developers balance tradeoffs of new quality with scale and maintenance. Systems should clean up that conversation.

Identifying how to version is simple (use SemVer!). However, identifying what’s versioned — by a library or by component — is more challenging. Versioning communicates how things change from launch through deprecation and end-of-life. This article takes us through that cycle of change across system outputs: code, tokens, design assets, and doc.

How to Version? Start with SemVer

Every discussion about versioning design system outputs begins and ends with the industry-standard Semantic Versioning (SemVer).

SemVer versions in a MAJOR.MINOR.PATCH format, incrementing each as a:

  • MAJOR version for incompatible API changes (that is, something “breaks”),
  • MINOR version for adding backward-compatible features, and
  • PATCH version for backward-compatible bug fixes.

Daniel O’Connor, Atlassian’s AtlasKit, and Morningstar’s Design System offer helpful deeper examples describing SemVer’s application to system features.

Long an industry-standard in versioning code, versioning is increasingly relevant in design tools too. Many system teams apply SemVer to Sketch symbol libraries in software tools like Abstract and Invision DSM. You can learn the methodology at

Takeaway: Strongly encourage designers to learn SemVer. Not only will it help them communicate with engineers more effectively, but it is increasingly meaningful in designer-to-designer collaboration too. It changes lives!

What to Version? A Library or Features Within

A design system team versions its library as a single, monolithic package or separately per feature, such as component by component.

Versioning the Library

A design system versioning by library applies the same version number to all system assets simultaneously, such as 1.4.0 applies across all components.

If any component adds a backward-compatible feature, then the entire library increments a minor version from 1.4.0 to 1.5.0. Similarly, if any component has a breaking change, the entire library increments the major number from 1.4.0 to 2.0.0.

Versioning “by library” is the comment choice for teams delivering vanilla HTML & CSS. Adopters typically integrate markup and style into their app and refer to a library’s collectively compiled CSS, such as core.css.

You can’t include a core.css from 2 or more versions without CSS conflicts. The only way to do so is if the system supports namespacing CSS files and classes across versions. I’ve not seen a system do that. Instead, they all operate like this: Want button from library version 1.4.0? Then every component on that page must use library version1.4.0. Otherwise, things may break.

Versioning By Component

Versioning “by component” enables adopting teams to mix and match button version 5.3.1 with form checkbox 3.1.0 and radio 1.1.0 on the same page.

Adopters need not worry about when each was released, since HTML markup, style, and script are encapsulated and won’t conflict with other components types included on the same page. This may or may not mean you can use multiple versions of one component simultaneously. “Can I include button’s 1.7.0 in one part of the page along with button 1.2.0 and 2.5.0 elsewhere on the same page?” It depends on how the library works.

Versioning by component is consistent for teams using a continuous release model and using a JavaScript framework (React, Vue, etc) or delivering web components. They’ll make much smaller changes more modularly more often.

System Versions Over Time

SemVer enables adopters to recognize key moments in a system’s life cycle.