@adobe/design-data-spec 0.12.0 → 0.14.0

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

@@ -0,0 +1,20 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/widget.json",
+      "name": "widget",
+      "displayName": "Widget",
+      "meta": {
+        "category": "feedback",
+        "documentationUrl": "https://spectrum.adobe.com/page/widget/"
+      },
+      "anatomy": [
+        {
+          "name": "not-a-real-part",
+          "description": "A custom part not in the anatomy-terms registry."
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-035",
+      "severity": "warning",
+      "message_pattern": ".*not in the design-system-registry anatomy-terms vocabulary.*"
+    }
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "old-widget",
+        "property": "color"
+      },
+      "value": "#000000"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/old-widget.json",
+      "name": "old-widget",
+      "displayName": "Old Widget",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/old-widget/"
+      },
+      "lifecycle": {
+        "deprecated": "1.0.0-draft",
+        "deprecatedComment": "Superseded by new-widget."
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-036",
+      "severity": "warning",
+      "message_pattern": ".*deprecated component.*"
+    }
+  ]
+}

package/conformance/valid/SPEC-035/dataset.json

@@ -0,0 +1,31 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/dialog.json",
+      "name": "dialog",
+      "displayName": "Dialog",
+      "meta": {
+        "category": "feedback",
+        "documentationUrl": "https://spectrum.adobe.com/page/dialog/"
+      },
+      "anatomy": [
+        {
+          "name": "header",
+          "description": "Top section of the dialog containing the title.",
+          "required": true
+        },
+        {
+          "name": "body",
+          "description": "Main content area of the dialog.",
+          "required": true
+        },
+        {
+          "name": "label",
+          "description": "Dialog title text.",
+          "required": true
+        }
+      ]
+    }
+  ]
+}

package/conformance/valid/SPEC-036/dataset.json

