Design System Documentation Spec 0.2.1

Design System Documentation Spec 0.2.1 Draft

Currently maintained by PJ Onori

Draft Specification — Spring 2026: 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.

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

Feedback: GitHub Issues

A machine-readable format for design system documentation

This standard structures design system documentation in an interoperable format. It currently covers components, design tokens, themes, styles, and patterns. Its goal is to act as a design system's single source of truth to feed documentation, train agents, and populate all system touchpoints.

Core tenets

Information is more valuable when it's portable. Tools change. Needs change. Budgets change. A design system's source of truth should handle any rehaul, reorg, or rethink.
Documentation shouldn't have to pick a side. Humans, parsers, and agents all need access to documentation. Teams shouldn't have to serve each independently. This standard aims to be the source of truth for everyone and everything it serves.
A format that grows with you. Getting started should be easy–but a documentation standard should be able to its system's needs.

Flexible and modular

Design systems have different documentation needs. The schema's structure aims to be as basic or as detailed as needed. DSDS is opinionated–but not heavy handed about it.

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.

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.