This page defines what it means to conform to the Design System Doc Spec 0.15.2, and indexes every normative statement the spec makes.
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in the DSDS schemas and on this page are to be interpreted as described in RFC 2119 (as clarified by RFC 8174): they are normative only when they appear in upper case.
DSDS keeps its normative language inside the schema
DSDS defines four conformance classes. A claim of conformance names the class it applies to.
A JSON document that validates against the DSDS schema for the version its
- identifier uniqueness
- reference resolution
- relationship-graph integrity
- token-layer resolution
tokenType inheritancedocOrigin block-key resolution- extension-key namespacing
Schema validity alone is necessary, but not enough.
A tool or person that emits DSDS documents. A conforming producer:
- MUST emit conforming documents
- MUST NOT emit deprecated forms in new output (a deprecated form exists only for reading old documents, never for writing new ones — as of 0.14.0, nothing is deprecated)
- SHOULD record how the documentation was produced, via the
docOrigin metadata field
A tool, renderer, or agent that reads DSDS documents. A conforming consumer:
- MUST NOT fail on optional fields it doesn't recognize
- MUST preserve
$extensions data it doesn't understand - MUST treat unresolvable references as defects, not silently drop them
- MUST respect RFC 2119 levels on guidance it acts on (a
must-not guideline is a hard gate for an agent writing code)
A tool that checks documents. A conforming validator MUST enforce both the structural layer (the JSON Schema, with format assertion enabled) and the semantic layer. It SHOULD also surface the lint layer (the rules catalog in
Every normative statement is enforced at one of three tiers, or is explicitly advisory:
| Tier | Mechanism | Failure mode |
|---|---|---|
| Structural | JSON Schema (patterns, required, minItems, conditionals) | Validation error — blocking |
| Semantic | Reference implementation checks (resolution, uniqueness, inheritance, cycles) | Validation error — blocking |
| Lint | Rules catalog ( | Warning — never blocking |
| Advisory | SHOULD/MAY statements consumed by judgment | None |
Generated from the v0.15.2 schemas by
- MUST — 'automated': a fully objective test checked programmatically; a
check MUST be present.common/criterion§verificationMode.1 - MUST NOT — When omitted, tools MUST NOT assume the criterion is automatable.
common/criterion§verificationMode.2 - MUST — Any process that doesn't recognize the tool MUST report the criterion as skipped, never as passing.
common/criterion§criterionCheck.1 - MUST — MUST be lowercase; dots permitted for namespacing (e.g. 'com.acme.contract-tests').
common/criterion§criterionCheck.scheme.1 - SHOULD — Test cases make criteria self-verifying: a conformance runner SHOULD execute the criterion's
check (when present) against each test case and confirm the declared outcome is reproduced — a 'fail' test case that passes means the check no longer detects what it claims to.common/criterion§criterionTestCase.1 - MAY — When omitted, tools MAY build a label from the URL.
common/criterion§reference.label.1 - MUST — MUST be lowercase kebab-case.
common/criterion§criterion.identifier.1 - SHOULD NOT — Test runs report pass/fail against this identifier, so it SHOULD NOT change once checks depend on it.
common/criterion§criterion.identifier.2 - SHOULD — Tools SHOULD render it in docs and test reports beside the identifier.
common/criterion§criterion.title.1 - MUST — MUST be objectively verifiable by inspection, static analysis, or runtime measurement.
common/criterion§criterion.statement.1 - SHOULD — A criterion referenced by a guideline SHOULD inherit the guideline's
level when omitted; a standalone criterion SHOULD declare its own.common/criterion§criterion.level.1 - MUST NOT — Criterion identifiers are stable: once published, an identifier MUST NOT be reused for a different requirement — retire the identifier and make a new one instead.
common/criterion§criterion.since.1
- MUST NOT — MUST NOT contain markup and MUST NOT be empty.
common/dated-note§plainNote.1
- MUST — Every identifier MUST match a documented entity.
common/entity-ref§(root).1 - MUST — MUST match that entity's
identifier .common/entity-ref§entityIdentifier.1 - SHOULD — Tools SHOULD resolve it to build cross-references.
common/entity-ref§entityIdentifier.2
- SHOULD — Tools SHOULD render value-only examples as table rows or inline displays.
common/example§example.1
- MAY — Tools MAY fetch it for merge, validation, or docs.
common/extends§documentExtends.url.1 - SHOULD — When omitted, tools SHOULD use the latest.
common/extends§documentExtends.version.1 - MUST — MUST match the base entity's
identifier in the parent system.common/extends§entityExtends.identifier.1 - MAY — Tools MAY use them for changelogs, diffs, or migration guides; when omitted, tools must diff the entities.
common/extends§entityExtends.modifications.1
- MUST — Keys MUST use vendor namespaces.
common/extensions§(root).1 - MUST — Keys MUST use a namespace of at least two dot-separated segments (reverse domain recommended), Example: 'com.figma', 'acme.tooling'; the pattern is case-tolerant.
common/extensions§extensions.1 - MUST — Tools that don't recognize an extension MUST keep it.
common/extensions§extensions.2 - SHOULD NOT — Extension data SHOULD NOT duplicate core schema fields.
common/extensions§extensions.3
- MUST — Custom values MUST match ^[a-z][a-z0-9-]*$.
common/link§link.kind.1 - MUST — MUST be a valid absolute URI.
common/link§link.url.1 - MAY — When omitted, tools MAY build one from the URL.
common/link§link.label.1
- MUST NOT — MUST NOT be empty.
common/presentation§mediaAlt.1 - MUST NOT — MUST NOT be empty.
common/presentation§presentationImage.alt.1 - MUST NOT — MUST NOT be empty.
common/presentation§presentationVideo.alt.1
- MUST — A relationship's target MUST be a documented entity.
common/relationship§(root).1 - MUST NOT — Tools work out the reverse relationship direction direction (target → source) and MUST NOT require them to be manually authored.
common/relationship§relationType.1 - MUST — Custom relations MUST be vendor-namespaced (e.g. 'acme.themes').
common/relationship§relationType.2 - MUST — MUST match a documented entity.
common/relationship§relationship.target.1
- MUST — Tools MUST render the value as markdown.
common/rich-text§richText.1
- MUST — MUST be lowercase kebab-case.
common/status§statusValue.1 - MUST — Custom values (ex: 'sunset', 'beta') are allowed and MUST follow the same pattern.
common/status§statusValue.2 - MUST — MUST say what to use instead and, where one exists, give a migration path.
common/status§deprecationNotice.1
- SHOULD — SHOULD follow semver so tools can compare it against
extends.version andreviewedAgainst .common/system-info§systemInfo.version.1
- MUST — Token references MUST name a documented token, never a raw value.
common/token-overrides§(root).1 - MUST — When the system documents a token layer, each value MUST resolve to a documented token.
common/token-overrides§tokenOverrides.1
- SHOULD — Order matters: tools SHOULD keep it for display, and authors SHOULD lead with recommended scenarios.
common/use-cases§useCases.items.1
- MUST NOT — When
schema is present it is authoritative;type is its display summary and MUST NOT disagree with it.document-blocks/api§apiProperty.type.1 - MUST NOT — When
schema is present it is authoritative;values is its display summary and MUST NOT disagree with it.document-blocks/api§apiProperty.values.1 - MUST NOT — When present,
schema is the authoritative type definition;type andvalues are display summaries of it and MUST NOT disagree.document-blocks/api§apiProperty.schema.1 - MUST — MUST say what to use instead (non-empty) and SHOULD give a migration path.
document-blocks/api§apiProperty.deprecationNotice.1
- MUST — MUST be specific — not 'check accessibility'.
document-blocks/checklist§checklistItem.label.1 - MUST — MUST be lowercase kebab-case.
document-blocks/checklist§checklistItem.criterion.1 - MAY — Tools MAY mark optional items differently.
document-blocks/checklist§checklistItem.optional.1 - SHOULD — Tools SHOULD show unordered checklists as checkboxes and ordered ones as a numbered list.
document-blocks/checklist§checklist.ordered.1 - MUST — Order matters when
ordered is true, so tools MUST preserve it.document-blocks/checklist§checklist.items.1
- SHOULD — These SHOULD match other
term values in this block'slabels array, so tools can cross-reference them.document-blocks/content§contentLabelEntry.alternatives.1 - SHOULD — Order matters for display, so tools SHOULD keep it; authors MAY sort alphabetically or by frequency.
document-blocks/content§content.labels.1 - SHOULD — Order matters for display, so tools SHOULD keep it; authors SHOULD lead with the highest-impact concerns.
document-blocks/content§content.localization.1
- MUST — If the system has tokens, this MUST be a token identifier (ex: 'color-action-primary', 'space-4'), not a raw value — that keeps it from drifting out of sync with the token system.
document-blocks/design-specifications§designValue.1 - MUST — Keys say what the value controls (ex: 'background', 'min-height') and MUST be lowercase kebab-case.
document-blocks/design-specifications§designProperties.1 - MUST — Keys name the relationship (ex: 'icon-to-label') and MUST be lowercase kebab-case.
document-blocks/design-specifications§spacingSpec.internal.1 - MUST — Keys name the relationship (ex: 'button-to-button') and MUST be lowercase kebab-case.
document-blocks/design-specifications§spacingSpec.external.1 - MUST — Keys name the element (ex: 'label', 'helper-text') and MUST be lowercase kebab-case.
document-blocks/design-specifications§typographySpec.1
- MUST — MUST be concrete and clear — not 'use sparingly' or 'when possible'.
document-blocks/guidelines§guidelineEntry.guidance.1 - MUST NOT — MUST NOT just repeat the guidance.
document-blocks/guidelines§guidelineEntry.rationale.1 - SHOULD — Tools SHOULD keep this order; authors SHOULD lead with the most important or group by category.
document-blocks/guidelines§guidelines.items.1
- SHOULD — SHOULD be copy-paste ready.
document-blocks/imports§importEntry.code.1
- MUST — Each
identifier MUST match a documented component; the optionalrole says what it does here.document-blocks/interactions§interactionEntry.components.1 - SHOULD — Authors SHOULD cover the trigger, the response, any recovery steps, and completion.
document-blocks/interactions§interactions.1 - SHOULD — Tools SHOULD keep this order so the sequence stays clear.
document-blocks/interactions§interactions.items.1
- MUST — P1x and P2x MUST be between 0 and 1; P1y and P2y can be any number (values outside 0–1 give a bounce/overshoot).
document-blocks/motion§motionEntry.function.1 - MUST — P1x — MUST be in [0, 1].
document-blocks/motion§motionEntry.function[prefixItems][0].1 - MUST — P2x — MUST be in [0, 1].
document-blocks/motion§motionEntry.function[prefixItems][2].1 - SHOULD — List the most common ones first; tools SHOULD keep this order.
document-blocks/motion§motion.1 - SHOULD — Tools SHOULD keep this order for display.
document-blocks/motion§motion.items.1
- SHOULD — Tools SHOULD keep this order; authors SHOULD lead with the most important.
document-blocks/principles§principles.items.1
- MUST — MUST match a token defined elsewhere in the system.
document-blocks/scale§scaleStep.token.1 - MAY — Tools MAY fill this in automatically.
document-blocks/scale§scaleStep.value.1 - SHOULD — Steps run smallest to largest; tools SHOULD keep this order.
document-blocks/scale§scale.1 - SHOULD — Tools SHOULD keep this order.
document-blocks/scale§scale.steps.1 - SHOULD — When adjusting a value, consumers SHOULD move to the adjacent step.
document-blocks/scale§scale.steps.2
- MUST — MUST be lowercase kebab-case and unique in the block.
document-blocks/sections§sectionEntry.anchor.1 - MAY — Left out, tools MAY derive one from the title.
document-blocks/sections§sectionEntry.anchor.2 - SHOULD — Tools SHOULD keep this order.
document-blocks/sections§sectionEntry.sections.1 - SHOULD — Tools SHOULD keep this order.
document-blocks/sections§sections.items.1
- SHOULD — Tools SHOULD keep this order for display.
document-blocks/states§states.items.1
- MUST — MUST be concrete and actionable: describe the action, not the goal.
document-blocks/steps§stepEntry.instruction.1 - MAY — Tools MAY render optional steps distinctly (ex: an 'optional' label).
document-blocks/steps§stepEntry.optional.1 - SHOULD — Tools SHOULD show ordered steps as a numbered list, unordered ones as a checklist.
document-blocks/steps§steps.ordered.1 - MUST — Tools MUST preserve this order when
ordered is true.document-blocks/steps§steps.items.1
- SHOULD — Tools SHOULD keep this order.
document-blocks/variants§enumVariant.values.1 - SHOULD — Tools SHOULD keep this order.
document-blocks/variants§variants.items.1
- MUST — MUST be relative — no absolute paths, protocol-relative paths, or scheme URIs (http:, file:, …).
dsds§fileRef.$ref.1 - MUST — Resolvers MUST catch cycles, MUST treat a broken file, pointer, or shape mismatch as a fatal error, and MUST only fetch remote files from an allow-list (see the spec's security rules).
dsds§fileRef.$ref.2 - MUST — A group MUST hold at least one entity.
dsds§entityGroup.1 - SHOULD — Order matters; tools SHOULD keep it.
dsds§entityGroup.entities.1
- MUST — MUST be lowercase kebab-case and unique within its entity group.
entities/chunk§chunk.identifier.1 - MUST — MUST be relative — no absolute paths, protocol-relative paths, or scheme URIs (http:, file:, …).
entities/chunk§chunk.code[oneOf][1].src.1 - SHOULD — Resolvers SHOULD only fetch from an allow-list, the same rule a
$ref fileRef follows.entities/chunk§chunk.code[oneOf][1].src.2
- MUST — MUST be unique within its entity group.
entities/component§component.identifier.1 - SHOULD — Tools SHOULD keep this order for display.
entities/component§component.documentBlocks.1 - MUST NOT — Tools MUST NOT show these blocks to humans.
entities/component§component.agentDocumentBlocks.1 - SHOULD — Agents SHOULD read both arrays, human docs first.
entities/component§component.agentDocumentBlocks.2
- MUST — MUST be unique within its entity group.
entities/foundation§foundation.identifier.1 - SHOULD — Tools SHOULD keep this order for display.
entities/foundation§foundation.documentBlocks.1 - MUST NOT — Tools MUST NOT show these blocks to humans.
entities/foundation§foundation.agentDocumentBlocks.1 - SHOULD — Agents SHOULD read both arrays, human docs first.
entities/foundation§foundation.agentDocumentBlocks.2
- MUST — MUST be lowercase kebab-case and unique within its entity group.
entities/guide§guide.identifier.1 - SHOULD — A guide reads top to bottom, so tools SHOULD keep this order.
entities/guide§guide.documentBlocks.1 - MUST NOT — Tools MUST NOT show these blocks to humans.
entities/guide§guide.agentDocumentBlocks.1 - SHOULD — Agents SHOULD read both arrays, human docs first.
entities/guide§guide.agentDocumentBlocks.2
- MUST — MUST be unique within its entity group.
entities/pattern§pattern.identifier.1 - SHOULD — Order matters —
interactions uses it to show the flow over time, and tools SHOULD keep it.entities/pattern§pattern.documentBlocks.1 - MUST NOT — Tools MUST NOT show these blocks to humans.
entities/pattern§pattern.agentDocumentBlocks.1 - SHOULD — Agents SHOULD read both arrays, human docs first.
entities/pattern§pattern.agentDocumentBlocks.2
- MUST — MUST match a token's
identifier defined elsewhere in the system.entities/theme§tokenOverride.token.1 - SHOULD — Tools SHOULD keep this order for display.
entities/theme§theme.documentBlocks.1 - MUST NOT — Tools MUST NOT show these blocks to humans.
entities/theme§theme.agentDocumentBlocks.1 - SHOULD — Agents SHOULD read both arrays, human docs first.
entities/theme§theme.agentDocumentBlocks.2
- MUST — MUST be set here unless a parent group already declares it — a token inherits the group's value if it skips its own.
entities/token§token.tokenType.1 - SHOULD — Tools SHOULD keep this order for display.
entities/token§token.documentBlocks.1 - MUST NOT — Tools MUST NOT show these blocks to humans.
entities/token§token.agentDocumentBlocks.1 - SHOULD — Agents SHOULD read both arrays, human docs first.
entities/token§token.agentDocumentBlocks.2 - MAY — A child MAY override it.
entities/token§tokenGroup.tokenType.1 - SHOULD — Order often shows a real progression (lightest to darkest, smallest to largest), so tools SHOULD keep it.
entities/token§tokenGroup.children.1 - MUST NOT — Tools MUST NOT show these blocks to humans.
entities/token§tokenGroup.agentDocumentBlocks.1 - SHOULD — Agents SHOULD read both arrays, human docs first.
entities/token§tokenGroup.agentDocumentBlocks.2
- MUST — MUST be lowercase kebab-case.
metadata/category§category.1
- SHOULD — 'ai-generated': mostly written by an AI with little to no human review — it MAY contain plausible-sounding mistakes and SHOULD be checked before an agent trusts it as fact.
metadata/doc-origin§authorshipValue.1 - MAY — Best for intent, but MAY be behind the shipped API.
metadata/doc-origin§docOriginValue.1 - SHOULD — 'reconstructed': written from memory or institutional knowledge, without checking the code — the least reliable for API facts, and SHOULD be verified before an agent relies on it.
metadata/doc-origin§docOriginValue.2 - SHOULD — For API accuracy, agents SHOULD prefer 'generated' or 'extracted'; for design intent, prefer 'authored'.
metadata/doc-origin§docOriginValue.3 - MAY — A document MAY be 'authored' overall while some blocks were 'extracted' or 'generated'.
metadata/doc-origin§docOrigin[oneOf][1].1 - MUST NOT — MUST NOT contain markup.
metadata/doc-origin§docOrigin[oneOf][1].note.1
- SHOULD — Owners SHOULD be teams, roles, or group aliases ('Design Systems', '@acme/design-system'), not individuals — a named person goes stale the moment they leave, which is exactly what this field is meant to survive.
metadata/governance§owner.1 - SHOULD — Tools SHOULD show the owner wherever a reader might need to flag a problem.
metadata/governance§owner.2 - SHOULD — SHOULD name a team or role, not an individual.
metadata/governance§owner[oneOf][1].name.1 - SHOULD — Freeform; tools SHOULD link it when it parses as a URL or email.
metadata/governance§owner[oneOf][1].contact.1 - SHOULD — Tools MAY treat an old or missing
lastReviewed as a staleness signal; agents SHOULD prefer more recently reviewed docs when sources disagree.metadata/governance§lastReviewed.1 - MUST NOT — MUST NOT contain markup.
metadata/governance§lastReviewed[oneOf][1].note.1 - MAY — Lets tools spot drift — if the code has moved past this version, the doc MAY be stale even if recently reviewed.
metadata/governance§lastReviewed[oneOf][1].reviewedAgainst.1 - SHOULD —
lastReviewed is optional but SHOULD be set once you have a review process; its object form records who reviewed it and which version, so a tool can answer 'is this verified, against what, and who vouches for it.'metadata/governance§governance.1
- MUST NOT — MUST NOT contain markup.
metadata/last-updated§lastUpdated[oneOf][1].note.1
- MUST — A deprecated entity MUST use the object form, because deprecation needs a deprecationNotice that says what to use instead.
metadata/status§status.1 - MAY — An entity MAY be 'stable' overall while some platforms are still 'experimental' or 'draft'.
metadata/status§status[oneOf][1].1 - SHOULD — Tools SHOULD show this as the main status indicator.
metadata/status§status[oneOf][1].overall.1 - MAY — Tools MAY surface this alongside the status indicator.
metadata/status§status[oneOf][1].note.1 - MUST — MUST say what to use instead (non-empty) and give a migration path.
metadata/status§status[oneOf][1].deprecationNotice.1 - SHOULD — Tools SHOULD display this prominently next to the status indicator.
metadata/status§status[oneOf][1].deprecationNotice.2
- MUST NOT — MUST NOT contain markup.
metadata/summary§summary.1
- MUST NOT — MUST NOT be empty.
metadata/thumbnail§thumbnail.alt.1