All Collections
Pro Tips
Using Sketch Libraries with Versions
Using Sketch Libraries with Versions

Versioning your Sketch files and libraries with Sympli Versions

Maria Merkulova avatar
Written by Maria Merkulova
Updated over a week ago

Sketch Libraries play a crucial part in design collaboration workflows across teams of all sizes and shapes: they enable designers to share styles and symbols with their colleagues to avoid building the same thing over and over again, to speed up the whole design process, and make room for everyone to participate. What a huge win for all teams!

But with great power comes great responsibility: with library files, it's more important than ever to keep them up to-date and available to all collaborators on a project. That's where your team can benefit from using Versions to manage your project files and libraries — it's a missing connector that propagates your design changes to everyone on your team and thus removing the hassle of the error-prone process of manually updating designs and libraries.

Versions supports and empowers all kinds of design workflows. Below, you can find a Q&A section that contains answers to the most common questions about collaborating on libraries in Versions we received from the community.

If you still have trouble integrating Versions into your workflow — don't hesitate to drop us an email at and we'll be glad to figure it out together!

How do we link libraries to the design files?

The same way you would do without Versions: open Preferences > Libraries in Sketch and use the "Add Library…" button.

  • Note: Versions will help you to link libraries automatically in the future so you can avoid manual work and eliminate mistakes. Please stay tuned!

How should we organize our library files? Does it make sense to keep them in a different project?

Whether or not to put your library files in a separate project depends on your team’s existing workflows and preferences.

If you're into Design Systems, then it's a good idea to make your libraries shareable across all your projects (say, iOS and Android application mockups) — i.e. to create a separate project in Versions just for those libraries. This way you can coordinate library updates and make sure that all of your designs are consistent across the whole company.

But if you don't share components/styles between multiple projects (say, your iOS components are no good in Web mockups) then it probably makes sense to keep your designs and libraries together in the same project so they stay in sync even if you switch branches back and forth often.

We keep our library files outside of the Versions project we're currently working on (either in a separate Versions project or not under Versions' control at all). How do we go about updating our design components from such libraries?

The rule of thumb here is:

You should always update your design components (library symbols, styles, etc) in the "Main" branch of your project and then propagate them to other branches you might have via the "Pull from Main" option. This way you'll avoid potential merge conflicts during the final merge into "Main".

To illustrate this rule, let's assume you're working on "The Project" that uses components from "The Library". One of your colleagues prefers to commit their changes directly to "Main" while you have your own branch "WIP" (created off "Main" some time ago) that you’re going to eventually merge back into "Main" when you're done with your changes.

💡 The key here is that both branches are under active development at the same time.

While you both work in your respective branches, "The Library" gets updated and some of your components are now out of date with this library. You want to update them to match the latest library revision.

To avoid introducing potential merge conflicts in the future, here's how you'd do it:

  1. Ask your colleague that works in the "Main" branch to

    1. Press the "Component Updates Available" button in the and update the desired components to their latest version

    2. Open and commit these changes.

  2. Now the "Main" branch of your project uses the up-to-date library components. To incorporate them into your "WIP" branch, use the "Pull from Main" option and merge your colleague's changes from Step 1 into your branch (solving conflicts between your other conflicting changes if needed).

  3. That's it. Now you have the up-to-date versions of the library components and won't have any merge conflicts around them in the future when you decide to merge your branch back into "Main".

Regarding the previous question: what if we’ve already introduced unwanted merge conflicts by updating our library components in multiple branches at the same time?

Unfortunately, there’s no other option at the moment other than going through all of these conflicts one by one and resolving them using the most recent revision of the conflicting components. In general, both “Main” and “branch” revisions presented on the conflicts resolution screen should be the same but beware that in some cases they’ll differ (e.g. when one of the branches was updated multiple times while the other one was updated just once — so the components revisions don’t match).

  • Note: We’re currently investigating solutions that would prevent such merge conflicts during component updates in the first place. In future updates, Versions will be able to resolve such cases automatically and you won’t see any conflicts to solve.

Given that we keep our libraries in a separate project, what are the best practices for making changes and experiments in those libraries?

It's always a good idea to see how your components fit into their context, especially if you're still playing around and making quick changes to a library.

Let's assume that you already have a components library and a design file that incorporates those components in a different project. Now you want to enter a "playground mode" and make changes to the library components to see how they look in the context of the actual design.

Here are your steps:

  1. Create a branch in the library project. Say, a branch named "WIP".

  2. Open your library in Sketch and make some changes to its components. You don't have to commit those changes yet!

  3. Now open your design file in Sketch and press the "Library Updates Available" badge to incorporate the library changes you've just made.

  4. See how it looks and adjust the design and/or the library if needed. Basically, you repeat steps 2-3 until you're happy with the results.

  5. Now it's time to commit! Start with the library:

    1. Commit your changes to the "WIP" branch of the library project.

    2. Press "Merge to Main" to update the Main branch with your changes. Resolve all conflicts (if any) and switch to the Main branch at the end.

    3. (Optional) You can delete the "WIP" branch or keep it to continue experiments later — you decide.

  6. Return to the design file and press the "Library Updates Available" badge once again if the badge is here (it may not appear if there were no merge conflicts during the previous step — it's totally fine, just move on to the next step).

  7. And finally, commit your changes to the design project as usual. If you've been working in a branch, make sure to merge it into Main when you're done with the changes.

Why do we need to be careful with our workflows around Sketch libraries?

When dealing with designs and libraries in different projects, the major obstacle is synchronization overhead.

It's easy to overlook the problem when you only work in Main but as soon as you start branching out, you'll notice that keeping your library branch in sync with the design branch is a lot of brain work.

And if you don't pay enough attention to what's going on in your projects, you may end up in a situation where your Main design starts referencing components that only exist in your own private branch of the library project (and thus will be overwritten by your coworkers in the most unexpected way anytime soon).

  • Note: In future updates, Versions will help you to prevent and get out of such situations without losing any of your progress. But currently, we recommend you stick to the safe "playground" workflow described above to avoid synchronization issues that may arise.

Did this answer your question?