How it works · foundations 2
The protocol
The model says the truth is a contract between the surfaces. The protocol says how that truth changes hands: contracts-in-git are the canon, CI is the enforcement point, and every change — in either direction — becomes a reviewable diff before it becomes real.
Contracts-in-git are the canon
There is no registry, no proprietary store, no sync service holding the truth. The canonical state of a design system is a directory of *.contract.json files in a Git repository — diffable, blameable, revertable, reviewable with the tools every engineering organization already trusts. Per-version history is the changelog; a contract's version field is the unit of change management. Everything else — the generated React library, the canvas component sets, the Storybook stories — is a derived surface that can be regenerated from the canon at any time.
CI is the enforcement point
A rule nobody runs is a suggestion. The referee is ds-contracts diff, and its exit codes are the whole enforcement interface: 0 clean · 1 drift, findings named on stderr · 2 configuration error. Wire it into CI (the committed recipes do) and the protocol stops depending on anyone's diligence: a pull request that would leave code and contracts disagreeing cannot merge. The code-led recipe keeps contracts current from the components on every push; the design-led recipe regenerates code from changed contracts and gates the PR on parity. Every step in both recipes has been executed verbatim against the published CLI (VALIDATION.md).
Every change is a reviewable diff
Both directions, one door. An engineer's hand-added prop is flagged by the differ with a complete proposed contract patch (replayed step by step). A designer's canvas edit becomes a proposed contract change through the plugin's Send tab or ds-contracts propose-pr — a pull request carrying one JSON diff. Nothing takes effect because someone had write access to a surface; it takes effect because a human reviewed a diff and merged it. The merge is the adoption decision, and the regeneration that follows is mechanical.
Authority is the power to refuse
In most design-system processes, "authority" means a person with final say — which fails the moment that person is busy. Here authority is structural: a layer is authoritative precisely because it can mechanically refuse, by name, before anything downstream happens.
| Layer | What it refuses | How |
|---|---|---|
| The schema | a malformed contract | validateContract — parse failure with the exact violation named; nothing emits |
| The token gate | a binding to a token that doesn't exist | the build itself fails, naming the contract path and the missing token |
| The generator | an illegal contract — defaults outside enums, composition cycles, duplicate bindings | refusal by name on every surface; no "best effort" mode |
| The differ | surfaces that disagree with the contract | diff exit 1 — CI blocks the merge until the disagreement is promoted or regenerated away |
| The canvas sync | running against the wrong file, or a foreign component | anchors and identity markers — a set without our marker is never touched |
Notice what is not on the list: no committee, no sync meeting, no reconciliation human. The protocol replaces standing arbitration with standing refusal.
The no-unilateral-changes rule
Surfaces never sync side-to-side, and nobody — human, CI job, or AI — writes both surfaces in one motion. Even the code-led CI job that adopts freshly extracted contracts lands its adoption as a commit in the repo's history, not a silent overwrite; even the plugin's in-place library update applies only received, schema-valid contracts and shows what it will change before it changes it. A change that skipped review is drift by definition, and the differ will name it on the next run. This is the same discipline Git brought to code and DTCG brought to tokens: unilateral edits don't become truth; proposed diffs do.
Where AI is allowed to sit
Propose, never decide. AI is welcome at exactly one position in the loop: upstream of the referees, as a proposer. The playground's prompt-to-contract assistant drafts contracts the schema is free to refuse; an agent generating screens is constrained by the compiled catalog and judged deterministically (the A/B result: governed 100/100 vs ungoverned 69/100 — the model page tells that story). Nothing an AI produces skips a single gate: the schema still parses it, the token gate still resolves it, the generator can still refuse it, the differ still checks the result, and a human still merges the diff. The referee re-checks everything — which is exactly why AI assistance is safe to accept.
Standing receipts: the CI recipes' executed-verbatim validation (examples/ci/VALIDATION.md), the journey evals that execute the documented commands (journey-engineer, journey-designer), and the C2 refusal family behind every row of the authority table.