How the schema is organizedThis spec is built from a small, fixed set of building blocks, reused rather than reinvented per file — each definition below documents its own fields directly. See Conformance in the README for how it's all enforced.
Every entry has a kind field. There are 5 well-known values, plus an open option for anything else.
| Kind | Description |
|---|
| system | The design system as a whole — version, organization, url, license, platforms, plus system-wide documentation. |
| component | A reusable UI element — buttons, inputs, modals. Carries its own sourceFiles, imports, traits (variants and states), and combos, on top of the fields every entry shares. |
| token | A single design token. Carries tokenType and a source pointer to the real DTCG value — never the value itself. |
| theme | A named set of token overrides — dark mode, high-contrast, a brand variant. Points at its own DTCG source file. |
| entry | The generic, open kind for anything else — a foundation, a pattern, a guide. Has no fields beyond what every entry shares. |
| (custom) | A custom kind like acme.icon-library, for a document that wants its own recognizable name instead of the generic entry. |
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@ @@
@@ @@
@@ @@@@@@@@@@@ @@@@@@@@@@ @@
@@ @@ @@ @@ @@ @@
@@ @@ @@ @@ @@
@@ @@ @@ @@@@@@@@@@ @@
@@ @@ @@ @@ @@
@@ @@ @@ @@ @@ @@
@@ @@@@@@@@@@@ @@@@@@@@@@ @@
@@ @@
@@ @@@@@@@@@@@ @@@@@@@@@@ @@
@@ @@ @@ @@ @@ @@
@@ @@ @@ @@ @@
@@ @@ @@ @@@@@@@@@@ @@
@@ @@ @@ @@ @@
@@ @@ @@ @@ @@ @@
@@ @@@@@@@@@@@ @@@@@@@@@@ @@
@@ @@
@@ @@
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Base
object
A DSDS document. Acts as the container for all content. Can be optionally extended or split across other DSDS documents.
The version of this spec the document follows.
The name of the design system this document describes.
Every entry this document owns, listed directly.
Min items: 1
An optional hint for editor tools, like autocomplete or validate-on-save.
Reusable content that is not itself a design system artifact, for example an accessibility rule or a guideline that applies broadly.
Min items: 1
The same pointer type entries use.
Escape hatch for tool-specific document-level data, keyed by namespace.
References: dispatch, Shared, list, Extensions
schemaVersion: "0.20.0"
name: Acme Design System
$schema: https://designsystemdocspec.org/v0.20.0/dsds.bundled.yaml
entries:
- id: acme-design-system
kind: system
...
shared:
- id: shared-a11y
...
refs:
- href: ./starter-kit-fragments/button.dsds.yaml
rel: file
$extensions:
com.acme: {...}
Shared
object
Reusable content other entries point at instead of restating. Not a design-system artifact in its own right.
This entry's unique id.
The human-readable display name.
A one-line statement of what this shared entry is for.
The reusable content itself, in the same section structure an entry uses.
Min items: 1
Pointers from this shared entry to entries and outside resources.
Escape hatch for tool data or an outside id, the same structure as an entry's own $extensions.
References: Id, Markdown, Metadata, dispatch, list, Extensions
- id: shared-a11y
name: Shared Accessibility Rules
description: Cross-cutting accessibility rules, stated once and referenced from every entry they apply to.
metadata:
status: {status: stable}
refs:
- href: https://www.w3.org/WAI/WCAG21/quickref/
rel: relates-to
sections:
- kind: guidelines
for: all
items:
- id: touch-target
statement: Minimum touch target 44x44px.
level: must
$extensions:
com.acme: {...}
common/
Combo
object
Defines what an element can or cannot be paired with. Relates to traits, tokens, and entries.
The subject of what elements can or cannot be paired with. Can be a trait, token, or entry id.
Whether the elements in items can or cannot be paired with the subject—and how strict the rule is.
The elements paired with the subject.
Min items: 1
Why this rule holds.
References: #/$defs/target, RequirementLevel, Id, #/$defs/traitTarget, #/$defs/tokenRef
combos:
- subject: "{color.action.primary}"
level: must
items: ["{color.surface.default}", "{color.surface.raised}"]
note: Contrast is verified only against these surfaces; on any other background the label ratio is unproven.
common/
target
An entry id, a trait target on this entry, or a token reference wrapped in braces.
Constraints: at least one of:
References: Id, #/$defs/traitTarget, #/$defs/tokenRef
size.large # a bare id
"{color.action.primary}" # or a token reference
common/
traitTarget
string
A boolean trait's id, or traitId.valueId for one enum value.
Values must match ^[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*(\.[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*)?$.
common/
tokenRef
string
A token reference, wrapped in braces.
Values must match ^\{[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*([./][A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*)*\}$.
common/
Example
object
A single example, illustrating something in context.
A short heading for the example.
Describes the example in detail.
A visual sample of this example.
Where this example lives in code.
At least one of title, description, showcase, ref must be present.
References: Markdown, Showcase, Ref, Example
example:
title: One primary action per surface
description: A toolbar with one filled primary button and two lower-emphasis secondary buttons.
showcase:
kind: image
url: https://cdn.acme.example/ds/showcase/button-primary-surface.png
alt: A toolbar with one filled primary button and two lower-emphasis secondary buttons.
ref:
href: https://storybook.acme.example/?path=/story/button--primary
rel: demo
common/
list
array
One or more examples, in order.
References: Example
- title: One primary action per surface
showcase: {kind: image, url: https://cdn.acme.example/ds/showcase/button-primary-surface.png}
- title: Loading state
ref: {href: ./stories/button.stories.tsx, rel: demo}
common/
Extensions
object
Escape hatch for tool data, or for an outside id that doesn't fit this schema's own id pattern. Each top-level key MUST be a dotted namespace, like com.acme, matching the Design Tokens Community Group's own $extensions convention.
Open map: keys are strings, values are object
References: namespaced
$extensions:
com.acme:
rationale: Multiple primary buttons compete for attention and force the user to guess which action is actually the recommended one.
failureMode: A dialog ships with two primary-styled buttons (e.g. "Save" and "Save as draft"), and usability testing shows users default to the wrong one.
common/
Id
string
Lowercase, dash-separated segments, optionally chained with dots. A section item's own id is optional, but a conforming consumer MUST be able to address every item. When an item has no id, consumers MUST derive one from the item's own text so content has a consistent id. The $comment below gives the exact derivation.
Values must match ^[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+(-[a-z0-9]+)*)*$.
id: color.action.primary
common/
apiId
string
A single identifier copied verbatim from a real API, in whatever case that API uses.
Values must match ^[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*$.
common/
tokenId
string
The same as apiId, but segments can also be chained with a dot or a slash.
Values must match ^[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*([./][A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*)*$.
color/action/primary
common/
namespaced
string
A dotted, namespaced custom value. The open extension point alongside a fixed set of well-known values.
Values must match ^[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+(-[a-z0-9]+)*)+$.
acme.icon-library
common/
Markdown
string
Prose written in CommonMark, with GFM tables and fenced code blocks allowed. It can link to something in the project with a dsds: link, whose target is any string a to field accepts.
statement: Do not use button when the action navigates to a new URL; use the link entry instead.
common/
Ref
A pointer from one thing to another, with rel saying what kind of pointer it is.
Accepts one of:
- string — A plain outside link, short for `{href: <string>}`.
- object
References: #/$defs/to, #/$defs/href, #/$defs/rel, #/$defs/role, #/$defs/note, namespaced, Ref, #/$defs/target
- href: https://example.atlassian.net/browse/DS-482
rel: relates-to
role: Tracks the two-primary-buttons issue
note: Filed after a usability test surfaced the ambiguity.
# or, pointing inside this document instead of outside it:
- to: shared-a11y#touch-target
rel: same-as
common/
list
array
One or more pointers, in order, each with its own rel.
References: Ref
- to: getting-started
rel: relates-to
- href: https://storybook.acme.example
rel: demo
common/
targets
array
One or more pointers of the kind the field is named for, in order.
References: #/$defs/target
checks:
- href: ./tests/button.a11y.test.ts
role: test
- to: release-checklist#focus-visible-check
common/
rel
What kind of pointer this is, or a namespaced custom value. A relationship is written once, on the thing it starts from. A conforming consumer works out the reverse direction itself, and MUST NOT require it to be written on the target as well. Where an object has a field named for a kind of pointer, that kind MUST go in the field, not in refs (DSDS-25).
Accepts one of:
References: namespaced
common/
target
A pointer in a field named for one kind of pointer. It has no rel, because the field name says the kind. A plain string means {href: <string>}.
Accepts one of:
- string — A plain outside link, short for `{href: <string>}`.
- object
References: #/$defs/to, #/$defs/href, #/$defs/role, #/$defs/note
# In a field named for one kind of pointer, like a guideline's evidence:
- href: https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html
role: WCAG 2.2 SC 2.4.4 (A)
# or, the shorthand for an outside link:
- https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html
common/
to
string
What this points at, inside the project.
Values must match ^[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*([./][A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*)*(#[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*(\.[A-Za-z0-9_$]+(-[A-Za-z0-9_$]+)*)*)?$.
common/
href
string
What this points at, outside the project. A file, a URL or a package.
common/
role
string
What the target does here.
common/
note
string
Anything else worth saying about this link.
common/
RequirementLevel
string
How strict a rule is, from must to must-not.
Allowed values:
- must
- should
- may
- should-not
- must-not
- statement: Limit each surface to one primary button.
level: should
- statement: Use buttons only for in-page actions, never navigation.
level: must
common/
Showcase
A visual sample of something. Can be a media file (image or video) or a link to a live page.
What kind of media this showcase is.
Where the showcase lives.
Alt text describing the image or video, for accessibility
Provides additional detail about the showcase if needed.
showcase:
kind: image
url: https://cdn.acme.example/ds/showcase/button-primary-surface.png
alt: A toolbar with one filled primary button and two lower-emphasis secondary buttons.
note: Captured from the Storybook build, light theme.
common/
Since
string
The version something was introduced in.
since: 1.4.0
metadata/
object
Optional information about an element.
How this entry's documentation came to exist, and who or what wrote it.
The owning team, role, or group.
A conforming consumer SHOULD treat updated.date as the cache key for this item's documentation specifically. updated.date is distinct from metadata.version/since which tracks the design system's own release. Always use updated.date as the source of truth for when to re-fetch or re-index.
Independent reviews confirming this item's documentation, each recording who confirmed it and when.
Min items: 1
Keywords for grouping, search, and filtering. By convention, the first tag, if any, is the main category.
Min items: 1
Escape hatch for tool data scoped to just this entry's metadata, keyed by namespace.
References: #/$defs/isoDate, Extensions
metadata:
tags: [actions, button, cta]
owner: ds@acme.example
reviewed:
- date: 2026-05-01
by: human:ahormati
note: Copy and contrast ratios re-checked; no changes needed.
updated:
date: 2026-06-02
note: Added the loading trait and its guideline.
origin:
method: generated
author: generated
note: Generated from custom-elements.json (CEM schemaVersion 2.1.0) by cem-to-dsds.
$extensions:
com.acme: {...}
metadata/
string
A plain-text note. MUST NOT contain markup.
Reviewed against the latest Figma file; no changes needed.
metadata/
string
An ISO 8601 date (YYYY-MM-DD).
Values must match ^\d{4}-\d{2}-\d{2}$.
2026-06-02
metadata/
EntryMetadata
object
Information about a single entry, on top of the fields every metadata object shares.
How this entry's documentation came to exist, and who or what wrote it.
The owning team, role, or group.
A conforming consumer SHOULD treat updated.date as the cache key for this item's documentation specifically. updated.date is distinct from metadata.version/since which tracks the design system's own release. Always use updated.date as the source of truth for when to re-fetch or re-index.
Independent reviews confirming this item's documentation, each recording who confirmed it and when.
Min items: 1
Keywords for grouping, search, and filtering. By convention, the first tag, if any, is the main category.
Min items: 1
Escape hatch for tool data scoped to just this entry's metadata, keyed by namespace.
A visual sample of this entry, either a media file or a link.
The version this entry was first introduced.
A group name this entry belongs to, for example "color.action" on a set of related tokens, or "action" on a family of related components.
Other names this entry is also known or searched by, like a past name or a common misspelling.
References: Metadata, Showcase, Since, #/$defs/status, #/$defs/statusEntry, Id, #/$defs/statusValue, targets, #/$defs/isoDate, Extensions
metadata:
status: {status: stable}
since: 1.4.0
group: color.action
aliases: [btn]
tags: [actions, button, cta, form-control]
owner: ds@acme.example
reviewed:
- date: 2026-05-01
by: human:ahormati
updated: {date: 2026-06-02, note: Added the loading trait and its guideline.}
origin: {method: authored, author: human}
preview: {kind: image, url: https://cdn.acme.example/ds/showcase/button.png}
$extensions:
com.acme: {...}
metadata/
status
A lifecycle status, optionally scoped to one platform - or a list of them, one per platform, when an entry has reached different maturity on each.
Accepts one of:
- #/$defs/statusEntry
- statusEntry[]
References: #/$defs/statusEntry
metadata/
statusEntry
One lifecycle status, optionally scoped to a single platform.
References: Id, #/$defs/statusValue, Since, targets
metadata/
statusValue
string
A lowercase, dash-separated lifecycle word, for example "stable" or "deprecated".
Values must match ^[a-z0-9]+(-[a-z0-9]+)*$.
stable
metadata/
object
Information about the design system as a whole, on top of the fields every metadata object shares.
How this entry's documentation came to exist, and who or what wrote it.
The owning team, role, or group.
A conforming consumer SHOULD treat updated.date as the cache key for this item's documentation specifically. updated.date is distinct from metadata.version/since which tracks the design system's own release. Always use updated.date as the source of truth for when to re-fetch or re-index.
Independent reviews confirming this item's documentation, each recording who confirmed it and when.
Min items: 1
Keywords for grouping, search, and filtering. By convention, the first tag, if any, is the main category.
Min items: 1
Escape hatch for tool data scoped to just this entry's metadata, keyed by namespace.
The team or company that owns the design system.
The main home page or repository for the design system.
The current version of the design system.
The platforms this system ships on, for example "react" or "web-component". When this list is present, every other platform value used anywhere in the document MUST match one of these.
Min items: 1
The license this design system is published under.
Where relative sourceFiles paths start from, when the code lives somewhere other than these documents. A path is relative to the document that holds this system entry; a URL is used as is. Every relative sourceFiles path in the project MUST be read from here when it's set (DSDS-11).
References: Metadata, Since, Id, #/$defs/isoDate, Extensions
metadata:
version: 1.4.0
organization: Acme Corp
url: https://design.acme.example
license: MIT
platforms: [react, web-component]
tags: [design-system]
owner: ds@acme.example
reviewed:
- date: 2026-05-01
by: human:ahormati
updated: {date: 2026-06-02}
origin: {method: authored, author: human}
$extensions:
com.acme: {...}
entries/
Entry
object
The structure every entry kind shares: id, kind, name, description (required), plus metadata, sections, uses, extends, alternatives, refs, $extensions (optional). This schema doubles as a general-use entry that isn't explicitly defined in the schema (ex: pattern, foundation, guideline). See schema/entries/ for each kind's own closing file.
What kind of thing this entry is, as a real design-system artifact: one of the 5 well-known kinds, or a namespaced custom kind.
This entry's unique id in the design system graph.
The human-readable display name.
What this entry is, and why it exists. Lead with what it is, in one sentence.
Information about a single entry, on top of the fields every metadata object shares.
Every documentation section for this entry.
Min items: 1
Entries this one is built from, needs, or follows (uses). No rel: this field says it.
The entry this one inherits from (extends). No rel: this field says it.
Entries to use instead of this one, in some situation (alternative-to). No rel: this field says it.
Every other pointer from this entry, to entries and outside resources, each with its own rel.
Escape hatch for tool data, or for an outside id that doesn't fit this schema's own id pattern. Each top-level key MUST be a dotted namespace, like com.acme, matching the Design Tokens Community Group's own $extensions convention.
References: Id, namespaced, Markdown, EntryMetadata, dispatch, targets, list, Extensions, ComponentEntry, TokenEntry, ThemeEntry, SystemEntry, Entry
id: empty-state
kind: entry
name: Empty State
description: Composition of components shown when a view has no content to display yet. Tells the user why an area is empty and what to do next.
metadata:
status: {status: stable}
uses:
- to: button
extends:
- to: base-dialog
alternatives:
- to: error-state
refs:
- href: https://github.com/acme/ds/tree/main/patterns/empty-state
rel: source
sections:
- kind: guidelines
for: all
items:
- statement: Use an empty state the first time a list or grid has no content.
level: should
$extensions:
com.acme: {...}
entries/
dispatch
Routes an entry to its own kind-specific schema by kind (system, component, token, theme), falling back to this open base for the generic entry kind or a namespaced custom kind.
References: ComponentEntry, TokenEntry, ThemeEntry, SystemEntry, Entry
- id: empty-state
kind: entry
name: Empty State
description: Composition of components shown when a view has no content yet.
- id: button
kind: component
...
entries/
ComponentEntry
object
A reusable UI element, like a button or a dialog.
Marks this entry as a component.
This entry's unique id in the design system graph.
The human-readable display name.
What this entry is, and why it exists. Lead with what it is, in one sentence.
Every documentation section for this entry.
Min items: 1
Entries this one is built from, needs, or follows (uses). No rel: this field says it.
The entry this one inherits from (extends). No rel: this field says it.
Entries to use instead of this one, in some situation (alternative-to). No rel: this field says it.
Every other pointer from this entry, to entries and outside resources, each with its own rel.
Escape hatch for tool data, or for an outside id that doesn't fit this schema's own id pattern. Each top-level key MUST be a dotted namespace, like com.acme, matching the Design Tokens Community Group's own $extensions convention.
One entry per platform's source file.
Min items: 1
One entry per platform.
Min items: 1
Machine-readable API contract(s) for this component (props, slots, events, etc.) in a standard, tool-readable format (contract). No rel: this field says it.
The component's variants and states. Every item says which one it is with traitType, and carries a kind of boolean or enum for the form it takes - an enum has its own values list, a boolean is a plain toggle.
Min items: 1
Define which of this component's own boolean traits or enum values can or cannot be paired with each other.
Min items: 1
References: Entry, EntryMetadata, Id, target, targets, traitValue, traitType, list, Combo, apiId, Markdown, list, Since, status, dispatch, Extensions
id: button
kind: component
name: Button
description: Triggers an action. Gives users a single, consistent way to trigger an action.
metadata: {status: {status: stable}}
uses: [{to: color.action.primary}]
extends: [{to: base-dialog}]
alternatives: [{to: link}]
refs: [{href: https://github.com/acme/ds/react/button, rel: source}]
sections:
- kind: guidelines
for: all
items: [{statement: Limit each surface to one primary button., level: should}]
$extensions:
com.acme: {...}
sourceFiles:
- platform: react
file: ./src/Button.tsx
imports:
- platform: react
package: "@acme/ui"
traits:
- traitType: state
kind: boolean
id: loading
description: Shows a spinner in place of the label and blocks interaction while active.
combos:
- subject: loading
level: must-not
items: [disabled]
note: A control can't be simultaneously loading and disabled...
specs:
- href: ./contracts/button.contract.json
role: DS Contracts
entries/
traitType
string
Whether this trait is a variant the caller configures, or a state the component can be in.
Allowed values:
entries/
traitValue
object
The shared properties of a boolean trait or one enum value - what it is, and what it's for.
The machine-readable id. Mirrors the real prop, attribute or value name, so it accepts camelCase, PascalCase, snake_case and kebab-case.
What this is, why it exists, how it looks or behaves, and any constraints.
The human-readable name. Uses id when left out.
Examples showing this in context.
The version this was introduced.
This trait's or value's own lifecycle status, when it differs from the component's.
References: apiId, Markdown, list, Since, status
id: loading
name: Loading
description: Shows a spinner in place of the label and blocks interaction while active, so an action can't be submitted twice.
examples:
- title: Default loading state
showcase: {kind: image, url: https://cdn.acme.example/ds/showcase/button-loading.png}
since: 1.4.0
entries/
SystemEntry
object
A DSDS design system. System-level information and guidance for the design system as a whole.
Marks this entry as a design system.
This entry's unique id in the design system graph.
The human-readable display name.
What this entry is, and why it exists. Lead with what it is, in one sentence.
Facts about the design system as a whole.
Every documentation section for this entry.
Min items: 1
Entries this one is built from, needs, or follows (uses). No rel: this field says it.
The entry this one inherits from (extends). No rel: this field says it.
Entries to use instead of this one, in some situation (alternative-to). No rel: this field says it.
Every other pointer from this entry, to entries and outside resources, each with its own rel.
Escape hatch for tool data, or for an outside id that doesn't fit this schema's own id pattern. Each top-level key MUST be a dotted namespace, like com.acme, matching the Design Tokens Community Group's own $extensions convention.
References: Entry, EntryMetadata, SystemMetadata, Markdown, dispatch, targets, list, Extensions
id: acme-design-system
kind: system
name: Acme Design System
description: Acme's cross-platform design system. One source of truth for how Acme builds and documents interfaces.
metadata:
version: 1.4.0
organization: Acme Corp
url: https://design.acme.example
license: MIT
platforms: [react, web-component]
status: {status: stable}
extends: [{to: base-design-system}]
uses: [{to: button}]
refs: [{to: acme-brand-system, rel: relates-to}]
sections:
- kind: section
for: all
title: Getting started
freeform: [{title: Install, body: Add the package and its peer dependencies.}]
$extensions:
com.acme: {...}
entries/
ThemeEntry
object
A defined system theme.
Marks this entry as a theme.
This entry's unique id in the design system graph.
The human-readable display name.
What this entry is, and why it exists. Lead with what it is, in one sentence.
Every documentation section for this entry.
Min items: 1
Entries this one is built from, needs, or follows (uses). No rel: this field says it.
The entry this one inherits from (extends). No rel: this field says it.
Entries to use instead of this one, in some situation (alternative-to). No rel: this field says it.
Every other pointer from this entry, to entries and outside resources, each with its own rel.
Escape hatch for tool data, or for an outside id that doesn't fit this schema's own id pattern. Each top-level key MUST be a dotted namespace, like com.acme, matching the Design Tokens Community Group's own $extensions convention.
Which native color-scheme setting this theme matches.
Default: "light"
The theme's DTCG source file (rel: source). No rel: this field says it.
References: Entry, EntryMetadata, target, Markdown, dispatch, targets, list, Extensions
id: dark
kind: theme
name: Dark
description: Inverted-luminance theme for low-light surfaces and user preference. Lets a product opt into a dark color scheme without redefining every token.
metadata: {status: {status: stable}}
extends:
- to: light
refs:
- href: https://www.figma.com/file/acme-dark-theme
rel: design
sections:
- kind: guidelines
for: all
items: [{statement: Test contrast against both themes before shipping., level: should}]
$extensions:
com.acme: {...}
source: tokens/dark.tokens.json
colorScheme: dark
entries/
TokenEntry
object
A single design token, from the Design Tokens Community Group (DTCG) format.
Marks this entry as a token.
This token's unique id.
The human-readable display name.
What this entry is, and why it exists. Lead with what it is, in one sentence.
Every documentation section for this entry.
Min items: 1
Entries this one is built from, needs, or follows (uses). No rel: this field says it.
The entry this one inherits from (extends). No rel: this field says it.
Entries to use instead of this one, in some situation (alternative-to). No rel: this field says it.
Every other pointer from this entry, to entries and outside resources, each with its own rel.
Escape hatch for tool data, or for an outside id that doesn't fit this schema's own id pattern. Each top-level key MUST be a dotted namespace, like com.acme, matching the Design Tokens Community Group's own $extensions convention.
The token's type, from DTCG.
Pattern: ^[a-z][a-zA-Z0-9]*$
The token's DTCG source file (rel: source). No rel: this field says it.
Rules about which other tokens this one must or must never be paired with.
Min items: 1
References: Entry, tokenId, EntryMetadata, target, Combo, Markdown, dispatch, targets, list, Extensions
id: space-4
kind: token
name: Space 4
description: A single step on the base spacing scale - 4 times the 4px base unit. Keeps spacing consistent across components without hand-picked pixel values.
metadata: {status: {status: stable}, group: space}
extends: [{to: space-base}]
alternatives: [{to: space-8}]
refs: [{href: https://www.figma.com/file/acme-spacing-scale, rel: design}]
sections:
- kind: guidelines
for: all
items: [{statement: Use for default padding/gap; use space-8 for section spacing., level: should}]
$extensions:
com.acme: {...}
tokenType: spacing
source: ./tokens.dtcg.json
combos:
- subject: "{color.action.primary}"
level: must
items: ["{color.surface.default}", "{color.surface.raised}"]
sections/
Section
object
A logical documentation section. Supplies the fields every section kind shares, in declaration order — kind, for, title, description, context, tags, items, freeform, $extensions — and is tagged with who it is for (human, agent, or all). Content always lives in items, never in a field named after the kind. Each sections/<kind>.schema.yaml file adds its own kind value (definitions, guidelines, steps, or the generic section) and its own structure for items on top of this shared base.
What kind of content section this is.
Who or what this section is written for.
Default: "all"
The one universal list for this section kind's own structured content.
Nestable written content that can include headings. Available on every section kind regardless of items' own structure.
Min items: 1
An optional heading for the section.
An optional one-line intro for the section.
What job this section is doing.
What this section is about. A section tagged accessibility holds the accessibility rules for its entry, and nothing else.
Min items: 1
Escape hatch for tool data scoped to just this one section, keyed by namespace.
At least one of items, freeform must be present.
References: namespaced, Markdown, #/$defs/freeformEntry, Extensions, DefinitionsSection, GuidelinesSection, StepsSection, Section, Id, list, list
- kind: section
for: all
title: Troubleshooting
description: Common problems and how to fix them.
context: acme.troubleshooting
items:
- title: Note
body: Generic items have no fixed fields - use freeform for prose instead.
freeform:
- title: Styles don't apply
body: Confirm the base theme is imported before any component renders - a component's own CSS assumes the theme's custom properties already exist.
$extensions:
com.acme: {...}
sections/
dispatch
Routes a section to its own kind-specific schema by kind (definitions, guidelines, steps), falling back to this open base for the generic section kind or a namespaced custom kind.
References: DefinitionsSection, GuidelinesSection, StepsSection, Section
- kind: guidelines
for: all
items:
- statement: Limit each surface to one primary button.
level: should
- kind: steps
...
sections/
freeformEntry
object
One nestable, headed block of prose - a freeform section's own building block.
The entry's heading, for example 'Installation'.
A stable id for linking to this entry directly, unique within the section. id is optional, but conforming consumer MUST derive one from this item's own text.
The entry's content.
One or more examples, in order.
"See also" pointers for this entry. To point at another entry, use the entry's own top-level refs instead.
Sub-entries nested beneath this one, to any depth.
Min items: 1
Escape hatch for tool data scoped to just this one freeform entry, keyed by namespace.
References: Id, Markdown, list, list, #/$defs/freeformEntry, Extensions
title: Install
id: install
body: Add the package and its peer dependencies.
examples:
- title: Install with the CLI
ref: {href: ./install.sh, rel: file}
refs:
- to: getting-started
rel: relates-to
items:
- title: Peer dependencies
body: React 18+ and a theme provider higher in the tree.
$extensions:
com.acme: {...}
sections/
DefinitionsSection
object
Term definitions. Can describe content labels within components or patterns, define naming conventions, act as a glossary, or be a simple way to outline component props/APIs.
Marks this section as term-definition documentation.
Who or what this section is written for.
Default: "all"
An optional heading for the section.
An optional one-line intro for the section.
What job this section is doing.
What this section is about. A section tagged accessibility holds the accessibility rules for its entry, and nothing else.
Min items: 1
One entry per term.
Min items: 1
Nestable written content that can include headings. Available on every section kind regardless of items' own structure.
Min items: 1
Escape hatch for tool data scoped to just this one section, keyed by namespace.
References: Section, Id, Markdown, targets, list, Extensions, namespaced, #/$defs/freeformEntry
- kind: definitions
for: all
title: Terms
description: Words used in this component's copy.
context: terms
items:
- term: OK
definition: To confirm an action.
- term: Cancel
definition: To cancel an action.
freeform:
- title: About
body: These terms match the ones used in product copy guidelines.
$extensions:
com.acme: {...}
sections/
GuidelinesSection
object
Rules for an entry. When and how to use it. Each item pairs a rule with why it exists. When an item carries a level and a ref but no statement, a conforming consumer SHOULD show the level and the link rather than rendering it as empty content. An author who expects a person to read the guideline without following the link SHOULD add a statement instead.
Marks this section as guidelines.
Who or what this section is written for.
Default: "all"
An optional heading for the section.
An optional one-line intro for the section.
What job this section is doing.
What this section is about. A section tagged accessibility holds the accessibility rules for its entry, and nothing else.
Min items: 1
The rules, in order.
Min items: 1
Nestable written content that can include headings. Available on every section kind regardless of items' own structure.
Min items: 1
Escape hatch for tool data scoped to just this one section, keyed by namespace.
Which kind of guidance this section holds.
Default: "how-to-use"
References: Section, Id, RequirementLevel, Markdown, Example, targets, list, Extensions, namespaced, #/$defs/freeformEntry
- kind: guidelines
for: agent
framing: when-to-use
title: When to use
description: Whether button is the right choice for this action.
context: acme.fit-check
items:
- statement: Do not use button when the action navigates to a new URL; use the link entry instead.
level: must-not
alternatives:
- to: link
freeform:
- title: Why this matters
body: A button that navigates breaks browser back/forward and "open in new tab."
$extensions:
com.acme: {...}
sections/
StepsSection
object
A series of actions/steps/tasks, like a tutorial, a migration, a pattern's interaction flow, or checklist of things to verify.
Marks this section as a stepped process or checklist.
Who or what this section is written for.
Default: "all"
An optional heading for the section.
An optional one-line intro for the section.
What job this section is doing.
What this section is about. A section tagged accessibility holds the accessibility rules for its entry, and nothing else.
Min items: 1
The steps or checklist entries, in order.
Min items: 1
Nestable written content that can include headings. Available on every section kind regardless of items' own structure.
Min items: 1
Escape hatch for tool data scoped to just this one section, keyed by namespace.
Whether entries must be done in order. Set to false for an unordered checklist.
Default: true
References: Section, Id, Markdown, list, targets, list, Extensions, namespaced, #/$defs/freeformEntry
- kind: steps
for: agent
ordered: false
title: Pre-release checklist
description: Run through before shipping a change to this component.
context: acme.checklist
items:
- title: Focus ring is visible in both light and dark themes.
- title: Loading state announces to screen readers.
- title: Works with a custom icon in the leading-icon slot.
optional: true
freeform:
- title: Why this matters
body: Skipping this checklist is how contrast regressions ship.
$extensions:
com.acme: {...}