Tier 1
low risk
- Examples
- Docs, story fixes, a11y fixes with no visual change, lint fixes, a token description edit (no value change)
- PR state
- Ready for review
- Required approvals
- 1 code owner
- Changeset
patchor none (docs only)
Governance
Same gates for every change, whoever writes it. The riskier the change, the more review it gets.
Who approves what
Risk tiers, from docs/GOVERNANCE.md. If a change spans tiers, the highest one applies.
Tier 2
medium risk
- Examples
- New component, new variant or prop, visual tweak using existing tokens
- PR state
- Draft until design review
- Required approvals
- Design owner + tech owner
- Changeset
minor
Tier 3
high risk
- Examples
- Token added, changed, renamed or removed; breaking prop change; guardrail or
AGENTS.mdchange - PR state
- Draft, labelled
tokensorbreaking - Required approvals
- Design owner and tech owner, mandatory
- Changeset
minor(added or changed token) ormajor(renamed or removed token)
By area
| Area | Design owner | Tech owner |
|---|---|---|
| Token values and names | Approves | Approves |
| Component visuals, states, a11y | Approves | Reviews |
| Component API, types, build | Reviews | Approves |
CI, lint rules, AGENTS.md | Approves | Approves |
How a token change travels
From an idea in Figma to updated docs, in eight steps. Nothing skips a step.
-
Step 1
Explore in Figma
A designer tries the change on real screens. Nothing in Figma reaches the product by itself.
-
Step 2
Propose with Bridge
The DS Bridge Figma plugin, or Edit mode in the token explorer, turns the proposal into a pull request against the token files. An issue works too; then the AI agent or a maintainer writes the pull request.
-
Step 3
Pull request
The change is a diff on a branch, with a risk tier, a changelog entry and a note on what to review.
-
Step 4
CI guardrails
Automated checks run on every pull request: tokens build, types check, no raw colors or shadows in components, Storybook builds, a changelog entry exists.
-
Step 5
Design and tech review
The design owner checks both themes, contrast and keyboard focus in Storybook, and reads token diffs in Bridge Reviews. The tech owner checks naming, API and version bump. Token changes need both.
-
Step 6
Merge
A person who owns that area merges. The AI agent never merges.
-
Step 7
Release
Changesets bumps the version and writes the changelog from the entries collected in each pull request.
-
Step 8
Docs update themselves
This site rebuilds from the repo: color tables, contrast checks, component pages, the changelog and llms.txt all reflect the change. Figma variables are re-imported from the same files.
The review gates, as written for reviewers
- 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: by a human code owner. 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.
How the AI agent is constrained
The agent reads AGENTS.md before every task. Here are its rules in plain language; expand a rule to see the exact wording it
follows. Rules marked "original wording" changed recently and have no plain-language version yet.
Always 7
Things the agent does on every change.
-
Works on its own branch, one topic at a time, so every change can be reviewed on its own.
Exact rule
Work on a branch named
agent/<short-topic>. One concern per PR. -
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. (original wording) -
Use the space, size, radius, type and motion scales. If a value is missing, stop and ask. (original wording)
-
Accessible by default: native elements or Base UI parts, visible focus, labels wired, color never the only signal. (original wording)
-
Write UI copy in the Bridge voice: sentence case, verbs on buttons, errors that say how to fix. No em dashes. (original wording)
-
Writes a changelog entry and says how big the change is (patch, minor, major).
Exact rule
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.
Exact rule
Fill the PR template, including the risk tier, and say the change is agent-authored.
Ask before 5
The agent stops and asks a person first, and the pull request gets the higher review tier.
-
Adding, renaming or removing a token. Design and tech owners both have to approve.
Exact rule
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.
Exact rule
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.
Exact rule
Changing a public prop name, default or type (breaking change,
major). -
Adding a third-party library.
Exact rule
Adding a dependency, or upgrading
@base-ui/react. -
Changing the safety checks, the CI setup, its own instructions or the governance rules.
Exact rule
Touching
.stylelintrc.json,.github/,AGENTS.md,CLAUDE.md,docs/GOVERNANCE.mdorcontrast.checks.json.
Never 6
Hard limits. Most are also blocked by CI, so breaking them fails the build.
-
Types a raw color or shadow value into a component. The CI check rejects it anyway.
Exact rule
Never write hex,
rgb(), named colors, rawbox-shadow,px/remlengths,ms/sdurations,cubic-bezier()or raw z-index values in component CSS. -
Switches off or weakens a check to make it pass.
Exact rule
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.
Exact rule
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.
Exact rule
Never edit
packages/tokens/dist/: it is generated. -
Copies values from Figma into code. Figma is for exploring; the token files decide.
Exact rule
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.
Exact rule
Never merge, push to
main, or publish. Humans merge.
What reviewers check on 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 indist/tokens.cssrenders 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.