Branching Workflow

What is a branch?

A branch is an isolated copy of your design system's current token values. Every edit you make on a branch — renaming a token, changing a color, adjusting spacing — is completely separate from your main design system until you merge it.

Branches exist only on the ReframeUI platform. They do not correspond to Git branches in your codebase until you choose to merge and publish a new version.

How branches map to pull requests

When you merge a branch in ReframeUI, the platform creates a new version of your design system. If you have GitHub integration enabled, a pull request is automatically opened in your connected repository with the updated token package.

This means the review process for a token change looks the same as any other code change: a diff in GitHub, CI checks running, and a merge by a reviewer.

Creating a branch via CLI

From a directory with a reframe.config.ts file, run:

reframe branch create feature/new-brand-colors

This creates the branch and switches your local session to it. Subsequent reframe push calls will send token changes to this branch instead of main.

You can also create a branch from the Studio UI by navigating to your project's Branches page and clicking New Branch.

Merging a branch

To merge a branch via CLI:

reframe merge feature/new-brand-colors

Before merging, ReframeUI performs a conflict check. A conflict occurs when the same token was modified on both the branch and main since the branch was created. You will be prompted to resolve each conflict by choosing which value to keep.

You can also merge from the Studio UI: go to Branches, click Merge next to the branch, resolve any conflicts in the UI, and confirm.

After a successful merge, the branch is deleted automatically. The merged tokens become the new main state but are not published as a new version until you run reframe publish. See Publishing for the full publish lifecycle.

Branch protection

On the Team plan, project owners can require that all changes to main go through a branch. With protection enabled:

• •Direct pushes to main are blocked for all roles except owner.
• •Merges require at least one approval from another team member.
• •The merge log in Studio tracks who approved and when.

Enable protection under Project Settings > Branches.

Listing branches

reframe branch list

This prints all active branches with their token change counts and who created them.

To learn how to gate merges behind a required approval, see Branch Review and Approval.