DSDS (Design System Doc Spec) is a YAML format for documenting design systems. It puts every piece of docs — components, tokens, themes, and anything else — in a machine-readable shape: a graph of entries, each carrying typed sections.

Write your documents in YAML — every example on this site, the default npm run check sweep, and the tooling all assume it. The schema itself is written in JSON Schema (that's the language the rules are written in, a separate thing from the format your documents need to be in). Since YAML is a superset of JSON, a JSON document would technically still parse — but nothing in this repo discovers or exercises that path, so don't rely on it.

• Structured — every section has a defined shape, no guessing
• Machine-readable — tools can parse, generate, validate, and transform it
• Portable — not locked to any docs tool or platform
• Extensible — add vendor metadata without breaking compatibility
• Validatable — the schema catches errors before they reach consumers

A DSDS document is a base: schemaVersion, a name, and a list of entries.

This much is valid YAML, but not a valid document yet — entries is required:

System-wide facts (version, organization, url, license, platforms) live on this list's own kind: system entry, not on the base document directly:

Any entry — a component, a token, a theme, or the generic entry kind — can sit alongside the system entry in the same entries array. Here, a system entry plus a component entry:

For a larger system, keep each entry in its own file and point at it with refs (rel: file) instead of inlining everything — pointing at a sibling document that owns another entry:

Every entry has a kind field. There are 5 well-known values, plus an open option for anything else.

Every entry kind shares one open base: id, kind, name, description (required), plus purpose, metadata, related, extends, refs, sections, $extensions (optional).

related, extends, and refs are three separate pointer lists, not three names for the same thing — each is scoped to a different kind of connection: related for entries that are similar in usage (rel: alternative-to, rel: pairs-with), extends for inheritance (rel: extends), and refs for anything else, including outside resources (rel: source, rel: storybook). This entry-level refs is the same field name as the base document's refs used above to split into files (rel: file) — same mechanism, different level, different job.

See How the schema is organized for how the schema itself is put together.

Status lives in metadata.status, always as an object — there's no bare-string shorthand. A component-wide status:

Scope a status to one platform when a component ships on more than one:

Structured docs live in the sections array on each entry. Each section has a kind field naming its type — guidelines, definitions, steps, or the generic section. Any entry kind can use any section kind; nothing restricts which section kinds go with which entry kind.

Every section also carries a for field (human, agent, or all) naming its audience — see Humans and agents on the Overview page.

Each guideline item pairs a statement with a level (an RFC 2119 requirement level) and, optionally, alternatives, evidence, or a checkedBy/checks verification pair. A component with a guidelines section:

The level field's values are lowercase kebab-case, like every DSDS vocabulary: must, should, should-not, must-not, may. Tools display them as badges: MUST, SHOULD, SHOULD NOT, MUST NOT. Agents treat must/must-not items as hard limits.

A guidelines section also carries framing: when-to-use for a fit judgment (is this entry the right choice at all), or how-to-use (the default) for an implementation rule once it's chosen.

A definitions section pairs a term with its definition — use it for anatomy parts, naming conventions, or a component's own prop/event list when there's no real source file to extract from. context (a field every section kind can carry, not just definitions — see sections/section) names which of those jobs it's doing (anatomy, terms, keyboard, events, or a namespaced custom value) — optional, but it's what lets a tool find "the anatomy table" without matching on the human-facing title. Here's an anatomy definitions section:

A steps section is an ordered procedure or an unordered checklist (ordered: false). Each item can point back at the guideline it verifies via checks (rel: depends-on). A self-check checklist:

Every section kind — including the generic section — can also carry freeform: headed, nestable prose alongside its own structured items:

Unlike sections, a few facts about a component live directly on the entry, not inside a section — they're facts about the component as a build artifact, not documentation content:

• sourceFiles — one entry per platform, pointing at the real source file a tool can extract the component's API from. Replaces hand-typed prop tables.
• imports — one entry per platform, with the install package and the exact import statement.
• traits — every way the component can vary: a kind: enum dimension (like size: sm | md | lg) or a kind: boolean toggle (like hover or loading). A trait's own optional setBy (consumer or component) says whether it's a value the consumer sets, or a condition the component sets on its own — kind alone doesn't tell you that, since a boolean trait can be either (disabled is usually a prop the consumer passes in; hover never is).
• combos — pairing rules between traits, tokens, or entries (e.g. "loading and disabled must not both be set").

Here's sourceFiles, traits, and combos together:

$extensions is a place for vendor or tool-specific data, at the document, entry, or section level. Keys MUST use a namespace (e.g. com.figma) so a tool integration never collides with a future field the spec adds. Here, linking a component to its Figma source:

When the generic entry kind isn't specific enough, use a custom kind instead — it's checked against the same open entry.schema.yaml base the generic kind is:

See Extending the schema for a third option too — profiles, for making an existing kind's optional fields required on your own project — and for more on when to reach for each of the three.

These are close to the smallest valid entry for each kind. Copy one, fill in your content, and add sections as your docs grow.

A minimal standalone component entry:

A token needs id, kind, name, description, and (usually) tokenType. Use source to point back at the DTCG file that holds the real value:

A described token adds metadata.group (the recommended way to group related tokens — there's no separate token-group kind) and a guideline:

A pattern, documented as a generic entry:

Content that isn't itself a design-system artifact — an accessibility rule that applies to more than one entry, stated once and pointed at from everywhere it applies — lives in the base document's shared array, addressed via entryId#itemId and rel: same-as — a shared rule, referenced instead of restated:

Add $schema to get editor autocompletion and inline validation:

You've seen the basics. Here's where to go deeper.