@adobe/design-data-spec 0.1.1 → 0.3.0

package/rules/rules.yaml

@@ -120,10 +120,118 @@ rules:
     introduced_in: "1.0.0-draft"
 
   - id: SPEC-014
-    name: last-modified-not-before-introduced
+    name: composite-inline-alias-exists
     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
+    category: reference-integrity
+    assert: Inline alias references ({token-name}) within composite values MUST resolve to an existing token in the dataset.
+    message: "Inline alias target not found within composite value: {path}"
+    spec_ref: spec/token-format.md#inline-alias-references
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-015
+    name: composite-inline-alias-type-compatible
+    severity: error
+    category: type-safety
+    assert: Resolved inline alias target within a composite value MUST have a value type compatible with the sub-value's expected type.
+    message: "Inline alias {path} within composite resolves to incompatible type"
+    spec_ref: spec/token-format.md#inline-alias-references
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-016
+    name: value-type-match
+    severity: error
+    category: type-safety
+    assert: When $valueType is present on a token with a literal value, the value MUST validate against the referenced value-type schema.
+    message: "Token {token} value does not validate against declared $valueType schema {schema}"
+    spec_ref: spec/token-format.md#value-type-declaration-valuetype
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-017
+    name: 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: spec/token-format.md#string-name-escape-hatch
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-018
+    name: component-name-exists
+    severity: error
+    category: reference-integrity
+    assert: Token name-object 'component' field value MUST match the 'name' of a declared component in the dataset.
+    message: "Token '{token}' references undeclared component '{component}'"
+    spec_ref: spec/component-format.md#name
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-019
+    name: component-variant-valid
+    severity: error
+    category: reference-integrity
+    assert: Token name-object 'variant' field value MUST match a value in the declared 'variant' option enum for the referenced component, when that enum exists.
+    message: "Token '{token}' has variant '{variant}' which is not declared on component '{component}'"
+    spec_ref: spec/component-format.md#options
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-020
+    name: component-anatomy-valid
+    severity: error
+    category: reference-integrity
+    assert: Token name-object 'anatomy' field value MUST match the 'name' of a declared anatomy part on the referenced component.
+    message: "Token '{token}' references undeclared anatomy part '{anatomy}' on component '{component}'"
+    spec_ref: spec/component-format.md#anatomy-stub
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-021
+    name: component-slot-vocabulary
+    severity: warning
+    category: component-contract
+    assert: Component slot declarations with a 'name' outside the canonical slot vocabulary SHOULD include a 'description' field documenting the custom slot's purpose.
+    message: "Component '{component}' has custom slot '{slot}' with no description — add a description or use a canonical slot name"
+    spec_ref: spec/component-format.md#canonical-slot-vocabulary
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-022
+    name: component-state-valid
+    severity: error
+    category: reference-integrity
+    assert: Token name-object 'state' field value MUST match the 'name' of a declared state on the referenced component, when state declarations are present.
+    message: "Token '{token}' references undeclared state '{state}' on component '{component}'"
+    spec_ref: spec/component-format.md#spec-rules
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-023
+    name: anatomy-custom-part-documented
+    severity: warning
+    category: component-contract
+    assert: Anatomy part declarations with a 'name' outside the canonical anatomy vocabulary SHOULD include a 'description' field.
+    message: "Component '{component}' has custom anatomy part '{part}' with no description"
+    spec_ref: spec/anatomy-format.md#canonical-anatomy-vocabulary
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-024
+    name: anatomy-part-name-unique
+    severity: error
+    category: component-contract
+    assert: Anatomy part names within a single component's anatomy array MUST be unique.
+    message: "Component '{component}' declares duplicate anatomy part name '{part}'"
+    spec_ref: spec/anatomy-format.md#name
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-025
+    name: anatomy-requires-component
+    severity: error
+    category: reference-integrity
+    assert: A token name object MUST NOT include an 'anatomy' field unless a 'component' field is also present.
+    message: "Token '{token}' has 'anatomy' field without a 'component' field"
+    spec_ref: spec/anatomy-format.md#cross-reference-with-token-name-objects
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-026
+    name: state-custom-name-documented
+    severity: warning
+    category: component-contract
+    assert: State declarations with a 'name' outside the canonical state vocabulary SHOULD include a 'description' field.
+    message: "Component '{component}' has custom state '{state}' with no description"
+    spec_ref: spec/state-model.md#canonical-state-vocabulary
     introduced_in: "1.0.0-draft"

