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.

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

Required shape

A token MUST contain:

1. name — a JSON object (the name object) as defined below.
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.

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 dimension), 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 dimension fields (axes of variation for cascade resolution). The tables below list Spectrum's foundation-standard fields as declared in the catalog.

Semantic fields

Dimension fields

NORMATIVE: Each field is validated according to the validation severity declared in its field declaration. Semantic fields typically use advisory severity (warning); dimension 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.

Alias ($ref)

When $ref is present, the token is an alias. The value 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).

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.

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.

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"
}

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

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

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.

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": "..." }
]

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.

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.

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.

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