# 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`.

```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.
- `variant` is emphasis, never `role`. A status tone is `feedback`; a step of size is `size`.
- 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`, `input` and `click`; 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.

## Next steps

- [Contracts](/concepts/contracts/)
- [Add a component](/guides/add-component/)
