Design System Documentation Standard 0.1

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.

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.

Design Principles

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