Spectrum Design Data Specification (Bikeshed Prototype)

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

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

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

1.2.1. Conformance levels

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

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

1.4. Normative references (sibling documents)

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

1.6. Relationship to existing Adobe packages

1.7. Umbrella discussions

• #714 — Design Data Specification (umbrella)

• #715 — Distributed Design Data Architecture

• #646 — Token Schema Structure and Validation System

2. Token format

Spec version: 1.0.0-draft (see Overview)

This document defines the normative token object: identity (name), either a literal value or an alias $ref, optional metadata, and value types validated by JSON Schema.

2.1. Token object

A token is a JSON object that satisfies the Layer 1 schema token.schema.json (canonical $id: https://opensource.adobe.com/spectrum-design-data/schemas/v0/token.schema.json).

2.1.1. Required shape

A token MUST contain:

1. name — a JSON object (the name object) as defined below, or a non-empty plain string (escape hatch — see String-name escape hatch).

2. Exactly one of:

   • value — a literal token value (type depends on value-type schema), or

   • $ref — a string reference to another token (alias).

A token MUST NOT include both value and $ref.

2.1.2. String-name escape hatch

A token’s name field MAY be a non-empty plain string instead of a name object when the token’s identity cannot be expressed using the structured taxonomy fields.

{
  "name": "focus-ring-color-key-focus",
  "value": "#0265dc",
  "uuid": "aaaaaaaa-0011-4000-8000-000000000001"
}

NORMATIVE: String-named tokens are schema-valid. Validators MUST accept them without a structural error.

NORMATIVE: String-named tokens MUST trigger rule SPEC-017 (severity: warning, category: tech-debt). The warning surfaces the token as tracked debt requiring future remediation.

NORMATIVE: String-named tokens MUST NOT participate in name-object cascade mode-set matching, specificity calculation, or registry vocabulary checks (SPEC-009 does not apply).

RECOMMENDED: Authors SHOULD treat string names as a temporary escape hatch and track a remediation plan. Each string-named token SHOULD eventually be given a structured name object, at which point SPEC-017 no longer fires.

2.1.3. Name object

The name object identifies the token in a structured way. Implementations use it for cascade matching, specificity, and tooling.

NORMATIVE fields (all string unless noted):

The set of available name-object fields is declared in the design system’s field catalog (fields/ directory). Each field declaration conforms to field.schema.json and specifies its kind (semantic or mode-set), vocabulary registry, validation severity, and default serialization position. See Taxonomy for the full concept category hierarchy, component anatomy vs. token objects, and serialization rules.

Fields are divided into semantic fields (identity, structure, intent) and mode-set fields (axes of variation for cascade resolution). The tables below list Spectrum’s foundation-standard fields as declared in the catalog.

2.1.3.1. Semantic fields

The table below lists all semantic fields. Fields marked with a scope are domain-restricted — see Taxonomy — Token-type taxonomies for the normative per-domain field rules and serialization orders. Validators enforce scope restrictions via rule SPEC-042.

Universal semantic fields (scope: null — apply to all token types):

Domain-scoped semantic fields (only valid on the indicated token type):

2.1.3.2. Mode-set fields

NORMATIVE: Each field is validated according to the validation severity declared in its field declaration. Semantic fields typically use advisory severity (warning); mode-set fields use strict severity (error). See Taxonomy — Name object field categories.

RECOMMENDED: Name objects use a consistent key ordering in authored files for diffs; this is not a conformance requirement. Concept ordering for serialized names is defined in Taxonomy — Default serialization.

2.1.4. Alias ($ref)

When $ref is present, the token is an alias. The $ref string MUST be a non-empty string interpreted as a token path or stable identifier resolvable by the validator (resolution rules are Layer 2; see rule SPEC-001 in rules/rules.yaml).

2.1.5. Literal value

When value is present, it MUST conform to the declared value type for that token. Value types are defined under schemas/value-types/ and referenced from the token schema.

2.1.6. Lifecycle and metadata

The following OPTIONAL fields implement the token lifecycle model described in #623 and the evolution policy in Evolution. Inspired by Swift’s @available attribute, Kotlin’s @Deprecated, and OpenAPI 3.3’s deprecation model.

2.1.6.1. Lifecycle example

{
  "name": { "component": "button", "object": "background", "property": "color", "variant": "primary" },
  "value": "#0265dc",
  "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
  "introduced": "1.0.0",
  "deprecated": "3.2.0",
  "deprecated_comment": "Use action-background-default instead.",
  "replaced_by": "bbbbbbbb-0002-4000-8000-000000000001",
  "plannedRemoval": "4.0.0"
}

2.1.6.2. Normative rules

NORMATIVE: If deprecated is present, deprecated_comment SHOULD be present.

NORMATIVE: If replaced_by is an array, deprecated_comment is REQUIRED — the comment MUST explain which replacement applies in which context.

NORMATIVE: If replaced_by is present, deprecated MUST be present.

NORMATIVE: If plannedRemoval is present, deprecated MUST be present, and the plannedRemoval version MUST NOT precede the deprecated version.

NORMATIVE: Each UUID in replaced_by MUST resolve to an existing token in the dataset (see rule SPEC-010).

2.1.6.3. Legacy format mapping

When generating legacy-format output from cascade tokens:

• deprecated: "3.2.0" maps to deprecated: true

• replaced_by: "<uuid>" maps to renamed: "<target-token-name>" (resolved via UUID lookup)

• introduced and plannedRemoval have no legacy equivalent and are not emitted

When migrating legacy-format tokens to cascade:

• deprecated: true maps to deprecated: "unknown" (authors should backfill the actual version)

• renamed: "<name>" maps to replaced_by: "<uuid>" (resolved via name lookup across all files in the migrated input set). If the rename target is not found in the scanned corpus, the field is dropped — replaced_by must be set manually in that case

2.1.7. specVersion

RECOMMENDED: Root token documents (when stored as standalone JSON files) include specVersion with const 1.0.0-draft for self-identification. Embedded tokens inside larger files MAY omit it if the parent document carries version metadata.

2.1.8. Name-object migration policy

This section defines the normative policy for migrating tokens from string-form names to structured name objects, and for narrowing the property field to its intended CSS/styling-attribute semantics.

2.1.8.1. String-name escape hatch — SPEC-017 severity schedule

String-named tokens (see String-name escape hatch) trigger SPEC-017 at warning severity through the current minor series. Authors SHOULD treat SPEC-017 warnings as actionable tech debt and maintain a remediation backlog (e.g. packages/tokens/naming-exceptions.json).

NORMATIVE: SPEC-017 MUST graduate from warning to error at spec version 2.0.0, no earlier than two minor versions after the minor release that ships this section. This conforms to the evolution policy — rule severity tightening is a major change.

No string-named token may remain in a conforming dataset after the 2.0.0 cut without first being converted to a structured name object or removed.

2.1.8.2. Narrowed property semantics

The property field on a name object is the CSS/styling attribute or design-system abstraction being defined — not an anatomy part, not a styling surface, and not a legacy compound name string. Not all valid values are CSS property identifiers; design-system abstractions (e.g. padding-horizontal, overlay-color, size) are permitted.

NORMATIVE: Values for property SHOULD come from the property-terms registry. Non-registry values emit an advisory warning (SPEC-009 applied to the property field).

Examples of valid property values: color, background-color, border-radius, font-size, gap, opacity.

Examples of invalid property values (migration debt):

• Anatomy parts — use the anatomy field instead (handle, icon, label).

• Styling surfaces — use the object field instead (background, border, edge).

• Legacy compound names — split into structured fields (focus-ring-color-key-focus → component + anatomy + object + property + state).

2.1.8.3. Author migration guidance

When converting a string-named token to a structured name object:

1. Parse the legacy name string into its constituent segments using the default serialization order.

2. Place the CSS/styling attribute in property (SHOULD be in property-terms.json).

3. Route anatomy parts to anatomy (validated against anatomy-terms.json).

4. Route styling surfaces (background, border, edge) to object (validated against token-objects.json).

5. Retain component, variant, state, and other structural fields as-is.

6. Remove the token from naming-exceptions.json after conversion.

2.2. Document shape

Cascade-format tokens are stored in JSON files that conform to cascade-file.schema.json (canonical $id: https://opensource.adobe.com/spectrum-design-data/schemas/v0/cascade-file.schema.json).

NORMATIVE: A cascade file MUST be a JSON array of token objects. Each element MUST conform to token.schema.json.

NORMATIVE: The array is ordered. Document order is used for tie-breaking during cascade resolution (earlier element wins); see Cascade — Semantic specificity.

RECOMMENDED: A cascade file uses the .tokens.json extension to distinguish it from legacy set-format files.

Example:

[
  { "name": { "object": "background", "property": "color" }, "value": "#f5f5f5", "uuid": "..." },
  { "name": { "object": "background", "property": "color", "colorScheme": "dark" }, "value": "#1e1e1e", "uuid": "..." }
]

2.3. Value types

Individual types (color, dimension, opacity, etc.) MUST be defined as JSON Schemas under schemas/value-types/ and MUST use $id under the same v0 base path as Overview — JSON Schema $id.

2.3.1. Value-type declaration ($valueType)

A token MAY include a $valueType field: a URI reference pointing to a value-type schema under schemas/value-types/.

{
  "name": { "property": "typography-scale", "scale": "desktop" },
  "$valueType": "value-types/typography-scale.schema.json",
  "value": { "fontSize": "14px", "lineHeight": "18px" },
  "uuid": "377145e8-079b-43fd-b522-8f16b1b8f883"
}

NORMATIVE: When $valueType is present on a token with a literal value, the value MUST validate against the referenced schema (rule SPEC-016).

NORMATIVE: When $valueType is present on an alias token ($ref), the alias resolution chain MUST terminate at a token whose value validates against the same value-type schema (rule SPEC-002, extended).

RECOMMENDED: All tokens with composite values (see below) SHOULD include $valueType to enable tooling discovery and validation. Tokens without $valueType remain valid under the permissive anyOf union in token.schema.json.

2.3.2. Composite value types

A composite value type is a value-type schema whose root type is object or array. Composite values bundle multiple sub-values into a single token.

NORMATIVE: Composite value types MUST be defined as JSON Schemas under schemas/value-types/ following the same conventions as primitive value types.

NORMATIVE: A composite token participates in cascade resolution as an atomic unit. Sub-values within a composite MUST NOT independently match, override, or participate in specificity calculation.

2.3.3. Inline alias references

Within a composite value, a string sub-value MAY be an inline alias: a reference to another token that is resolved to produce the final sub-value.

{
  "name": { "property": "component-m-regular" },
  "$valueType": "value-types/typography.schema.json",
  "value": {
    "fontFamily": "{sans-serif-font-family}",
    "fontSize": "{font-size-100}",
    "fontWeight": "{regular-font-weight}",
    "letterSpacing": "{letter-spacing}",
    "lineHeight": "{line-height-font-size-100}"
  }
}

NORMATIVE: In legacy format, inline aliases use the syntax {token-name} (curly-brace-wrapped token property name). In cascade format, the inline alias syntax is {token-name} for backward compatibility; UUID-based inline aliases are reserved for a future spec version.

NORMATIVE: Inline aliases within composite values are subject to alias resolution rules. Validators MUST resolve inline aliases and report errors for missing targets (SPEC-014), type mismatches (SPEC-015), and circular references (SPEC-003, extended).

2.4. Component bindings

The optional componentBindings array on a token is the reverse index of tokenBindings on a component declaration (Phase 6.7). It declares which components reference this token in their tokenBindings list.

"componentBindings": [
  { "component": "button",    "context": "Minimum height" },
  { "component": "checkbox",  "context": "Height" }
]

componentBindings is informative and optional. It is fully derivable from the tokenBindings arrays on component declarations and does not need to be hand-maintained. Tooling that generates component files may populate componentBindings as a convenience for consumers that query token files directly.

2.5. Relationship to legacy Spectrum tokens

The current @adobe/spectrum-tokens JSON uses sets (color-set, scale-set, …). This specification describes the target per-token model. Mapping from legacy to this format is out of scope for this document; see #743.

2.6. Relationship to RFC #646 token shape

RFC #646 proposed an analytical token shape during the design process. This spec defines the canonical serialization format. The two are related but not identical:

NORMATIVE: The flat name object defined in this spec is the authoritative serialization format. RFC #646’s name.structure / name.original shape is not a conformance target; it remains a useful reference for the analytical model that informed this design.

RFC #646 remains open as a historical reference. It is not superseded; the spec evolved the format during Phase 2 based on implementation experience.

2.7. References

• #646 — Token Schema Structure and Validation System

• #623 — Token Lifecycle Metadata

• #756 — Phase 2: Cascade token file schema

• #759 — Phase 2: Token shape reconciliation

3. Taxonomy

Spec version: 1.0.0-draft (see Overview)

This document defines the token taxonomy: a hierarchical system of concept categories that classify design tokens, the token term vocabulary of allowed words within each category, and the formatting style rules that control serialization of structured token names into platform-consumable strings.

3.1. Motivation

"Naming convention" is too broad a term when discussing malleability across platform teams. A token name like accent-background-color-hover embeds multiple independent decisions:

1. Which concepts are represented and in what hierarchy (taxonomy).

2. Which words describe each concept (vocabulary).

3. How the words are rendered — casing, delimiters, abbreviations, concept order (formatting).

Each layer has a different malleability profile: the taxonomy is shared across all platforms; the vocabulary is shared with platform-aware compromises; the formatting is platform-malleable.

3.2. Three layers of naming

3.2.1. Layer 1: Token taxonomy

A token taxonomy is a hierarchical set of concept categories for classifying design ideas and use cases. It creates a clear, consistent, and predictable shared language across disciplines and teams.

The taxonomy is NORMATIVE and shared — all platforms use the same concept categories in the same hierarchy. Changing the taxonomy changes the meaning of token names across the entire ecosystem.

Taxonomies are scoped to specific token types for clarity. The semantic/layout taxonomy defined in this document is one such scope; additional taxonomies (e.g. for color tokens) will be defined in future spec versions.

3.2.2. Layer 2: Token term vocabulary

The token term vocabulary is the set of specific words used to describe each conceptual option within the taxonomy. The vocabulary creates a shared language across disciplines and teams.

The vocabulary is NORMATIVE at the foundation level — the foundation defines canonical terms. Platforms MAY declare vocabulary mappings (e.g. hover → highlighted for iOS) in their manifest for platform-specific consumption.

3.2.3. Layer 3: Formatting style

Formatting style defines rules for altering the appearance of a token’s name for platform-specific consumption and usability needs. This includes concept ordering, casing, delimiters, and abbreviations.

Formatting is platform-malleable — each platform manifest MAY declare its own formatting rules. The foundation defines a default formatting style for legacy compatibility.

NORMATIVE: The name object defined in Token format is unordered structured data. Concept ordering is purely a serialization concern and MUST NOT affect cascade resolution, specificity, or validation.

3.3. Principles

The taxonomy is designed with three guiding principles:

1. Object-oriented — Designers and developers think in terms of how they would construct components, rather than abstract semantic ideas.

2. Agnostic (with compromises) — Platform-agnostic terms are used except when platforms have specific terms for the same concept. In those cases, the most common or clear term is used.

3. Verified — Multiple existing components must be rebuildable using the taxonomy system, and consumers must find them reasonably understandable or learnable.

3.4. Token-type taxonomies

Concept categories for name-object fields are declared in the design system’s field catalog — a set of field declarations in the fields/ directory, each conforming to field.schema.json. Each declaration specifies the field name, vocabulary registry, validation severity, default serialization position, and an optional scope that restricts the field to a specific token type.

NORMATIVE: The field catalog is the authoritative source for what fields exist on the name object. Tools, validators, and serializers SHOULD read the catalog rather than hardcoding field knowledge.

NORMATIVE: A field with a non-null scope declaration MUST only appear on tokens of that type. Using a scoped field on a mismatched token type triggers rule SPEC-042 (field-scope-violation, warning).

3.4.1. Semantic / layout token taxonomy

The following concept categories are defined in Spectrum’s foundation field catalog for semantic and layout tokens (scope: null — universal), ordered by default serialization position. This ordering is the default serialization order for legacy format output; it is not a conformance requirement for stored name objects.

NORMATIVE: Each category listed below corresponds to a field on the token name object. Tokens MAY use any subset of these fields. Exception: property is REQUIRED on every name object — see token-format.md.

Additional categories for variant and state are inherited from the existing name object:

3.4.2. Color token taxonomy

Color tokens describe palette entries and semantic color assignments. Their name objects use scope: "color" fields alongside the universal property and state fields.

NORMATIVE: Color tokens SHOULD include colorFamily, scaleIndex, or both to allow tooling to group and sort palette entries. Tokens missing both are flagged by rule SPEC-043 (domain-required-fields, warning).

Default serialization order for color tokens:

{variant}-{colorFamily}-{scaleIndex}

Example: colorFamily=blue + scaleIndex=100 → blue-100.

3.4.3. Typography token taxonomy

Typography tokens describe typeface attributes: family, weight, style, and numeric scale. Their name objects use scope: "typography" fields alongside the universal property field.

NORMATIVE: Typography tokens SHOULD include at least one of family, weight, or style. Tokens missing all three are flagged by rule SPEC-043 (domain-required-fields, warning).

Default serialization order for typography tokens:

{family}-{weight}-{style}-{scaleIndex}

Example: family=sans-serif + weight=bold → sans-serif-bold. family=sans-serif + style=italic + scaleIndex=100 → sans-serif-italic-100.

3.4.4. Motion token taxonomy

Motion tokens describe timing, easing, and animation role for UI animation. Their name objects use scope: "motion" fields alongside the universal property field.

NOTE: No motion tokens exist in the foundation dataset at the time of this writing. This taxonomy is normative but the registry values for motionRole and easing are provisional — they will be refined when motion tokens are added to the foundation. Validators emit SPEC-043 at warning severity so provisional tokens are not blocked.

NORMATIVE: Motion tokens SHOULD include motionRole or easing. Tokens missing both are flagged by rule SPEC-043 (domain-required-fields, warning).

Default serialization order for motion tokens:

{motionRole}-{easing}-{scaleIndex}

Example: motionRole=enter + easing=ease-out → enter-ease-out. motionRole=transition + scaleIndex=100 → transition-100.

3.4.5. Alias / semantic token name objects

Alias tokens ($schema: …/alias.json) MAY carry name objects using the same field vocabulary as their target domain. A color alias carrying colorFamily is valid when its alias chain resolves to a color-domain schema (color.json, color-set.json).

NORMATIVE: SPEC-042 (field-scope-violation) evaluates alias tokens by following the alias_target chain to the terminal non-alias schema, then checking that schema against the field’s domain. This is the alias-target-domain rule: the alias inherits its domain from what it ultimately resolves to.

Examples:

// icon-color-blue-primary-default  ($schema=alias.json, $ref → icon-color-blue-100 which is color-set.json)
// Valid: colorFamily allowed because target resolves to color domain.
{ "property": "icon-color", "colorFamily": "blue", "variant": "primary" }

// icon-color-primary-default  ($schema=alias.json, $ref → icon-color-blue-primary-default)
// Valid: no domain-scoped fields used — variant and state are universal.
{ "property": "icon-color", "variant": "primary" }

What stays deferred: alias tokens referencing the same target but carrying modifiers that have no current field (e.g. inverse, emphasized, subtle, subdued) remain unclassified until a color-modifier RFC defines those fields.

3.4.6. Structure vs. component — when does the line move?

The structure and component fields both answer "What?" but apply at different scopes. A useful rule of thumb:

• Use component when the token belongs to a specific component’s surface (e.g. button-background-color — the background color of the Button component).

• Use structure when the token belongs to a reusable visual pattern that recurs across components (e.g. container-padding — padding for any container-shaped surface, regardless of which component owns it).

Worked example — card:

• As a structure: when "card" describes a layout primitive used inside many components (e.g. card-padding-medium on a list item, a popover body, or a modal header), the token is structure-scoped.

• As a component: when "card" describes the dedicated Card component’s own surfaces (e.g. card-background-color on the Card root), the token is component-scoped.

The same word can validly appear in both fields across the dataset; they are independent. Authors choose based on whether the token’s meaning generalizes across many components (structure) or is specific to one component’s identity (component).

Source: Nate Baldwin, "Naming conventions & shared taxonomy" — Design Data & Platforms onsite, April 1, 2026.

3.5. Component anatomy vs. token objects

Two concepts that are often conflated but serve different purposes:

3.5.1. Component anatomy

Component anatomy refers to the visible, named parts of a component as defined by designers. These are the parts called out in component specification diagrams (e.g. icon, label, track, handle, hold icon).

Component anatomy is declared per component in component schemas and validated against the anatomy registry. A token referencing a component’s anatomy part (e.g. slider + handle) can be validated as a legitimate combination.

Anatomy parts fall into three tiers:

3.5.2. Token objects (styling surfaces)

Token objects (or styling surfaces) describe where a visual property is applied on a UI element. These are NOT anatomy — they are abstract styling targets that exist on any element regardless of its component type.

Token objects are stored in a separate registry from anatomy parts. Both may appear in the same token name — e.g. a token for the background color of a slider’s handle would reference anatomy handle and object background.

3.6. Name object field categories

Name object fields fall into two categories with different validation behavior:

3.6.1. Semantic fields

Semantic fields describe identity, structure, and intent. They are used for querying and organization but do not participate in cascade resolution or specificity calculation.

NORMATIVE: Semantic field values are validated against their declared vocabulary registry with the severity specified in the field declaration (typically advisory — warning, not error). Values not in the registry are permitted but flagged.

Semantic fields are those declared with kind: "semantic" in the field catalog. In Spectrum’s foundation catalog, these are: structure, substructure, component, anatomy, object, property, variant, state, orientation, position, size, density, shape.

3.6.2. Mode-set fields

Mode-set fields represent axes of variation that drive the cascade resolution algorithm and specificity calculation.

NORMATIVE: Mode-set field values are validated against declared mode set modes with strict severity (error). An invalid mode value would silently fail to match any context during cascade resolution.

Mode-set fields are those declared with kind: "mode-set" in the field catalog, plus any additional mode set keys from the dataset’s mode set declarations. In Spectrum’s foundation catalog, the standard mode-set fields are: colorScheme, scale, contrast.

See Mode Sets for mode set declarations, modes, and defaults.

3.7. Default serialization (legacy format)

The default serialization produces a kebab-case string from the name object by ordering fields according to their serialization.position values (ascending) as declared in the field catalog. Omitted fields are skipped.

For Spectrum’s foundation catalog, this produces the following concept order:

{variant}-{component}-{structure}-{substructure}-{anatomy}-{object}-{property}-{orientation}-{position}-{size}-{density}-{shape}-{state}

All fields are independent — variant and component MAY both appear in the same token name (e.g. a token with component: "button" and variant: "accent" serializes as accent-button-...).

This ordering is preserved for backward compatibility with the current @adobe/spectrum-tokens package. It is a serialization convention, not a structural requirement.

NORMATIVE: A conforming formatter MUST produce deterministic output for a given name object and formatting configuration. Two name objects that differ only in field ordering MUST produce identical serialized strings.

3.8. Platform formatting configuration

A platform manifest MAY declare formatting rules in its extensions.formatting section to control concept ordering, casing, delimiters, and abbreviations. The normative contract for these fields is defined in Manifest — extensions.formatting.

When no platform formatting is declared, the default serialization above is used.

3.9. Scalability

The taxonomy and terms are built to scale as new concepts and terms are identified:

• New concept categories MAY be added by creating a new field declaration file in the field catalog — no spec version change is required for the mechanism itself.

• New terms MAY be added to the vocabulary registry without spec version changes.

• New token type taxonomies MAY be added by creating scoped field declarations (non-null scope) and a corresponding registry section in taxonomy.md. Color, typography, and motion taxonomies are defined above.

• Platform manifests MAY extend the vocabulary with platform-specific terms and formatting.

3.10. Where name objects live

Token taxonomy data is decoupled from the published @adobe/spectrum-tokens package to avoid bumping the tokens version on every taxonomy change.

The sidecar package (@adobe/token-names) is private (not published to npm). Its delivery format for downstream consumers is TBD.

3.10.1. SDK validator integration

Pass --names-dir packages/token-names/names/ to the design-data validate CLI to merge sidecar names into the token graph at ingest. All relational rules (SPEC-042, SPEC-043, SPEC-018…022, cascade, diff, query) continue to read record.raw["name"] as if the field were inline:

cargo run --bin design-data -- validate packages/tokens/src/ \
  --names-dir packages/token-names/names/

Validation without --names-dir is a valid fail-open configuration (name-scope rules are silent); CI always supplies the flag.

3.10.2. Regenerating name data

node tools/token-corpus-migrate/src/cli.js \
  --root packages/tokens/src \
  --names-out packages/token-names/names \
  --write

3.11. References

• #806 — Token Taxonomy, Vocabulary, and Formatting

• #661 — Spectrum Design System Glossary

• #646 — Token Schema Structure and Validation System

• Manifest — extensions.formatting — normative contract for platform formatting rules

• Nate Baldwin, "Naming conventions & shared taxonomy" — Design Data & Platforms onsite, April 1, 2026

4. Agent-readable surface

Spec version: 1.0.0-draft (see Overview)
Status: Implemented — RFC-C / Phase 8 (epic #830). Core read/validate/write surface shipped. write_component and explain deferred (no CLI subcommand or MCP tool yet).

This document defines the agent-readable surface: the contract an external AI agent uses to consume design data conformant with this specification. It standardizes a small set of operations exposed through three transports — a CLI, a Model Context Protocol (MCP) server, and a Claude Code Agent Skill — all backed by the same resolver, validator, and query implementations that power the rest of the SDK.

4.1. Goals

The surface targets three consumer shapes:

1. Authoring an external system. A non-Spectrum design system being constructed inside an AI tool (e.g. a finance-dashboard prototype tool) wants to produce spec-conformant tokens, mode sets, and components without re-deriving the format from prose.

2. Extending Spectrum. A product or platform team adds tokens, components, or overrides on top of the published Spectrum foundation and needs to validate that the additions cascade and resolve correctly.

3. Adhering to Spectrum. A prototyping tool generates UI that should match Spectrum even where no bound component exists (e.g. CSS for a custom card). The agent needs to look up tokens by intent, validate proposed property values against the foundation, and report drift.

NORMATIVE: A conforming agent surface implementation MUST support all three consumer shapes, parameterized by the manifest provided at session start (see Session primer).

4.2. Non-goals

• Generating finished platform code (Swift, CSS, etc.). Output formatting is the consumer’s responsibility; the surface returns structured tokens.

• Hosting design data. The surface operates on local datasets reachable from the consumer’s filesystem, plus optionally a remote published manifest.

• Replacing the existing Spectrum-bound tools (@adobe/spectrum-design-data-mcp, @adobe/s2-docs-mcp). Those expose Spectrum-specific shapes; this surface is generic to any spec-conformant dataset.

4.3. Tool catalog

NORMATIVE: A conforming implementation MUST expose the following operations. Transport-specific naming (CLI subcommand vs MCP tool name vs skill action) MAY differ; the semantics MUST NOT.

NORMATIVE: validate_usage, resolve_token, query_tokens, diff_datasets, and describe_component MUST be implemented in a conforming agent surface. suggest_token, get_guidance, write_token, and write_component are RECOMMENDED.

RECOMMENDED: When write_token or write_component is invoked, the implementation SHOULD capture a rationale argument from the agent session context and record it in both the token’s inline rationale field and the product context document’s overrides[].rationale or extensions.tokens[].rationale. See Product context — Agent capture behavior.

4.4. Session primer

An agent loop benefits from a small, structural overview at session start so that subsequent calls are well-scoped. The session primer is a single operation that returns a serialized summary of the active dataset.

NORMATIVE: A conforming implementation MUST expose a primer operation returning a JSON object with at least:

RECOMMENDED: The primer payload SHOULD fit within 2,000 tokens of LLM context for typical Spectrum-scale datasets. Implementations that produce larger payloads SHOULD provide a --summary mode.

RATIONALE: The primer replaces the "DESIGN.md emit" approach explored in earlier RFC-C drafts. A live, queryable primer keeps the agent’s session context current without requiring the agent to maintain a frozen prose summary that can drift from the dataset.

4.5. Transports

NORMATIVE: A conforming implementation MUST expose the Tool catalog through at least one of the following transports.

4.5.1. CLI

The reference CLI is design-data (see sdk/cli/). RFC-C extends the existing subcommands (validate, resolve, diff, query) with:

• design-data primer [PATH] — emit the Session primer payload.

• design-data suggest "<intent>" [--property <hint>] — invoke suggest_token.

• design-data explain <token-uuid|component-id> — invoke get_guidance. (Deferred — not yet shipped; pending get_guidance wire-up.)

NORMATIVE: All RFC-C CLI output MUST default to JSON when stdout is not a TTY, and MUST emit human-friendly output when stdout is a TTY. This makes the CLI directly composable from agent shells without per-call format flags.

4.5.2. MCP server

A reference MCP server is RECOMMENDED to ship as @adobe/design-data-agent-mcp (separate from the existing Spectrum-bound @adobe/spectrum-design-data-mcp to avoid coupling to a specific dataset).

NORMATIVE: The MCP server MUST register one tool per Tool catalog operation. Tool names MUST match the operation name in the table verbatim. Each tool’s input schema MUST mirror the CLI flag set; agents that learn one transport SHOULD work with the other.

4.5.3. Agent skill

A reference Claude Code Agent Skill is RECOMMENDED at tools/design-data-agent-mcp/skills/design-data/SKILL.md. The skill SHOULD trigger on intent words covering all three Goals — for example "design system", "design tokens", "drift", "spec-conformant", and explicit Spectrum mentions when the active manifest binds Spectrum.

RECOMMENDED: The skill SHOULD shell out to the CLI rather than embedding tool calls, so its description (the only persistent context cost) stays small and the heavy lifting happens out-of-band.

4.6. describe_component return shape

The describe_component tool returns the component declaration object as stored in the dataset, extended with tokenBindings when Phase 6.7 data is present. A conforming implementation MUST include tokenBindings in the response when the component declaration contains that field.

{
  "name": "button",
  "displayName": "Button",
  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
  "options": {
    "variant": { "type": "string", "values": [{"value": "accent"}, {"value": "negative"}, {"value": "primary"}, {"value": "secondary"}], "default": "accent" }
  },
  "anatomy": [
    { "name": "icon",  "description": "Leading icon." },
    { "name": "label", "description": "Button text.", "required": true }
  ],
  "states": [
    { "name": "hover",    "trigger": "interaction", "precedence": 50 },
    { "name": "focus",    "trigger": "interaction", "precedence": 60, "layered": true },
    { "name": "disabled", "trigger": "prop",        "precedence": 100 }
  ],
  "tokenBindings": [
    { "token": "component-height-100", "context": "Minimum height" },
    { "token": "corner-radius-full",   "context": "Rounding" }
  ]
}

tokenBindings enables agents to retrieve a complete picture of a component’s token usage — including shared structure and foundation tokens that do not carry the component name in their name-object — without issuing a second query_tokens call.

4.7. Conformance

NORMATIVE: An agent surface implementation that claims conformance MUST:

1. Implement all NORMATIVE operations in the Tool catalog.

2. Implement the Session primer operation.

3. Expose the catalog through at least one transport in Transports.

4. Emit validate_usage diagnostics that match the structure produced by validate::validate_all_with_options (see sdk/core/src/report.rs): each diagnostic MUST include rule_id, severity, message, instance_path, schema_path, file, and token where applicable.

5. Honor manifest-based filtering: when a manifest is present in the session, query_tokens and resolve_token MUST respect include/exclude and MUST apply manifest overrides before returning results.

4.8. Worked example

The following sketch shows an agent loop that adheres-to-Spectrum while authoring a non-bound component.

1. Agent calls primer ./spectrum-data and learns that colorScheme and scale are the active mode sets and that button, picker, and card are exposed components.

2. User asks for a "subtle hover background for a card on dark mode".

3. Agent calls suggest_token "subtle hover background for card" --property background-color.

4. Surface returns a ranked list including background-color-hover from Spectrum foundation and background-color-card-hover from a card component group.

5. Agent calls resolve_token background-color-card-hover --color-scheme dark.

6. Surface returns the resolved literal value for the dark-mode card hover background.

7. Agent emits CSS using that value and calls validate_usage against the proposed token document fragment to confirm no SPEC-NNN diagnostics fire.

The same loop, with a different manifest passed at primer time, authors a non-Spectrum system: the surface returns whatever tokens that dataset declares, and validate_usage enforces the same spec rules independent of which design system is in play.

4.9. References

• #714 — Design Data Specification (umbrella)

• #625 — Token Authoring Workflow

• #832 — Component Contract in Design Data Spec — supplies describe_component once implemented

• Document blocks (forthcoming, RFC-D / Phase 9) — supplies get_guidance payloads

• sdk/cli/src/main.rs — CLI surface to extend

• sdk/core/src/report.rs — diagnostic shape

5. Validation rule catalog (excerpt)

This excerpt demonstrates stable-ID cross-references using five representative rules drawn from rules/rules.yaml. The full catalog ships in the canonical @adobe/design-data-spec package.

5.1. Rules

SPEC-001 — alias-target-exists

• Severity: error

• Category: reference-integrity

• Assert: Every alias $ref MUST resolve to an existing token in the dataset.

• Message: Alias target not found for $ref: {path}

• Introduced in: 1.0.0-draft

SPEC-005 — cascade-coverage

• Severity: error

• Category: completeness

• Assert: Mode set declarations MUST satisfy coverage rules (e.g. default ∈ modes; peer mode requirements from coverage metadata).

• Message: Mode-set coverage violation for {mode_set}

• Introduced in: 1.0.0-draft

SPEC-006 — specificity-correctness

• Severity: warning

• Category: type-safety

• Assert: When two tokens from the same layer match a context with equal specificity, the tie MUST be broken by document order (earlier in file wins; lexicographically earlier file path wins across files). Ties MUST be reported as warnings.

• Message: Ambiguous cascade resolution (specificity tie) between {token_a} and {token_b} for context {context}; resolved by document order

• Introduced in: 1.0.0-draft

SPEC-009 — name-field-enum-sync

• Severity: warning

• Category: naming-consistency

• Assert: Recognized name object fields (component, state, variant, etc.) SHOULD use values drawn from the corresponding design-system-registry enums when those enums are available.

• Message: Token name field '{field}' value '{value}' is not in the design-system-registry enum for '{field}'

• Introduced in: 1.0.0-draft

SPEC-017 — string-name-tech-debt

• Severity: warning

• Category: tech-debt

• Assert: Token names SHOULD be structured name objects. A plain string name is permitted as a temporary escape hatch but MUST be treated as tech debt and tracked for remediation.

• Message: Token "{name}" uses a string name instead of a name object — treat as tech debt and plan remediation

• Spec ref: String-name escape hatch

• Introduced in: 1.0.0-draft