Conformance

This page defines what it means to conform to the Design System Documentation Spec 0.13.0, 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.

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, not an illustration of one. The index at the bottom of this page is generated from the schemas on every build, so it cannot drift from them. Cite statements by their location-based ID (e.g. common/link§link.kind.1); an ID changes only when the schema path it points at changes, which is the correct signal that a citation needs re-checking.

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 JSON Schema cannot 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 sufficient.

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 (deprecated forms exist for reading old documents, not writing new ones), and 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 does not recognize the meaning of, MUST preserve $extensions data it does not understand, MUST treat unresolvable references as defects rather than silently dropping them, and 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, and SHOULD 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:

TierMechanismFailure mode
StructuralJSON Schema (patterns, required, minItems, conditionals)Validation error — blocking
SemanticReference implementation checks (resolution, uniqueness, inheritance, cycles)Validation error — blocking
LintRules catalog (rules/rules.yaml, DSDS-001…)Warning — never blocking
AdvisorySHOULD/MAY statements consumed by judgmentNone
Normative statements index

Generated from the v0.13.0 schemas by scripts/extract-normative.mjs — do not edit by hand. 171 statements: 68 MUST, 24 MUST NOT, 64 SHOULD, 2 SHOULD NOT, 13 MAY.

common common/criterion
  • MUST — Values are lowercase kebab-case like every DSDS-native vocabulary — in prose, the keywords stay capitalized (MUST, SHOULD NOT) where they carry conformance weight. common/criterion§conformanceLevel.1
  • MUST — 'automated': a runner fully decides; 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 — A runner that does not recognize the scheme 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 — Fixtures make criteria self-verifying: a conformance runner SHOULD execute the criterion's check (when present) against each fixture and confirm the declared outcome is reproduced — a 'fail' fixture that passes means the check no longer detects what it claims to. common/criterion§criterionFixture.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 — renaming breaks result history across runs. 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 mint 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 — Tools resolve every entity reference through the same rule: the 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 against the entity catalog to build navigable cross-references; a reference that resolves to nothing is a defect in the document. 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 — When provided, tools MAY fetch and resolve the base document for merge, validation, or docs generation. common/extends§documentExtends.url.1
  • SHOULD — When omitted, tools SHOULD resolve to the latest available version. common/extends§documentExtends.version.1
  • MUST — MUST match the identifier property of the base entity in the parent system. common/extends§entityExtends.identifier.1
  • MAY — Tools MAY use these for changelog generation, diff views, or migration guides. common/extends§entityExtends.modifications.1
common/extensions
  • MUST — Keys MUST use vendor-specific namespaces. common/extensions§(root).1
  • MUST — Keys MUST use vendor-specific namespaces (reverse domain name notation is recommended) — at least two dot-separated segments, e.g. 'com.figma', 'acme.tooling'. common/extensions§extensions.1
  • MUST — Tools that do not 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
  • SHOULD — Those forms still validate for backward compatibility, but tools SHOULD warn (DSDS-010) and authors SHOULD migrate them to relationships. common/link§link.1
  • MUST — Custom values are allowed and MUST match ^[a-z][a-z0-9-]*$ (schema-enforced; all standard kinds already do). common/link§link.kind.1
  • MUST — MUST be a valid absolute URI. common/link§link.url.1
  • MUST — Retained for backward compatibility: a link with an identifier still follows entityRef resolution rules (it MUST match a documented entity). common/link§link.identifier.1
common/presentation
  • MUST NOT — MUST be provided and MUST NOT be empty. common/presentation§mediaAlt.1
  • MUST NOT — MUST be provided for accessibility and MUST NOT be empty. common/presentation§presentationImage.alt.1
  • MUST NOT — MUST be provided for accessibility and MUST NOT be empty. common/presentation§presentationVideo.alt.1
