@adobe/design-data-spec 2.7.0 → 2.8.0

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

@@ -0,0 +1,21 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/menu.json",
+      "name": "menu",
+      "displayName": "Menu",
+      "meta": {
+        "category": "collections",
+        "documentationUrl": "https://spectrum.adobe.com/page/menu/"
+      },
+      "anatomy": [
+        {
+          "name": "menu-item",
+          "description": "A single row within the menu.",
+          "contains": ["item-checkbox"]
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-048",
+      "severity": "warning",
+      "message_pattern": ".*menu-item.*item-checkbox.*"
+    }
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/menu.json",
+      "name": "menu",
+      "displayName": "Menu",
+      "meta": {
+        "category": "collections",
+        "documentationUrl": "https://spectrum.adobe.com/page/menu/"
+      },
+      "anatomy": [
+        {
+          "name": "menu-item",
+          "description": "A single row within the menu.",
+          "contains": ["item-icon", "item-label"]
+        },
+        { "name": "item-icon", "description": "Leading icon of a menu item." },
+        { "name": "item-label", "description": "Label text of a menu item." }
+      ]
+    }
+  ]
+}

package/package.json

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

package/rules/rules.yaml

@@ -544,3 +544,19 @@ rules:
     message: "Token '{token}' has space-between endpoint '{endpoint}' that is not a known position, anatomy term, or declared anatomy part on component '{component}'"
     spec_ref: spec/token-format.md#space-between-endpoints
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-048
+    name: anatomy-contains-resolves
+    severity: warning
+    layer: 2
+    category: completeness
+    assert: >
+      Each string in an anatomy part's `contains` array SHOULD match the `name` of
+      another anatomy part declared on the same component. Unresolved references are
+      advisory rather than an error: `contains` may legitimately point at sub-component
+      anatomy in layered designs (anatomy-format.md#contains), so this rule only warns
+      when a `contains` entry cannot be resolved against the same component's declared
+      parts.
+    message: "Anatomy part '{part}' on component '{component}' contains '{child}', which is not a declared anatomy part on this component"
+    spec_ref: spec/anatomy-format.md#contains
+    introduced_in: "1.0.0-draft"

package/schemas/anatomy-part.schema.json

@@ -2,7 +2,7 @@
   "$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.",
+  "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, anatomy-contains-resolves) are Layer 2.",
   "type": "object",
   "required": ["name"],
   "properties": {
@@ -28,7 +28,7 @@
         "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."
+      "description": "List of child anatomy part names nested within this part. SHOULD reference a `name` declared elsewhere in the same component's anatomy array; unresolved references are permitted (they may point at sub-component anatomy in layered designs) but rule anatomy-contains-resolves fires an advisory warning."
     },
     "documentBlocks": {
       "type": "array",

package/schemas/component.schema.json

@@ -225,7 +225,7 @@
         "contains": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "Informative: anatomy part names nested within this part."
+          "description": "Anatomy part names nested within this part. SHOULD reference a `name` declared elsewhere in this component's anatomy array (see anatomy-contains-resolves)."
         },
         "documentBlocks": {
           "type": "array",

package/schemas/token.schema.json

@@ -51,6 +51,10 @@
           "type": "string",
           "description": "Semantic: interactive or semantic state (e.g. hover, focus, disabled)."
         },
+        "qualifier": {
+          "type": "string",
+          "description": "Semantic: behavioral or layout modifier that narrows a property/anatomy without being a state, variant, or position (e.g. stacked, multiline, precision, collapsed, expanded, drag, highlight)."
+        },
         "orientation": {
           "type": "string",
           "description": "Semantic: direction or order (e.g. vertical, horizontal)."
@@ -71,6 +75,10 @@
           "type": "string",
           "description": "Semantic: overall component shape (e.g. uniform)."
         },
+        "role": {
+          "type": "string",
+          "description": "Semantic: an object's role within a nesting relationship (e.g. container, control), distinct from `size`."
+        },
         "from": {
           "type": "string",
           "description": "Semantic: starting endpoint of a space-between measurement (e.g. top, edge, text). Paired with `to`; used with property `space-between`."
@@ -90,6 +98,11 @@
         "contrast": {
           "type": "string",
           "description": "Mode set: contrast level (e.g. regular, high)."
+        },
+        "legacyKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Escape hatch: pins the exact flat key written to legacy output (packages/tokens/src), overriding reconstruction from the rest of this name object. Use when correcting or extending a token's decomposition would otherwise change its published legacy key."
         }
       },
       "additionalProperties": {

package/spec/anatomy-format.md

@@ -46,11 +46,13 @@ When `required` is `true`, the anatomy part is unconditionally rendered (e.g. a
 
 ### `contains`
 
-**OPTIONAL.** An informative list of child anatomy part `name` values that are visually or structurally nested within this part. This field is for documentation and tooling assistance; it does not carry enforcement semantics.
+**OPTIONAL.** A list of child anatomy part `name` values that are visually or structurally nested within this part.
 
-**RECOMMENDED:** When a part logically encloses other declared anatomy parts, authors **SHOULD** use `contains` to make the nesting explicit.
+**RECOMMENDED:** When a part logically encloses other declared anatomy parts, authors **SHOULD** use `contains` to make the nesting explicit, rather than declaring the children only as flat, unrelated parts.
 
-Each string in `contains` **MUST** match the pattern `^[a-z][a-z0-9-]*$`. References to anatomy part names not declared on the same component are permitted (they may refer to sub-component anatomy in layered designs) but validators **MAY** surface a warning for unresolved references.
+Each string in `contains` **MUST** match the pattern `^[a-z][a-z0-9-]*$`. References to anatomy part names not declared on the same component are permitted (they may refer to sub-component anatomy in layered designs), but a reference that cannot be resolved against the same component's declared parts triggers an advisory warning (rule SPEC-048, `anatomy-contains-resolves`) — it is not an error.
+
+**Authoring convention — flat vs. nested:** declare a part as a flat leaf when it has no meaningful internal sub-structure of its own (e.g. `label`, `icon`). Declare a part with `contains` when it is a composite that visually groups other declared parts (e.g. a `menu-item` row containing an `icon` and a `label`, or a `list-item` row containing a `checkbox`, `thumbnail`, and `label`). Prefer the canonical vocabulary (below) for children where the semantics match, falling back to a documented custom name (SPEC-023) otherwise.
 
 ### `lifecycle`
 
@@ -135,6 +137,7 @@ The following rules in the Layer 2 rule catalog (`rules/rules.yaml`) apply to an
 | 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`).                                       |
 | SPEC-037 | `sub-entity-deprecation-cascade`  | warning  | A non-deprecated token **SHOULD NOT** reference a deprecated anatomy part via `name.anatomy`. Advisory warning prompts migration.                         |
+| SPEC-048 | `anatomy-contains-resolves`       | warning  | An anatomy part's `contains` entries **SHOULD** match the `name` of another part declared on the same component. Advisory warning for unresolved entries. |
 
 ## Full example
 

package/spec/taxonomy.md

@@ -73,6 +73,7 @@ The following concept categories are defined in Spectrum's foundation field cata
 | Size          | `size`            | When/Why? | Relative terms used to create relationships and patterns of usage across multiple tokens and token types.                                                                                                                                                                                                                                                                                                                                                                                      |
 | Density       | `density`         | When/Why? | Options that create more or less space within or around the parts of a component.                                                                                                                                                                                                                                                                                                                                                                                                              |
 | Shape         | `shape`           | When/Why? | Relative to the overall shape of a component (e.g. "uniform" creates a 1:1 padding ratio between horizontal and vertical padding).                                                                                                                                                                                                                                                                                                                                                             |
+| Role          | `role`            | When/Why? | An object's role within a nesting relationship (e.g. `container`, `control`), distinct from `size` — e.g. corner-radius tokens where a container and its nested control each need an independently-scaled rounding step.                                                                                                                                                                                                                                                                       |
 
 Additional categories for variant and state are inherited from the existing name object:
 

package/spec/token-format.md

@@ -70,6 +70,7 @@ The table below lists all semantic fields. Fields marked with a scope are domain
 | `size`         | OPTIONAL | Size              | Relative t-shirt sizing for relationships across tokens (e.g. `small`, `medium`, `large`).                                                                               |
 | `density`      | OPTIONAL | Density           | Space within or around component parts (e.g. `spacious`, `compact`).                                                                                                     |
 | `shape`        | OPTIONAL | Shape             | Relative to overall component shape (e.g. `uniform`).                                                                                                                    |
+| `role`         | OPTIONAL | Role              | An object's role within a nesting relationship (e.g. `container`, `control`), distinct from `size`.                                                                      |
 | `scaleIndex`   | OPTIONAL | —                 | Numeric scale index appended at the end of the serialized name (e.g. `100`, `200`, `900`). Used by color palette, spacing, font-size, and motion duration tokens.        |
 | `from`         | OPTIONAL | —                 | Starting endpoint of a `space-between` measurement (e.g. `top`, `edge`, `text`). See [Space-between endpoints](#space-between-endpoints).                                |
 | `to`           | OPTIONAL | —                 | Ending endpoint of a `space-between` measurement (e.g. `text`, `visual`, `control`). See [Space-between endpoints](#space-between-endpoints).                            |