Schema architecture
The DSDS schema uses three directories plus a root schema:
| Directory | Contents |
|---|
| common/ | Shared primitives used across all schemas — richText, statusObject, link, example, extensions, metadata, useCases |
| entities/ | Entity type schemas — component, token (including tokenGroup), theme, style, pattern |
| document-blocks/ | Document block type schemas — guideline, anatomy, api, variant, state, design-specifications, accessibility, purpose, scale, principle, motion, content, interaction, plus the scoped union (document-blocks.schema.json) |
spec/schema/
├── dsds.schema.json # Root document schema
├── dsds.bundled.schema.json # Auto-generated single-file bundle
├── common/ # Shared primitives
│ ├── agent-collection.schema.json # agentCollection (multi-entity agent context)
│ ├── agents.schema.json # agents (agent context for AI/LLM consumption)
│ ├── example.schema.json # example, examples (guideline container), presentations
│ ├── extensions.schema.json # $extensions
│ ├── link.schema.json # link (external resources + internal artifact references)
│ ├── system-metadata.schema.json # systemMetadata
│ ├── rich-text.schema.json # richText
│ ├── purpose.schema.json # purpose, useCase
│ └── status.schema.json # statusValue, statusObject, platformStatus
├── entities/ # Artifact types
│ ├── component.schema.json # component
│ ├── pattern.schema.json # pattern
│ ├── style.schema.json # style
│ ├── theme.schema.json # theme, tokenOverride
│ └── token.schema.json # token, tokenGroup
└── document-blocks/ # Document block types
├── document-blocks.schema.json # Scoped unions: componentDocumentBlock, styleDocumentBlock, etc.
├── accessibility.schema.json # accessibility, keyboardInteraction, ariaAttribute, colorContrast
├── anatomy.schema.json # anatomy, anatomyEntry
├── api.schema.json # api, apiProperty, apiEvent, apiSlot, etc.
├── guideline.schema.json # guideline, guidelineEntry
├── content.schema.json # content, contentLabelEntry, localizationEntry
├── design-specifications.schema.json # designSpecifications, spacingSpec, sizingSpec, etc.
├── interaction.schema.json # interactions, interactionEntry
├── motion.schema.json # motion, motionEntry, motionDuration
├── principle.schema.json # principles, principleEntry
├── scale.schema.json # scale, scaleStep
├── state.schema.json # states, stateEntry
└── variant.schema.json # variants, variantEntry, variantValue, variantExclusion
Document structure
A DSDS file is a JSON object with a required dsdsVersion and exactly one of two primary shapes: a documentation array for multi-entity documents, or an entity object for single-entity files. Every valid DSDS document must have one or the other.
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.
Documentation groups
Each entry in documentation is a named collection of typed entities. Entities are organized into separate typed arrays — one for each entity kind. All arrays are optional; include only the ones your documentation needs.
Every entity array accepts either inline entity objects or $ref objects pointing to external DSDS files (see Multi-file documents). The documentation array itself also accepts $ref objects, allowing whole groups to be defined in separate files.
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.
Single-entity documents
When each entity lives in its own file, use the entity property instead of documentation. The kind field on the entity identifies its type.
{
"$schema": "https://designsystemdocspec.org/v0.2.1/dsds.bundled.schema.json",
"dsdsVersion": "0.2.1",
"entity": {
"kind": "component",
"identifier": "button",
"name": "Button",
"metadata": [
{ "kind": "description", "value": "An interactive element that triggers an action." },
{ "kind": "status", "status": "stable" }
],
"documentBlocks": []
}
}
Valid kind values for entity: "component", "token", "token-group", "theme", "style", "pattern".
Multi-file documents
Entity arrays support $ref JSON Reference objects alongside inline entities. This allows large design systems to split documentation across individual files while maintaining a single manifest that assembles them.
Each $ref object has one property: $ref. Its value is a URI or relative path to a DSDS file, optionally followed by a JSON Pointer fragment that targets a specific value within that file.
Individual entity file (button.dsds.json):
{
"dsdsVersion": "0.2.1",
"entity": {
"kind": "component",
"identifier": "button",
"name": "Button",
"metadata": []
}
}
Manifest file (index.dsds.json):
{
"dsdsVersion": "0.2.1",
"documentation": [
{
"name": "Acme Design System",
"components": [
{ "$ref": "./button.dsds.json#/entity" },
{ "$ref": "./link.dsds.json#/entity" }
],
"tokenGroups": [
{ "$ref": "./tokens/color.dsds.json#/entity" }
]
}
]
}
The #/entity fragment is a JSON Pointer — it pulls the entity value out of the referenced file. Tooling resolves all $ref objects into a merged document before validation, using a library such as json-schema-ref-parser. The schema validates the structure of $ref objects; resolution and deep validation of referenced content is the responsibility of consuming tooling.
Entity type discriminators
Every entity carries a type property that identifies its kind. The type is a required string const on every entity schema. Entities live in typed arrays (components, tokenGroups, themes, styles, patterns), so the array name already pins the expected type. The type property is still required on each entity for self-description and validation.
| type value | Array | Entity | Defined in |
|---|
| "component" | components | A reusable UI component | entities/component.schema.json |
| "token" | — | A single design token (nested inside token groups via children) | entities/token.schema.json |
| "token-group" | tokenGroups | A nested group of related tokens (recursive) | entities/token.schema.json |
| "theme" | themes | A named set of token value overrides | entities/theme.schema.json |
| "style" | styles | A macro-level visual style (foundation) | entities/style.schema.json |
| "pattern" | patterns | A broad interaction pattern | entities/pattern.schema.json |
Each typed array accepts only its matching entity type. A documentation group uses as many or as few arrays as needed:
{
"name": "Acme Design System",
"components": [
{ "type": "component", "identifier": "button", "..." }
],
"tokenGroups": [
{ "type": "token-group", "identifier": "color-palette", "..." }
],
"themes": [
{ "type": "theme", "identifier": "dark", "..." }
],
"styles": [
{ "type": "style", "identifier": "spacing", "..." }
],
"patterns": [
{ "type": "pattern", "identifier": "empty-state", "..." }
]
}
Metadata
The name of the design system.
The version of the design system.
The organization that maintains the system.
URL to the system's documentation site.
SPDX license identifier or license URL.
Root purpose
The optional purpose property on the root document describes the design system: what it is for, who it serves, and when teams should or should not adopt it. This is a system-level property; it applies to the design system as a whole, not to each entity.
{/* Hand-rolled: the root purpose object is defined inline in dsds.schema.json and has no entry in $defs, so it can't be rendered by the shortcode. */}
| Property | Type | Required | Description |
|---|
| description | richText | No | A high-level description of the design system's purpose and goals. |
| useCases | array | No | An array of use-case entries describing positive and negative adoption scenarios. |
Each use-case entry has this shape:
Describes the scenario. Should be concrete and situation-driven — describe the user's situation, not the artifact's features.
Whether the use case is an example to follow or to avoid.
The recommended alternative artifact for this scenario. Typically provided for whenNotToUse entries to direct the reader toward a more appropriate component, pattern, or token.
{
"purpose": {
"description": "Acme DS provides a unified component library for all customer-facing web products.",
"useCases": [
{
"description": "Building a new customer-facing web application on the Acme platform.",
"kind": "positive"
},
{
"description": "Building internal tooling with specialized data-heavy dashboards.",
"kind": "negative",
"alternative": {
"identifier": "Acme Admin Kit",
"rationale": "Admin Kit is optimized for data-dense internal interfaces."
}
}
]
}
}
Root best practices
The optional bestPractices property on the root document defines cross-cutting rules for the whole design system — not for any single entity. These are system-wide conventions like "always use semantic tokens" or "test all components at 200% zoom."
Each bestPractices entry uses the same shape as a guideline entry (guidelineEntry):
The guidance statement. MUST be concrete and unambiguous. Avoid vague phrases like 'use sparingly' or 'when possible'.
How strictly the guideline should be followed. Values align with RFC 2119: 'required' (MUST — non-compliance is a defect), 'encouraged' (SHOULD — follow in most cases; exceptions need justification), 'informational' (MAY — advisory only), 'discouraged' (SHOULD NOT — avoid unless justified), 'prohibited' (MUST NOT — violations are defects). Defaults to 'informational'.
Default: "informational"
Why this guidance exists. Cite evidence, accessibility standards, or user research when available. MUST NOT restate the guidance.
The discipline this guideline belongs to. Used to group guidelines by concern. Standard values: 'visual-design' (color, typography, spacing, layout), 'interaction' (behavior, animation, transitions, gestures), 'accessibility' (inclusive design, assistive tech, WCAG), 'content' (text, imagery, tone, voice, labeling), 'motion' (animation timing, easing, reduced-motion), 'development' (implementation patterns, performance, code conventions). Custom values are allowed and SHOULD be lowercase kebab-case.
The anatomy part or content area this guideline applies to (e.g., 'label', 'icon', 'helper-text'). When omitted, the guideline applies to the whole artifact.
Criteria this guideline addresses or defines. Each entry is either an external reference (citing a published standard such as WCAG) or an internal criterion (defining a testable success condition owned by this design system). External references cite an authoritative external rule. Internal criteria support WCAG-style governance: a stable, author-owned identifier anchors the criterion across edits, and tooling can derive citable display codes from those identifiers via a persistent registry. Authors SHOULD attach internal criteria only to guidelines whose success condition is objectively verifiable.
Examples showing encouraged and discouraged approaches.
Freeform keywords that relate guidelines across categories and disciplines (e.g., 'rtl', 'localization', 'validation', 'contrast').
{
"bestPractices": [
{
"guidance": "Always use semantic tokens instead of raw color values.",
"rationale": "Semantic tokens ensure consistent theming and make future design changes non-breaking.",
"kind": "required",
"category": "development"
},
{
"guidance": "Test all components at 200% browser zoom.",
"rationale": "WCAG 1.4.4 requires content to remain functional at 200% zoom.",
"kind": "required",
"category": "accessibility",
"criteria": [
{
"url": "https://www.w3.org/TR/WCAG22/#resize-text",
"label": "WCAG 1.4.4 Resize Text"
}
]
},
{
"guidance": "Do not override token values at the component level.",
"rationale": "Component-level overrides break theme consistency and make system-wide updates unreliable.",
"kind": "prohibited",
"category": "development"
}
]
}
System-level vs. entity-level: The root purpose and bestPractices properties describe the design system as a whole. They differ from the entity-level purpose and guideline document block types inside each entity's documentBlocks array. Entity-level document block entries describe when and how to use a specific component, token, or pattern. System-level properties describe when and how to use the design system itself. Both levels follow the same structure but serve different audiences and scopes.
Entity types
Every entity shares a common set of identity and metadata properties, plus a documentBlocks array for all structured docs. The documentBlocks array accepts only the document block types suited to that entity type. Every entity also carries a required type discriminator (see Entity Type Discriminators).
Common entity properties
These properties are on all entity types. Required fields differ by entity type — see the notes column and each entity section.
{/* Hand-rolled: cross-entity summary that intentionally diverges from any single schema. */}
| Property | Type | Required | Notes |
|---|
| type | string | Yes | Entity type discriminator. |
| identifier | string | Yes | Machine-readable identifier. Components, styles, patterns, and themes enforce ^[a-z][a-z0-9-]*$. Token and token-group identifiers are unconstrained by design (see Token Identifier Exception). |
| name | string | Varies | Human-readable name. Required on component, style, pattern, theme. Not present on token or token-group — the identifier itself serves as the display label. |
| summary | string | No | One-line plain-text summary for compact display. MUST NOT contain markup. |
| description | richText | Varies | Description with CommonMark support. Required on component, style, pattern, theme. Optional on token and token-group. |
| status | statusObject | Varies | Lifecycle status with optional per-platform readiness. Required on component, style, pattern, theme. Optional on token and token-group — when omitted inside a group, inherited from the parent. |
| since | string | No | The version in which this entity first shipped. |
| tags | string[] | No | Freeform keywords for categorization and search. |
| aliases | string[] | No | Other names for search, migration mapping, and cross-referencing. |
| category | string | No | Classification within the system's taxonomy. |
| documentBlocks | array | No | Typed document block objects. See Document block. |
| agents | object | No | Agent-optimized context for efficient agentic consumption. See Agents. |
| links | array | No | Typed references to external resources and internal entities. See Links. |
| extends | entityExtends | No | Declares that this entity extends a base entity in a parent system. Available on component and token entities. See Extends. |
| $extensions | object | No | Vendor-specific extensions. See Extensions. |
Component
A reusable UI element. Accepts component-scoped document block types (anatomy, api, variants, states, design-specifications) and all general document block types.
Required properties: type, identifier, name, description, status.
Token
A single design token. Accepts general document block types only.
Required properties: type, identifier, tokenType.
More properties:
{/* Hand-rolled: this table is intentionally a delta of properties unique to Token beyond the common entity properties documented above, not the full Token schema. */}
| Property | Type | Required | Description |
|---|
| tokenType | string | Yes | DTCG-aligned token type (e.g., "color", "dimension", "fontFamily", "fontWeight", "duration", "cubicBezier", "shadow"). |
| source | string | No | URI or relative path to the W3C DTCG file that contains this token's authoritative definition. |
| category | string | No | Semantic category: "base", "semantic", "component". Custom values permitted. |
DSDS does not duplicate token values or platform identifiers. The W3C Design Tokens Format file is the source of truth for values. Use the source property to link tokens to their DTCG definitions.
Tokens have no separate name property by design. The token identifier itself serves as the human-readable display label. Token identifier conventions (dots, slashes, kebab-case) are already human-readable in their native format.
The description and status properties are optional on tokens to reduce verbosity at scale. When omitted inside a token group, status inherits from the parent group.
Token group
A nested group of related tokens. The children array can hold token objects, nested token group objects, or a mix of both — forming a recursive tree of any depth. Accepts general document block types only.
Required properties: type, identifier.
More properties:
{/* Hand-rolled: this table is intentionally a delta of properties unique to Token group beyond the common entity properties documented above, not the full Token group schema. */}
| Property | Type | Required | Description |
|---|
| tokenType | string | No | Inherited default for children that omit their own tokenType. |
| category | string | No | Inherited default for children that omit their own category. |
| children | array | No | Recursive array of tokens and/or nested token groups. |
Like tokens, name, description, and status are optional. Children inherit tokenType, category, and status from the parent group when they omit their own values.
Theme
A named set of token overrides that adapt the system to a specific context (color mode, density, brand variant). Accepts general document block types.
Required properties: type, identifier, name, description, status, overrides.
More properties:
{/* Hand-rolled: this table is intentionally a delta of properties unique to Theme beyond the common entity properties documented above, not the full Theme schema. */}
| Property | Type | Required | Description |
|---|
| overrides | tokenOverride[] | Yes | Array of token identifiers that differ from the default in this theme. Only tokens that change need to be listed. |
| source | string | No | URI or relative path to the W3C DTCG file that contains this theme's authoritative token values. |
Each tokenOverride identifies a token by token (the token identifier). Override values live in the DTCG source file, not in DSDS.
Style
A macro-level visual style (foundation) governing a domain like color, typography, spacing, elevation, motion, or content. Accepts style-scoped document block types (principles, scale, motion) and all general document block types.
Required properties: type, identifier, name, description, status.
Styles document base visual attributes like color and spacing, plus cross-cutting concerns like accessibility, motion systems, and content rules. The category property classifies the domain (e.g., "color", "typography", "spacing", "motion", "accessibility", "content").
Pattern
A broad interaction pattern — a recurring, multi-component solution to a common UX problem. Accepts pattern-scoped document block types (interactions) and shared structural document block types (anatomy, variants, states) as well as all general document block types.
Required properties: type, identifier, name, description, status.
Patterns reference their participating components through the links array (with type: "component", identifier, and role) instead of through a dedicated guideline type.
Agents
The optional agents property provides context intended exclusively for agentic (AI/LLM) consumption. All properties are optional.
A single sentence stating the primary purpose of this entity: what problem it solves and why it exists. MUST be concrete and distinct from similar entities. Agents use it to judge relevance quickly without parsing the full description.
Hard rules for using this entity. Each constraint pairs a rule with an enforcement level aligned to RFC 2119. Agents use these to validate decisions without inferring rules from prose.
Min items: 1
Entries that resolve common confusion between this entity and similar ones. Each entry names a confusable entity and states the precise distinction. Agents use it to pick the right entity without trial and error.
Min items: 1
Common incorrect uses of this entity. Each entry describes what NOT to do and provides the correct alternative. Every entry SHOULD include an instead value — an anti-pattern without a correction is not actionable guidance. Agents use these to avoid known failure modes.
Min items: 1
Usage examples agents can apply directly. Each example pairs a description of the scenario with code or a structured representation. Prefer minimal, correct examples over exhaustive ones. For examples tied to a specific constraint, use the constraint-level examples property instead.
Min items: 1
Semantic terms that support retrieval and entity matching. Include synonyms, related concepts, common query terms, and vocabulary that designers or engineers use when searching for this entity but that may not appear in its name or description.
Min items: 1
ISO date when this agent context block was last validated against the live design system. Absence signals unverified content. Agents and tooling can use this to assess data freshness and flag stale guidance.
The package version, test run identifier, or audit reference this block was validated against. Provides traceability for empirical data. Example: '@sanity/ui@3.2.0', 'agent-test-run-2026-05-30', 'a11y-audit-Q2-2026'.
{
"agents": {
"intent": "Trigger a user action within the current view without causing page navigation.",
"constraints": [
{ "rule": "Do not use for navigation between pages.", "level": "must-not" }
],
"disambiguation": [
{ "entity": "link", "distinction": "Use button for in-page actions; use link for navigation to a URL." }
],
"keywords": ["action", "submit", "click", "CTA", "trigger"]
}
}
Block-level agents
Document blocks also accept the same optional agents object. Block-level agent context is scoped to that specific documentation section — an anatomy block's agents might disambiguate part naming, while a guideline block's agents might provide enforcement constraints for AI code generation.
{
"kind": "guideline",
"items": ["..."],
"agents": {
"intent": "Enforce correct Button usage in generated UI code.",
"constraints": [
{ "rule": "Never place two primary buttons on the same surface.", "level": "must-not" }
],
"keywords": ["button rules", "best practices", "usage guidelines"]
}
}
Agent context collections
For system-wide agent guidance spanning many entities, use agent-collection.schema.json. A collection file contains named sections, each validated as a full agents block:
{
"name": "Pre-Generation Checklist",
"updated": "2025-07-19",
"sections": {
"button": {
"intent": "Use Button for all interactive action triggers.",
"constraints": [
{ "rule": "Never override height below 36px.", "level": "must", "evidence": "9/10 agent test runs failed." }
],
"verified": "2025-07-19"
}
}
}
Status
The statusObject groups lifecycle status, per-platform readiness, and deprecation notices into a single object. Every entity that carries status uses this object instead of a bare string.
Overall lifecycle status of the artifact. An editorial judgment of maturity; it need not match the most or least advanced platform status. Tools SHOULD display this as the primary status indicator.
Per-platform readiness. Keys are platform identifiers (freeform strings; common values include 'react', 'web-component', 'ios', 'android', 'flutter', 'figma', 'sketch', 'compose'). Values describe the artifact's status on that platform. An artifact MAY be 'stable' overall while individual platforms are still 'experimental' or 'draft'.
Required when status is 'deprecated'. MUST say what to use instead and give a migration path. Tools SHOULD display this prominently next to the status indicator.
Status values
Status values MUST be lowercase kebab-case (pattern: ^[a-z][a-z0-9-]*$). The four standard values are:
| Value | Meaning |
|---|
| draft | Under development, not ready for use. |
| experimental | Available but API may change without notice. |
| stable | Production-ready, changes follow semver. |
| deprecated | Scheduled for removal. deprecationNotice is required. |
Custom values are permitted (e.g., "sunset", "archived", "beta") and MUST follow the same pattern.
Platform status entry
Lifecycle status of the artifact on this platform. Uses the same vocabulary as the top-level status: 'draft', 'experimental', 'stable', 'deprecated'. Custom values are allowed.
The version in which this artifact became available on this platform.
Required when status is 'deprecated'. Says what to use instead on this platform.
Notes about the artifact's status on this platform (e.g., 'Available as a Web Component wrapper; native implementation planned for v4').
Document block
Document block entries are the core unit of structured docs in DSDS. Every piece of docs on an entity is a document block object with a type discriminator. Document block types cover:
- guidelines, purpose, accessibility, examples, and content (general — all entity types)
- anatomy, API specs, variants, states, and design specifications (component-scoped)
- principles, scales, and motion definitions (style-scoped)
- interactions (pattern-scoped)
Scoped document block unions
Each entity type accepts only the document block types relevant to it. The scoping rationale:
- Components get full structural docs. They are rendered UI elements with code-level interfaces, visual anatomy, configurable dimensions, interactive states, and measurable design specs.
- Patterns get structural docs without code-level details — they have visual layouts (anatomy), sub-types (variants), and states, but they are not single-component code interfaces. They do not accept api or design-specifications.
- Styles get domain-level docs — they govern a visual or cross-cutting domain through guiding principles, constrained value progressions (scales), and motion definitions.
- Tokens get only general document block types — they are atomic values with usage guidance but no visual structure or interaction behavior.
| Scope | Used by | Accepts |
|---|
| Component | component | import, anatomy, api, events, variants, states, design-specifications + general |
| Pattern | pattern | interactions, events, anatomy, variants, states + general |
| Style | style | principles, scale, motion + general |
| Token | token, token-group, theme | general only |
General (available on all entity types): guideline, purpose, accessibility, examples, content.
Document block types
| Type value | Container property | Item type | Scope | Description |
|---|
| "import" | items | importEntry | Component | Platform-specific import statements — packages, code snippets, and setup context. |
| "guideline" | items | guidelineEntry | General | Actionable usage rules with rationale and enforcement levels. |
| "purpose" | useCases | useCases (whenToUse/whenNotToUse) | General | Scenario-driven guidance for when to use and when not to use an entity. |
| "accessibility" | Named properties | various | General | Structured a11y specs — keyboard, ARIA, screen reader, contrast, motion. |
| "examples" | items | example | General | Visual/interactive demos — images, videos, code, URLs, values. |
| "content" | labels, localization | contentLabelEntry, localizationEntry | General | Recommended action labels and localization/i18n notes. |
| "anatomy" | parts | anatomyEntry | Component, Pattern | Visual structure broken into named parts with token references. |
| "api" | Named arrays | various | Component | Code-level interface — props, events, slots, CSS hooks, methods. |
| "events" | items | eventEntry | Component, Pattern | Events emitted by the component — trigger conditions, return shapes, DOM behavior, lifecycle. |
| "variants" | items | variantEntry | Component, Pattern | Dimensions of variation with enumerated values. Optional exclusions. |
| "states" | items | stateEntry | Component, Pattern | Interactive states with triggers, token overrides, and previews. |
| "design-specifications" | Named properties | various | Component | Token inventory, spacing, sizing, typography, responsive behavior. |
| "principles" | items | principleEntry | Style | High-level guiding beliefs that shape decisions. |
| "scale" | steps | scaleStep | Style | Ordered progression of token values (spacing scale, type scale, etc.). |
| "motion" | items | motionEntry | Style | Named easing curves with cubic-bezier functions and recommended durations. |
| "interactions" | items | interactionEntry | Pattern | Ordered steps in a pattern's interaction flow. |
Every document block type accepts an optional agents property — the same structure available on entities. Use it to provide AI/LLM context scoped to a specific documentation section.
General document block types
These document block types are available on all entity types.
Guideline (guideline)
Documents actionable usage rules for an entity. Each item is a self-contained rule pairing guidance with a rationale. Guidelines tell the reader how to use the entity correctly after choosing it. For guidance on whether to use it at all, see Purpose.
Guideline entry
The guidance statement. MUST be concrete and unambiguous. Avoid vague phrases like 'use sparingly' or 'when possible'.
How strictly the guideline should be followed. Values align with RFC 2119: 'required' (MUST — non-compliance is a defect), 'encouraged' (SHOULD — follow in most cases; exceptions need justification), 'informational' (MAY — advisory only), 'discouraged' (SHOULD NOT — avoid unless justified), 'prohibited' (MUST NOT — violations are defects). Defaults to 'informational'.
Default: "informational"
Why this guidance exists. Cite evidence, accessibility standards, or user research when available. MUST NOT restate the guidance.
The discipline this guideline belongs to. Used to group guidelines by concern. Standard values: 'visual-design' (color, typography, spacing, layout), 'interaction' (behavior, animation, transitions, gestures), 'accessibility' (inclusive design, assistive tech, WCAG), 'content' (text, imagery, tone, voice, labeling), 'motion' (animation timing, easing, reduced-motion), 'development' (implementation patterns, performance, code conventions). Custom values are allowed and SHOULD be lowercase kebab-case.
The anatomy part or content area this guideline applies to (e.g., 'label', 'icon', 'helper-text'). When omitted, the guideline applies to the whole artifact.
Criteria this guideline addresses or defines. Each entry is either an external reference (citing a published standard such as WCAG) or an internal criterion (defining a testable success condition owned by this design system). External references cite an authoritative external rule. Internal criteria support WCAG-style governance: a stable, author-owned identifier anchors the criterion across edits, and tooling can derive citable display codes from those identifiers via a persistent registry. Authors SHOULD attach internal criteria only to guidelines whose success condition is objectively verifiable.
Examples showing encouraged and discouraged approaches.
Freeform keywords that relate guidelines across categories and disciplines (e.g., 'rtl', 'localization', 'validation', 'contrast').
Enforcement levels align with RFC 2119 requirement levels:
| Level | RFC 2119 | Meaning |
|---|
| required | MUST | Non-compliance is a defect. |
| encouraged | SHOULD | Follow in most cases; exceptions require justification. |
| informational | MAY | Advisory context with no enforcement expectation. |
| discouraged | SHOULD NOT | Avoid unless justified. |
| prohibited | MUST NOT | Violations are defects. |
Purpose (purpose)
Documents what an entity is for — the concrete scenarios where it is the right choice and where a different entity fits better. Purpose document block entries help the reader decide whether to reach for this entity before they start using it.
The purpose document block type wraps the common useCases data model with a type discriminator:
{
"type": "purpose",
"useCases": {
"whenToUse": [
{ "description": "When the user needs to trigger an action such as submitting a form." }
],
"whenNotToUse": [
{
"description": "When the action navigates to a different page.",
"alternative": {
"identifier": "link",
"rationale": "Links carry native navigation semantics."
}
}
]
}
}
This uses the same useCases shape as variant values and state entries (full model in Use Cases).
Accessibility (accessibility)
Documents structured accessibility specs. It captures machine-readable specs for:
- keyboard interactions
- ARIA attributes
- screen reader behavior
- focus management
- color contrast pairs
- motion concerns
For actionable accessibility rules with rationale (e.g., "Provide an aria-label for icon-only buttons"), use a guideline entry with category: "accessibility" instead.
Identifies this guideline as an accessibility spec.
The minimum WCAG conformance level targeted by this artifact. Most design systems target AA. Set to AAA when the artifact exceeds standard requirements.
Keyboard interaction specs — what happens when each key or key combination is pressed while the artifact has focus.
ARIA attribute docs. Lists every ARIA attribute the artifact uses, what it communicates, and when to apply it.
How the artifact is announced by screen readers in various states. Include announcements for default, focused, disabled, loading, expanded, and other relevant states. Name specific screen readers (VoiceOver, NVDA, JAWS) when behavior differs.
How focus moves into, within, and out of the artifact. Document focus trapping (for modals/dialogs), focus restoration (when dismissing overlays), and programmatic focus movement. Describe both keyboard and programmatic focus behavior.
Contrast ratio documentation for foreground/background color pairs used by this artifact. Each entry documents a specific pairing, its measured ratio, and the WCAG level it meets.
How the artifact respects the prefers-reduced-motion media query. Document what animations or transitions exist and what happens when reduced motion is preferred (e.g., 'The loading spinner is replaced with a static ellipsis indicator').
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
Examples (examples)
Documents visual or interactive demos of an entity. Each item is a single demo — a static image, a video, a code snippet, a URL to a live demo, or a literal value.
Each example requires at least a presentation or a value (or both):
- Presentation: A visual or interactive demo — one of presentationImage, presentationVideo, presentationCode, or presentationUrl.
- Value: A literal value for API property examples (e.g., "primary", 44, true). When given without a presentation, the example is a concrete data point.
Optional title and description provide context.
Content (content)
Documents structured content documentation — recommended action labels and localization/i18n concerns. Content document block entries complement guideline document block entries: guidelines say "Use sentence case" (a rule), content entries say "Add: Takes an existing object and uses it in a new context" (a reference).
At least one of labels or localization must be present.
Content label entry
The recommended label text (e.g., 'Add', 'Cancel', 'Delete', 'Save as', 'Learn more'). The canonical form as it should appear in the UI.
What this label means — the action it represents. Should be concrete and unambiguous (e.g., for Delete: 'Destroys an existing object so that it no longer exists').
When and how to use this label. Include context, formatting rules, and any caveats (e.g., 'Where appropriate, combine Add with the object: Add user, Add role').
Related terms that serve a different purpose but are often confused with this one. Listed for comparison; helps authors pick the right label. The terms SHOULD match other term values in the same content guideline so tools can cross-reference them.
Where this label is used in the UI (e.g., 'Buttons in dialogs', 'Navigation links', 'Form submission', 'Toolbar actions'). Tells authors where the label normally appears.
Visual or code examples showing the label in context: do/don't pairs, screenshots of correct usage, or code snippets.
Localization entry
The localization concern being addressed. Standard values: 'rtl' (right-to-left layout mirroring and bidirectional text), 'text-expansion' (content lengthening during translation), 'pluralization' (plural forms varying across languages), 'date-format' (date and time formatting conventions), 'number-format' (decimal separators, grouping), 'currency' (currency symbol placement and formatting), 'text-direction' (mixed-direction content within a single string), 'icon-direction' (icons that imply directionality), 'truncation' (text overflow behavior across languages), 'sorting' (locale-specific sort order and collation), 'concatenation' (avoiding string concatenation that breaks in other languages). Custom values are allowed and SHOULD be lowercase kebab-case.
Guidance for handling this localization concern. Should be actionable and specific: say what changes across locales, what the author or developer must do, and what to avoid.
Visual or code examples that illustrate the concern: before/after screenshots for RTL, samples of text expansion, or code patterns for pluralization.
Component-scoped document block types
These document block types are only accepted on component entities.
Anatomy (anatomy)
Documents the visual structure of a component or pattern by listing its named sub-elements (parts). Each part can reference the design tokens that style it, bridging the entity's visual design and its token architecture.
For components, parts represent rendered UI sub-elements (container, label, icon, focus-ring). For patterns, parts represent the structural sections of the pattern's visual layout (image, title, body, primary action).
Anatomy entry
Machine-readable identifier for the part (e.g., 'container', 'label', 'icon', 'focus-ring').
What this part is, what it does, and any constraints on its content or appearance.
Whether this part is always present in the rendered output. Defaults to false. When false, the part is conditionally rendered based on props or content.
Default: false
Human-readable name (e.g., 'Container', 'Label', 'Leading Icon').
Design tokens applied to this part. Keys are token-purpose names describing what visual attribute the token controls (e.g., 'background', 'border-radius', 'padding-horizontal', 'text-color'). Values are the token identifiers that provide the value (e.g., 'color-action-primary', 'radius-md', 'space-4').
Links to resources for this anatomy part — design tool nodes, source code blocks, documentation sections, or other addressable references.
API (api)
Documents the code-level interface of a component on a single platform. For multi-platform components, create one API guideline per platform using the platform property.
Sections:
- properties (apiProperty[])
- events (apiEvent[])
- slots (apiSlot[])
- cssCustomProperties (apiCssCustomProperty[])
- cssParts (apiCssPart[])
- dataAttributes (apiDataAttribute[])
- methods (apiMethod[])
Property entry (apiProperty)
The property identifier as used in code (e.g., 'variant', 'size', 'disabled', 'onClick').
The property's type as it would appear in a type signature (e.g., 'boolean', 'number', 'string', 'ReactNode', 'IconComponent'). For enum properties, use values instead of encoding members here.
What this property controls, how it affects the component, and any constraints or side effects.
Whether the consumer must provide this property. Defaults to false.
Default: false
The accepted values for enum-like properties (e.g., ['default', 'primary', 'ghost']). Use this instead of encoding members in type.
A JSON Schema (Draft 2020-12) object defining the property's type in machine-readable form. Follows the same conventions as OpenAPI parameter schemas.
The default value in its native JSON type. Accepts any JSON type: string, number, boolean, object, array, or null.
Example values for this property.
The version in which this property was introduced.
Whether this property is deprecated. Defaults to false.
Default: false
What to use instead, if deprecated.
For enum properties, set type to the base type ("string") and list the accepted values in values:
{
"identifier": "variant",
"type": "string",
"values": ["default", "primary", "ghost", "danger"],
"description": "The visual style of the button.",
"required": false,
"defaultValue": "default"
}
Event entry (apiEvent)
The event identifier (e.g., 'onClick', 'onChange', 'onDismiss').
When this event fires, what it communicates, and how consumers should respond.
Description of the event return shape (e.g., '(event: MouseEvent) => void', '{ value: string, index: number }').
The version in which this event was introduced.
Variants (variants)
Documents all dimensions of visual or behavioral variation. Each item is a single axis of config (e.g., "size", "emphasis", "full-width"). Multiple axes document orthogonal dimensions that combine independently.
The optional exclusions array documents invalid combinations across dimensions:
{
"type": "variants",
"items": [
{ "identifier": "emphasis", "description": "...", "values": [...] },
{ "identifier": "size", "description": "...", "values": [...] }
],
"exclusions": [
{
"conditions": [
{ "dimension": "emphasis", "value": "ghost" },
{ "dimension": "size", "value": "sm" }
],
"description": "Ghost emphasis at small size does not provide adequate visual affordance."
}
]
}
Each exclusion requires at least two conditions. A single condition would exclude a whole value, which should be removed from the dimension's values array instead.
Variant value
Machine-readable value identifier (e.g., 'sm', 'md', 'lg', 'primary', 'secondary').
What this value looks like, when to use it, and how it differs from other values in this dimension.
Human-readable name (e.g., 'Small', 'Medium', 'Large', 'Primary', 'Secondary').
Why this flag exists — the user need or design rationale it addresses (e.g., 'Prevents user interaction during form submission to avoid duplicate requests').
Visual previews showing this variant value in isolation or in context.
States (states)
Documents all interactive states — hover, focus, active, disabled, loading, selected, error, etc. — with triggers, token overrides, and previews.
State entry
Machine-readable state identifier (e.g., 'default', 'hover', 'focus', 'active', 'disabled', 'loading', 'selected', 'error', 'read-only').
What triggers this state, how appearance and behavior change, and any constraints or side effects.
Human-readable name (e.g., 'Default', 'Hover', 'Focus', 'Active / Pressed', 'Disabled', 'Loading').
Design token overrides applied when this state is active. Keys are token property names scoped to the component (e.g., 'button-background', 'button-border-color'). Values are the token identifiers or resolved values used in this state. Only tokens that change from the default state need to be listed. Note: these token references are descriptive summaries for designers. Authoritative resolved values for each variant × state combination live in the design-specifications guideline's overrides array.
Why this state exists — the user need or design rationale it addresses.
Visual previews showing the component in this state.
Design specifications (design-specifications)
Documents measurable visual specs — token inventory, spacing relationships, dimension constraints, typography settings, and responsive behavior. At least one section must be present.
Identifies this guideline as a design specs document.
Base design properties for the default config. Keys are property names describing what each value controls (e.g., 'background', 'text-color', 'border-radius'). Values are design token names or raw CSS values.
Base spacing spec for the default config.
Base sizing spec for the default config.
Base typography spec for the default config.
Responsive behavior describing how the component adapts across breakpoints. Entries are ordered from smallest to largest breakpoint.
Design properties grouped by variant. Each entry is a full set of property-to-value mappings for one variant. Values are the variant's own tokens (e.g., 'button-primary-bg') or raw values — not overrides of base tokens.
Design properties grouped by size. Each entry defines the dimensions, spacing, typography, and other properties that change at each size step.
Design properties grouped by interactive state. Each entry defines properties that change when the component enters a given state. Only properties that differ from the default need to be listed.
Design properties for specific variant–state combinations where the state's visual treatment differs across variants. Only needed when a single state entry cannot describe the behavior across all variants.
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
Variants, sizes, and states
The base-level properties map defines the default spec — typically the primary variant at medium size in the default state. Values are always strings: either design token names (e.g., "button-background", "space-4") or raw CSS values (e.g., "#0055b3", "16px", "transparent"). Systems that do not use tokens provide raw values directly.
The remaining arrays group design properties by condition:
- variants — by variant. Each entry has an identifier and its own properties map, plus optional spacing, sizing, and typography sections.
- sizes — by size, including size-specific spacing, sizing, and typography.
- states — by interactive state (e.g., hover, focus, disabled).
The variantStates array handles variant×state combinations where the state's visual treatment differs across variants. Each entry specifies both a variant and a state along with the properties map for that combination.
Each entry is self-contained — it holds the complete set of values for that condition, not a diff of the base properties. For example, a "danger" variant entry carries its own token names (like "button-danger-bg") or raw values, independent of the base properties.
Note: the tokens field on state entries (in the states guideline) is a descriptive summary for designers — it shows which tokens change in a given state. The authoritative resolved values for each variant × state combination live in the design-specifications guideline's variants, states, and variantStates arrays.
Style-scoped document block types
These document block types are only accepted on style entities.
Principles (principles)
Documents high-level guiding principles that shape decisions for a domain. Principles answer "what do we believe?" and "what constraints do we accept?" — they sit above specific best practices.
Each principleEntry has a title (short, memorable name) and a description (what it means in practice).
Scale (scale)
Documents an ordered progression of values forming a visual scale (type scale, spacing scale, elevation scale, or similar).
Each scaleStep references a design token and optionally provides a label, value (display convenience), and description (usage notes). Steps are ordered from smallest/lowest to largest/highest.
The scale guideline requires an identifier, description, and steps array.
Motion (motion)
Documents the motion system — named easing curves, their cubic-bezier timing functions, recommended durations, and usage guidance. Each item is a single easing definition that designers and engineers select from when adding animation or transitions.
Motion entry
Machine-readable identifier of the easing (e.g., 'expressive', 'enter', 'exit', 'lateral', 'bounce', 'linear'). Used for cross-referencing and tooling.
What this easing is for, when to use it, and how it affects the user experience. Explain the visual character of the curve and the types of transitions it suits.
Human-readable name of the easing (e.g., 'Expressive Ease', 'Enter Ease', 'Exit Ease').
Cubic-bezier control points as a four-number array [P1x, P1y, P2x, P2y], aligned with the W3C Design Tokens Format Module cubicBezier type (§8.6). P1x and P2x MUST be in [0, 1]. P1y and P2y can be any real number (values outside [0, 1] produce bounce/overshoot effects). Maps to CSS cubic-bezier() and DTCG cubicBezier token values. When omitted, the easing is described in the description field or references a token via token.
Min items: 4
Reference to a DTCG cubicBezier or transition token that defines this easing (e.g., 'motion-ease-expressive', 'transition-enter'). When both function and token are present, function is the display value and token is the authoritative source.
Recommended duration range when using this easing. Different easings suit different durations — enter transitions are typically longer (300–500ms) to draw attention, while exit transitions are shorter (200–300ms) to feel responsive.
A short, comma-separated list of usage contexts (e.g., 'entering elements', 'exiting elements', 'lateral navigation', 'micro-interactions'). Provides a scannable summary — use description for detailed guidance.
Visual or interactive examples showing this easing in action — screen recordings, interactive curve visualizations, or CSS code snippets.
Pattern-scoped document block types
These document block types are only accepted on pattern entities (in addition to the shared anatomy, variants, and states document block types).
Interactions (interactions)
Documents the interaction flow of a pattern as an ordered sequence of steps. The ordering is critical: it represents the chronological flow of the user journey.
Interaction entry
What happens during this step — the system's response, visual changes, state transitions, and user-facing feedback. CommonMark supported.
What starts this interaction step — a user action, system event, or condition (e.g., 'User submits the form by activating the submit button', 'API returns a 422 response'). When omitted, the step continues the previous step's flow without a new trigger.
Names of the components involved in this step. Each name MUST match the name of a component documented elsewhere in the system. Creates a cross-reference between the pattern's interaction flow and individual component docs.
Visual or interactive examples for this step — screenshots of the resulting state, screen recordings of the transition, or code snippets showing the implementation.
Links
The links array provides typed references to external resources and internal DSDS entity relationships. Links combine external URL references and internal entity references into a single model.
Every link requires a kind and at least one of url (for external resources) or identifier (for internal DSDS entity references). Both can be present when an internal entity also has an addressable URL.
The category of the linked resource or relationship. Standard external kinds: 'source', 'design', 'storybook', 'documentation', 'package', 'repository'. Standard relationship kinds: 'alternative', 'parent', 'child', 'related'. Standard artifact kinds (for internal references): 'component', 'token', 'token-group', 'style', 'pattern', 'theme'. Custom values are allowed and SHOULD match ^[a-z][a-z0-9-]*$.
The URL of the linked resource. MUST be a valid absolute URI. Required for external resource links. Optional for internal artifact references (where identifier names the artifact). When both url and identifier are present, url points to the artifact's docs page and identifier is the machine-readable cross-reference.
The identifier of a referenced DSDS artifact (e.g., 'button', 'form-field', 'color-text'). MUST match the identifier property of a documented DSDS artifact. Required for internal artifact references. Optional for external resource links. When present, tools SHOULD resolve this identifier against the artifact catalog to create navigable cross-references.
Display text for this link — what a user sees when the link renders (e.g., 'React component source', 'Design file — variants', 'Button component'). Use it for the display name of the resource. To describe an internal artifact's role, use role instead.
The functional role this artifact plays in the current entity (e.g., 'Primary action trigger', 'Error summary container', 'Provides semantic text color tokens'). Distinct from label, which is display text for the link itself. Use it on internal artifact references to explain *why* this artifact is linked. When omitted, the link is a general association.
Whether this linked artifact is required for the parent entity to work. Used on internal artifact references — for example, a form-validation pattern might mark 'form-field' as required and 'toast' as optional. Defaults to false. Not used on external resource links.
Default: false
Standard link types
External resource types: "source", "design", "storybook", "documentation", "package", "repository".
Relationship types: "alternative", "parent", "child", "related".
Artifact types (for internal references): "component", "token", "token-group", "style", "pattern", "theme".
Custom values are permitted and SHOULD be lowercase strings matching ^[a-z][a-z0-9-]*$.
Rich text
Fields that contain human-written prose use the richText type:
- String form: A bare JSON string, interpreted as CommonMark for backward compatibility.
- Object form: \{ "value": "...", "format": "plain" | "markdown" | "html" \} for explicit format control.
Use cases
The useCases data model provides scenario-driven guidance for when an entity or option is — and is not — the right choice. It appears in three places:
- Purpose document block type — wrapped with a type: "purpose" discriminator to appear in the document block array.
- Variant values — inline useCases property on each variant value for "when to choose this value."
- State entries — inline useCases property on each state entry for "when this state is appropriate."
In all three contexts, the shape is identical:
{
"whenToUse": [
{ "description": "Scenario description..." }
],
"whenNotToUse": [
{
"description": "Scenario description...",
"alternative": {
"identifier": "alternative-artifact",
"rationale": "Why the alternative is better."
}
}
]
}
Each whenNotToUse entry SHOULD include an alternative pointing to a more fitting entity.
Extends
The extends mechanism enables systems-of-systems architectures — where an extension design system inherits from a core system. It operates at two levels:
Document-level extends (documentExtends)
The root extends property declares that the whole DSDS document inherits from another DSDS document. This sets up the parent–child relationship between systems.
The name or identifier of the base design system being extended (e.g., 'Acme Core Design System', 'acme-core', '@acme/design-system'). A display name or a package name, not a URL. Tools use it to resolve the base system from a registry, file system, or package manager.
URL to the base DSDS document (e.g., 'https://design.acme.com/v2/core.dsds.json', './core.dsds.json'). When provided, tools MAY fetch and resolve the base document for merge, validation, or docs generation.
The version of the base system this document extends (e.g., '2.0.0', '>=2.0.0', '^3.1.0'). Follows semver. When omitted, tools SHOULD resolve to the latest available version.
Description of the relationship: what this extension adds, changes, or narrows relative to the base system.
{
"extends": {
"system": "Acme Core Design System",
"url": "https://design.acme.com/v2/core.dsds.json",
"version": "2.0.0",
"description": "Adds enterprise-specific components, stricter accessibility requirements, and product-specific token overrides."
}
}
Entity-level extends (entityExtends)
Components and tokens can declare that they extend a base entity from a parent system.
The identifier of the base entity being extended (e.g., 'button', 'color-text-primary', 'form-validation'). MUST match the identifier property of the base entity in the parent system.
The name or identifier of the system that owns the base entity (e.g., 'Acme Core Design System', 'acme-core'). When omitted, the base entity is resolved from the system declared in the root document's extends property. When provided, lets you extend from a system other than the document's default base.
Direct URL to the base entity's docs or DSDS definition. Useful for cross-linking in docs sites.
The version of the base entity or base system this entity extends (e.g., '2.0.0'). When omitted, the version comes from the document-level extends declaration.
What this entity adds or changes relative to the base: new variants, more props, overridden guidelines, and so on.
Summary of what this entity changes relative to the base. Each entry describes one change. Tools MAY use these for changelog generation, diff views, or migration guides. When omitted, consuming tools must diff the entities to find changes.
{/* Hand-rolled: the modifications array items are defined inline in common/extends.schema.json (no $defs entry), so they can't be rendered by the shortcode. */}
Each modifications entry has this shape:
| Property | Type | Required | Description |
|---|
| type | string | Yes | "added", "modified", "removed", or "inherited". |
| target | string | No | What was changed — a property name, guideline kind, variant name, etc. (e.g., "variant:enterprise", "prop:theme", "guideline:accessibility"). |
| description | richText | Yes | A human-readable description of the change. |
{
"kind": "component",
"identifier": "button",
"extends": {
"identifier": "button",
"system": "Acme Core Design System",
"version": "2.0.0",
"description": "Adds an 'enterprise' variant and a 'theme' prop for sub-brand theming.",
"modifications": [
{ "type": "added", "target": "variant:enterprise", "description": "High-emphasis variant using enterprise brand color." },
{ "type": "added", "target": "prop:theme", "description": "Prop accepting 'default' or 'admin' for sub-brand palette switching." },
{ "type": "inherited", "target": "guideline:anatomy", "description": "Anatomy inherited from core without changes." }
]
},
"name": "Button",
"description": "Enterprise Button extends core Button with additional variants and props.",
"status": "stable"
}
Merge semantics are tooling's responsibility. The extends declaration defines the relationship between systems and entities. How properties, guidelines, and tokens are merged, overridden, or inherited is up to consuming tooling — the schema does not prescribe resolution rules. The modifications array provides a human-readable changelog that tooling MAY use for diff views, migration guides, or docs generation.
See examples/extension-system.dsds.json for a complete enterprise extension system showing both document-level and entity-level extends with modifications.
Extensions
The root document, each documentation group, and each entity can carry a $extensions property. Keys MUST use vendor-specific namespaces (reverse domain name notation recommended). Tools that do not recognize an extension MUST preserve it. Extension data SHOULD NOT duplicate info already in core schema fields.
{
"$extensions": {
"com.designTool": {
"componentId": "1234:5678"
},
"com.storybook": {
"storyId": "components-button--primary"
}
}
}
Naming conventions
Token identifier exception
Most entity types enforce a strict ^[a-z][a-z0-9-]*$ pattern on the identifier property. Tokens and token groups are the exception by design. Their identifiers are unconstrained to fit the W3C Design Tokens Format Module, design tool variable systems, and existing token setups. These setups may use dots (color.text.primary), slashes (color/text/primary), or other separators. Token identifiers SHOULD still be lowercase and human-readable, but the schema does not enforce a pattern.
Document block type naming
Document block type values follow two naming patterns based on their structural role:
- Plural names for document block types that wrap a list of like items in an items array: "guideline", "variants", "states", "principles", "interactions", "examples", "motion", "content".
- Singular names for document block types that are self-contained with their own internal structure:
- "scale" (has identifier, steps)
- "anatomy" (has parts)
- "api" (has properties, events, etc.)
- "accessibility" (has keyboardInteraction, ariaAttributes, etc.)
- "design-specifications" (has tokens, spacing, etc.)
- "purpose" (has useCases)
The distinction: plural types are containers of interchangeable items where the container has no identity beyond its type. Singular types have meaningful internal structure where properties are named and semantically distinct. Note: "guideline" uses a singular name despite wrapping a list, because it describes the concept of providing guidelines (actionable rules with rationale) rather than being a generic plural container.
Companion files
| File | Description |
|---|
| schema/dsds.schema.json | JSON Schema for validating DSDS documents. |
| schema/dsds.bundled.schema.json | Single-file bundled version (auto-generated). |
| examples/starter-kit.dsds.json | Starter kit with components, tokens, a style, and a pattern. |
| examples/minimal/ | Minimal examples showing the floor of docs for each entity type. |
| examples/entities/component.json | Complete component docs (Button). |
| examples/entities/token.json | Token docs with value, API, and resolution examples. |
| examples/entities/token-group.json | Nested token group (color palette). |
| examples/entities/theme.json | Dark mode theme with token overrides. |
| examples/entities/style.json | Style docs (Spacing) with scale, motion, and best practices. |
| examples/entities/pattern.json | Pattern docs (Error Messaging). |
| examples/entities/empty-state-pattern.json | Pattern docs (Empty State) with anatomy, variants, states, interactions, and content. |
| examples/extension-system.dsds.json | Enterprise extension system showing document-level and entity-level extends with modifications. |
Conformance levels
| Level | Requirement |
|---|
| Level 1: Core | Identity fields only. For tokens: type, identifier, tokenType. For all others: type, identifier, name, description, status (+ overrides for themes). |
| Level 2: Complete | Level 1 + at least one substantive document block entry (anatomy/api/variants for components, principles/scale for styles, interactions for patterns, guideline/purpose for tokens). |
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub