Contract format
Fields of a component contract, an abridged example, and the lifecycle statuses.
A contract is spec/components/<name>/contract.json, validated against spec/schemas/contract.schema.json (check C1). Check C3 compares the code to it.
Top-level fields
The schema allows only these fields.
| Field | Purpose | Required |
|---|---|---|
component |
Component name, for example Badge. |
Yes |
tag |
Custom element tag, for example sb-badge. |
Yes |
status |
Lifecycle status (see below). | Yes |
platforms |
Where the component exists, for example web, design. |
Yes |
summary |
One-sentence description. | Yes |
props |
The component API: each prop with type, values, default and note. | Yes |
anatomy |
Named parts, their role and parent. | Yes |
accessibility |
Role, native element, accessible name, target size, keyboard, ARIA, contrast pairs. | Yes |
tokens |
Component tokens, each aliasing a semantic token. | Yes |
realizations |
How each platform realizes the contract. | Yes |
openQuestions |
Questions with a recommendation, status and answer. | Yes |
version |
Contract version. | No |
dependsOn |
Other components this one needs. | No |
variantMatrix |
Variant combinations. | No |
content |
What goes in each slot, whether it is required or repeatable. | No |
events |
Events the component dispatches. | No |
states |
Interaction states with trigger and the tokens they use. | No |
aiHints |
Category, keywords, use cases and anti-patterns for agents. | No |
decisions |
Decisions that apply to this component. | No |
elements |
Sub-elements of a component family, each checked by C3 against its own API. | No |
$extensions |
The one open section: dotted namespaces such as design.figma. |
No |
Note
Prop, event and state names must come from
spec/api.json(check A1). Token references must exist (checks C2 and T2).
Example
Abridged from spec/components/badge/contract.json.
{
"component": "Badge",
"tag": "sb-badge",
"status": "beta",
"platforms": ["web", "design"],
"summary": "A small pill that labels or counts something, optionally a link.",
"props": {
"variant": {
"type": "variant",
"values": ["default", "secondary", "destructive", "outline", "ghost", "link"],
"default": "default",
"reflect": true
},
"href": { "type": "text", "default": null }
},
"accessibility": {
"role": "none for a plain badge (text); link for a badge with href",
"keyboard": { "Tab": "focuses a link badge", "Enter": "follows the link" }
},
"tokens": {
"badge.font-family": "{font.family.body}",
"badge.font-size": "{font.size.caption}"
}
}
Lifecycle statuses
The status field and the entry in spec/registry.json move together. Check R1 requires evidence for each step.
| Status | Meaning | Evidence R1 requires |
|---|---|---|
planned |
Registered, no contract content yet. | None. |
draft |
Contract written, open questions remain. | The contract exists. |
wip |
Implementation in progress. | The contract exists. |
beta |
Implemented, not fully audited. | Web files, stories, a behavior spec, and no C3 errors. |
stable |
Verified end to end. | Also a parity audit, an a11y audit with a ready verdict, an Approved-by: line, and a complete design realization. |
deprecated |
Superseded. | The contract exists. |
code-only |
Implementation with no design counterpart. | Same as beta. |
Names
Every contract speaks one vocabulary, registered in spec/api.json. Check A1 fails on a name that is not registered, and sketchbook api list shows each contract against it.
- Prop keys are camelCase; prose spells them dash-case.
variantis emphasis, neverrole. A status tone isfeedback; a step of size issize.- What a component holds (text, icons, children) is content, not a prop:
label,leadingIcon. - A boolean that changes the look (
disabled,readOnly,selected) is a boolean prop. - Events are
change,inputandclick; any other event is named with the prefix (sb-toggle).
To add a name, register it in spec/api.json with its meaning, then use it. sketchbook api explain <name> explains one.