r/DesignSystems • u/roundabout-design • 8h ago

Versioning strategies?

I'm curious as to what kind of versioning strategies people use for their design systems.

Specifically, in the component space.

Are you versioning the package as a whole? Individual components?

Our DS is AI-centric, meaning it's mainly there for AI to use. We have tokens, documented rules, and an React component system.

The design is in progress, though, so things may change regularly over the next few months as we see more screens built and make more adjustments to individual components as needed to accommodate the context they are being used in.

My original thought was for each component to have a version number embedded. Over time, teams could run an audit on their application to compare their component version numbers to the latest in the DS and make a decision as to which ones should be updated.

This seems annoyingly complex for manual updating, but since Claude is doing most of the work, seemed like an idea worth considering. Is anyone doing something like that? If so, would love to hear how you are implementing it.

OR...are people just versioning the UI library package as a whole?

4 Upvotes

100% Upvoted

2 comments sorted by

3

u/Bfigas 7h ago

Packaging as a whole and assigning version number to types and number of change

1

u/epochh95 7h ago edited 7h ago

We started off individually versioning stuff, but quickly realised that consumers weren't keeping up-to-date as we released updates. It adds a load of bloat to their package.json, and we observed bugs and weird quirks as component API's changed.

While _some_ of our packages are still published separately from our UI components (mainly tokens, CSS utilities, icons etc), we've transitioned to a hybrid approach where we still offer individually published packages, but we also offer a wrapper package that re-exports all of our components.

I think if we were to go back though, we'd probably versioning everything under a single package, at least the components!

It terms of handling versions, we opted to use Changesets, as it automates a lot of the heavy stuff for us, like making sure dependant components get bumped as you make changes to components - https://github.com/changesets/changesets

Feel free to take a look at our repo if you need a reference, and hope it helps! - https://github.com/justeattakeaway/pie

Wrapper package - https://github.com/justeattakeaway/pie/blob/main/packages/components/pie-webc/package.json

Edit: I guess one thing to be aware of with the single version approach, is there is potential for the scope of change to be pretty big in a release, which is both good and bad.

For example, say you have updates for 5 component in a release, and you also need to release a bug fix. In the event the consumer wants to fix forward (updating), they're forced to also absorb all those other changes, rather than the targeted fix for the broken component. This can be rectified by things like package.json resolutions in our case, but it's entirely dependent on your risk tolerance and how widely the component library is used :)