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#

The usual way to create a branch in the Studio is Start a change: name the change, state your intent, and pick a base branch. The change name becomes the branch name, and the intent becomes the branch's description — see Changes & governance for the full flow. You can also create a branch directly from the branch selector and choose New branch — either way, opening that branch in the editor still requires an active change before you can edit.

Branch names must be unique within a project — reusing a name returns HTTP 409 BRANCH_NAME_TAKEN, and the Studio's create form validates this before you submit.

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. If the branch came from a change, clicking Request review on the Change Bar opens this same form prefilled with the change's name as the title and its intent shown alongside as context for the reviewer.

Status	What it means
Open	Your request is waiting for review. Team members can leave comments.
Approved	Enough distinct reviewers approved to meet the project’s quorum, and every matching owner rule is satisfied.
Rejected	Changes were declined with comments. A single rejection closes the request — 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 review permissions see Approve and Reject buttons. A request flips to approved only when two conditions are met: the number of distinct approvals reaches the project’s required approvals quorum (1–5, set in Protection settings), and every owner rule matching the request’s changed tokens has an approval from one of its listed owners. Once approved, any reviewer can click Merge to finalise the change.

Owner rules and quorum

Owner rules work like CODEOWNERS for tokens: each rule pairs a path pattern (with * wildcards, e.g. colors/*), an optional tier, and a list of owners. When a request touches tokens matching a rule, at least one of that rule’s owners must be among the approvers — meeting the quorum alone is not enough. Rules are managed by org admins in the project’s Protection settings.

While main is protected, you cannot approve your own request (HTTP 403 SELF_APPROVAL). If ownership can never be satisfied — for example, the only listed owner is the request’s author — an org admin’s approval overrides the ownership requirement, and the override is recorded as an audited ownership_override governance event.

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.

When the target is a protected main, the merge itself is gated: merging requires an approved token request (HTTP 403 REVIEW_REQUIRED otherwise), and the accessibility gate is re-checked at merge time. Org admins retain an emergency path — a direct write to protected main succeeds for an admin but is recorded as an audited hotfix_write governance event, so hotfixes are loud, not silent.

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	Reviewers approve until the quorum is met and matching owner rules are satisfied.
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 review permissions can approve, reject, or merge — and while main is protected, authors cannot approve their own requests.