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).

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