Branching in Figma

As designers, we need open, collaborative workspaces that give us the freedom to explore and iterate without disturbing existing work. Now, with branching in Figma, you can have both. Branches are exploratory spaces that enable designers to safely try new ideas without making changes to the main, or existing, file. Rather than auto-saving to the main file, changes from branches are merged into the main file when you're ready.

This guide will cover some helpful tips, and highlight considerations for when branching may (or may not!) be appropriate in your individual or team workflow.

When to consider branching

A branch is most useful when you're starting individual work that's derived from an existing source, mainly if it's experimental or iterative in nature. Here, we'll look at some common use cases where you may want to consider creating a branch from an existing design file.

Maintaining and contributing to a design library

Branches can be helpful for those tasked with maintaining asset libraries and those interested in contributing to them. Those who support and maintain asset libraries can have peace of mind knowing that the main file is the published source of truth, while branches can be used to explore:

• Adding or modifying shared styles
• Modifying existing components and Variants
• Creating new components for a library

Using a branch can help alleviate confusion around which components are approved for use, have an existing code counterpart, or are still in an exploratory phase. If your teams regularly view the main file to read accompanying documentation or use it as a sticker sheet, making updates in a branch ensures the main file always has the most up-to-date assets and information.

Branches can also be used to facilitate design contributions to your library, allowing non-editors of the library file to create a branch for exploring their proposal and open a conversation with maintainers to contribute the change back much like a pull request in code. This means less detaching of components, redesigning and sharing files, and manually having an editor copy and paste the changes into the library.

Sharing with collaborators and stakeholders

When starting work on a new feature or additional steps in a flow, using a branch will give you a snapshot of the current experience where you can quickly begin to iterate. When you're ready to collaborate or share progress and get feedback from stakeholders, you can share a file or prototype link directly to the branch. That way, collaborators can view, comment, or edit within the branch without affecting the main file, and all comments will be preserved in context with the branch when it's merged and/or archived.

Freezing feature work for development handoff

In addition to sharing with stakeholders, sharing feature work completed in a branch with development partners gives them a clear view of any new assets and design work that has been completed and is ready to be built. Collaborators can have a back-and-forth conversation within the branch as the feature is being built, and when it's complete, there is an easily accessible and visible place to QA the build against the design.

You can merge the branch to your main file when everything looks good, while the feature also gets added on the code side. This establishes a similar workflow between design and development and can help create cohesion around a shared language from conceptualization to release.

Isolated design experiments and user testing

Branches allow you to test prototypes of derivative design explorations, so you can get valuable insights earlier in the design process. For example, if you're working on a purchase flow, you may want to compare the current flow with an alternate layout or copy.

You can generate a prototype link from your current design while creating a branch to prototype the variation(s) and get sharing links for each exploration. You can then test each of the designs using the sharing links, and if an alternate version performs best, leave it as a branch to share with developers to build and merge it to become the new main file. If the current flow continues to perform best, you can archive the test branches to be referenced later while keeping your main file as it was.

Best practices when using branches

Naming your branches

Once you've decided to use branching, one thing to consider is naming your branches to clearly communicate what they contain or address. A common practice in development where branching is used with code repositories is to prefix the branch name with something to quickly identify it. This could be a ticket number, type of work, emoji status, or similar:

• UX-5141: Redesign login screen
• 🔥 Layout fix for payment info
• [contrib] - Propose a new design for tabs

If you don’t have a current naming convention for design work, one thing that I like to recommend is talking with your development partners to see what type of conventions they use. If there's an opportunity to align and use the same conventions, it can help streamline communication across the entire process!

Requesting a review on a branch

If you're an editor in the organization, you can create a branch on any file that you have view or edit access to. If you're a viewer on the file—say a design system asset library in another team—you will not be able to merge the branch directly and will need to request a review from an editor of the file. There are two ways to get feedback from the editors of the file, either via comments as you're working in a branch or using the description field when you request a review.

