Design Data Specification

Version: 1.0.0-draft
Status: Draft — normative text and schemas may change before 1.0.0.

This document is the top-level overview for the Design Data Specification: a machine-readable model for Spectrum design tokens, mode sets, platform manifests, and validation.

Scope

The specification defines:

1. Token format — structured token identity (name), literal value or alias $ref, and lifecycle metadata (Token format).
2. Taxonomy — concept categories, token term vocabulary, formatting style, and the distinction between component anatomy and token objects (Taxonomy).
3. Registry — named value collections that supply allowed vocabulary for token name fields and component metadata; three-registry boundary (anatomy-terms, token-objects, categories) and packaging strategy (Registry).
4. Component format — component declaration shape: API options, named content slots, anatomy parts, state model, and cross-reference validation rules (Component format).
   • Anatomy format — anatomy part declaration shape: field constraints, canonical anatomy vocabulary, and cross-reference rules for token anatomy field values (Anatomy format).
   • State model — state declaration shape: trigger semantics, precedence and resolution algorithm, canonical state vocabulary, and cross-reference rules for token state field values (State model).
5. Cascade and resolution — layered data (foundation, platform, product), specificity, and how a context picks a winning value (Cascade).
6. Mode Sets — declared modes, defaults, and coverage expectations (Mode Sets).
7. Platform manifest — how a platform repo pins foundation data, filters tokens, and applies typed overrides (Manifest).
8. Semantic diff — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions (Diff).
9. Query notation — filter syntax for selecting tokens by structured fields (Query).
10. Accessibility — component accessibility vocabulary: semantic role, interaction and keyboard intents, focus behavior, WCAG criteria, and state-level AT fields (Accessibility).
    • Accessibility adapters — informative platform adapter contracts: Web/ARIA, iOS UIAccessibility, Android AccessibilityNodeInfo, and voice/multimodal (Accessibility adapters).
11. Document blocks — typed prose blocks attachable to tokens, components, and anatomy parts; makes design guidance machine-readable and agent-queryable (Document blocks).
12. Agent-readable surface — operations and transport contracts (CLI, MCP server, Agent Skill) for AI agents consuming spec-conformant design data; covers session primer, token resolution, validation, query, and component description (Agent-readable surface).
13. Evolution — deprecation lifecycle, migration windows, change classification, and legacy format contract (Evolution).
14. Dataset layout — normative directory structure of a dataset (tokens/, components/, fields/, mode-sets/, registry/, guidelines/), discovery algorithm, and optional root descriptor (Dataset layout).
15. Guideline documents — standalone JSON files representing non-component design guidance pages (color, typography, motion, spacing, principles, etc.); each wraps page metadata and a documentBlocks body (Guideline format).
16. Authoring workflow — normative contract for authoring design data via tooling: authoritative source location, lifecycle operations (create / edit / deprecate / rename / alias-rewire / mode-set management), taxonomy-aware decomposition requirement, and output-generation obligations (Authoring workflow).

Conformance

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, and OPTIONAL in this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Conformance levels

Validation layers

Conformance is checked in three layers (all under @adobe/design-data-spec):

A conforming validator MUST implement Layer 1 for supported document types and SHOULD implement Layer 2 rules whose introduced_in is less than or equal to the validator’s claimed spec version.

Spec version and SemVer

This document set carries the spec version 1.0.0-draft. Published artifacts (schemas, rule catalog) are expected to align with Semantic Versioning once 1.0.0 is released: MAJOR for incompatible schema or rule behavior, MINOR for backward-compatible additions, PATCH for clarifications and compatible fixes.

Full governance (compatibility tiers, migration, CLI --spec-version) is discussed in discussion #735 — Versioning and Evolution.

Normative references (sibling documents)

JSON Schema $id and versioning

NORMATIVE: Canonical schema documents use versioned path $id URIs so major revisions can coexist on the documentation host:

• Base: https://opensource.adobe.com/spectrum-design-data/schemas/v0/
• Examples: .../v0/token.schema.json, .../v0/mode-set.schema.json, .../v0/manifest.schema.json

The v0 segment denotes the draft / pre-1.0 schema family aligned with spec version 1.0.0-draft. A future 1.0.0 stable release MAY introduce v1 paths without reusing v0 URLs for incompatible shapes.

RECOMMENDED: Each root schema document includes a top-level string property specVersion (const matching this spec’s version label) when the instance is a design-data document that should self-identify; see individual schemas.

Packaged copies in this repository live under packages/design-data-spec/schemas/; their $id still identifies the canonical published URL above.

Relationship to existing Adobe packages

Umbrella discussions

• #714 — Design Data Specification (umbrella)
• #715 — Distributed Design Data Architecture
• #646 — Token Schema Structure and Validation System