# Conformance — DSDS 0.15.2 This page defines what it means to conform to the Design System Doc Spec {{VERSION}}, 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](https://www.rfc-editor.org/rfc/rfc2119) (as clarified by [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)): they are normative only when they appear in upper case. ## Where the normative text lives DSDS keeps its normative language inside the schema `description` strings, next to the structures that enforce it. The schema *is* the specification. The index at the bottom of this page is generated from the schemas on every build to avoid drift. Cite statements by their location-based ID (ex: `common/link§link.kind.1`). An ID only changes when the schema path it points to changes. That's signals a citation needs to be checked. ## Conformance classes DSDS defines four conformance classes. A claim of conformance names the class it applies to. ### Conforming document A JSON document that validates against the DSDS schema for the version its `dsdsVersion` declares, **and** satisfies the semantic rules that JSON Schema alone can't express: - identifier uniqueness - reference resolution - relationship-graph integrity - token-layer resolution - `tokenType` inheritance - `docOrigin` block-key resolution - extension-key namespacing Schema validity alone is necessary, but not enough. ### Conforming producer 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 ### Conforming consumer 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) ### Conforming validator 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 `rules/rules.yaml`) as non-blocking diagnostics. The reference implementation is `scripts/validate.js`. Its negative-fixture suite in `test/invalid/` pins every guard, and doubles as a conformance test suite for independent validators. ## Enforcement tiers 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 (`rules/rules.yaml`, DSDS-001…) | Warning — never blocking | | Advisory | SHOULD/MAY statements consumed by judgment | None | ## Normative statements index {/* dsds:normative-index */} *Generated from the v{{VERSION}} schemas by `scripts/extract-normative.mjs` — do not edit by hand. 148 statements: 54 MUST, 23 MUST NOT, 55 SHOULD, 2 SHOULD NOT, 14 MAY.* ### common #### common/criterion - **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` #### common/dated-note - **MUST NOT** — MUST NOT contain markup and MUST NOT be empty. `common/dated-note§plainNote.1` #### common/entity-ref - **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` #### common/example - **SHOULD** — Tools SHOULD render value-only examples as table rows or inline displays. `common/example§example.1` #### common/extends - **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` #### common/extensions - **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` #### common/link - **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` #### common/presentation - **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` #### common/relationship - **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` #### common/rich-text - **MUST** — Tools MUST render the value as markdown. `common/rich-text§richText.1` #### common/status - **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` #### common/system-info - **SHOULD** — SHOULD follow semver so tools can compare it against `extends.version` and `reviewedAgainst`. `common/system-info§systemInfo.version.1` #### common/token-overrides - **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` #### common/use-cases - **SHOULD** — Order matters: tools SHOULD keep it for display, and authors SHOULD lead with recommended scenarios. `common/use-cases§useCases.items.1` ### document-blocks #### document-blocks/api - **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` and `values` 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` #### document-blocks/checklist - **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` #### document-blocks/content - **SHOULD** — These SHOULD match other `term` values in this block's `labels` 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` #### document-blocks/design-specifications - **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` #### document-blocks/guidelines - **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` #### document-blocks/imports - **SHOULD** — SHOULD be copy-paste ready. `document-blocks/imports§importEntry.code.1` #### document-blocks/interactions - **MUST** — Each `identifier` MUST match a documented component; the optional `role` 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` #### document-blocks/motion - **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` #### document-blocks/principles - **SHOULD** — Tools SHOULD keep this order; authors SHOULD lead with the most important. `document-blocks/principles§principles.items.1` #### document-blocks/scale - **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` #### document-blocks/sections - **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` #### document-blocks/states - **SHOULD** — Tools SHOULD keep this order for display. `document-blocks/states§states.items.1` #### document-blocks/steps - **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` #### document-blocks/variants - **SHOULD** — Tools SHOULD keep this order. `document-blocks/variants§enumVariant.values.1` - **SHOULD** — Tools SHOULD keep this order. `document-blocks/variants§variants.items.1` ### Root schema #### dsds - **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` ### entities #### entities/chunk - **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` #### entities/component - **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` #### entities/foundation - **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` #### entities/guide - **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` #### entities/pattern - **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` #### entities/theme - **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` #### entities/token - **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` ### metadata #### metadata/category - **MUST** — MUST be lowercase kebab-case. `metadata/category§category.1` #### metadata/doc-origin - **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` #### metadata/governance - **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` #### metadata/last-updated - **MUST NOT** — MUST NOT contain markup. `metadata/last-updated§lastUpdated[oneOf][1].note.1` #### metadata/status - **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` #### metadata/summary - **MUST NOT** — MUST NOT contain markup. `metadata/summary§summary.1` #### metadata/thumbnail - **MUST NOT** — MUST NOT be empty. `metadata/thumbnail§thumbnail.alt.1` {/* /dsds:normative-index */}