Leveraging the releases feature to version your design system
Michelle Chin
Our releases feature is a powerful tool for any maturing or scaling design system. We’ll go into two ways you can leverage releases. Teams commonly use releases to manage a production version (one that viewers can see) and an in-progress version, which is only visible to editors. Teams can also use versions and releases to align an entire product portfolio to one design system gradually.
Managing the design system lifecycle
Like software development, design system documentation goes through phases of progress. For example, a design system might be in a “development” phase, where editors and reviewers actively work on updating or adding content. When this is only visible to them, editors and reviewers can freely add or change content without worrying about confusing viewers.
Similarly, viewers can feel confident and trust what they’re viewing is the most stable content. Check out our learning hub article to see how the releases feature works.
Aligning your product portfolio with releases
Aligning to one design system can be challenging for established organizations with multiple products and endpoints. Some challenges include:
- Products often existed before design systems were common practice – so they might not be ready for a design system
- Mergers and acquisitions don’t follow the same design/development practices, yet they still need updating
- Not all products in the portfolio may have the same level of investment. For example, legacy products might be in a “keep the lights on” phase compared to new-technology products that are high profile.
- Not all design/development teams work in the same way or at the same pace
- Not all products have the bandwidth to align with the latest design system. Instead, they might have to focus on releasing features, and their designers and developers still need to use existing UI libraries.
The releases feature can help you navigate the alignment process, create a shared understanding with stakeholders, and preserve your and your team’s sanity!
The main idea is to use releases to stagger the alignment process. Doing so alleviates the pressure to align everything all at once. With this method, you can create guidelines and a plan for how different products can start to align. Let’s walk through an example of how this would work.
Let’s say we have a few legacy products and a product that can’t align just yet, but they’re using an existing design system. We can say they’re using version 1.0 – and because of their priority in the company, it’s OK they’re on version 1.0. Maybe someday, they’ll upgrade.
Simultaneously, our company is growing, and we’re in the process of a brand refresh. We’ll call the design system for that initiative version 2.0. It’s a priority for any high-profile or net new products to use version 2.0.
Determining which version products should use is a collaborative decision between product management, design, and development. Factors from each discipline can affect the decision made. For example, a product might not use the same code base as the components in version 2.0. The code base needs to be updated before they can use version 2.0.
Identifying and sharing guidelines on the approach to alignment can help level-set expectations for product teams and stakeholders. It’ll help product teams have a clear focus. It’ll help stakeholders understand why not everything is aligned all at once, why it’s OK that not all products are aligned, and how they can eventually align.
Benefits of using zeroheight for managing releases
Creating and managing releases is quick and easy in zeroheight. When you create a release, it captures a snapshot of your styleguide from that moment in time. From our scenario earlier, let’s say the button color was blue in the original design system. When we create version 1.0, all the details of the button – specs, usage guidelines, etc. are in that version. With the brand refresh for version 2.0, let’s say the button color is now green. As you resync your design files with zeroheight, that change is now in version 2.0. But if you switch back to view version 1.0, you’ll see that the button in that version remains blue.
What’s convenient about this release feature is that viewers can switch between versions easily, trust the content preserved in them, and avoid confusion. This is especially helpful if you have teams that work on more than one product and those products are using different versions of the system.
A few tips for practicing this approach
Theoretically, this sounds good but it can be a little tricky in real life. Here are some tips for implementing versioning this way.
- Document which design system each product uses. Documenting can be done in the styleguide, design deliverables, Jira tickets, etc. It will help anyone referencing code and design stay aligned and use the correct version.
- Document older versions where it makes sense. While you might focus on version 2.0, teams could still actively use version 1.0. If that’s the case, then make sure some of that information is in your styleguide. Because they’re still using an old version, they can still benefit from usage guidelines, specs, etc. This can be extra work, so consider to what extent you need to document the information. If you know version 1.0 will be around for another year, it might be worth putting in more effort to document things appropriately.
- Use the version number from the documentation as the number you reference. There are several places for versioning – design libraries, each code base for each product or endpoint, etc. Aligning these versions is nearly impossible, so the most straightforward version number to go with is the one used in your documentation system. The number for your documentation references a holistic design system, which includes design, code, and documentation.
- Document how versioning works in your design system. Documenting can help people understand the numbering convention and how the team approaches versioning across the product portfolio. While you can get pretty granular with numbering, we recommend keeping it as simple as possible to understand. If your company has a numbering system for your products, it might be worth following the same convention. Bonus points if you include a roadmap of how products will eventually align to one system.
- Hide any deprecated versions. Remove old versions that are no longer used to reduce confusion.
Let’s keep the conversation going! 😄
Let us know if you tried this method and what worked well and what didn’t. Do you use versioning differently? Where have you found success with using releases in your team’s workflow? We’d love to hear more. Join the conversation on zheroes, our Slack community of design system makers.