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 │ ├── 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 dsdsVersion string and a documentation array. Each documentation group is a named collection of one or more typed entities.

Root properties

Property	Type	Required	Description
$schema	string	No	URI reference to the DSDS JSON Schema for validation.
dsdsVersion	string	Yes	The version of this spec the document conforms to. MUST be "0.1" for this version.
systemMetadata	object	No	System-level metadata about the design system. See Metadata.
purpose	object	No	System-level purpose describing what the design system is for and when to adopt it. See Root Purpose.
bestPractices	array	No	System-level best practices that apply across the whole design system. See Root Best Practices.
documentation	array	Yes	One or more documentation groups. See Documentation Groups.
extends	object	No	Declares that this document extends another DSDS document — typically a core design system. See Extends.
$extensions	object	No	Vendor-specific extensions. See Extensions.

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.

Property	Type	Required	Description
name	string	Yes	Human-readable name of the collection (e.g., "Acme Design System", "Color Foundations", "Button Documentation").
description	richText	No	Description of the collection.
components	array	No	Component entities. Each item must have "type": "component".
tokenGroups	array	No	Token group entities (which contain tokens via children). Each item must have "type": "token-group".
themes	array	No	Theme entities. Each item must have "type": "theme".
styles	array	No	Style entities. Each item must have "type": "style".
patterns	array	No	Pattern entities. Each item must have "type": "pattern".
$extensions	object	No	Vendor-specific extensions.

Entity type discriminators

Every entity carries a type property that identifies its kind. The type is a required string const on every entity schema. Because entities are placed in typed arrays (components, tokenGroups, themes, styles, patterns), the array name already determines the expected type — but 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", "name": "button", "..." } ], "tokenGroups": [ { "type": "token-group", "name": "color-palette", "..." } ], "themes": [ { "type": "theme", "name": "dark", "..." } ], "styles": [ { "type": "style", "name": "spacing", "..." } ], "patterns": [ { "type": "pattern", "name": "empty-state", "..." } ] } Metadata

Property	Type	Required	Description
systemName	string	Yes	The name of the design system (e.g., "Carbon", "Gestalt", "Spectrum").
systemVersion	string	No	The version of the design system.
organization	string	No	The organization that maintains the system.
url	string	No	URL to the system's docs site.
license	string	No	SPDX license identifier or license URL.

Root purpose

The optional purpose property on the root document describes what the design system 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.

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:

Property	Type	Required	Description
description	richText	Yes	The scenario being described.
kind	string	Yes	"positive" (when the system is the right choice) or "negative" (when it is not).
alternative	object	No	For negative entries, a recommended option with name and rationale.

