Design System Documentation Standard (DSDS) v0.1

Root Properties

The DSDS spec version this document conforms to.

One or more documentation groups. Each group is a named collection that organizes entities into separate typed arrays — components, tokenGroups, themes, styles, and patterns. Multiple groups let a single DSDS file organize entities into logical sections (e.g., one group for foundations, another for components). All entity arrays are optional; a group only needs a name.
Min items: 1

URI reference to the DSDS JSON Schema for validation.

Declares that this DSDS document inherits from another DSDS document — typically a core design system. The base document provides the foundational entities. This document layers on top, adding or extending entities. Enables systems-of-systems architectures where product- or brand-specific systems inherit from a shared core.

The purpose of the design system as a whole — why it exists, what problems it solves, and who it serves. Helps stakeholders, new team members, and external consumers understand the system's intent before exploring individual components or tokens.

System-level best practices that apply across the entire design system — broad guidance for teams adopting, contributing to, or consuming the system. These are not component-specific rules (those live in each entity's guidelines array) but cross-cutting principles like 'always use semantic tokens instead of raw values' or 'test all components at 200% zoom'. Each entry is a self-contained rule paired with a rationale.

Human-readable name of the collection (e.g., 'Acme Design System', 'Color Tokens', 'Button Documentation').

Component entities in this documentation group. Each item describes a UI component — its anatomy, variants, states, accessibility guidelines, and usage rules.

Token group entities in this documentation group. Each item describes a collection of related design tokens — colors, spacing, typography scales, etc.

Theme entities in this documentation group. Each item describes a theme — a named set of token overrides that customize the visual appearance of the system (e.g., light/dark mode, brand variations).

Style entities in this documentation group. Each item describes a reusable visual style — a named combination of token values that can be applied to elements (e.g., elevation levels, text styles).

Pattern entities in this documentation group. Each item describes a UX pattern — a reusable solution to a common design problem, composed of one or more components (e.g., form validation, empty states, navigation flows).

References: richText, component, tokenGroup, theme, style, pattern, extensions