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. DSDS sits above them, documenting meaning and usage instead of restating what they already own.

ConcernSource of truthHow DSDS points at it
Token values and platform mappingsW3C Design Tokens (DTCG) filesA token or theme entry's source
Component source code, per platformA source file or framework typingsA component's sourceFiles — pointing a tool at the real file to extract from, instead of hand-typing an interface
Component API contract, already generatedCustom Elements Manifest (CEM), or another standard contract formatA component's specs — pointing at the generated document itself, not re-deriving it from source
Live component demosStorybook or equivalentA refs/examples entry with rel: storybook
Design artifactsDesign tool filesA refs entry with rel: design, or metadata.preview
Source codeThe repositoryA refs entry with rel: source, or a component's own sourceFiles

DTCG owns token values; DSDS owns their meaning and usage, so the two can never disagree. CEM (and similar manifests) own a component's generated API details — specs points at the manifest itself, sourceFiles at the raw source a step earlier in the same pipeline; a component can use either, both, or neither. See examples/interop/ for worked examples.

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.
  • Afyia Smith: the owner/reviewed and origin metadata schemas.