common/relationship
  • MUST — The target is named by identifier and follows the same resolution rule as every entity reference: it MUST match a documented entity. common/relationship§(root).1
  • MUST NOT — Tools derive the inverse edges ('composed-by', 'replaced-by', 'contains', 'dependency-of', 'extended-by') and MUST NOT require them to be authored. common/relationship§relationType.1
  • MUST — Custom relations are allowed and MUST be vendor-namespaced (e.g. 'acme.themes'). common/relationship§relationType.2
  • MUST — MUST match a documented entity's identifier. 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 are allowed (e.g., 'sunset', 'archived', 'beta') 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
  • MUST NOT — MUST NOT be empty. common/status§platformStatus.deprecationNotice.1
common/system-info
  • SHOULD — SHOULD follow semver so tools can compare against extends.version and reviewedAgainst values. common/system-info§systemInfo.systemVersion.1
common/token-overrides
  • MUST — One definition anchors the same rule in every position: token references MUST name a documented token, never a raw value, so styling can't silently drift from the token source. common/token-overrides§(root).1
  • MUST — Values are token identifier references (e.g., 'color-action-primary', 'radius-md') and follow the same resolution rule as every entity reference: in a system that documents its token layer, they MUST resolve to a documented token. common/token-overrides§tokenOverrides.1
common/use-cases
  • SHOULD — Order matters: tools SHOULD keep it for display. common/use-cases§useCases.items.1
  • SHOULD — Authors SHOULD lead with recommended scenarios. common/use-cases§useCases.items.2
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
document-blocks/checklist
  • MUST — An item MUST carry a label; all other fields are optional. document-blocks/checklist§checklistItem.1
  • MUST — MUST be specific enough to confirm. document-blocks/checklist§checklistItem.label.1
  • MUST — MUST be lowercase kebab-case. document-blocks/checklist§checklistItem.criterion.1
  • SHOULD — Custom values are allowed and SHOULD be lowercase kebab-case. document-blocks/checklist§checklistItem.category.1
  • MAY — Tools MAY render optional items distinctly (e.g., an 'optional' label). document-blocks/checklist§checklistItem.optional.1
  • SHOULD — Tools SHOULD render unordered checklists as checkboxes and ordered ones as a numbered sequence. document-blocks/checklist§checklist.ordered.1
  • MUST — Order is significant for ordered checklists, so tools MUST preserve it. document-blocks/checklist§checklist.items.1
document-blocks/content
  • SHOULD — The terms SHOULD match other term values in this content block's labels array — the block is the dictionary they resolve against, so tools can cross-reference them. document-blocks/content§contentLabelEntry.alternatives.1
  • SHOULD — Custom values are allowed and SHOULD be lowercase kebab-case. document-blocks/content§localizationEntry.concern.1
  • SHOULD — Order matters, so tools SHOULD keep it for display. document-blocks/content§content.labels.1
  • MAY — Authors MAY order alphabetically or by frequency of use. document-blocks/content§content.labels.2
  • SHOULD — Order matters, so tools SHOULD display entries in this order. document-blocks/content§content.localization.1
  • SHOULD — Authors SHOULD order by impact or frequency. document-blocks/content§content.localization.2
document-blocks/design-specifications
  • MUST — In a system with a token layer, this MUST be a design token identifier (e.g., 'color-action-primary', 'space-4') so the value stays single-sourced and cannot silently drift from the token system. document-blocks/design-specifications§designValue.1
document-blocks/guidelines
  • MUST — MUST be concrete and unambiguous. document-blocks/guidelines§guidelineEntry.guidance.1
  • MUST NOT — MUST NOT restate the guidance. document-blocks/guidelines§guidelineEntry.rationale.1
  • SHOULD — Custom values are allowed and SHOULD be lowercase kebab-case. document-blocks/guidelines§guidelineEntry.category.1
  • SHOULD — Order matters, so tools SHOULD display guidelines in this order. document-blocks/guidelines§guidelines.items.1
  • SHOULD — Authors SHOULD order by importance or group by category. document-blocks/guidelines§guidelines.items.2
document-blocks/imports
  • SHOULD — SHOULD be copy-pasteable and ready to use. document-blocks/imports§importEntry.code.1