{ "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": { "name": "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 has this shape:

Property	Type	Required	Description
guidance	richText	Yes	The actionable guidance statement. MUST be concrete and unambiguous.
rationale	richText	Yes	Why this guidance exists. MUST NOT be a restatement of the guidance.
kind	string	No	Enforcement level: "required", "encouraged", "informational", "discouraged", "prohibited". Uses the same RFC 2119 alignment as entity-level best practice entries.
category	string	No	Discipline grouping (e.g., "visual-design", "accessibility", "development").
criteria	array	No	URLs to external standards. Each entry has url and label.

{ "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.

Property	Type	Required	Notes
type	string	Yes	Entity type discriminator.
name	string	Yes	Machine-readable ID. Components, styles, patterns, and themes enforce ^[a-z][a-z0-9-]*$. Token and token group names are unconstrained by design (see Token Name Exception).
displayName	string	Varies	Human-readable name. Required on component, style, pattern, theme. Not present on token or token-group — the token name serves as the display name.
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, name, displayName, description, status.

Token

A single design token. Accepts general document block types only.

Required properties: type, name, tokenType.

More properties:

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 displayName property by design. The token name itself serves as the human-readable display name. Token naming 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, name.

More properties:

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, displayName, 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, name, displayName, description, status, overrides.

More properties:

Property	Type	Required	Description
overrides	tokenOverride[]	Yes	Array of token names 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 name). 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, name, displayName, 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, name, displayName, description, status.

Patterns reference their participating components through the links array (with type: "component", name, 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.

Property	Type	Description
intent	string	One sentence stating the primary purpose. Agents use this to determine relevance without parsing the full description.
constraints	array	Hard rules with must/must-not/should/should-not enforcement levels. Each entry has rule, level, and optional context.
disambiguation	array	Entries resolving confusion with similar entities. Each has entity (name) and distinction (the deciding criterion).
antiPatterns	array	Known incorrect uses. Each has description (what not to do) and instead (correct alternative).
examples	array	Ready-to-use code examples. Each has description, code, and optional language.
keywords	string[]	Semantic retrieval terms — synonyms, common query vocabulary, related concepts.

{ "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"] } }

---

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.

Property	Type	Required	Description
status	statusValue	Yes	Overall lifecycle status. See Status Values.
platformStatus	object	No	Platform-specific readiness. Keys are platform identifiers (e.g., "react", "ios", "figma"). Values are platform status entries.
deprecationNotice	string	Conditional	Required when status is "deprecated". MUST explain what to use instead.

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

Property	Type	Required	Description
status	statusValue	Yes	Lifecycle status on this platform.
since	string	No	Version available on this platform.
deprecationNotice	string	Conditional	Required when status is "deprecated".
description	string	No	Notes about this platform's status.

---

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	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
"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, payload 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

Property	Type	Required	Description
guidance	richText	Yes	The actionable guidance statement. MUST be concrete and unambiguous.
rationale	richText	Yes	Why this guidance exists. MUST NOT be a restatement of the guidance.
level	string	No	Enforcement level: "required", "encouraged", "informational", "discouraged", "prohibited". When omitted, consumers MAY treat as "encouraged".
category	string	No	Discipline grouping (e.g., "visual-design", "accessibility", "content", "interaction", "motion", "development").
target	string	No	Anatomy part this applies to (e.g., "label", "icon"). When omitted, applies to the entity as a whole.
criteria	string[]	No	URLs to external standards (e.g., WCAG success criteria).
examples	example[]	No	Examples showing encouraged and discouraged approaches.
tags	string[]	No	Freeform keywords.

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": { "name": "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.

Property	Type	Required	Description
type	"accessibility"	Yes	Discriminator.
wcagLevel	string	No	Minimum WCAG conformance level: "A", "AA", "AAA".
keyboardInteraction	keyboardInteraction[]	No	Key/action pairs. Each entry has key, action, and optional context.
ariaAttributes	ariaAttribute[]	No	ARIA attribute docs. Each entry has attribute, value, description, required.
screenReaderBehavior	richText	No	How the entity is announced by screen readers.
focusManagement	richText	No	How focus moves into, within, and out of the entity.
colorContrast	colorContrast[]	No	Measured contrast ratios for foreground/background pairs. Each entry has foreground, background, contrastRatio, level, and optional context.
motionConsiderations	richText	No	How the entity respects prefers-reduced-motion.

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

Property	Type	Required	Description
term	string	Yes	The canonical label text (e.g., "Add", "Cancel", "Delete").
definition	richText	Yes	What this label means — the action it represents.
usage	richText	No	When and how to use this label.
alternatives	string[]	No	Related terms commonly confused with this one (e.g., Add lists ["Create", "Insert", "New"]).
context	string	No	Where this label is commonly used (e.g., "Buttons in dialogs", "Toolbar actions").
examples	example[]	No	Visual examples showing the label in context.

Localization entry

Property	Type	Required	Description
concern	string	Yes	The i18n concern: "rtl", "text-expansion", "pluralization", "concatenation", "date-format", "number-format", "currency", "icon-direction", "truncation", "sorting". Custom values permitted.
description	richText	Yes	Actionable guidance for this concern.
examples	example[]	No	Visual examples showing the concern.

---

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

Property	Type	Required	Description
name	string	Yes	Machine-readable part name (e.g., "container", "label").
displayName	string	No	Human-readable name.
description	richText	Yes	What this part is and any constraints.
required	boolean	Yes	Whether this part is always present in the rendered output.
tokens	object	No	Token map: keys are purposes (e.g., "background", "text-color"), values are token names (e.g., "color-action-primary"). Same format as variant and state token references.
links	link[]	No	Links to design tool nodes, source code, etc.

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[])

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": [ { "name": "emphasis", "description": "...", "values": [...] }, { "name": "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

Property	Type	Required	Description
name	string	Yes	Machine-readable value name.
displayName	string	No	Human-readable name.
description	richText	Yes	What this value looks like and when to use it.
tokens	object	No	Token overrides: keys are purposes, values are token names.
preview	example[]	No	Visual previews.
useCases	useCases	No	When to choose this value over others.

States (states)

Documents all interactive states — hover, focus, active, disabled, loading, selected, error, etc. — with triggers, token overrides, and previews.

State entry

