Version control best practices for design systems

You’ve been there before: you’re working on a design project and your colleague is working on the same project. The client asks for some changes. You tweak things only to find out your colleague has been making updates in another file. At this point, there are many versions of the same design, and nobody can decide which one is final.

This is where version control comes in, which can make this process a lot easier.

A typical version control system will have a main file and work on a push/pull workflow. This lets you check out the file (pull) to make changes and then merge your changes into the main file (push). You can also add a description of your changes to help others understand what you’ve done. To manage this process, a person or group is in charge of the file so they can review the change requests. They will either accept the changes or suggest some improvements.

Developers are used to version control: if you’ve used GitHub before, then you’ll have experienced version control. The main file you work on is the code project folder, which contains all the files you need to make your app.


The Node.js repository on GitHub showing the main branch’s files

GitHub makes use of “branches” in the workflow, where you can create variations of the main file. For example, you could have a branch where you’re building a new navigation bar named “new-nav.” Your colleague might have another branch for fixing an important bug named “bug-fix.” When you’re happy with the feature, you can merge your branch back into the main one. If there are no conflicts with your work, your colleague can also merge the bug fixes into the main branch. Everything is up to date all the time.

Without version control, developers wouldn’t be able to simultaneously collaborate on the same project. It makes you wonder how design has gone this long without it. Are design systems the key to introducing version control to design?

Version control and your design system

A design system version control process looks like this:

  1. You sync the most recent design system version.
  2. You test a component against an accessibility guideline.
  3. You notice some text does not have enough contrast.
  4. You change the color and size of the text to meet the contrast ratio.
  5. You submit the changes to the owner of the design system with a description of what you updated.
  6. The owner of the design system accepts the changes (or requests improvements).

Once these steps have been completed, the new version of the design system will be available for everyone. Conflicting designs become less of an issue when practicing version control like this. Everybody has access to the latest design system.

Why do design systems need version control?

Version management needs practicing in the design system to ensure updated components don’t clash. For example, if a designer changes the look of a button in one component but not across the entire design system it will look odd in the interface.

Version updates can either be major, minor, or patches. Major updates involve changes that create conflicts or “break” prior elements of the design system. Minor changes update prior elements of the design system. Patches are small updates that tweak the design system. Here are some examples of the different types of updates:

  • Major: a large-scale redesign involving changes to all previous components and design tokens.
  • Minor: updating a modal component to look different.
  • Patch: changing a design token (e.g. complimentary text color) to be more accessible.

Encouraging collaboration with version control

Design systems should be collaborative environments. 

  • Designers can create components and global design tokens. 
  • Developers can reference the system when building to make sure they have the right specifications. 
  • Writers can edit copy in certain components and instances to perfect the tone. 
  • Product managers can have oversight of how the product should look now and in the future.

For asynchronous teams, being able to collaborate seamlessly is critical. When anyone working on or with a design system can make changes and explain their reasoning for easy, effective collaboration.

The role of a well-maintained design system is to ensure consistency. If you’re not regularly practicing version control, your design system could become useless.

With many designers now able to collaborate with little fuss, the scalability of your design system improves. Your team can worry about larger problems like improving how to improve accessibility and upgrade your product. 

How version control helps guarantee good UX

The role of a well-maintained design system is to ensure consistency. If you’re not regularly practicing version control, your design system could become useless.

Design systems are often implemented as a way to remove or reduce inconsistencies within a product. If you have two designers working on the same button or footer without practicing version control, you’ll continue to find design inconsistencies throughout your product. When developers work with these different versions of the design system, they’ll build mismatched experiences—which is the exact opposite of great UX.

Prevent re-work with version control

Without version control, you’re playing Russian roulette with your files. If you’re guilty of “finalversion_1,” “final_finalversion,” “final_final_12,” version control can keep you and your team from losing up-to-date work.

You might have many versions on your desktop and overwrite the wrong one. All that hard work, time, and effort are gone and you have to recreate your changes again. This can be frustrating and there is no guarantee you will remember everything you did.

A key improvement you’d get with version control would be the ability to roll back to a previous version. For example, you release a  redesign of your application, but testers uncover usability issues in some areas. Before developers start their update, you roll back to the previous version and can correct the problems. Then you can merge them with the main version again.

Lost work is especially costly when you involve an agency. If you are using an agency to develop an interface but you send an out-of-date design system, they’ll build a useless product. You’ll have to pay for more hours of their time to fix the problem you created.

Inconsistencies and lost work are in the past when you practice version control, as you could have a single point of truth for the final version. If everybody is working from the same design, there would be no confusion about which to put in place. Iterative improvements rely on good feedback, but if there is no central source of truth for finalized design and development elements, it can get lost. But, when your design system is a central source of truth, stakeholders can leave feedback in the design. This speeds up your ability to recognize and resolve these comments.


Versioning of your project files is crucial for any effective team, regardless of whether you are a designer or a developer. Lost and inconsistent work can not only cost you time, effort, and motivation but reputation and money too.

Developers are already used to a version-controlled world where they only have to rely on one point of reference. Aligning design with this workflow makes sense and improves communication and efficiency.

Get started

See how Knapsack helps you reach your design system goals.

Get started

See how Knapsack makes design system management easy.