Spec reference
Versioning
Two version lines, deliberately separate: each contract carries semver; the schema has a single current version. The change-by-change history lives in the repository, not here.
Current versionCurated#
The schema is at v16 — one live document, scripts/contract-schema.ts, reflected by npm run schema into the generated JSON Schema (contracts/contract.schema.json) and published as @ds-contracts/schema (its semver major is the spec version; the JSON Schema ships in the package at @ds-contracts/schema/contract.schema.json — point your editor's $schema at it). Every reference page on this site is generated from the same source at build time, so this site always documents the current version. What changed, when, and why is the repository’s history: see the CHANGELOG and MILESTONES.md on GitHub.
Contract versions (semver)Curated#
Any change to props, states, anatomy, or a11y bumps the contract’s version — semver semantics: an added optional prop or a widened slot is minor; a removed or renamed prop or value, or a narrowed slot, is major. The version string is schema-enforced (MAJOR.MINOR.PATCH — a malformed version is refused).
Contract changes land as PRs. The PR diff is the design-system change review — one artifact, reviewable by designers and engineers alike. The promotion flow generates these PRs from drift detected on either surface: an engineer’s hand-added prop became Button v1.0.0 → v1.1.0 through exactly this door (the full lifecycle, replayed).
How breaking changes are handledCurated#
The schema grows by addition, never by repurposing: new vocabulary lands as optional fields, and every existing contract must keep parsing — a schema change that breaks a shipping contract does not merge. Each addition ships with its refusal rules (the illegal states, named) and an eval behind it, and this site’s coverage guard fails the build if a schema branch lands undocumented.
For contracts, breaking is a major version: removing or renaming a prop or value, or narrowing a slot’s accepts. Widening is minor. Consumers pin contract versions the way they pin package versions — the version field is the unit of change management.
To propose a change, see Contribute — fixture first, refusals named, eval-locked, then the claim.