document-blocks/interactions
  • MUST — Each identifier MUST match a component documented in the system; the optional role says what the component does in this step. document-blocks/interactions§interactionEntry.components.1
  • SHOULD — Authors SHOULD include steps for the initial trigger, the system's response, recovery or correction steps, and completion. document-blocks/interactions§interactions.1
  • SHOULD — Ordering is significant, so tools SHOULD keep and display steps in this order to show the sequence over time. document-blocks/interactions§interactions.items.1
document-blocks/motion
  • MUST — When neither is provided, the description field MUST explain the guidance — an empty duration object carries no information, so at least one of min, max, or description is required. document-blocks/motion§motionDuration.1
  • MUST — P1x and P2x MUST be in [0, 1]. 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 — Ordering is significant, so tools SHOULD display easings in this order. document-blocks/motion§motion.1
  • SHOULD — Ordering is significant, so tools SHOULD display easings in this order. document-blocks/motion§motion.items.1
document-blocks/principles
  • SHOULD — Ordering is significant, so tools SHOULD display principles in this order. document-blocks/principles§principles.items.1
  • SHOULD — Authors SHOULD order by importance or by the natural progression of the design philosophy. document-blocks/principles§principles.items.2
document-blocks/scale
  • MUST — MUST match the identifier of a token defined elsewhere in the system. document-blocks/scale§scaleStep.token.1
  • MAY — Tools MAY fill this in from the token catalog. document-blocks/scale§scaleStep.value.1
  • SHOULD — Tools SHOULD keep this order for display. document-blocks/scale§scale.1
  • SHOULD — Ordering is significant, so tools SHOULD keep it for display. document-blocks/scale§scale.steps.1
  • SHOULD — Consumers SHOULD treat adjacent steps as the natural next-smaller and next-larger options when adjusting a value. document-blocks/scale§scale.steps.2
document-blocks/sections
  • MUST — A section MUST carry a title. document-blocks/sections§sectionEntry.1
  • MUST — MUST be lowercase kebab-case and unique within the parent block. document-blocks/sections§sectionEntry.anchor.1
  • MAY — When omitted, tools MAY derive an anchor from the title. document-blocks/sections§sectionEntry.anchor.2
  • SHOULD — Ordering is significant, so tools SHOULD render sub-sections in this order. document-blocks/sections§sectionEntry.sections.1
  • SHOULD — Ordering is significant, so tools SHOULD keep it. document-blocks/sections§sections.items.1
document-blocks/states
  • SHOULD — Ordering is significant, so tools SHOULD display states in this order. document-blocks/states§states.items.1
document-blocks/steps
  • MUST — A step MUST carry a title. document-blocks/steps§stepEntry.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 (e.g., an 'optional' label). document-blocks/steps§stepEntry.optional.1
  • SHOULD — Tools SHOULD render ordered procedures as numbered lists and unordered ones as a checklist or bulleted list. document-blocks/steps§steps.ordered.1
  • MUST — Ordering is significant, so tools MUST preserve it for ordered procedures. document-blocks/steps§steps.items.1
document-blocks/variants
  • SHOULD — Ordering is significant, so tools SHOULD keep it for display. document-blocks/variants§enumVariant.values.1
  • SHOULD — Ordering is significant, so tools SHOULD display dimensions in this order. document-blocks/variants§variants.items.1
