@adobe/design-data-spec 0.2.0 → 0.4.0

package/conformance/README.md

@@ -48,20 +48,20 @@ Each **diff** case lives under `diff/<name>/` with:
 * `new/` — new token dataset
 * `expected.json` — full `DiffReport` structure (six category arrays: renamed, deprecated, reverted, added, deleted, updated)
 
-| Folder                                | Intent                                                                           |
-| ------------------------------------- | -------------------------------------------------------------------------------- |
-| `diff/identical-tokens`               | Two identical datasets MUST produce an empty diff (all arrays empty).            |
-| `diff/simple-add-delete`              | One old-only token → deleted; one new-only token → added.                        |
-| `diff/rename-by-uuid`                 | Same UUID, different name objects → renamed (not add + delete).                  |
-| `diff/deprecated-new-token`           | Unmatched new token with `deprecated: true` → deprecated (not added).            |
-| `diff/deprecated-set-level`           | All set entries `deprecated: true` normalizes to token-level deprecated.         |
-| `diff/reverted-token`                 | Matched token that loses `deprecated` → reverted (not updated).                  |
-| `diff/matched-gaining-deprecated`     | Matched token that gains `deprecated` → updated (not deprecated).               |
-| `diff/property-value-update`          | Matched token with changed `value` → updated with property change.               |
-| `diff/property-nested-change`         | Nested object change reported at leaf path (e.g. `sets.light.value`).            |
-| `diff/uuid-backfill`                  | Old lacks UUID, new gains it with same name object → paired (not add + delete).  |
-| `diff/cross-format`                   | Legacy old + cascade new, paired by UUID across formats.                         |
-| `diff/rename-with-property-changes`   | Renamed token with additional value changes populates `property_changes`.        |
+| Folder                              | Intent                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------------- |
+| `diff/identical-tokens`             | Two identical datasets MUST produce an empty diff (all arrays empty).           |
+| `diff/simple-add-delete`            | One old-only token → deleted; one new-only token → added.                       |
+| `diff/rename-by-uuid`               | Same UUID, different name objects → renamed (not add + delete).                 |
+| `diff/deprecated-new-token`         | Unmatched new token with `deprecated: true` → deprecated (not added).           |
+| `diff/deprecated-set-level`         | All set entries `deprecated: true` normalizes to token-level deprecated.        |
+| `diff/reverted-token`               | Matched token that loses `deprecated` → reverted (not updated).                 |
+| `diff/matched-gaining-deprecated`   | Matched token that gains `deprecated` → updated (not deprecated).               |
+| `diff/property-value-update`        | Matched token with changed `value` → updated with property change.              |
+| `diff/property-nested-change`       | Nested object change reported at leaf path (e.g. `sets.light.value`).           |
+| `diff/uuid-backfill`                | Old lacks UUID, new gains it with same name object → paired (not add + delete). |
+| `diff/cross-format`                 | Legacy old + cascade new, paired by UUID across formats.                        |
+| `diff/rename-with-property-changes` | Renamed token with additional value changes populates `property_changes`.       |
 
 The Rust SDK drives these fixtures in `sdk/core/src/lib.rs` (`diff_conformance` module, closes [#788](https://github.com/adobe/spectrum-design-data/issues/788)).
 
@@ -75,17 +75,17 @@ Each **query** case lives under `query/<name>/` with:
 * `query.txt` — plain-text filter expression
 * `expected.json` — sorted array of matched token UUIDs
 
-| Folder                        | Intent                                                                    |
-| ----------------------------- | ------------------------------------------------------------------------- |
-| `query/single-field`          | Basic `key=value` equality filter.                                        |
-| `query/and-conditions`        | `,` (AND) requires all conditions to match.                               |
-| `query/or-conditions`         | `\|` (OR) matches if any alternative matches.                             |
-| `query/negation`              | `!=` matches non-equal values and absent fields.                          |
-| `query/wildcard-suffix`       | Glob `*` at end of value matches prefix.                                  |
-| `query/wildcard-prefix`       | Glob `*` at start of value matches suffix.                                |
-| `query/empty-matches-all`     | Empty filter expression is a universal match.                             |
-| `query/no-matches`            | Filter with no matching tokens returns empty result.                      |
-| `query/schema-key`            | `$schema` key queries the top-level `$schema` field.                      |
-| `query/and-or-precedence`     | AND binds tighter than OR: `a,b\|c` = `(a AND b) OR c`.                  |
+| Folder                    | Intent                                                  |
+| ------------------------- | ------------------------------------------------------- |
+| `query/single-field`      | Basic `key=value` equality filter.                      |
+| `query/and-conditions`    | `,` (AND) requires all conditions to match.             |
+| `query/or-conditions`     | `\|` (OR) matches if any alternative matches.           |
+| `query/negation`          | `!=` matches non-equal values and absent fields.        |
+| `query/wildcard-suffix`   | Glob `*` at end of value matches prefix.                |
+| `query/wildcard-prefix`   | Glob `*` at start of value matches suffix.              |
+| `query/empty-matches-all` | Empty filter expression is a universal match.           |
+| `query/no-matches`        | Filter with no matching tokens returns empty result.    |
+| `query/schema-key`        | `$schema` key queries the top-level `$schema` field.    |
+| `query/and-or-precedence` | AND binds tighter than OR: `a,b\|c` = `(a AND b) OR c`. |
 
 The Rust SDK drives these fixtures in `sdk/core/src/lib.rs` (`query_conformance` module, closes [#788](https://github.com/adobe/spectrum-design-data/issues/788)).

package/conformance/invalid/SPEC-014/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-014",
+      "severity": "error",
+      "message_pattern": "lastModified .* earlier than introduced"
+    }
+  ]
+}

package/conformance/invalid/SPEC-014/tokens.tokens.json

@@ -0,0 +1,9 @@
+[
+  {
+    "name": { "property": "last-modified-before-introduced" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+    "introduced": "2.0.0",
+    "lastModified": "1.5.0"
+  }
+]

package/conformance/invalid/SPEC-018/dataset.json

@@ -0,0 +1,9 @@
+{
+  "tokens": [
+    {
+      "name": { "component": "nonexistent", "property": "background-color" },
+      "value": "#ff0000"
+    }
+  ],
+  "components": []
+}

package/conformance/invalid/SPEC-018/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-018",
+      "severity": "error",
+      "message_pattern": ".*undeclared component.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-019/dataset.json

@@ -0,0 +1,29 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "button",
+        "variant": "electric",
+        "property": "background-color"
+      },
+      "value": "#0000ff"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "options": {
+        "variant": {
+          "type": "string",
+          "enum": ["accent", "negative", "primary", "secondary"]
+        }
+      }
+    }
+  ]
+}

