Changes & governance

The token editor is govern-first: opening a project always lands you in read-only browse mode. Every edit — big or small — happens inside a named Change, so nothing gets modified by accident and every edit carries a reason from the moment it's made.

What is a Change?#

A Change is the primary editing object in the Studio. When you open a project, the whole token system is visible but read-only — you can browse every token, but the detail form stays locked until you deliberately start a Change.

Click Start a change in the topbar, or from the read-only inspector card on any token. You'll be asked for three things:

Submitting the form creates a working branch and switches you into it — the detail form unlocks and editing begins. Under the hood, a Change is 1:1 with a branch: starting a change always creates a new branch, and the change's name and intent are exactly the branch's name and description.

The Change Bar#

While a change is active, a Change Bar docks at the bottom of the editor. It keeps the two things you need mid-edit — what changed, and whether it's safe to ship — always in view:

The gate is read from GET /v1/projects/:id/branches/:branchId/a11y-gate, which evaluates every tagged foreground/background contrast pair in the project against the branch's current token values — at WCAG AA, or AAA if the project's accessibility enforcement level is set to AAA. It runs even when enforcement is set to off: the gate is an always-on signal on the Change Bar, independent of whether the organisation has turned on blocking enforcement elsewhere.

{
  "passed": false,
  "totalPairs": 12,
  "failingPairs": [
    {
      "pairId": "018fde70-…",
      "foregroundTokenId": "018fde70-…",
      "backgroundTokenId": "018fde70-…",
      "foregroundName": "color/text-muted",
      "backgroundName": "color/surface",
      "ratio": 3.1,
      "required": 4.5
    }
  ]
}

A failing gate only blocks review — editing stays free. Fix the failing pairs, or point them at compliant tokens, and the badge clears on its own.

How it composes with branches#

Clicking Request review opens the token-request form prefilled with the change's name as the request title, and its intent shown alongside as read-only context for the reviewer. Submitting ends the change and returns the editor to main — from there, review and merge follow the same token-request lifecycle described in Branches & reviews.

A change survives reloads: it's persisted client-side, so reopening the project drops you straight back into whatever change you were working on, on the same branch, with the Change Bar already docked.

Governance controls#

Beyond the editor's browse-mode gate, governance is enforced server-side per project. Everything below lives in the project's Protection settings (org admins only) and applies to every client — Studio, CLI, Figma plugin, and API alike.

The one exemption: the first import into an empty main is always allowed, so onboarding can seed a brand-new protected project before any governance is relevant.

The audit trail#

Every governance-relevant action is recorded as an event and readable at GET /v1/projects/:id/governance/events?page=&pageSize= — newest first, with the actor, branch, and detail attached. The same feed is shown in the Studio under the project rail's Activity page.