Design System Documentation Standard 0.1

Design System Documentation Standard 0.1 Draft

Draft Specification — February 2026

Latest version: https://github.com/somerandomdude/design-system-documentation-schema

Editors:

PJ Onori

A machine-readable format for design system docs

It covers six entity types: components, design tokens (including nested token groups), themes, styles, and patterns.

All structured docs use a unified document block system. Each document block entry is a typed object with a type field. Document block types include guidelines, anatomy, API specs, variants, states, accessibility, purpose, examples, content, design specs, principles, scales, motion, and interactions.

Entity types accept only the document block types relevant to them. Components accept component-scoped and general types. Patterns accept pattern-scoped and general types. Styles and tokens each accept their own scoped types plus general types.

DSDS is a companion to the W3C Design Tokens Format Module. The Design Tokens Format Module defines the interchange format for token values. DSDS defines the interchange format for the docs that surround components, tokens, styles, and patterns.

Status of this document

This is a draft spec and is subject to change. It has not been endorsed by any standards body. Feedback and contributions are welcome via GitHub.

Design principles

This section is non-normative.

Documentation is a product. It deserves the same rigor as the components it describes.
Structure enables quality. A defined format creates a floor of quality and completeness.
Guidance without justification is incomplete. Every recommendation must answer "why?"
Documentation should be portable. A standard format makes migration tractable.
Education is a responsibility. Explain what, why, and how.
Specificity over subjectivity. "Use sparingly" is not guidance. "Limit to one per surface" is.

Next steps

New to DSDS? Start with the Quick Start Guide. It covers document structure, entity types, the document block system, and minimal examples you can copy.

For the full schema reference — document structure, entity properties, document block types, and all shared models — see Schema Architecture.

See the schema files in spec/schema/ for the normative JSON Schema definitions and the examples in spec/examples/ for valid demos of each entity and document block type.