package/conformance/invalid/SPEC-019/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-019",
+      "severity": "error",
+      "message_pattern": ".*variant.*electric.*not declared.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-020/dataset.json

@@ -0,0 +1,27 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "button",
+        "anatomy": "capsule",
+        "property": "background-color"
+      },
+      "value": "#ff0000"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "anatomy": [
+        { "name": "icon", "description": "Leading icon." },
+        { "name": "label", "description": "Button text.", "required": true }
+      ]
+    }
+  ]
+}

package/conformance/invalid/SPEC-020/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-020",
+      "severity": "error",
+      "message_pattern": ".*undeclared anatomy part.*capsule.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-021/dataset.json

@@ -0,0 +1,18 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "slots": [
+        { "name": "default", "description": "Text label of the button." },
+        { "name": "badge" }
+      ]
+    }
+  ]
+}

package/conformance/invalid/SPEC-021/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-021",
+      "severity": "warning",
+      "message_pattern": ".*custom slot.*badge.*no description.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-022/dataset.json

@@ -0,0 +1,33 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "button",
+        "state": "jello",
+        "property": "background-color"
+      },
+      "value": "#ff0000"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "states": [
+        { "name": "hover", "trigger": "interaction", "precedence": 50 },
+        {
+          "name": "focus",
+          "trigger": "interaction",
+          "precedence": 60,
+          "layered": true
+        },
+        { "name": "disabled", "trigger": "prop", "precedence": 100 }
+      ]
+    }
+  ]
+}

package/conformance/invalid/SPEC-022/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-022",
+      "severity": "error",
+      "message_pattern": ".*undeclared state.*jello.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-023/dataset.json

@@ -0,0 +1,18 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "anatomy": [
+        { "name": "label", "description": "Button text.", "required": true },
+        { "name": "shimmer" }
+      ]
+    }
+  ]
+}

package/conformance/invalid/SPEC-023/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-023",
+      "severity": "warning",
+      "message_pattern": ".*custom anatomy part.*shimmer.*no description.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-024/dataset.json

@@ -0,0 +1,18 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "states": [
+        { "name": "hover", "trigger": "interaction", "precedence": 50 },
+        { "name": "wobble" }
+      ]
+    }
+  ]
+}

package/conformance/invalid/SPEC-024/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-024",
+      "severity": "warning",
+      "message_pattern": ".*custom state.*wobble.*no description.*"
+    }
+  ]
+}

package/conformance/valid/component-refs/dataset.json

@@ -0,0 +1,63 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "button",
+        "variant": "accent",
+        "property": "background-color"
+      },
+      "value": "#0265dc"
+    },
+    {
+      "name": {
+        "component": "button",
+        "anatomy": "label",
+        "property": "color"
+      },
+      "value": "#ffffff"
+    },
+    {
+      "name": {
+        "component": "button",
+        "state": "hover",
+        "property": "background-color"
+      },
+      "value": "#0255be"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "options": {
+        "variant": {
+          "type": "string",
+          "enum": ["accent", "negative", "primary", "secondary"]
+        }
+      },
+      "slots": [
+        { "name": "default", "description": "Text label of the button." },
+        { "name": "icon", "description": "Leading icon." }
+      ],
+      "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 }
+      ]
+    }
+  ]
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {
@@ -20,20 +20,33 @@
   },
   "exports": {
     "./package.json": "./package.json",
+    "./components/*.json": "./components/*.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"
+    "./schemas/component.schema.json": "./schemas/component.schema.json",
+    "./schemas/anatomy-part.schema.json": "./schemas/anatomy-part.schema.json",
+    "./schemas/state-declaration.schema.json": "./schemas/state-declaration.schema.json",
+    "./rules/rules.yaml": "./rules/rules.yaml",
+    "./src/validate.js": "./src/validate.js",
+    "./src/canonical.js": "./src/canonical.js"
   },
   "files": [
-    "spec",
-    "schemas",
+    "components",
+    "conformance",
     "fields",
     "rules",
-    "conformance",
+    "schemas",
+    "spec",
+    "src",
     "README.md"
   ],
-  "scripts": {}
+  "devDependencies": {
+    "ava": "^6.0.1"
+  },
+  "scripts": {
+    "test": "ava"
+  }
 }

package/rules/rules.yaml

@@ -154,3 +154,84 @@ rules:
     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
+}