Design system documentation is better when it's portable, structured, and connected. DSDS works to make all three possible.

Draft Specification: This is a draft. It can still change—and has done so. No standards body has endorsed it. We welcome feedback and contributions on GitHub.

One entry, three readers

Write a component's guidance once, in YAML. A docs site renders it for people, an agent reads it before writing code, and a linter checks it for gaps. Here's one entry:

kind: component id: button name: Button description: Triggers an action on the current screen. sections: - kind: guidelines for: all framing: when-to-use items: - level: should statement: Use for an action that happens in place, like saving a form. - level: should-not statement: Avoid for navigation. A link tells people they're going somewhere. - kind: guidelines for: human items: - level: must statement: Label the button with the action it performs, like "Save draft". - level: should statement: Keep to one primary button per screen. - kind: guidelines for: agent items: - level: must-not statement: Do not build a button from a div with a click handler. checkedBy: assisted What a docs site shows

The sections written for people (for: human) and everything (for: all):

Button

Triggers an action on the current screen.

When to use

  • Should: Use for an action that happens in place, like saving a form.
  • Should not: Avoid for navigation. A link tells people they're going somewhere.

How to use

  • Must: Label the button with the action it performs, like "Save draft".
  • Should: Keep to one primary button per screen.
What an agent reads

Agents can be given their own specific documentation with a for: agent section to guide agents with things only they need:

- kind: guidelines for: agent items: - level: must-not statement: Do not build a button from a div with a click handler. checkedBy: assisted What the linter reports

npm run lint checks the entry and points at a gap:

button.yaml ⚠ [DSDS-14 guideline-missing-checkedby] /sections/1/items/0/checkedBy: guideline in "button" is a hard requirement (level: must) with no checkedBy, and no same-as target that declares one — declare 'automated', 'assisted', or 'manual' so a tool can tell whether this rule is verifiable at all. 1 file(s) linted: 0 clean, 1 warning(s).

The labeling rule is a must, but nothing says how anyone would check it. Add checkedBy: manual and the warning clears. The linter never fails a build. It points out what a reviewer would otherwise have to catch.

Connected documentation

A design system is a set of connected pieces. A dialog is built from a button, a button uses color tokens, and many components follow the same rules. DSDS lets things connect, so those links are data rather than copy/paste-waste.

kind: component id: dialog name: Dialog description: A window over the page that asks for a decision before the person can go on. sections: - kind: guidelines for: all items: - refs: - to: shared-a11y#focus-visible rel: same-as uses: - to: button - to: color.surface.raised alternatives: - to: popover refs: - href: https://www.figma.com/design/abc123/Dialog rel: design - href: https://storybook.example.com/?path=/story/dialog rel: demo

Because the links are data, a docs site can show what's related, an agent can check what a change would affect, and a rule shared by many components is written once and reused instead of copied.

→ common/ref lists every kind of link, what it means, and where it goes.

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.

For 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 and use for: agent when all else fails.

How a document is built

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. The same file feeds your docs site, gives your agents context, and shows up everywhere your design system does.

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.

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.
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 what it means to conform to the spec and every rule the validator enforces, see Conformance. 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 two token-description lint rules (DSDS-13 and DSDS-16).
  • Suleiman Ali Shakir: the README validate command and lockfile, and a stale version string fix.
  • Mykhaylo Ryechkin: the agent skills (.agents/skills/) and scripts/generate/sync-skill-versions.js, and keeping them current with the schema.
  • Mark Toadvine: the shared-a11y WCAG 2.2 accessibility guidelines in the starter kit.
  • Chris Strahl: real API identifier shapes on a trait id (apiId), the widened combo target, and the DSDS-14 same-as false positive fix.
  • isabelthedesigner: the anti-pattern for bare WCAG conformance claims.
  • Afyia Smith: the owner/reviewed and origin metadata schemas.