Branches and Versions in Figma: How to Test Changes Without Breaking the Main File
Figma branches let you experiment in a copy of the file and merge it back later, and version history lets you restore. Plans, workflow, and limits.
What are branches and version history?
If you don’t know the tool well yet, the Figma entry in this wiki covers the basics. A branch is a working copy of the main file. When you create one, you can change components, reorganize screens, or try a new structure without the team seeing the change. The main file remains the single source of truth, and branches work as spaces for exploration.
Figma presents branches as exploratory spaces that let designers try new ideas without changing the main file (Figma, “How (and why) we built branching”). Version history, meanwhile, is the file’s record over time: Figma creates an automatic checkpoint every 30 minutes and lets you name versions and add a description (Figma Help, “View a file’s version history”). On Starter and drafts, history goes back up to 30 days.
Why should a designer care?
Because a shared design file is fragile. Someone moves a library component and breaks another team’s screen. Someone experiments in the main file and doesn’t know how to go back. Branches and history separate the experiment from the stable version and give you a way back.
They also order the review. A branch reviewed by another person, with visible changes and a recorded merge, is easier to defend than a series of direct edits nobody remembers.
What does the workflow look like?
A practical flow, based on Figma’s guide to branching:
- Create the branch from the main file, with a name that says what you’re testing.
- Work in the branch without touching the original file. You can share it so another person can see it.
- Update the branch when the main file changes, so you don’t work on something outdated.
- Request a review. A reviewer approves or asks for changes.
- Merge. Whoever has edit access to the main file completes the merge.
Figma creates checkpoints in version history when a branch is created and when it is merged, and adds an extra one right before merging, so you can review that activity later. If a merge goes wrong, you can undo it by restoring an earlier version of the branch or the main file (Figma Help, “Guide to branching”; Figma Help, “Merge branch into main file”).
Which plans and limits apply?
Figma’s official help says the feature is available on Organization, Enterprise, Government, and K-12 education plans. Creating a branch requires a Full seat and view or edit access to the main file. Requesting a review requires edit access to the branch and view access to the main file (Figma Help, “Request a branch review”). Plans change, so if your team depends on this feature, confirm availability in Figma’s help before planning around it.
Limits worth knowing:
- Updating from the main file isn’t selective. According to Figma’s help, you can’t choose which changes to apply. What comes in, comes in whole.
- You can’t branch from a branch. Figma left it out on purpose to keep the feature simple (Figma, “How (and why) we built branching”).
- Memory limits block review. If the file has an active memory-limit banner, you can’t review or merge until usage goes down.
- Anyone without edit access can’t merge. They have to ask someone who has it.
What happens when you restore a version?
Restoring an earlier version doesn’t delete anything. Figma adds two checkpoints: one with the current state, before restoring, and one with the restored version. Comments from all versions are kept, though ones that were already deleted don’t come back. This lets you experiment with history: if you restore and don’t like the result, you can go back to the previous state. What you can’t do is erase checkpoints; you can remove the name and description of a version, and that can’t be undone. Creating, naming, deleting, or restoring versions requires edit access to the file (Figma Help, “View a file’s version history”).
Example
Illustrative example: a team wants to redesign the navigation of its product, which uses 40 components from the library. Instead of touching the main file, it creates a branch called “nav-v2”. It works there for three days, updates the branch twice when the library changes, and asks the design systems lead for a review. The review flags three components that break focus accessibility. They are fixed in the branch, merged, and the history shows the creation and merge checkpoints. If the launch goes wrong, the team can restore the earlier version without losing the redesign.
When NOT to use branches
- For small text changes. A branch to change one label is bureaucracy. Edit directly and leave a record with a named version.
- If nobody is going to review. A branch without review is just another copy. Decide who approves before you create it.
- When the file is overloaded. If the file has a memory limit, reduce its size first.
- As a substitute for communication. A branch doesn’t replace a conversation with whoever maintains the library.
Common mistakes
- Creating branches and never updating them, so changes get merged onto an old base.
- Merging without a review.
- Using generic names like “test 2”.
- Editing the main file while a branch is open on the same components.
- Not naming important versions, such as the handoff to development.
How to start tomorrow
Pick a pending change in your team’s library. Create a branch with a name that says what changes, and spend a session working in it. Ask someone on your design systems team for a review. Before merging, save a named version of the main file. After the merge, note in the design documentation what changed and why. If the change affects components other teams use, coordinate with the development team before publishing it.