# Design system doc spec 0.21.2 **Draft Specification:** This is a draft. It can still change—and has done so in dramatic fashion. No standards body has endorsed it. We welcome feedback and contributions on GitHub. * **Latest version:** [GitHub repo](https://github.com/somerandomdude/design-system-documentation-schema) * **Feedback:** [GitHub Issues](https://github.com/somerandomdude/design-system-documentation-schema/issues) --- ## A machine-readable format for design system documentation DSDS puts design-system docs in one format any tool can read. A document is a [**base**](schema.html#base) — `schemaVersion`, `name`, and a list of [**entries**](schema.html#entries-entry): a [system](schema.html#entries-system), any number of [components](schema.html#entries-component), [tokens](schema.html#entries-token), [themes](schema.html#entries-theme), or the generic `entry` for anything else. One source of truth that feeds your docs, trains your agents, and shows up everywhere your design system does. --- ## Principles 1. **Documentation only.** This schema is focused on the how, when, and why of a design system. That's it. If a better source of truth exists elsewhere, the schema links rather than restating. 2. **A consistent schema pattern.** Each part of the schema follows the same structure, so writing one part teaches you the rest. 3. **No learning cliffs.** It's designed to have a low barrier of entry. But it can grow with you. DSDS' `$extensions` let you add on to the schema when you actually need it. 4. **Everything can link to everything else.** A design system is a network of connections; the documentation reflects that. 5. **There's always a way out.** The schema has opinions, but always a way to step outside them. --- ## Flexible and modular Design systems have different documentation needs. This schema can be as simple or as detailed as needed. Every entry's structured docs live in one `sections` array, and each section has a `kind`. The spec defines three kinds — `guidelines`, `definitions`, `steps`, plus the generic `section`. Any section can also carry `freeform`: headed, nestable prose alongside its own `items`. A component also carries `sourceFiles`, `specs`, `traits`, `combos`, and `imports` as fields of its own, not sections. Any entry kind can use any section kind — nothing restricts which goes with which. --- ## Humans and agents A DSDS document has two readers: people and AI agents. Both are served by the same file. Every section carries a `for` field naming its audience: - **`for: human` or `for: all`**: Everything a person needs—definitions, guidelines, steps, freeform narrative. Agents read these too. - **`for: agent`**: Agent-only notes—for the times when basic documentation can't get through those thick titanium skulls. This allows you to write documentation specifically for agent misunderstandings, hallucinations, or agent-specific tasks. Write for people by default. It serves agents too. Use `for: agent` when all else fails. --- ## Interoperability No open standard covers design-system documentation end to end. The formats that do exist each cover one layer well — [DTCG](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) owns token values, [CEM](https://github.com/webcomponents/custom-elements-manifest) owns a component's generated API, [CSF](https://storybook.js.org/docs/api/csf) owns a story, a test runner owns whether a rule actually holds. DSDS sits above them and documents meaning and usage. **If another format owns a fact, DSDS points at it rather than restating it** — which is why a token entry has a `source` and no `value`, and a component entry has `sourceFiles` and `specs` and no property table. A pointer can go stale in exactly one way, and `DSDS-11` catches it; a copy goes stale silently. → **[Interoperability](interoperability.html)** covers every format DSDS is built to sit alongside, the field that points at each, and a worked example for all of them. --- ## Next steps New to DSDS? Start with the [Quick Start Guide](quickstart.html) — document structure, entry kinds, the section system, and examples you can copy. For the full schema reference, see [Schema](schema.html). For the JSON Schema source, see `schema/`; for working examples, see [Examples](examples.html). --- ## Contributors - [PJ Onori](https://pjonori.com): Current maintainer. - [Cody Clark](https://github.com/codysue): the CEM interop example, the nested/aliased DTCG interop example, and the two token-description lint rules (`DSDS-13` and `DSDS-16`). - [Suleiman Ali Shakir](https://iamsuleiman.com/): the README validate command and lockfile, and a stale version string fix. - [Mykhaylo Ryechkin](https://github.com/mryechkin): the agent skills (`.agents/skills/`) and `scripts/generate/sync-skill-versions.js`, and keeping them current with the schema. - [Mark Toadvine](https://github.com/marktoadvine): the `shared-a11y` WCAG 2.2 accessibility guidelines in the starter kit. - [Chris Strahl](https://github.com/chrisstrahl): real API identifier shapes on a trait `id` (`apiId`), the widened `combo` target, and the `DSDS-14` same-as false positive fix. - [isabelthedesigner](https://www.isabelthedesigner.com): the anti-pattern for bare WCAG conformance claims. - [Afyia Smith](https://afyiasmith.co/): the `owner`/`reviewed` and `origin` metadata schemas.