@adobe/design-data-spec 0.0.1 → 0.1.1

package/conformance/resolution/base-fallback/input/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "background-color-default" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/resolution/base-fallback/query.json

@@ -0,0 +1,4 @@
+{
+  "property": "background-color-default",
+  "context": { "colorScheme": "dark" }
+}

package/conformance/resolution/specificity-wins/dimensions/color-scheme.json

@@ -0,0 +1,5 @@
+{
+  "name": "colorScheme",
+  "modes": ["light", "dark", "wireframe"],
+  "default": "light"
+}

package/conformance/resolution/specificity-wins/expected.json

@@ -0,0 +1,5 @@
+{
+  "description": "When both a base (dimensionless) and a non-default dimension variant exist, the higher-specificity variant MUST win.",
+  "resolved": true,
+  "expected_uuid": "bbbbbbbb-0002-4000-8000-000000000002"
+}

package/conformance/resolution/specificity-wins/input/tokens.tokens.json

@@ -0,0 +1,12 @@
+[
+  {
+    "name": { "property": "background-color-default" },
+    "value": "#ffffff",
+    "uuid": "bbbbbbbb-0001-4000-8000-000000000001"
+  },
+  {
+    "name": { "property": "background-color-default", "colorScheme": "dark" },
+    "value": "#000000",
+    "uuid": "bbbbbbbb-0002-4000-8000-000000000002"
+  }
+]

package/conformance/resolution/specificity-wins/query.json

@@ -0,0 +1,4 @@
+{
+  "property": "background-color-default",
+  "context": { "colorScheme": "dark" }
+}

package/conformance/valid/lifecycle-with-last-modified.json

@@ -0,0 +1,12 @@
+{
+  "name": {
+    "component": "button",
+    "object": "background",
+    "property": "color",
+    "variant": "primary"
+  },
+  "value": "#0265dc",
+  "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+  "introduced": "1.0.0",
+  "lastModified": "2.1.0"
+}

package/fields/anatomy.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "anatomy",
+  "description": "Visible named part of a component (e.g. handle, icon, label, track). Refers to a specific sub-element, not a styling surface.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/anatomy-terms.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 4
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/color-scheme.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "colorScheme",
+  "description": "Theme / appearance dimension. Controls which color scheme a token applies to (e.g. light, dark, wireframe). Drives cascade resolution.",
+  "kind": "dimension",
+  "registry": null,
+  "validation": "strict",
+  "serialization": {
+    "position": 13
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/component.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "component",
+  "description": "Component scope — the UI component this token belongs to (e.g. button, checkbox, slider).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/components.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 1
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/contrast.json

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

package/fields/density.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "density",
+  "description": "Space density within or around component parts (e.g. spacious, compact). Distinct from the dimension scale field.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/densities.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 10
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/object.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "object",
+  "description": "Styling surface being targeted (e.g. background, border, edge, visual). Refers to what is being styled, not the property value.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/token-objects.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 5
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/orientation.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "orientation",
+  "description": "Direction or layout axis (e.g. vertical, horizontal).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/orientations.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 7
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/position.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "position",
+  "description": "Location relative to another object or edge (e.g. top, bottom, start, end, affixed).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/positions.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 8
+  },
+  "scope": null,
+  "required": false,
+  "valueType": "string"
+}

package/fields/property.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "property",
+  "description": "The stylistic attribute being defined (e.g. color, width, padding, gap). The only required field on every name object.",
+  "kind": "semantic",
+  "registry": null,
+  "validation": "advisory",
+  "serialization": {
+    "position": 6
+  },
+  "scope": null,
+  "required": true,
+  "valueType": "string"
+}

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.1",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {
@@ -18,11 +18,11 @@
     "node": ">=20.12.0",
     "pnpm": ">=10.17.1"
   },
-  "packageManager": "pnpm@10.17.1",
   "exports": {
     "./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,9 +30,10 @@
   "files": [
     "spec",
     "schemas",
+    "fields",
     "rules",
     "conformance",
     "README.md"
   ],
   "scripts": {}
-}
+}

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,66 @@ 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"
+
+  - id: SPEC-014
+    name: last-modified-not-before-introduced
+    severity: error
+    category: completeness
+    assert: If lastModified is present, its semver MUST NOT precede introduced.
+    message: "Token {token} has lastModified {lastModified} earlier than introduced {introduced}"
+    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
     }
   },