@adobe/design-data-spec 0.0.1 → 0.1.0

package/fields/scale.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "scale",
+  "description": "Platform density scale dimension (e.g. desktop, mobile). Drives cascade resolution.",
+  "kind": "dimension",
+  "registry": null,
+  "validation": "strict",
+  "serialization": {
+    "position": 14
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/shape.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "shape",
+  "description": "Overall component shape qualifier (e.g. uniform, rounded).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/shapes.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 11
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/size.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "size",
+  "description": "Relative t-shirt sizing of a component or token (e.g. small, medium, large, extra-large). Distinct from dimension scale.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/sizes.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 9
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/state.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "state",
+  "description": "Interactive or semantic state (e.g. hover, focus, disabled, selected). Compound states use hyphenation (e.g. selected-hover).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/states.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 12
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/structure.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "structure",
+  "description": "Reusable visual pattern that occurs across many components (e.g. drop-shadow, overlay). Distinct from component.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/structures.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 2
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/substructure.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "substructure",
+  "description": "Child element within a parent structure (e.g. item within list-item, cell within table).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/substructures.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 3
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/variant.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "variant",
+  "description": "Primary color or semantic variant (e.g. accent, negative, informative, neutral). Not for visual style treatment — see style field for that.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/variants.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 0
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {
@@ -23,6 +23,7 @@
     "./package.json": "./package.json",
     "./schemas/token.schema.json": "./schemas/token.schema.json",
     "./schemas/dimension.schema.json": "./schemas/dimension.schema.json",
+    "./schemas/field.schema.json": "./schemas/field.schema.json",
     "./schemas/manifest.schema.json": "./schemas/manifest.schema.json",
     "./schemas/value-types/color.schema.json": "./schemas/value-types/color.schema.json",
     "./rules/rules.yaml": "./rules/rules.yaml"
@@ -30,6 +31,7 @@
   "files": [
     "spec",
     "schemas",
+    "fields",
     "rules",
     "conformance",
     "README.md"

package/rules/rules.yaml

@@ -51,8 +51,8 @@ rules:
     name: specificity-correctness
     severity: warning
     category: type-safety
-    assert: When two tokens from the same layer match a context, the more specific name object MUST win; ties MUST be reported.
-    message: "Ambiguous cascade resolution (specificity tie) for context {context}"
+    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"
     spec_ref: spec/cascade.md#semantic-specificity
     introduced_in: "1.0.0-draft"
 
@@ -64,3 +64,57 @@ rules:
     message: "Token '{token}' does not roundtrip through name-object generation rules"
     spec_ref: spec/token-format.md#name-object
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-008
+    name: cascade-completeness
+    severity: warning
+    category: completeness
+    assert: For every cascade token that has a non-default mode variant, a base/default variant (name object with no dimension fields for that dimension, or explicitly the default mode value) MUST also exist in the dataset. Ensures all consumers can resolve without a fallback gap.
+    message: "Token property '{property}' has mode variant '{mode}' but no base/default variant"
+    spec_ref: spec/cascade.md#coverage
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-009
+    name: 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}'"
+    spec_ref: spec/token-format.md#name-object
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-010
+    name: replaced-by-target-exists
+    severity: error
+    category: reference-integrity
+    assert: Every UUID in replaced_by MUST resolve to an existing token in the dataset.
+    message: "replaced_by target UUID not found: {uuid}"
+    spec_ref: spec/token-format.md#lifecycle-and-metadata
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-011
+    name: replaced-by-array-requires-comment
+    severity: error
+    category: completeness
+    assert: When replaced_by is an array, deprecated_comment MUST be present to explain which replacement applies in which context.
+    message: "replaced_by is an array but deprecated_comment is missing on token {token}"
+    spec_ref: spec/token-format.md#lifecycle-and-metadata
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-012
+    name: replaced-by-requires-deprecated
+    severity: error
+    category: completeness
+    assert: If replaced_by is present, deprecated MUST also be present.
+    message: "Token {token} has replaced_by but is not marked deprecated"
+    spec_ref: spec/token-format.md#lifecycle-and-metadata
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-013
+    name: planned-removal-requires-deprecated
+    severity: error
+    category: completeness
+    assert: If plannedRemoval is present, deprecated MUST also be present.
+    message: "Token {token} has plannedRemoval but is not marked deprecated"
+    spec_ref: spec/token-format.md#lifecycle-and-metadata
+    introduced_in: "1.0.0-draft"

package/schemas/cascade-file.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/cascade-file.schema.json",
+  "title": "Cascade token file",
+  "description": "Layer 1 — document envelope for cascade-format tokens. A cascade file is an ordered array of token objects; document order determines tie-breaking during cascade resolution.",
+  "type": "array",
+  "items": {
+    "$ref": "token.schema.json"
+  }
+}

package/schemas/field.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "title": "Name-object field declaration",
+  "description": "Declares a single field on the token name object — its kind, vocabulary source, validation severity, and serialization position. Design systems provide a catalog of these declarations to make the name object schema configurable rather than hardcoded.",
+  "type": "object",
+  "required": ["name", "kind", "validation", "serialization"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "specVersion": {
+      "const": "1.0.0-draft"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Field key on the name object (e.g. 'property', 'component', 'scaleIndex')."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the field's purpose."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["semantic", "dimension"],
+      "description": "Whether this field participates in cascade resolution. 'dimension' fields drive cascade specificity; 'semantic' fields describe identity only."
+    },
+    "registry": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path to the registry file containing valid values for this field (relative to the design system root)."
+        },
+        {
+          "type": "null",
+          "description": "No registry — field accepts free-form values."
+        }
+      ]
+    },
+    "validation": {
+      "type": "string",
+      "enum": ["strict", "advisory", "none"],
+      "description": "Validation severity when a value is not found in the registry. 'strict' = error, 'advisory' = warning, 'none' = no check."
+    },
+    "serialization": {
+      "type": "object",
+      "required": ["position"],
+      "properties": {
+        "position": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Default position in the serialized name string (0-based). Used when the platform manifest does not specify a custom conceptOrder."
+        }
+      },
+      "additionalProperties": false
+    },
+    "scope": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "description": "Restrict this field to a specific token type scope (e.g. 'typography', 'color'). Null = universal."
+        },
+        {
+          "type": "null",
+          "description": "Field applies to all token types."
+        }
+      ]
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether this field must be present on every name object. Default: false.",
+      "default": false
+    },
+    "valueType": {
+      "type": "string",
+      "enum": ["string", "integer"],
+      "description": "Type of the field value. Default: 'string'.",
+      "default": "string"
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/manifest.schema.json

@@ -64,7 +64,61 @@
     },
     "extensions": {
       "type": "object",
-      "description": "Platform-local tokens or dimensions; structure validated by separate documents.",
+      "description": "Platform-local tokens, dimensions, and formatting rules.",
+      "properties": {
+        "formatting": {
+          "type": "object",
+          "description": "Rules for serializing structured name objects into platform-specific token name strings.",
+          "properties": {
+            "conceptOrder": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "variant",
+                  "component",
+                  "structure",
+                  "substructure",
+                  "anatomy",
+                  "object",
+                  "property",
+                  "orientation",
+                  "position",
+                  "size",
+                  "density",
+                  "shape",
+                  "state"
+                ]
+              },
+              "uniqueItems": true,
+              "description": "Ordered list of field names for serialization. Values must match declared field names from the design system's field catalog (field.schema.json declarations). Replaces the default serialization.position order from each field declaration."
+            },
+            "casing": {
+              "type": "string",
+              "enum": [
+                "kebab-case",
+                "camelCase",
+                "PascalCase",
+                "SCREAMING_SNAKE_CASE"
+              ],
+              "description": "Casing style for serialized token names. Default: kebab-case."
+            },
+            "delimiter": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Character(s) separating concepts in the serialized string. Default: -."
+            },
+            "abbreviations": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "description": "Map of full term to abbreviated form, applied after ordering and before casing."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
       "additionalProperties": true
     }
   },

