How review works

Every change goes through the same gates, whoever writes it: a designer, an engineer or an AI agent. The riskier the change, the more review it gets.

Open in Studio

Risk tiers

The tier decides who approves. If a change spans tiers, the highest one applies, and Bridge computes it the same way in the plugin, the Studio, the CLI and the MCP server.

Tier	Examples	PR state	Required approvals	Changeset
Tier 1, low	Docs, story fixes, a11y fixes with no visual change, lint fixes, a token description edit (no value change)	Ready for review	1 code owner, or none when a lead publishes it (see Tier 1 publish by leads)	`patch` or none (docs only)
Tier 2, medium	New component, new variant or prop, visual tweak using existing tokens	Draft until design review	Design owner + tech owner	`minor`
Tier 3, high	Token added, changed, renamed or removed; breaking prop change; guardrail or `AGENTS.md` change	Draft, labelled `tokens` or `breaking`	Design owner and tech owner, mandatory. A token value change (values changed or tokens added only): design owner only, see BUILD-REQUESTS.md (TV-1)	`minor` (added or changed token) or `major` (renamed or removed token)

How a change travels

8 steps

Explore in Figma
A designer tries the change on real screens. Nothing in Figma reaches the product by itself.
Start an exploration and send it for review
In Studio (Start an exploration, with the library as where) or the DS Bridge Figma plugin, a designer starts a change to the library and sends it for review. For developers: on GitHub that change is a branch off main and a pull request against the token files. An issue works too; then the AI agent or a maintainer writes the pull request.
Pull request
The pull request is a diff with a risk tier, a changelog entry and a note on what to review. Studio shows it as a change with its status: Draft, In review, Approved, waiting for code, Added to the library or Closed.
CI guardrails
Checks run on every pull request: tokens build, types check, no raw colors or shadows in components, Storybook builds, a changelog entry exists.
Design and tech review
The design owner checks both themes, contrast and keyboard focus. The tech owner checks naming, API and version bump. A token rename or removal needs both; a new token value needs the design owner only.
Review and add to the library
A person who owns that area adds the change to the library (on GitHub, merges it into main). The AI agent never does.
Publish
Changesets bumps the version and writes the changelog from the entries collected in each pull request.
Docs update themselves
This site rebuilds from the repo: color tables, contrast checks, component pages, the changelog and llms.txt. Figma variables are re-imported from the same files.

Component change requests

3 steps

Variables are data: a variable edit is a pull request you approve. Components are code: a component change is a request, and a pull request that closes it does the work. Teams triage requests where they plan: in GitHub by the component-change label.

Request
A designer asks for a new component or a change (variant, prop, structure, visual, token binding) from the Push tab of the Figma plugin or from a component in Studio. It becomes a GitHub issue labeled component-change.
Implement
A developer, or Claude with bridge request implement <number> or the bridge_get_request MCP tool, changes the code in a pull request that says Closes #<number>.
Review and add to the library
The pull request goes through the same tiers and gates as any other change. Once it is in the library, the request closes as done.

Suggestions

3 steps

A suggestion is a change filed as an issue instead of a branch, for teams where designers do not write to the code. The tier decides who approves it, as for a branch. Follow them in GitHub by the bridge-suggestion label; Studio lists the ones that wait on you on Home and in the review queue.

Suggest
When the team works in suggestion mode, a designer sends the change from Studio, the Figma plugin or Claude. It becomes a GitHub issue labeled bridge-suggestion: what changes, its checks, and a machine-readable block a developer applies. Nobody needs write access to the code.
Review
Owners decide in Studio (Changes and the review queue) or on GitHub: Approve, Ask for changes or Decline. Only owners listed in bridge.config.json count, and an approval counts for the version they saw: when the suggestion changes, earlier approvals stop counting and Studio says so.
Apply
A developer runs npx bridge apply <number> or asks Claude to "Apply Bridge suggestion #<number>". Bridge checks it again against the library as it is now and stops on a conflict. The pull request says Closes #<number> and goes through the same tiers and gates.

Explorations

3 steps

An exploration tries experimental variables and components in a real product staging branch without touching the library. Follow them in Studio Changes, Explorations, or in GitHub by the exploration label.

Start
From Studio Changes, Explorations, bridge explore start <name> or Claude (bridge_start_exploration): a branch explore/<name> from main and a draft pull request labeled exploration. Token edits and requests filed on it land there, never on main.
Try it in a product staging preview
Every push publishes snapshot packages (npm i @bridge-ds/react@<snapshot>) and per-branch previews: a coded prototype for a user test, a stakeholder demo or an A/B idea on real screens.
Promote or close
It never goes into the library as is: the Exploration not merged as is check fails while the label is on. Send for review removes the label, adds the tier labels and marks it ready, then the usual gates apply. Otherwise, close it.

Review gates

