Branching a design file
A design branch is a fork of the document you can take an idea as far as it goes in, then compare against the original and merge the parts worth keeping. It works because the document is structured — a semantic merge can combine two edits to the same node when they touched different fields.
Why design files resisted this
Branching is unremarkable in code because a merge tool can reason about text line by line and most edits do not overlap. Design files historically could not: a binary or deeply nested proprietary format offers a merge tool nothing but "these two bytes differ", so the only available resolution is to pick a whole file. Which is why the design version of branching was, for years, duplicating the page and calling it Homepage v3 FINAL.
A structured document changes the input. Two branches that both touched one node can be compared field by field, and if one changed padding while the other changed the text, both changes survive.
What a semantic merge can and cannot do
The rule is narrow and worth knowing exactly, because it is what tells you when to expect a prompt:
- Different nodes, either side — both applied.
- Same node, different fields — both applied.
- Same node, same field, different values — a conflict, and you choose.
- Moved on one side, deleted on the other — a conflict, and you choose.
The lifecycle
A branch is active while it is being worked on, proposed when it is put up for a decision, and then either applied or closed. Proposed, applied, and closed branches are read-only, so the thing being reviewed cannot move underneath the reviewer.
A branch is never the live design. It is not exported and not shared as the published version, which means an unfinished idea cannot escape by accident.
What it changes with an agent
This is the answer to "how do I let an agent try something without risking the file". Not supervision, not smaller instructions — a branch. The agent creates one, works inside it, and Main is untouched the whole time.
It also changes what you can ask for. Three branches, three interpretations of the same brief, compared side by side, is a reasonable request when a branch costs nothing and merging is semantic. On a single mutable document it is not a request at all.
- createBranch — fork the current document
- compareBranch — field-level diff against Main
- proposeBranch — freeze it for review
- applyBranch — merge it in
- closeBranch / reopenBranch — shelve it, or bring it back
Branches and history are different tools
Version history is the timeline of one document: commit points you can compare and roll back to. A branch is a parallel document. Use history when you want to undo what happened; use a branch when you want to find out what would happen.
Questions
Can you branch a design file like code?
Yes, when the document is structured. A branch forks the document, and merging compares it field by field — so two edits to the same node combine cleanly as long as they touched different fields.
What happens when two branches change the same thing?
Only a genuine collision surfaces: the same field on the same node with different values, or a node moved on one side and deleted on the other. Everything else merges without asking.
How do I let an agent experiment safely?
Ask it to create a branch first. Its work is isolated until you apply it, Main is untouched, and closing the branch discards everything with no cleanup.
Published 2026-08-02.