Governance

Each also carries component, version and wave. Button is the reference implementation, at 2.5.0: one slot, five props, nine tokens and three prohibitions. Its prohibitions, as the contract states them:

• No two primary buttons in one group. The second one is not an emphasis choice, it is a missing decision about which action the group is for.
• No destructive action on the primary variant. Destructive work takes danger, so that "the emphasised action" and "the dangerous action" never look like the same thing.
• No button whose accessible name comes only from an icon. The icon size changes the shape, never the naming requirement.

Read the whole file at docs/contracts/button.md, or see it rendered as the Button page, whose API and token tables are read from it.

Thirty-seven contracts: the thirty-six governed components and the Overlay hook they share, read from their frontmatter when this page was built. Inherited rows are counted in full, so Text area’s figures include what it takes from Text input. The foundations (spacing, radius, breakpoint, type) have contracts too, in docs/contracts/foundations/, and answer to token-drift instead.

1. 1

   Rule 1: Every component has one contract file, docs/contracts/<component>.md, in the same repo as the site. Read more

2. 2

   Rule 2: No component code changes without a matching contract update first, even for one-line fixes.

3. 3

   Rule 3: Each contract is versioned with semver. A prohibition change is breaking, a new optional slot is minor, and a copy or description edit is a patch.

4. 4

   Rule 4: A drift check reads each contract’s declared tokens and verifies the component’s code references exactly those variables, and nothing else. It fails the build on a mismatch. Read more

5. 5

   Rule 5: Figma components carry their contract version in the description field, so anyone opening the file knows which spec they are looking at.

6. 6

   Rule 6: Every component set in the kit is either governed (a contract declares it, and its description carries that contract’s version) or ungoverned, and says so in the same place. Nothing is unlabelled. Read more

7. 7

   Rule 7: Where the kit and a contract disagree, the kit wins: correct the contract, not the kit. Where the kit disagrees with itself, the more specific artefact wins. Where the kit has no opinion, the code keeps its own. Read more

8. 8

   Rule 8: Rules 6 and 7 say who wins; neither says what should exist. A governed component with no counterpart in the kit is kept only while something needs it, and rule 6’s demand test decides. Read more

The README lists eight rules today, and this page checks that when it is built. Read the README.

This reversed on 2026-08-28. Until then the contract was canonical and Figma and the site both implemented it. Contracts are still the written spec the code is checked against, and a component still may not change without its contract changing first. What moved is precedence: a contract now describes the kit rather than outranking it, so a disagreement is a bug in the contract. In practice the site’s components look like the kit’s. For Button that meant square corners, Carbon’s asymmetric 0 64px 0 16px inset, a filled secondary, and primary as ghost’s label.

When the kit is not of one mind

Rule 7 settles kit against contract. It does not settle kit against kit, which came up three times in one pass, so the tie-break is written down rather than re-derived.

Kit pages

45

Component sets

206

Public sets

115

Contracts

37

Counted from the committed kit snapshot and the contracts directory. The _ prefix is the kit’s own line between public and private: private sets carry “Do not edit” and are internals the public ones are built from, so the labelling duty applies to public sets only. The disposition walk of 2026-08-28 found 27 of the kit’s pages claimed by no contract, holding 132 sets (73 public, 59 private).

Labelling beats deleting. The harm an ungoverned set does is that a designer cannot tell it from a governed one, and saying so in its description is the whole fix. The library is published, so removing a set is a breaking change for anyone consuming it. Movement is one way: a set becomes governed by acquiring a contract, and nothing goes back. Contained list was the first to move; Accordion was the first adoption the rule decided.

1. Does the kit have a governed counterpart? Rule 7 applies: the kit wins, and the code is brought to it.
2. If not, does the kit answer the same need inside something it governs? Then absorb it there. The kit ships no Label set, but it has a firm opinion about where a label lives: on the control.
3. Does the kit say nothing at all? The contract is authoritative, and rule 6’s demand test decides whether the component is kept.

Read from .github/workflows/checks.yml. Every step runs even if an earlier one failed, so a contract change that trips more than one check reports them together. The job deliberately does not run next build: Vercel already does, and a green build proves the site compiles, not that it matches its spec.

If CI is ever broken badly enough to block its own fix, the way out is to disable protection, land the fix and re-enable it: a deliberate act that leaves a trace, which is what having no bypass is meant to cost.

• Contracts README

  The authority for everything on this page, including the build order and the component API conventions.

• Components

  Thirty-six governed components, each page generated from its contract.

• Run Graphite locally

  Running the checks locally before you open a pull request.