Design System Documentation Spec (DSDS) v0.2.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. Items may be inlined or referenced via a $ref object pointing to another DSDS file.
Min items: 1

A single entity document — one component, token, token group, theme, style, or pattern. Use this instead of documentation when each entity lives in its own file. The kind field on the entity identifies its type.

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.

2 definitions in this file:

fileRef
documentationGroup

A relative or absolute URI pointing to a DSDS file, optionally with a JSON Pointer fragment identifying the target value within that file.

Human-readable name of the collection (e.g., 'Acme Design System', 'Color Tokens', 'Button Documentation'). This is already a display label — it does NOT have an identifier counterpart and need not match a slug pattern.

Component entities in this documentation group. Each item describes a UI component — its anatomy, variants, states, accessibility guidelines, and usage rules. Items may be inlined or referenced via a $ref object pointing to another DSDS file.

Token group entities in this documentation group. Each item describes a collection of related design tokens — colors, spacing, typography scales, etc. Items may be inlined or referenced via a $ref object pointing to another DSDS file.

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). Items may be inlined or referenced via a $ref object pointing to another DSDS file.

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). Items may be inlined or referenced via a $ref object pointing to another DSDS file.

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). Items may be inlined or referenced via a $ref object pointing to another DSDS file.

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