Versioning Design Tokens

Some strategic tips for versioning design tokens the right way.

Design tokens are an essential aspect of every Design System.

Versioning them correctly is crucial for maintaining consistency and ensuring everyone is on the same page.

Here are some strategic tips to do for doing it the right way.

---

1. Version design tokens separately

Since design tokens are technology-agnostic, they should be versioned separately from any other Design System library. At their core, they’re component dependency.

We can confidently incorporate new colors, such as a data visualization palette, or fine-tune our interactive blue to improve accessibility in the next version of tokens.

However, we need to be aware that embedding these changes in a web-based component library could potentially block release, as we would need to update all of the components as well.

If you package tokens as a dependency of a UI component library, the following benefits can be gained:

1. All adopters, not just the design system team, have access to the most up-to-date definition of visual style.

2. Communication can better focus on updates to style fundamentals.

3. Style can evolve separately from UI component code, and the token dependency can be upgraded when it makes sense to do so.

4. Update the system’s visual language without updating all components and patterns, saving time and effort

---

2. Use a common versioning system

To correctly version a design tokens library, start by defining a clear versioning system.

The system should be easy to understand and follow, no matter what tool is used to manage the design tokens.

The most widely used versioning system is called SemVer. It stands for Semantic Versioning and is used to version software and other digital products. SemVer provides a way to number versions that helps people understand how much a product has changed between versions.

The system uses three numbers separated by dots, such as "1.2.3". The first number represents a major change, such as a new feature or a significant redesign. The second number represents a minor change, such as a bug fix or a small enhancement. The third number represents a patch change, such as a small bug fix or a typo correction.

By following this system, people can understand how much a product has changed and know what to expect when updating to a new version.

---

3. Keep a changelog

Design tokens changelog — Polaris Design System

Keeping a history of design token versions is crucial.

This history helps in tracking changes, debugging issues, and ensuring consistency across the design system.

The format proposed by Keep a Changelog is easy to use and contains all the essential information. Here's a preview:

# Changelog  

## [Unreleased]

Track here the unreleased changes. 

## [1.0.0] - 2023-05-14 

### Added 

- New blue color- New xs (10px) and xxs (8px) icon sizes

Each release can be divided into three sections, depending on the changes:

• Added, indicates all the new features introduced

• Changed, indicates changes made to existing elements

• Removed, indicates all the elements that have been removed or deprecated

• Fixed, indicates the correction of a bug

The “Unreleased” section could be used to track the unreleased changes.

Keeping a changelog of design token versions can be done manually or using systems like Git, which enables the creation of branches, commits, and tags to track changes to design tokens. By using a version control system, you can easily restore previous versions of design tokens if needed.

---

4. Create a dedicated repository

The design tokens repository from GOV IT Design System

Creating a dedicated repository for design tokens is crucial because it enables more efficient management of the tokens and their versions.

By separating the design tokens from other design system libraries, it becomes simpler to version them separately and guarantee that all users are working with the most recent definition of visual style.

Moreover, a dedicated repository can facilitate monitoring changes and issues to the tokens over time, allowing users to effortlessly restore previous versions if needed.

This also streamlines the management and tracking of changes to the repository, enhancing collaboration and communication across the design team.

---

5. Document changes in the style guide

Release changes documentation — Nord Design System

Lastly, it's crucial to document design token changes, including the reason for the change and its impact on the design system.

Documentation of design token changes should be published in the Design System style guide and it should include the version number, the date of the change, the reason, and its impact on the Design System.

---

In conclusion

To sum up, versioning design tokens is a critical aspect of preserving a consistent and current design system.

By adhering to the five fundamental steps of versioning design tokens, which consist of establishing a clear versioning system, maintaining a record of design token versions, utilizing a tool to manage design tokens, testing design tokens prior to release, and documenting design token alterations, you can guarantee that your design system is consistent and up-to-date for all users.

---

Did you know?
I just launched Design Tokens Manager 🚀

Design Tokens Manager is a Notion template for design tokens management. It provides categories, properties, and modifiers, building names in an automated way.