Governance

How Syntara changes: who decides, how a request gets in, and how something gets out again without breaking the products that use it. The full text is GOVERNANCE.md.

Decision records

Every choice with a design trade-off gets an architecture decision record: context, decision, alternatives, consequences — one page each. Each one names who made the call: Anuj, or Claude’s recommendation that Anuj accepted or hasn’t reviewed yet.

How a change gets in

1. Issue: describe the need, with the screen it’s for.
2. RFC, when one is needed: the proposal, the alternatives, and what it costs every tenant.
3. Design review: a designer signs off on the API, states and tokens.
4. Build: component, meta.json, examples and tests together.
5. Docs: the component page is generated from meta.json, so docs ship with the code.
6. Release: a changeset describes the change for consumers; Changesets versions and writes the changelog.

An RFC is needed for a new component, a breaking change, a deprecation, or a change to what the theme engine guarantees. A fix, a new prop that fits a component’s purpose, or a docs change doesn’t need one.

Extend, vary, add or override

A request ends in one of four outcomes, cheapest first:

• Extend an existing component — a new prop that fits its purpose.
• Add a variant — same component, a new visual style every tenant can use.
• Add a component — a new job no existing component does. Needs an RFC.
• Local override — a one-off in the product, not the system.

Versioning and deprecation

Packages follow semver through Changesets.

1. Deprecate in a minor release. The old API keeps working and renders exactly as before.
2. Remove in the next major release.
3. Before 1.0, semver lets a minor release break things. Syntara doesn’t use that: a deprecated API keeps working through every 0.x release and is removed at 1.0.0.
4. Every breaking change ships with a codemod. A codemod rewrites what it can be sure of and reports the rest with file and line. It never guesses.
5. Alpha components are exempt. Beta and stable components change only through this policy.

Removing or renaming a component, prop, value or token is breaking. So is changing a default, or a data-* attribute that a consumer could target in CSS.

What a deprecation includes

The first one

Button was the only component that put a status in variant; every other component uses tone. So variant="danger" became tone="danger", which also works on outline and ghost buttons. See it on the Button page.

// Deprecated in 0.2.0, removed in 1.0.0
<Button variant="danger">Delete card</Button>

// Use this instead
<Button tone="danger">Delete card</Button>

npx @syntara/codemods button-variant-danger-to-tone src

The brief named the new value critical. It became danger because twelve components and the feedback.danger.* tokens already say danger (ADR-021).

Maturity

Every component page shows a maturity badge: alpha, beta or stable. The badge is a claim about the component, and each claim has written criteria. pnpm check:meta checks every criterion a script can check and fails the build when a beta or stable component misses one. The rest are browser checks or a dated review recorded in the component’s meta.json. Every level needs everything from the level below it.

Alpha: new, and the API may change

The API can change in any release, without a deprecation.

Alpha is the floor, so a component that misses an alpha criterion stays alpha. pnpm check:meta prints each gap as a note on every run until someone closes it.

Beta: used in a real screen

The API changes only through a deprecation: deprecate in a minor release, remove in the next major, with a codemod (see Versioning and deprecation above).

Stable: frozen under semver

The API only breaks in a major release.

Why the manual review sits at stable

Axe and keyboard tests are automated, so they’re part of alpha. No person has run a screen-reader review on any component yet. Requiring one for beta would make every component alpha, and recording one from an automated run would be false. So beta rests on the automated checks and real use in a screen, and stable adds the manual review. review.a11y stays empty until a review actually happens.

Agent trust levels

AI agents change code too, so how much they may do alone depends on how far a change reaches and how easily it’s undone (ADR-008):

Not enforced yet: CODEOWNERS, branch protection and the drift auditor arrive with the MCP server. Until then this is a working agreement, kept by recording who decided in every decision record, RFC and log entry.