package/schemas/anatomy-part.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/anatomy-part.schema.json",
+  "title": "Anatomy part declaration",
+  "description": "Layer 1 structural schema for a single anatomy part object within a component declaration. Semantic rules (component-anatomy-valid, anatomy-custom-part-documented, anatomy-part-name-unique, anatomy-requires-component) are Layer 2.",
+  "type": "object",
+  "required": ["name"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "description": "Kebab-case anatomy part identifier. Must match the value used in token name-object 'anatomy' fields."
+    },
+    "description": {
+      "type": "string",
+      "description": "Plain-text description of the part's visual role and boundaries."
+    },
+    "required": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether this part is always rendered regardless of component configuration."
+    },
+    "contains": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "uniqueItems": true,
+      "description": "Informative list of child anatomy part names nested within this part. Does not carry enforcement semantics."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/component.schema.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "title": "Design data component declaration",
+  "description": "Layer 1 structural schema for a component declaration. Semantic cross-reference rules (component-name-exists, component-variant-valid, etc.) are Layer 2.",
+  "type": "object",
+  "required": ["$id", "name", "displayName", "meta"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version this document targets (e.g. '1.0.0-draft')."
+    },
+    "$id": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical identifier for this component declaration."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "description": "Machine identifier (kebab-case). Must match the value used in token name-object 'component' fields."
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable component name (e.g. 'Button')."
+    },
+    "description": {
+      "type": "string",
+      "description": "Plain-text description of the component's purpose."
+    },
+    "meta": {
+      "$ref": "#/$defs/meta"
+    },
+    "options": {
+      "$ref": "#/$defs/optionsMap"
+    },
+    "slots": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/slotDeclaration"
+      },
+      "description": "Named content injection points. See spec/component-format.md#slots."
+    },
+    "anatomy": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/anatomyPart"
+      },
+      "description": "Named visible parts of the component. Full spec in spec/anatomy-format.md (Phase 6.2)."
+    },
+    "states": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/stateDeclaration"
+      },
+      "description": "Per-component state declarations. Full spec in spec/state-model.md (Phase 6.3)."
+    },
+    "lifecycle": {
+      "$ref": "#/$defs/lifecycle"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "meta": {
+      "type": "object",
+      "required": ["category", "documentationUrl"],
+      "properties": {
+        "category": {
+          "type": "string",
+          "enum": [
+            "actions",
+            "containers",
+            "data visualization",
+            "feedback",
+            "inputs",
+            "navigation",
+            "status",
+            "typography"
+          ],
+          "description": "Design system category for this component."
+        },
+        "documentationUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL of the component's documentation page."
+        }
+      },
+      "additionalProperties": false
+    },
+    "optionsMap": {
+      "type": "object",
+      "description": "Component API options. Each key is a camelCase option name; each value is an option descriptor.",
+      "additionalProperties": {
+        "$ref": "#/$defs/optionDescriptor"
+      }
+    },
+    "optionDescriptor": {
+      "type": "object",
+      "description": "JSON Schema-compatible descriptor for a single component option.",
+      "properties": {
+        "type": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "string",
+                "boolean",
+                "number",
+                "integer",
+                "object",
+                "array",
+                "null"
+              ]
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "string",
+                  "boolean",
+                  "number",
+                  "integer",
+                  "object",
+                  "array",
+                  "null"
+                ]
+              },
+              "minItems": 1
+            }
+          ]
+        },
+        "enum": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Exhaustive list of permitted values."
+        },
+        "default": {
+          "description": "Default value when the option is not specified."
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain-text description of what the option controls."
+        },
+        "$ref": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "Reference to a shared type schema."
+        }
+      },
+      "additionalProperties": false
+    },
+    "slotDeclaration": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Slot identifier. Should come from the canonical slot vocabulary."
+        },
+        "description": {
+          "type": "string",
+          "description": "What content belongs in this slot."
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether consumers must populate this slot."
+        }
+      },
+      "additionalProperties": false
+    },
+    "anatomyPart": {
+      "type": "object",
+      "required": ["name"],
+      "description": "Named visible part of a component. Full spec in spec/anatomy-format.md (Phase 6.2).",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Anatomy part identifier (e.g. 'icon', 'label', 'handle')."
+        },
+        "description": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean",
+          "default": false
+        },
+        "contains": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Informative: anatomy part names nested within this part."
+        }
+      },
+      "additionalProperties": false
+    },
+    "stateDeclaration": {
+      "type": "object",
+      "required": ["name"],
+      "description": "Per-component state declaration. Full spec in spec/state-model.md.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "State identifier (e.g. 'hover', 'focus', 'disabled')."
+        },
+        "description": {
+          "type": "string"
+        },
+        "trigger": {
+          "type": "string",
+          "enum": ["prop", "interaction"],
+          "description": "'prop' for persistent prop-driven states (isDisabled); 'interaction' for runtime states (hover, focus, pressed)."
+        },
+        "precedence": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Resolution precedence; higher integer wins when multiple states are active simultaneously."
+        },
+        "layered": {
+          "type": "boolean",
+          "default": false,
+          "description": "true for states that compose with others (e.g. focus ring layered over hover)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "lifecycle": {
+      "type": "object",
+      "description": "Version lifecycle metadata, mirroring the token lifecycle pattern.",
+      "properties": {
+        "introduced": {
+          "type": "string",
+          "description": "Spec version when this component declaration was added (e.g. '1.0.0-draft')."
+        },
+        "deprecated": {
+          "type": "string",
+          "description": "Spec version when this component was deprecated. Truthy = deprecated."
+        },
+        "deprecatedComment": {
+          "type": "string",
+          "description": "Human-readable explanation of the deprecation and migration path."
+        },
+        "replacedBy": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "minItems": 1
+            }
+          ],
+          "description": "name value(s) of the replacement component(s)."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/field.schema.json

