Set up your design contract

What the contract is

A contract names your canonical components (the ones agents and people should reuse instead of rebuilding) and the stylesheet files that define your tokens. Every published contract gets a content-addressed identity (an FCID) and a version. Agent hooks, CI checks, and the hosted MCP tools all read the same contract, so a component is either canonical everywhere or nowhere.

Adopting the contract arms exactly four Tier A rules. They are components/shadow-component (FUI1007), components/prefer-library (FUI1004), tokens/css-vars-must-be-defined (FUI2015), and tokens/upstream-drift (FUI2017). Until a contract exists, the customer default produces zero findings.

There is deliberately no free-text way to add vocabulary in the dashboard. The Contract page approves what your repository publishes — it never invents.

Path A — you have a component library

If your repository builds a component library with Fragments, the library's compiled manifest is the source of truth. Build it once locally to see what will be published:

npx @usefragments/cli build

Then declare the package as a canonical source in fragments.config.ts and let your existing governance CI run. The same scan that reports findings also publishes the manifest's vocabulary — every root component, including compound roots and their members — to Fragments Cloud:

npx @usefragments/cli check --ci

Open your repository's Contract page. A proposal card shows the published manifest — package name, root count, manifest digest, and the commit it came from. Click Adopt vocabulary. That one click writes the contract with full provenance, and the next scan publishes a new contract version that your gates enforce. Nothing changes until you approve.

Path B — no library yet

If your repository has components but no compiled library manifest, the scan detects component definitions and the Contract page lists them as candidates. You confirm the ones that are canonical and pick your token source files, then save the manifest as one revision and run a scan to publish it. Same approval surface, same result: a versioned, enforceable contract.

When your library changes

Add a component to your library and the next CI scan republishes the manifest. The Contract page flips to Behind manifest and shows exactly which roots were added or removed. Click Update contract to adopt the new vocabulary; the enforced contract never moves without that click. When the adopted vocabulary matches the latest manifest, the card shows a quiet in-sync line with the manifest digest and adoption date.

Troubleshooting

Run the doctor whenever enforcement looks wrong — it walks the whole chain and names the one action for the first broken link:

npx @usefragments/cli doctor

Common states it will name:

No canonical components registered — nothing has been adopted or configured yet. Follow Path A or Path B above.

Manifest error on the Contract page — your declared package published a missing, empty, or invalid manifest. Fix the manifest and push; Fragments never silently falls back to detection for a declared package.

Contract stale in the hook card — your local session is pinned to an older contract version. Re-run npx @usefragments/cli init to refresh the local bundle.

For the wider governance model — rules, FUI codes, and the enforcement surfaces — see Governance.