Branches & reviews

Branches give your team a safe space to experiment. All token changes happen on a branch first and reach main only after review — nothing ships without approval.

What is a branch?

A branch is an isolated copy of your project's tokens. When you create a branch, it starts with a snapshot of all tokens from main (or any other branch). You can freely edit, add, and delete tokens without affecting the rest of your team.

Think of it like a layer in Figma — changes on a branch stay on that branch until you choose to merge them.

Creating a branch

In the Studio, click the branch selector in the sidebar and choose New branch. Name it something descriptive (e.g. "rebrand-2025" or "dark-mode-palette") and pick a source branch to copy tokens from. The new branch is immediately ready for editing.

In the Figma plugin, use the branch dropdown at the top of the navigation and tap the+ button to create a branch inline.

Saving snapshots

A commit is a labelled snapshot of all tokens on a branch. Use commits to mark stable checkpoints — before a big change, after you finish a colour scale, or when you want a clear rollback point.

The History tab in the Studio shows a timeline of all commits with their message, date, and token count. You can revert any branch to a previous commit, which replaces all current tokens with the snapshot and records the revert as a new commit for traceability.

Reverting is non-destructive — the revert creates a new commit, so you can always undo the undo.

Token requests

A token request is how you propose merging your branch into main — like a design review but for tokens. Open a request from the Studio or the Figma plugin.

Status	What it means
Open	Your request is waiting for review. Team members can leave comments.
Approved	An admin or designer with review permissions has approved the changes.
Rejected	Changes were declined with comments. Update your branch and re-submit.
Merged	The branch was successfully merged into the target. The request is closed.

Reviewing a request

The request detail page shows a live diff: added tokens (highlighted green), changed tokens (highlighted amber with old and new values), and removed tokens. Colour tokens display swatches so you can visually compare the before and after.

Reviewers with the request:review permission see Approve and Reject buttons. Once approved, any reviewer can click Merge to finalise the change.

Merging and conflict resolution

When you merge a branch, every changed token is copied into the target branch. If a token was modified on both the source and target, the diff view highlights the conflict and lets you pick which value to keep — per token.

The merge conflict UI shows each conflicting token with the source and target values side by side. Choose "Use source" or "Use target" individually, then confirm the merge.

Deleting a branch

Deleting a branch is a soft delete — it is hidden from branch lists but its name still appears in closed token requests so the history stays meaningful. A trash icon chip signals that a branch no longer exists.

Typical workflow

Here is how a designer typically works with branches:

Step	Action
1. Create	Branch from main to start experimenting.
2. Edit	Add, modify, or delete tokens on your branch.
3. Commit	Save a snapshot when you reach a stable point.
4. Review	Open a token request so your team can see the diff.
5. Approve	A reviewer approves the changes.
6. Merge	Click Merge — your tokens are now live on main.
7. Release	Publish a versioned release for developers to pull.

Every role can create branches and open token requests. Only Admins and Designers with the request:review permission can approve, reject, or merge.