Contracts
The written spec a component is built and verified against.
On this page
Each component has a folder, spec/components/<name>/, with three files.
| File | Holds |
|---|---|
contract.json |
Machine-readable spec: props, events, states, accessibility, and the component tokens in tokens |
contract.md |
The same spec for people |
plan.md |
Scope, files, tokens, accessibility approach, test plan, risks, open questions |
No implementation is added without a contract.json that passes sketchbook check. The component tokens it declares are the only token variables the component's CSS may use. The full field list is in Contract format.
Lifecycle
spec/registry.json gives every component a status: planned, draft, wip, beta, stable, deprecated or code-only.
The evidence each status needs is in Lifecycle statuses. stable needs an accessibility audit with an Approved-by: line.
Note
Editing the registry alone cannot raise a status. Check R1 fails when the evidence is missing.
Workflow
-
Scaffold the contract. The name must already be in
spec/registry.json.sketchbook add "<Name>" --blank -
Fill
contract.jsonandcontract.mdwith thecontract-authorskill. Anything the sources do not confirm is marked"proposal": true. -
Run the checks until they pass.
sketchbook check -
Write
plan.md, then stop at the planning gate. Write no tests or code until the plan is approved. Record the answers in the contract'sopenQuestionsand in the plan. -
Build test-first with the
component-builderskill: write the story and behavior spec, see the tests fail, then write the smallest code that passes.
In Claude Code, /add <Name> runs this flow and stops at the planning gate. The gates are described in Checks.
Next steps
- Add a component
- Checks
- Contract format
- API vocabulary: the names a contract may use