Root schema dsds
  • MUST — MUST be relative — the pattern rejects absolute paths, protocol-relative references, and scheme-bearing URIs (http:, file:, …). dsds§fileRef.$ref.1
  • MUST — Resolvers MUST detect cycles. dsds§fileRef.$ref.2
  • MUST — They MUST treat unresolvable files or pointers and shape mismatches as fatal. dsds§fileRef.$ref.3
  • MUST — They MUST gate any remote dereferencing behind an allow-list (see the spec's reference-resolution and security rules). dsds§fileRef.$ref.4
  • MUST — A group MUST hold at least one entity — an empty group has nothing to document. dsds§entityGroup.1
  • SHOULD — Order is significant: tools SHOULD keep it for display. 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 — the pattern rejects absolute paths, protocol-relative references, and scheme-bearing URIs (http:, file:, …). entities/chunk§chunk.code[oneOf][1].src.1
  • SHOULD — Resolvers SHOULD gate any remote dereferencing behind an allow-list, following the same rules a $ref fileRef obeys. entities/chunk§chunk.code[oneOf][1].src.2
  • MUST — Content here is agent-only: hard MUST/MUST-NOT rules, verification checklists, and adaptation constraints an agent needs when copying the chunk into an application. entities/chunk§chunk.agentDocumentBlocks.1
  • MUST — When both this shorthand and an equivalent block in documentBlocks are present, tools MUST treat the documentBlocks block as authoritative. entities/chunk§chunk.guidelines.1
  • SHOULD — Authors SHOULD lead with recommended scenarios. entities/chunk§chunk.useCases.1
  • MUST — When both this shorthand and an equivalent block in documentBlocks are present, tools MUST treat the documentBlocks block as authoritative. entities/chunk§chunk.useCases.2
entities/component
  • MUST — MUST be unique within its entity group. entities/component§component.identifier.1
  • SHOULD — Order matters, so tools SHOULD keep it for display. entities/component§component.documentBlocks.1
  • MUST — For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. entities/component§component.agentDocumentBlocks.1
  • MUST NOT — Tools MUST NOT render these blocks in human-facing docs. entities/component§component.agentDocumentBlocks.2
  • SHOULD — Agents SHOULD read both arrays, human blocks first. entities/component§component.agentDocumentBlocks.3
entities/foundation
  • MUST — MUST be unique within its entity group. entities/foundation§foundation.identifier.1
  • SHOULD — Order matters, so tools SHOULD keep it for display. entities/foundation§foundation.documentBlocks.1
  • MUST — For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. entities/foundation§foundation.agentDocumentBlocks.1
  • MUST NOT — Tools MUST NOT render these blocks in human-facing docs. entities/foundation§foundation.agentDocumentBlocks.2
  • SHOULD — Agents SHOULD read both arrays, human blocks first. entities/foundation§foundation.agentDocumentBlocks.3
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 order matters and tools SHOULD keep it for display. entities/guide§guide.documentBlocks.1
  • MUST — For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. entities/guide§guide.agentDocumentBlocks.1
  • MUST NOT — Tools MUST NOT render these blocks in human-facing docs. entities/guide§guide.agentDocumentBlocks.2
  • SHOULD — Agents SHOULD read both arrays, human blocks first. entities/guide§guide.agentDocumentBlocks.3
entities/pattern
  • MUST — MUST be unique within its entity group. entities/pattern§pattern.identifier.1
  • SHOULD — Order matters, so tools SHOULD keep it for display. entities/pattern§pattern.documentBlocks.1
  • MUST — For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. entities/pattern§pattern.agentDocumentBlocks.1
  • MUST NOT — Tools MUST NOT render these blocks in human-facing docs. entities/pattern§pattern.agentDocumentBlocks.2
  • SHOULD — Agents SHOULD read both arrays, human blocks first. entities/pattern§pattern.agentDocumentBlocks.3
entities/theme
  • MUST — MUST match the identifier of a token defined elsewhere in the system. entities/theme§tokenOverride.token.1
  • SHOULD — Order matters, so tools SHOULD keep it for display. entities/theme§theme.documentBlocks.1
  • MUST — For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. entities/theme§theme.agentDocumentBlocks.1
  • MUST NOT — Tools MUST NOT render these blocks in human-facing docs. entities/theme§theme.agentDocumentBlocks.2
  • SHOULD — Agents SHOULD read both arrays, human blocks first. entities/theme§theme.agentDocumentBlocks.3
entities/token
  • MUST — MUST be present unless an ancestor token group declares tokenType — children inherit the group's value when they omit their own. entities/token§token.tokenType.1
  • SHOULD — Order matters, so tools SHOULD keep it for display. entities/token§token.documentBlocks.1
  • MUST — For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. entities/token§token.agentDocumentBlocks.1
  • MUST NOT — Tools MUST NOT render these blocks in human-facing docs. entities/token§token.agentDocumentBlocks.2
  • SHOULD — Agents SHOULD read both arrays, human blocks first. entities/token§token.agentDocumentBlocks.3
  • MAY — Each token in children MAY override this value. entities/token§tokenGroup.tokenType.1
  • MUST — Each item MUST be either a token or a tokenGroup. entities/token§tokenGroup.children.1
  • SHOULD — Order often shows a meaningful progression (e.g., lightest to darkest, or smallest to largest), so it matters and tools SHOULD keep it for display. entities/token§tokenGroup.children.2
  • MUST — For example: hard MUST/MUST-NOT rules an agent should treat as firm limits; notes that correct a mistake an agent is likely to make, such as reaching for this entity when a confusable one fits better; constraints backed by test-run evidence; and machine-checkable criteria with verification modes. entities/token§tokenGroup.agentDocumentBlocks.1
  • MUST NOT — Tools MUST NOT render these blocks in human-facing docs. entities/token§tokenGroup.agentDocumentBlocks.2
  • SHOULD — Agents SHOULD read both arrays, human blocks first. entities/token§tokenGroup.agentDocumentBlocks.3
metadata metadata/category
  • MUST — MUST be lowercase kebab-case. metadata/category§category.1
metadata/doc-origin
  • SHOULD — 'ai-generated': produced by an AI model or agent with at most light human review; MAY contain plausible-but-wrong statements and SHOULD be verified before an agent treats it as ground truth. metadata/doc-origin§authorshipValue.1
  • MAY — 'authored': written before or alongside the implementation as its specification — the code follows the doc; authoritative for intent, but MAY lag the shipped API. metadata/doc-origin§docOriginValue.1
  • SHOULD — 'reconstructed': written after the fact from institutional knowledge, without systematically consulting the implementation; lowest fidelity to the API and SHOULD be verified before an agent relies on it for API facts. metadata/doc-origin§docOriginValue.2
  • SHOULD — Agents SHOULD prefer 'generated' and 'extracted' documentation for API accuracy and 'authored' documentation for design intent. metadata/doc-origin§docOriginValue.3
  • MAY — A document MAY be 'authored' overall while individual 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 (e.g., 'Design Systems', '@acme/design-system') rather than named individuals — person-level ownership goes stale on turnover, which is the exact situation this field exists for. metadata/governance§owner.1
  • SHOULD — Tools SHOULD surface the owner wherever a reader might need to escalate a discrepancy. 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 render it as a link when it parses as a URL or email. metadata/governance§owner[oneOf][1].contact.1
  • SHOULD — Tools MAY treat an old or absent lastReviewed as a staleness signal, and agents SHOULD prefer recently reviewed documentation when sources conflict. metadata/governance§lastReviewed.1
  • MUST NOT — MUST NOT contain markup. metadata/governance§lastReviewed[oneOf][1].note.1
  • MAY — Lets tools detect drift: if the implementation has moved past this version, the documentation MAY be out of date even if recently reviewed. metadata/governance§lastReviewed[oneOf][1].reviewedAgainst.1
  • SHOULDlastReviewed is optional but SHOULD be set once a review process exists; its object form records who reviewed and which implementation version was verified (reviewedAgainst), so a tool can answer 'is this doc verified, against which version, 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 individual platforms are still 'experimental' or 'draft'. metadata/status§status[oneOf][1].1
  • SHOULD — Tools SHOULD display this as the primary status indicator. metadata/status§status[oneOf][1].overall.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 be provided for accessibility and MUST NOT be empty. metadata/thumbnail§thumbnail.alt.1

Design System Documentation Spec (DSDS) 0.13.0 — Draft Specification

GitHub