package/schemas/token.schema.json

@@ -15,30 +15,73 @@
   "$defs": {
     "nameObject": {
       "type": "object",
-      "description": "Structured token identity; additional dimension keys MUST be strings.",
+      "description": "Structured token identity. Semantic fields describe identity and structure; dimension fields drive cascade resolution. See spec/taxonomy.md and spec/token-format.md. Additional dimension keys MUST be strings.",
       "required": ["property"],
       "properties": {
         "property": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "Semantic: the stylistic attribute being defined (e.g. color, width, padding, gap)."
         },
         "component": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: component scope (e.g. button, checkbox)."
+        },
+        "structure": {
+          "type": "string",
+          "description": "Semantic: reusable visual pattern (e.g. base, container, list). Distinct from component."
+        },
+        "substructure": {
+          "type": "string",
+          "description": "Semantic: child within a parent structure (e.g. item in list-item)."
+        },
+        "anatomy": {
+          "type": "string",
+          "description": "Semantic: visible named part of a component (e.g. handle, icon, label)."
+        },
+        "object": {
+          "type": "string",
+          "description": "Semantic: styling surface (e.g. background, border, edge, visual)."
         },
         "variant": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: variant within a component (e.g. accent, negative, primary)."
         },
         "state": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: interactive or semantic state (e.g. hover, focus, disabled)."
+        },
+        "orientation": {
+          "type": "string",
+          "description": "Semantic: direction or order (e.g. vertical, horizontal)."
+        },
+        "position": {
+          "type": "string",
+          "description": "Semantic: location relative to another object (e.g. affixed, top, bottom)."
+        },
+        "size": {
+          "type": "string",
+          "description": "Semantic: relative t-shirt sizing (e.g. small, medium, large). Distinct from dimension scale."
+        },
+        "density": {
+          "type": "string",
+          "description": "Semantic: space within or around component parts (e.g. spacious, compact)."
+        },
+        "shape": {
+          "type": "string",
+          "description": "Semantic: overall component shape (e.g. uniform)."
         },
         "colorScheme": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: color scheme mode (e.g. light, dark, wireframe)."
         },
         "scale": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: platform density scale (e.g. desktop, mobile)."
         },
         "contrast": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: contrast level (e.g. regular, high)."
         }
       },
       "additionalProperties": {
@@ -89,19 +132,33 @@
           "type": "string"
         },
         "deprecated": {
-          "type": "boolean"
+          "type": "string",
+          "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
         },
         "deprecated_comment": {
           "type": "string"
         },
