Design System Versioning: One Package or Many?
Do you version your design system as one big package or as many small ones? The first ensures consistency, the second offers flexibility. This choice impacts how product teams consume updates.
Why it exists
When a design system serves multiple products or teams, distributing updates becomes a critical challenge. A versioning strategy defines how changes are packaged and consumed, aiming to provide stability for users while allowing the system to evolve. The goal is to manage dependencies and updates predictably across an entire organization.
The mental model
Think of it as a choice between a curated box set and an à la carte menu. Versioning the whole library is the box set: you get a complete, cohesive collection where all parts are guaranteed to work together (e.g., Polaris v8.0). Versioning individual components is à la carte: you pick only the specific items you need (e.g., Atlaskit Badge v15.0.8), giving you flexibility but making you responsible for ensuring everything works together.
How it works
With whole library versioning, a single version number in one package.json file applies to all components. Maintainers publish one package, and consumers update a single dependency to receive all changes. This simplifies testing and keeps the code library in sync with design tools.
With individual component versioning, each component is a separate package with its own version number, often managed with a tool like Lerna. A consuming team can update their datepicker component without touching the button component. They control their own update timeline for each dependency.
When to use it
Favor whole library versioning when system-wide quality, consistency, and stability are paramount. It's simpler to maintain, guarantees compatibility between components in a given version, and makes it easier to sync with UI kits in design tools. This approach treats the design system as a single, coherent product.
When not to use it
Individual component versioning is better when team autonomy is the highest priority. If different teams work on isolated parts of a large application, this model allows them to update only the components they care about, on their own schedule. This avoids forcing a checkout team to deal with a breaking change in a component only used on the homepage.
One canonical example
The biggest footgun of individual versioning is dependency bloat. Imagine your application uses Modal v4.3, which itself depends on an older Button v3.8. If another part of your app directly uses the latest Button v12, you can unwittingly end up with two different versions of the Button component bundled into your final application. This increases page weight and hurts performance.
Interview question
When would a design system team most likely opt for individual component versioning over whole library versioning?
- a.When the design system needs to be tightly coupled and synchronized with external design tools.
- b.When system-wide consistency and guaranteed component compatibility are paramount.
- c.When different product teams require maximum autonomy to update only the specific components they use.Correct
- d.When the primary goal is to simplify dependency management and reduce application bundle size.
Why? this is the answer
Individual component versioning is favored when team autonomy is the highest priority, allowing teams to update specific components on their own schedule. Option D is incorrect because individual versioning can actually lead to dependency bloat and increased bundle size due to multiple versions of the same component.
Just read this? Test yourself on what you have been reading.
Read the original → bradfrost.com
- #design systems
- #versioning
- #frontend architecture
- #dependencies
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on design systems — each one lists the topics its interview covers.
See open roles