CI must be green: token build, typecheck, Stylelint, Storybook build, changeset present. A red check is never fixed by disabling a rule or deleting a test.
Design review (Tier 2 and 3): open the Storybook preview, check light and dark, check the Accessibility panel, check keyboard focus, compare against the intent in the linked issue.
Tech review: API shape, naming, semver level, no new dependency without reason.
Merge (ship): by a human who holds the ship right (see Roles) and has write access to the repo. Agents do not merge. A listed owner may merge past missing approvals only, with a written reason (see Owner override).
Release: Changesets turns merged changesets into a version bump and CHANGELOG.md. teams expanded. Only when no owner is configured does any approval count. opened it: once the design approval is in, the tech approval counts as given and it ships after the checks. A rename, a removal or code still needs the tech owner (decision TV-1, BUILD-REQUESTS.md). approvals (approvedSuggestionOnGitHub, withSuggestionApprovals), see Suggestions. (overrideReasonProblem).

Owner override

GitHub never lets authors approve their own pull request, so a solo maintainer can never collect a design and a tech approval. The owner override is the audited way through, and it is off unless bridge.config.json turns it on.

Who. @peterbono, with a token that has write access. Agents never use it.
When. Only when approvals are the one thing missing: never while CI fails or runs, after a request for changes, on a draft, or with a merge conflict.
Trail. Bridge posts the reason on the pull request (20 characters or more) before it merges, and History shows it.
GitHub protection still wins. The override changes what Bridge allows, not what GitHub enforces.

Who approves by area

Area	Design owner	Tech owner
Token values (changed or added)	Approves	Not needed (TV-1)
Token names (renamed or removed)	Approves	Approves
Component visuals, states, a11y	Approves	Reviews
Component API, types, build	Reviews	Approves
CI, lint rules, `AGENTS.md`	Approves	Approves

Rules the AI agent follows

The agent reads AGENTS.md before every task. Its rules in plain language; open a rule for its exact wording.

Always 7

On every change.

Works on its own branch, one topic at a time, so every change can be reviewed on its own.
Work on a branch named agent/<short-topic>. One concern per PR.
Uses the named color, shadow and focus tokens (like action/primary/bg), never a raw color value.
Use semantic or component tokens for color, elevation and focus: var(--color-action-primary-bg), never a primitive (--color-orange-500) and never a literal.
Uses the existing spacing, size, corner, type and motion steps. If the value it needs is not in the scale, it stops and asks.
Use the space, size, radius, type and motion scales. If a value is missing, stop and ask.
Keeps components accessible: real HTML buttons and inputs, a visible keyboard focus ring, labels linked to fields, and never color as the only signal.
Accessible by default: native elements or Base UI parts, visible focus, labels wired, color never the only signal.
Writes interface text the Bridge way: sentence case, buttons that start with a verb, errors that say how to fix them, no em dashes.
Write UI copy in the Bridge voice: sentence case, verbs on buttons, errors that say how to fix. No em dashes.
Writes a changelog entry and says how big the change is (patch, minor, major).
Add a changeset. Pick the bump with the rules in .changeset/README.md.
Fills in the review form: risk tier and what reviewers should look at.
Fill the PR template, including the risk tier, and say the change is agent-authored.

Ask before 5

It stops and asks a person first, and the pull request gets the higher tier.

Adding, renaming or removing a token. A rename or a removal needs the design and tech owners; a new token or value needs the design owner only.
Adding, renaming or removing any token (Tier 3, needs design and tech owner approval).
Adding a component, a variant or an option. It opens as a draft for design review first.
Adding a new component or a new variant or prop (Tier 2, open as draft PR).
Changing how an existing component is used in code. That can break product screens, so it is a major release.
Changing a public prop name, default or type (breaking change, major).
Adding a third-party library.
Adding a dependency, or upgrading @base-ui/react.
Changing the safety checks, the CI setup, its own instructions or the governance rules.
Touching .stylelintrc.json, .github/, AGENTS.md, CLAUDE.md, docs/GOVERNANCE.md or contrast.checks.json.

Never 6

Hard limits. Most are also blocked by CI.

Types a raw color or shadow value into a component. The CI check rejects it anyway.
Never write hex, rgb(), named colors, raw box-shadow, px/rem lengths, ms/s durations, cubic-bezier() or raw z-index values in component CSS.
Switches off or weakens a check to make it pass.
Never disable or loosen a lint rule or a contrast pair, add stylelint-disable, or use !important.
Deletes or skips a test or a story to make a check pass.
Never delete or skip tests or stories to make a check pass.
Edits the generated token files by hand. They are rebuilt from the source.
Never edit packages/tokens/dist/: it is generated.
Copies values from Figma into code. Figma is for exploring; the token files decide.
Never treat a Figma file as the source of truth or copy values from it into code. Figma explores; tokens decide.
Merges, ships or publishes. A human always makes that call.
Never merge, push to main, or publish. Humans merge.

Reviewing an agent's pull request

Check the tier. Did the agent under-classify? A "small style fix" that adds a token is Tier 3.
Read the CSS diff, not only the summary. Look for literal values that slipped past lint (for example a spacing value that should be a scale step).
Look for invented tokens. A var(--something) that does not exist in dist/tokens.css renders as nothing. Search the generated CSS for every new variable name.
Open the stories in both themes. Agents often check light only.
Check that nothing was removed to pass CI. Deleted stories, loosened lint config, stylelint-disable.
Ask for the token, do not accept the workaround. If a change needs a value the system does not have, the right outcome is a token proposal, not a hardcoded value.

Updated Nov 11, 2026