Property	Type	Required	Description
name	string	Yes	Machine-readable state name.
displayName	string	No	Human-readable name.
description	richText	Yes	Triggers, visual changes, and constraints.
tokens	object	No	Token overrides active in this state. Same map format as variants.
preview	example[]	No	Visual previews.
useCases	useCases	No	When this state is and is not appropriate.

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.

Section	Type	Description
properties	Record	Open map of design property names to values. Values are token names (e.g., "button-background") or raw CSS values (e.g., "#0055b3", "16px").
spacing	spacingSpec	Internal padding/gaps and external recommended margins. Keys are named relationships (e.g., "container-horizontal", "icon-to-label"), values are token names or resolved values.
sizing	sizingSpec	Dimension constraints: minWidth, maxWidth, minHeight, maxHeight, aspectRatio.
typography	typographySpec	Per-element typographic settings. Keys are anatomy part names, values are objects with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textTransform, typeToken.
responsive	responsiveEntry[]	Breakpoint-specific behavior. Each entry has breakpoint and description.
variants	specVariant[]	Design properties grouped by variant. Each entry has name, properties, and optional spacing, sizing, typography.
sizes	specSize[]	Design properties grouped by size. Each entry has name, properties, and optional spacing, sizing, typography.
states	specState[]	Design properties grouped by interactive state. Each entry has name, properties, and optional spacing, sizing, typography.
variantStates	specVariantState[]	Design properties for variant×state combinations. Each entry has variant, state, and properties.

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 a name 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 a name, 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

Property	Type	Required	Description
name	string	Yes	Machine-readable easing name (e.g., "expressive", "enter", "exit").
displayName	string	No	Human-readable name.
description	richText	Yes	Visual character, usage context, and UX effect.
function	number[4]	No	Cubic-bezier control points [P1x, P1y, P2x, P2y], aligned with the W3C DTCG cubicBezier type (§8.6).
token	string	No	Reference to a DTCG cubicBezier or transition token.
duration	motionDuration	No	Recommended duration range: min, max, and/or description.
usage	string	No	Comma-separated usage contexts (e.g., "entering elements, snap-to-position").
examples	example[]	No	Visual demos.

---

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

Property	Type	Required	Description
trigger	string	No	What starts this step. When omitted, the step continues the previous flow.
description	richText	Yes	What happens — system response, visual changes, state transitions.
components	string[]	No	Names of components involved. MUST match documented component names.
examples	example[]	No	Visual/interactive illustrations of this step.

---

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 type and at least one of url (for external resources) or name (for internal DSDS entity references). Both can be present when an internal entity also has an addressable URL.

Property	Type	Required	Description
type	string	Yes	Category of the link. See Standard Link Types.
url	string	Conditional	URL of the external resource. Required when name is not provided.
name	string	Conditional	Name of a referenced DSDS entity. Required when url is not provided.
label	string	No	Display text for the link — what a user sees when it renders in docs.
role	string	No	The functional relationship this entity has to the current entity — what part it plays here. Distinct from label: label names the thing, role describes its function.
required	boolean	No	Whether this linked entity is required for the parent entity to work.

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:

1. Purpose document block type — wrapped with a type: "purpose" discriminator to appear in the document block array.
2. Variant values — inline useCases property on each variant value for "when to choose this value."
3. 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": { "name": "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.

Property	Type	Required	Description
system	string	Yes	The name or identifier of the base design system being extended (e.g., "Acme Core Design System").
url	string (URI)	No	URL to the base DSDS document. Tooling MAY fetch and resolve the base document for merge operations.
version	string	No	Semver version of the base system this document extends. When omitted, tooling SHOULD resolve to the latest available version.
description	richText	No	Description of the relationship — what this extension adds, changes, or specializes.

{ "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.

Property	Type	Required	Description
name	string	Yes	The name of the base entity being extended. MUST match the name property of the base entity in the parent system.
system	string	No	The owning system of the base entity. When omitted, resolved from the document-level extends.system.
url	string (URI)	No	Direct URL to the base entity's docs or DSDS definition.
version	string	No	Version of the base entity or system. When omitted, inherits from the document-level extends.version.
description	richText	No	Description of what this entity adds or changes relative to the base.
modifications	array	No	A human-readable changelog of changes relative to the base entity.

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", "name": "button", "extends": { "name": "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." } ] }, "displayName": "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 name exception

Most entity types enforce a strict ^[a-z][a-z0-9-]*$ pattern on the name property. Tokens and token groups are the exception by design. Their names 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 names 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 name, 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, name, tokenType. For all others: type, name, displayName, 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 Standard (DSDS) 0.1 — Draft Specification

GitHub