@@ -0,0 +1,43 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "new-widget",
+        "property": "background-color"
+      },
+      "value": "#0265dc"
+    },
+    {
+      "name": {
+        "component": "old-widget",
+        "property": "color"
+      },
+      "value": "#000000",
+      "deprecated": "1.0.0-draft"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/new-widget.json",
+      "name": "new-widget",
+      "displayName": "New Widget",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/new-widget/"
+      }
+    },
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/old-widget.json",
+      "name": "old-widget",
+      "displayName": "Old Widget",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/old-widget/"
+      },
+      "lifecycle": {
+        "deprecated": "1.0.0-draft",
+        "deprecatedComment": "Superseded by new-widget."
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {

package/rules/rules.yaml

@@ -332,3 +332,26 @@ rules:
     message: "Component '{entity}' meta.category value '{value}' is not in the design-system-registry categories vocabulary"
     spec_ref: spec/registry.md#categories
     introduced_in: "1.0.0-draft"
+  - id: SPEC-035
+    name: anatomy-part-name-registry-sync
+    severity: warning
+    category: naming-consistency
+    assert: >
+      A component anatomy part's name SHOULD reference an id from the anatomy-terms registry in
+      @adobe/design-system-registry (anatomy-terms.json). Unknown values are reported as
+      warnings; custom names remain permitted but the registry is the authoritative vocabulary.
+    message: "Component '{entity}' anatomy part name '{value}' is not in the design-system-registry anatomy-terms vocabulary"
+    spec_ref: spec/anatomy-format.md#canonical-anatomy-vocabulary
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-036
+    name: component-deprecation-cascade
+    severity: warning
+    category: reference-integrity
+    assert: >
+      Tokens SHOULD NOT reference a deprecated component via `name.component` unless the token
+      is itself deprecated. Non-deprecated tokens referencing a deprecated component are surfaced
+      as warnings to prompt authors to update the reference or mark the token deprecated.
+    message: "Token '{token}' references deprecated component '{component}' (deprecated since {version}); update the reference or mark the token deprecated"
+    spec_ref: spec/component-format.md#lifecycle
+    introduced_in: "1.0.0-draft"

package/spec/anatomy-format.md

@@ -86,6 +86,8 @@ The following anatomy part names are defined by the cross-platform design audit
 
 Custom part names are permitted. When a custom name is used, the anatomy part object **SHOULD** include a `description` field explaining its visual role (rule SPEC-023).
 
+The table above is informative; the authoritative vocabulary is `@adobe/design-system-registry/registry/anatomy-terms.json` (119 entries). SPEC-035 fires advisory warnings when a declared anatomy part `name` is not in that registry, pointing authors at the canonical list. Custom names remain valid — SPEC-035 is advisory, not an error.
+
 ## Cross-reference with token name objects
 
 Token name objects use an `anatomy` field to scope a token to a specific visible part of a component. The `anatomy` field value must correspond to a part declared in the component's `anatomy` array.
@@ -112,12 +114,13 @@ See [Token format — Name object](token-format.md#name-object) for the full nam
 
 The following rules in the Layer 2 rule catalog (`rules/rules.yaml`) apply to anatomy part declarations. SPEC-020 was introduced in Phase 6.1 (component-format); SPEC-023, SPEC-024, and SPEC-025 are introduced by this chapter.
 
-| Rule ID  | Name                             | Severity | Assert                                                                                                                                                    |
-| -------- | -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SPEC-020 | `component-anatomy-valid`        | error    | Token `anatomy` field value **MUST** match the `name` of a declared anatomy part on the referenced component.                                             |
-| SPEC-023 | `anatomy-custom-part-documented` | warning  | Anatomy part declarations with a `name` outside the canonical anatomy vocabulary **SHOULD** include a `description` field documenting the part's purpose. |
-| SPEC-024 | `anatomy-part-name-unique`       | error    | Anatomy part `name` values **MUST** be unique within a single component's `anatomy` array.                                                                |
-| SPEC-025 | `anatomy-requires-component`     | error    | A token name object **MUST NOT** include an `anatomy` field unless a `component` field is also present.                                                   |
+| Rule ID  | Name                              | Severity | Assert                                                                                                                                                    |
+| -------- | --------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SPEC-020 | `component-anatomy-valid`         | error    | Token `anatomy` field value **MUST** match the `name` of a declared anatomy part on the referenced component.                                             |
+| SPEC-023 | `anatomy-custom-part-documented`  | warning  | Anatomy part declarations with a `name` outside the canonical anatomy vocabulary **SHOULD** include a `description` field documenting the part's purpose. |
+| SPEC-024 | `anatomy-part-name-unique`        | error    | Anatomy part `name` values **MUST** be unique within a single component's `anatomy` array.                                                                |
+| SPEC-025 | `anatomy-requires-component`      | error    | A token name object **MUST NOT** include an `anatomy` field unless a `component` field is also present.                                                   |
+| SPEC-035 | `anatomy-part-name-registry-sync` | warning  | A component anatomy part's `name` **SHOULD** appear in the canonical anatomy-terms registry (`anatomy-terms.json`).                                       |
 
 ## Full example
 

package/spec/registry.md

@@ -33,7 +33,7 @@ Anatomy terms fall into three tiers:
 | Component-specific | Unique to one component                | `loupe`, `gripper`, `hold-icon`                        |
 
 **File:** `packages/design-system-registry/registry/anatomy-terms.json`\
-**Validated by:** SPEC-020, SPEC-023, SPEC-024, SPEC-025\
+**Validated by:** SPEC-020, SPEC-023, SPEC-024, SPEC-025, SPEC-035 (advisory — anatomy part `name` values SHOULD match the anatomy-terms registry)\
 **See also:** [Taxonomy — Component anatomy vs. token objects](taxonomy.md#component-anatomy-vs-token-objects), [Anatomy format](anatomy-format.md)
 
 ### Token objects (`token-objects.json`)