Overview
Branching allows multiple strands of design exploration to coincide while maintaining a transparent master file.
Any Figma file can be branched.
Branches act as separate files, which allows non-destructive changes and safe exploration. Branch files can be moved or archived later if required.
When to create a branch
All active design work should be conducted in a branch, regardless of the change’s size or scope.
Branches should be merged back into the master file as soon as the work is in a usable state.
Multiple branches can be open at the same time, but branches should not remain open longer than necessary.
Avoid mixing unrelated work in a single branch, as this makes the content more complicated to understand and review.
Common use cases
Branching is proper when:
- Working on a new project based on a master file
- Suggesting a bug fix to a file or component
- Exploring alternatives for a piece of work or a component
- Creating a leaner prototype file from a larger master file
Branching quick start
- Create a branch from the file that requires changes
- Make the necessary changes in the branch
- When working with components, update existing components and avoid deleting and recreating components
- Share the branch for feedback
- Request a review from at least two peers using Figma’s branch review feature
- Once both reviewers approve, merge the branch back into master
- Save 💾 the branch in version history with clear notes as a milestone
- Make sure documentation is updated to match any component or pattern changes
Merging — how and when
In an ideal workflow, branches are merged when the related work is live and available to customers.
In practice, design work is often completed before development or may undergo several rounds of refinement.
Jane Doe is working on a new modal to announce a feature being added to the application. The design has been agreed on and all the screens are in place, but there’s some back and forth on copy and illustration work that may need tweaking. It has been decided that this can wait for now, as development has been pushed back to the next quarter for unrelated reasons.
Emoji markers in files should be used to show the status of work, for example, exploration versus published.
Content should be merged once it is in a clear, consumable state, with a new branch created later if further refinement is required.
Sharing branches
When a branch is ready for wider input, sharing options include:
- Please post it in #team-ux-show-and-share or present it in the following UX review
- Branches can be shared like any other Figma file or shared using the built-in review request.
- If sharing in a group, include short notes explaining the change
Peer-Reviews
No branch should be merged into the master file without peer review from at least two UX designers.
Within Figma, the review request feature can be used to:
- Add notes that summarise the work and its intent
- Invite specific team members to review the branch
Peer reviews are not for debating design choices, unless a design conflicts with component standards or conventions.
Their purpose is to maintain quality and consistency across the system. The checklist guidelines can be used as a point of reference when conducting a peer review.
Reviews and Comments
Use Figma comments to provide feedback. Follow the commenting guidelines to ensure feedback is clear, constructive, and easy to act on.
Approving Branches
When a branch is received for review, the reviewer should:
- Read the context and any supporting notes
- Check the file against the review checklist and relevant guidelines
Figma allows reviewers to approve the branch or suggest changes with supporting comments. Two approvals are required before a branch can be merged.
If the branch includes changes to a component, any related documentation must be updated to match the change.
Merging & Saving
After the required approvals have been received, the branch can be merged into the master file.
Use the Merge branch option in Figma. If Figma shows conflicts, these must be reviewed and resolved manually.
Once the merge is complete, the master file can be reopened and checked.
Although Figma adds a marker to the version history, it is best practice to create an additional manual save point with clear notes to explain the milestone.
Official Figma Branching Links