@@ -23,8 +23,8 @@
     },
     "kind": {
       "type": "string",
-      "enum": ["semantic", "dimension"],
-      "description": "Whether this field participates in cascade resolution. 'dimension' fields drive cascade specificity; 'semantic' fields describe identity only."
+      "enum": ["semantic", "dimension", "numeric"],
+      "description": "Whether this field participates in serialization ordering or cascade resolution. 'semantic' fields describe identity and appear in the standard serialization order; 'dimension' fields drive cascade specificity; 'numeric' fields hold integer indices appended at the end of the serialized name."
     },
     "registry": {
       "oneOf": [

package/schemas/state-declaration.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/state-declaration.schema.json",
+  "title": "State declaration",
+  "description": "Layer 1 structural schema for a single state declaration object within a component declaration. Semantic rules (component-state-valid, state-custom-name-documented) are Layer 2.",
+  "type": "object",
+  "required": ["name"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "description": "Kebab-case state identifier. Must match the value used in token name-object 'state' fields."
+    },
+    "description": {
+      "type": "string",
+      "description": "Plain-text description of the state's semantics and the conditions under which it is active."
+    },
+    "trigger": {
+      "type": "string",
+      "enum": ["prop", "interaction"],
+      "description": "'prop' for persistent prop-driven states (e.g. isDisabled); 'interaction' for transient runtime interaction states (hover, focus, pressed)."
+    },
+    "precedence": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Resolution precedence. Higher value wins when multiple non-layered states are active simultaneously. Defaults to 0 when omitted."
+    },
+    "layered": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, this state composes on top of the winning non-layered state rather than competing with it. Use for focus rings, selection overlays, and similar compositing states."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/token.schema.json

@@ -99,7 +99,19 @@
           "const": "1.0.0-draft"
         },
         "name": {
-          "$ref": "#/$defs/nameObject"
+          "oneOf": [
+            { "$ref": "#/$defs/nameObject" },
+            {
+              "type": "string",
+              "minLength": 1,
+              "description": "String escape hatch for tokens that cannot be expressed as a name object. Valid but triggers SPEC-017 (tech-debt warning). See token-format.md#string-name-escape-hatch."
+            }
+          ]
+        },
+        "$valueType": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "URI reference to a value-type schema under schemas/value-types/. When present, value MUST validate against the referenced schema (rule SPEC-016)."
         },
         "value": {
           "description": "Literal value; type narrowed by value-type schemas where applicable.",
@@ -131,10 +143,6 @@
         "introduced": {
           "type": "string"
         },
-        "lastModified": {
-          "type": "string",
-          "description": "Spec version when token value or metadata last changed (e.g. \"2.1.0\"). MUST be >= introduced (see SPEC-014)."
-        },
         "deprecated": {
           "type": "string",
           "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
@@ -178,7 +186,19 @@
           "const": "1.0.0-draft"
         },
         "name": {
-          "$ref": "#/$defs/nameObject"
+          "oneOf": [
+            { "$ref": "#/$defs/nameObject" },
+            {
+              "type": "string",
+              "minLength": 1,
+              "description": "String escape hatch for tokens that cannot be expressed as a name object. Valid but triggers SPEC-017 (tech-debt warning). See token-format.md#string-name-escape-hatch."
+            }
+          ]
+        },
+        "$valueType": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "URI reference to a value-type schema under schemas/value-types/. When present, the alias resolution chain MUST terminate at a token whose value validates against this schema."
         },
         "$ref": {
           "type": "string",
@@ -192,10 +212,6 @@
         "introduced": {
           "type": "string"
         },
-        "lastModified": {
-          "type": "string",
-          "description": "Spec version when token value or metadata last changed (e.g. \"2.1.0\"). MUST be >= introduced (see SPEC-014)."
-        },
         "deprecated": {
           "type": "string",
           "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."

package/schemas/value-types/drop-shadow.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/value-types/drop-shadow.schema.json",
+  "title": "Drop shadow composite value",
+  "description": "Array of shadow layers. Each layer defines offset, blur, spread, and color.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "x": { "type": "string" },
+      "y": { "type": "string" },
+      "blur": { "type": "string" },
+      "spread": { "type": "string" },
+      "color": { "type": "string" }
+    },
+    "required": ["x", "y", "blur", "spread", "color"],
+    "additionalProperties": false
+  },
+  "minItems": 1
+}

package/schemas/value-types/typography-scale.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/value-types/typography-scale.schema.json",
+  "title": "Typography scale composite value",
+  "description": "Pairs a font size with its corresponding line height at a single typographic tier.",
+  "type": "object",
+  "properties": {
+    "fontSize": { "type": "string" },
+    "lineHeight": { "type": "string" }
+  },
+  "required": ["fontSize", "lineHeight"],
+  "additionalProperties": false
+}

package/schemas/value-types/typography.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/value-types/typography.schema.json",
+  "title": "Typography composite value",
+  "description": "Object bundling font properties for a typographic style. Sub-values may be literal strings or inline alias references ({token-name}).",
+  "type": "object",
+  "properties": {
+    "fontFamily": { "type": "string" },
+    "fontSize": { "type": "string" },
+    "fontWeight": { "type": "string" },
+    "letterSpacing": { "type": "string" },
+    "lineHeight": { "type": "string" }
+  },
+  "required": ["fontFamily", "fontSize", "fontWeight", "lineHeight"],
+  "additionalProperties": false
+}