Dsds Specs

Design System Doc Spec (DSDS)

DSDS is a machine-readable YAML format for documenting design systems. DSDS specs are the single source of truth — everything else (React components, Figma, docs, AI catalogs) derives from them.

DSDS documents a graph of entries (a system, a component, a token, a theme, or the generic entry kind for anything else), each carrying typed sections (definitions, guidelines, steps, or the generic section). It never duplicates data a better source of truth already owns — a component's sourceFiles points at the real code instead of hand-typing its props; a token's source points at the real DTCG value instead of restating it.

Schema Sources

When you need precise field-level details beyond this skill, consult these in order:

1. Bundled schema: https://designsystemdocspec.org/v0.21.2/dsds.bundled.schema.json (or node_modules/design-system-documentation-schema/schema/dsds.bundled.schema.json if installed as a dependency)
2. Schema architecture reference: https://designsystemdocspec.org/schema#how-the-schema-is-organized (and Conformance for conformance classes and the full rule catalog)
3. Quick start with examples: https://designsystemdocspec.org/quickstart — and the style guide for the field order every example follows. The schema permits any order; the style guide picks one. It is a convention, not a constraint — the DSDS-17–DSDS-23 rules that report deviations are advisory warnings from npx dsds-lint, never a validation failure.
4. GitHub source (split schema + examples): https://github.com/somerandomdude/design-system-documentation-schema/tree/main/schema

Key pages for field-level detail:

Each definition has its own small markdown mirror under /schema/ — a few KB of field names, types, requiredness and descriptions for that one shape, in the order the schema declares them. Fetch one of these rather than the whole bundle when you need a single shape.

• Entry kinds: https://designsystemdocspec.org/schema/entries-component.md, and the same path for entries-token, entries-theme, entries-system, entries-entry
• Section kinds: https://designsystemdocspec.org/schema/sections-guidelines.md, and the same for sections-definitions, sections-steps, sections-section
• Shared building blocks: https://designsystemdocspec.org/schema/common-ref.md (the one pointer type), and the same for common-combo, common-example

The Schema page carries the same content for a human reader, one anchor per definition — for example /schema#entries-component.

Entry Kinds

There is no token-group kind: a group of related tokens is a metadata.group fact on the tokens in it, not a separate artifact.

Document Structure

A standalone entry file (most components, tokens, themes) has no wrapper — the entry's own fields sit at the file's top level:

kind: component
id: checkbox
name: Checkbox
description: A styled checkbox input for boolean or indeterminate selection.

A base document (the root index.dsds.yaml, or any file meant to hold more than one entry) requires schemaVersion, name, and a non-empty entries array. System-wide facts live on that list's own kind: system entry:

schemaVersion: "0.21.2"
name: Acme Design System

entries:
  - kind: system
    id: acme-design-system
    name: Acme Design System
    description: Acme's cross-platform design system.
    metadata:
      version: 1.4.0
      platforms: [react, web-component]

refs:
  - href: ./components/checkbox.dsds.yaml
    rel: file
    role: Checkbox component

Splitting a system across many files uses refs (rel: file) pointing at sibling documents — not a $ref/JSON-Pointer include. There's also scripts/tools/compose.js upstream, for concatenating many hand-authored fragment files into one document before validation.

Sections

Every entry's structured docs live in one sections array. Each section has a kind and a for (human, agent, or all, naming its audience):

• definitions — term/definition pairs. Use for anatomy, naming conventions, or a prop/event list when there's no real source file to extract from.
• guidelines — a statement paired with a level (must/should/may/should-not/must-not). Carries framing: when-to-use (a fit judgment) or how-to-use (the default, an implementation rule).
• steps — an ordered procedure or unordered checklist.
• section (generic) — for anything else, or purely freeform narrative prose.

Every section kind can also carry freeform: headed, nestable prose alongside its own structured items.

Two optional fields on any section kind make it findable without matching on a human-written title:

• context — the job the section is doing: anatomy, terms, keyboard, events, or a namespaced custom value. Set it whenever the section has one of those jobs, so a tool can find "the anatomy table" by field rather than by heading text.
• tags — what the whole section is about ([accessibility]). The first tag is the primary one. A tag-scoped section sorts after the broader sections covering the same entry.

A guidelines item that claims checkedBy: automated must point checks at what actually runs the check — rel: test (the design system's own code), rel: lint-rule (static analysis), or rel: agent-test (a fixture that runs an AI agent against the guideline and grades what it generates). An agent-test usually reports a pass rate or a judged rubric rather than a strict pass/fail, so pair it with checkedBy: assisted unless its assertion really is deterministic.