Design System Contract reference
A design system's rules usually live where code tools can't read them: a docs site, a Figma library, a component package's source. So an AI coding agent guesses. It invents variant names, fills in props, and builds lookalike components.
The Design System Contract writes those rules down as data. One JSON file per component says which props exist, what type each one is, which values are legal, and what the defaults are. A manifest lists those files and records a content address for each one. Both formats have JSON Schema 2020-12 schemas, so any stock validator can check them.
A design system isn't documentation to consult. It's a contract to check against. These pages are the lookup: every member, every rule, every constraint.
format v0.1 spec 0.11.0
Reference topics
- Component contractEvery member of the component contract:
contractId,component,props,slots, andstates. - Manifest
contractVersion,artifacts, and the artifact record:path,address, andorigin. - contractId and the foldThe five fold steps, rejection reasons, collision scope, and worked examples.
- Content addressingThe
sha256:address format, RFC 8785 canonical form, and mismatch handling. - DSDS integrationThe DSDS
specspointer and the mapping from props and states to DSDS traits. - Scope and limitsWhat v0.1 does not cover, what schema validation does not check, and permissive schema behavior.
Schemas and examples
| File | Contents |
|---|---|
schemas/v0/component.contract.schema.json | JSON Schema 2020-12 for the component contract |
schemas/v0/manifest.schema.json | JSON Schema 2020-12 for the manifest |
examples/button-primary.contract.json | A valid component contract |
examples/manifest.json | A valid manifest listing the example contract |
These reference pages render the schemas in readable form. Where prose and a schema disagree, the schema is correct.
The schema $id values under https://knapsack-oss.github.io/design-system-contract/schemas/v0/ are served from this site, so a validator can fetch them by $schema. See schema identifiers.
At a glance
| Item | Value |
|---|---|
| Component contract required members | contractId, component |
| Manifest required members | contractVersion, artifacts |
contractId pattern | ^[a-z0-9]+(-[a-z0-9]+)*$ |
| Address pattern | ^sha256:[0-9a-f]{64}$ |
origin values | inferred, synced |
| Additional members | Not permitted on the contract root, props, a prop schema, a slot record, slot accessibility, the manifest root, or an artifact record. props.properties is a map whose keys are prop names. |
| License | Apache-2.0 |