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.

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 — schemaVersion, name, and a list of entries: a system, any number of components, tokens, themes, 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 owns token values, CEM owns a component's generated 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 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 — document structure, entry kinds, the section system, and examples you can copy.

For the full schema reference, see Schema. For the JSON Schema source, see schema/; for working examples, see Examples.

Contributors
  • PJ Onori: Current maintainer.
  • Cody Clark: the CEM interop example, the nested/aliased DTCG interop example, and the token-description lint rule (DSDS-13).
  • Suleiman Ali Shakir: the README validate command and lockfile, and a stale version string fix.
  • Mykhaylo Ryechkin: the agent skills (.agents/skills/) and scripts/sync-skill-versions.js.
  • Mark Toadvine: the shared-a11y WCAG 2.2 accessibility guidelines in the starter kit.
  • Afyia Smith: the owner/reviewed and origin metadata schemas.