If you're looking for feedback while making edits in your branch, we recommend tagging an editor in a comment as you're working. This will send them a notification, and they can switch to your branch to view in-progress changes, leaving additional comments as the work is being completed.

Once you have finished your exploration and are ready to have it merged, you can easily request a review from the editor(s) of the main file. The review window will automatically recommend some editors of the main file, and you can specify others to include in the review as well.

When requesting a review you’ll want to give as much context as possible. Be sure to fill out the description field with the details of your proposal or issue being solved to help the editors of the file know what they are reviewing in your contribution. This is similar to how a PR request is made in the engineering process and a great opportunity for process alignment!

Merging branches

When you want to apply your changes to the main file, you can merge the branch. If you're an editor on the main file, you can initiate the merge to review any changes from main in the branch and resolve any conflicts that may appear.

After a branch has been merged into the main file, it's automatically archived along with all comments made within it and can no longer be restored. If you need to undo a merge, you can restore a previous version of the file from the version history.

Manually archiving branches

When you have designs in a branch that you’ve decided not to move forward with right now, you may want to archive it in case you or your team want to come back to it at a later time. Archived branches will continue to be associated with the main file, and links shared from a branch will continue to work even when archived. If your branches have been archived without being merged into the main one, they can be viewed or restored at any time, making it easy to recover them if you need to revisit an idea.

This saves you from having multiple branches in flux that may be outdate, which causes confusion for others accessing the file. Your archived history of branches will also remain until you manually remove any branches that are no longer needed.

When to consider not using a branch

While branching can be beneficial for collaborative explorations, there are also scenarios in which working in a single file is the way to go.

Creating a new file for exploration

If you're starting from scratch or doing a complete ground-up overhaul on an existing design, it likely makes sense to start with a new file or duplicate an existing file. This keeps all new work completely separate in its own file, which can live in any project, team, or your personal drafts.

Making minor updates to the source of truth

You may want to simply update your main file if you're the only editor, are making minor or time-sensitive updates, or have multiple collaborators all making little polish changes. For example, copy edits, layer organization, updating colors to use shared styles, or wiring up a prototype are often done right in the main file.

Actively referencing alternate designs

When you're exploring multiple concepts or collaborating with others where you may need to actively reference each design, using pages in the same file may be more convenient. By using pages, you can essentially have multiple scratchpads by concept or collaborator, allowing you to quickly jump and move items between the pages.

Keeping the same workflow that you have today

That's totally cool! Working in Figma, you still have automatic saves and version history where you can revert to or duplicate any previous save points to a new file. You can continue to work and collaborate as you do today.

Parting thoughts

We hope that this guide will help you when exploring scenarios and deciding if you should use a branch. While many collaborative component library and feature design workflows can be more seamless using branching, ultimately, the decision to branch or not to branch should align with your organization's collaboration and sharing model.

For additional questions, be sure to check out some branching FAQs and connect with the Figma Community on forum.figma.com.

FAQs

Who is able to create a branch?

Anyone who has editor access at the organization level will be able to create a branch. If an editor only has viewer access to a specific file, they can still create a branch from it but will not be able to merge changes.

Who can access branches?

Anyone who has access to the main branch has the ability to see other branches.

Can you create a branch of a branch?

You can create multiple branches off of the main file, but you can't make a branch of a branch.

What happens if there are changes to main while working in a branch?

Users in the branch will receive a notification (much like a library update) that there have been updates and they can update their file from main.

Can libraries be published from a branch?

It is not currently possible to publish from a branch.

Who can approve and merge changes from a branch?

Merging can only done by those who have editor access on the main file. Viewers who created a branch will need to reach out to an editor to have the branch reviewed and merged.

What happens to comments when a branch is merged and/or archived?

Open and resolved comments stay connected with the branch they were created in and will not merge into the main file. After a branch has merged and archived, you can open the branch to view any comments in it.