-        "status": {
-          "type": "string"
+        "replaced_by": {
+          "oneOf": [
+            { "type": "string", "format": "uuid" },
+            {
+              "type": "array",
+              "items": { "type": "string", "format": "uuid" },
+              "minItems": 1
+            }
+          ],
+          "description": "UUID(s) of the replacement token(s). Array form requires deprecated_comment."
         },
-        "renamed": {
-          "type": "string"
+        "plannedRemoval": {
+          "type": "string",
+          "description": "Spec version when token will be removed."
         },
         "private": {
           "type": "boolean"
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain text describing the token's purpose (aligns with DTCG $description)."
         }
       },
       "additionalProperties": false
@@ -132,19 +189,33 @@
           "type": "string"
         },
         "deprecated": {
-          "type": "boolean"
+          "type": "string",
+          "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
         },
         "deprecated_comment": {
           "type": "string"
         },
-        "status": {
-          "type": "string"
+        "replaced_by": {
+          "oneOf": [
+            { "type": "string", "format": "uuid" },
+            {
+              "type": "array",
+              "items": { "type": "string", "format": "uuid" },
+              "minItems": 1
+            }
+          ],
+          "description": "UUID(s) of the replacement token(s). Array form requires deprecated_comment."
         },
-        "renamed": {
-          "type": "string"
+        "plannedRemoval": {
+          "type": "string",
+          "description": "Spec version when token will be removed."
         },
         "private": {
           "type": "boolean"
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain text describing the token's purpose (aligns with DTCG $description)."
         }
       },
       "additionalProperties": false

package/spec/cascade.md

@@ -26,7 +26,12 @@ Design data is organized in three layers, ordered from lowest to highest precede
 
 **NORMATIVE:** When two candidates from the **same layer** match the context, the candidate with **higher** specificity **MUST** win.
 
-**NORMATIVE:** Ties on layer and specificity **MUST** be broken by a deterministic **document order** rule defined by the manifest or dataset index (implementation-defined in this draft; validators **SHOULD** emit a warning on ambiguous ties).
+**NORMATIVE:** Ties on layer and specificity **MUST** be broken by **document order**:
+
+1. Within a single source file, the token that appears **earlier** in the array **MUST** win.
+2. Across multiple files, the file with the **lexicographically earlier path** within the dataset **MUST** win.
+
+**NORMATIVE:** Validators **MUST** emit a SPEC-006 warning when a tie is detected, as ties indicate potential authoring mistakes.
 
 ## Context
 
@@ -40,10 +45,19 @@ The following outline is **RECOMMENDED** for conforming resolvers:
 2. Filter to candidates at or below the requested layer.
 3. Select the maximum **layer** precedence.
 4. Within that layer, select the maximum **specificity**.
-5. Break remaining ties by deterministic ordering.
+5. Break remaining ties by document order (earlier in file wins; lexicographically earlier file path wins across files). Emit SPEC-006 warning.
+6. If the winning candidate is an alias (`$ref`), **resolve the alias chain** to a literal value (see [Alias resolution](#alias-resolution)).
 
 Exact matching rules for omitted dimensions are defined alongside dimension declarations in [Dimensions](dimensions.md).
 
+## Alias resolution
+
+**NORMATIVE:** Alias (`$ref`) resolution **MUST** occur **after** cascade selection. The resolution algorithm selects the winning candidate using layer, specificity, and tie-breaking rules before any alias chain is followed.
+
+**NORMATIVE:** If the winning candidate is an alias, its `$ref` chain **MUST** be resolved to a literal value using the standard alias-resolution rules (SPEC-001 through SPEC-003 in `rules/rules.yaml`). The alias target is resolved within the same dataset (i.e. the same merged layer stack), not relative to any single layer.
+
+**RATIONALE:** Aliases participate in cascade as opaque references — their target values are not examined during specificity calculation or layer comparison. This keeps resolution deterministic and allows aliases to be valid candidates at any specificity level.
+
 ## Cross-dimensional overrides
 
 **NORMATIVE:** Overrides that combine multiple dimensions in a way not expressible by a single name object alone **MUST** use **explicit combination tokens** (tokens whose name object sets multiple non-default dimensions) as defined in the dataset; magic merging of unrelated tokens is **NOT** allowed.
@@ -52,3 +66,5 @@ Exact matching rules for omitted dimensions are defined alongside dimension decl
 
 * [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
 * [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#757 — Phase 2: Cascade tie-breaking rule](https://github.com/adobe/spectrum-design-data/issues/757)
+* [#758 — Phase 2: Alias resolution ordering in cascade context](https://github.com/adobe/spectrum-design-data/issues/758)