# Design System Doc Spec (DSDS)

> A machine-readable format for design system documentation. DSDS structures a design system as a graph of entries (systems, components, tokens, themes, and custom kinds) and sections (definitions, guidelines, steps, and freeform content) for humans, parsers, and agents.

This site documents DSDS, a versioned JSON Schema. Every page below has an HTML version (for people) and a plain-markdown mirror at the same path with a `.md` extension (e.g. `/quickstart.md`, `/schema.md`) — the full content as text, no HTML/JS to parse. The Schema page's markdown includes every definition's field names, types, and requiredness; the bundled schema below is the single-file version of the same data.

## Machine-readable schema

- [manifest.json](https://designsystemdocspec.org/manifest.json): the typed machine index — every entry kind and section kind, with links to each one's page, markdown and schema. Start here.
- [Bundled schema, v0.23.0](https://designsystemdocspec.org/v0.23.0/dsds.bundled.yaml): every definition in one file
- **Per-definition markdown**: 23 small files, one per schema definition, a few KB each and in the schema's own field order — e.g. [entries-component](https://designsystemdocspec.org/schema/entries-component.md) or [common-ref](https://designsystemdocspec.org/schema/common-ref.md). Fetch one of these to learn a single definition instead of the whole bundle; manifest.json lists all of them under `definitions`.
- [llms-small.txt](https://designsystemdocspec.org/llms-small.txt): a primer of about 5k tokens - the core model, the field and kind lists, one worked example, and how to validate. Read this first if you're short on context
- [llms-full.txt](https://designsystemdocspec.org/llms-full.txt): every guide's full text plus the bundled schema, in one file for one-request ingestion
- [AGENTS.md](https://designsystemdocspec.org/AGENTS.md): how to consume these docs as an agent — where to start, what's normative, how to self-check your work
- [sitemap.xml](https://designsystemdocspec.org/sitemap.xml): every page on this site

## Guides

- [Conformance — DSDS 0.23.0](https://designsystemdocspec.org/conformance): What it means to follow the DSDS spec: the four kinds of conforming thing, the three ways a rule is checked, and every rule. ([markdown](https://designsystemdocspec.org/conformance.md))
- [Examples — DSDS 0.23.0](https://designsystemdocspec.org/examples): Every validated example document DSDS ships, browsable by category: base documents, standalone entries, quickstart snippets, interop pairs, and the negative-test corpus. ([markdown](https://designsystemdocspec.org/examples.md))
- [Interoperability — DSDS 0.23.0](https://designsystemdocspec.org/interoperability): Every format DSDS is built to sit alongside — DTCG, CEM, CSF/Storybook, source files, tests and lint rules, standards, design tools and packages — with the field that points at each and a worked example. ([markdown](https://designsystemdocspec.org/interoperability.md))
- [Processing model — DSDS 0.23.0](https://designsystemdocspec.org/processing): What a tool reading DSDS documents has to work out that isn't written down: which item an address points to, which files belong together, where reused content comes from, how relationships read backwards, what replaces something deprecated, and how to avoid loops. Normative, with test vectors. ([markdown](https://designsystemdocspec.org/processing.md))
- [Security considerations — DSDS 0.23.0](https://designsystemdocspec.org/security): DSDS's trust model: a document is data, not instruction. What that means for for: agent rules, for href/checks pointers, and for $extensions. ([markdown](https://designsystemdocspec.org/security.md))
- [Stability — DSDS 0.23.0](https://designsystemdocspec.org/stability): The DSDS compatibility policy: what counts as breaking, version semantics, the deprecation window, what's safe to build tooling around, and the criteria for declaring 1.0. ([markdown](https://designsystemdocspec.org/stability.md))
- [DSDS authoring style guide — DSDS 0.23.0](https://designsystemdocspec.org/style-guide): How to order things inside a DSDS document, so every document reads the same way no matter who wrote it. ([markdown](https://designsystemdocspec.org/style-guide.md))
- [Design system doc spec 0.23.0](https://designsystemdocspec.org/): DSDS is a schema for design system documentation. It's open, portable, and (debatedly) simple. ([markdown](https://designsystemdocspec.org/index.md))
- [Specification — DSDS 0.23.0](https://designsystemdocspec.org/specification): The DSDS specification: what a document is, what each part has to contain, how pointers work, and what validators and consumers have to do. Every requirement names what checks it. ([markdown](https://designsystemdocspec.org/specification.md))
- [DSDS quick start guide](https://designsystemdocspec.org/quickstart): Get started with DSDS — document structure, entry kinds, the section system, and minimal examples you can copy. ([markdown](https://designsystemdocspec.org/quickstart.md))
- [Extending the schema — DSDS 0.23.0](https://designsystemdocspec.org/extending): Three ways to go beyond what the spec ships with — $extensions for tool-specific data, custom kinds for a kind of document the spec doesn't have, and profiles for making an existing kind's optional fields required. ([markdown](https://designsystemdocspec.org/extending.md))
- [Schema](https://designsystemdocspec.org/schema): Every DSDS schema definition, on one page, each with a real example next to it. ([markdown](https://designsystemdocspec.org/schema.md))