@adobe/design-data-spec 4.9.0 → 4.11.0

package/package.json

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

package/schemas/component-changelog.schema.json

@@ -213,6 +213,10 @@
           "type": "boolean",
           "description": "True when a bound token's own record is unchanged but its alias-resolved value changed."
         },
+        "reachedBy": {
+          "enum": ["tokenBinding"],
+          "description": "Set when the component reaches the changed token only through its tokenBindings (by token name), not through a relationship. Absent for relationship-reached and component-owned changes."
+        },
         "contexts": {
           "type": "array",
           "items": {

package/schemas/component-spec-sheet.schema.json

@@ -2,14 +2,18 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component-spec-sheet.schema.json",
   "title": "Component spec sheet (draft)",
-  "description": "Draft model of a per-component spec sheet generated by `design-data spec-sheet`: pages of blocks, one block per relationship context. Renderers draw each block's scene and add no layout of their own.",
+  "description": "Draft model of a per-component spec sheet generated by `design-data spec-sheet`: pages of blocks, one block per relationship context, plus one generated block per relationship property for records that carry no context. Renderers draw each block's scene and add no layout of their own.",
   "type": "object",
-  "required": ["specVersion", "component", "size", "block", "pages"],
+  "required": ["specVersion", "component", "visual", "size", "block", "pages"],
   "properties": {
     "$schema": { "type": "string" },
     "specVersion": { "type": "string" },
     "component": { "type": "string" },
     "displayName": { "type": "string" },
+    "visual": {
+      "description": "True when the component has a visual recipe. False marks a table-only sheet: blocks carry token rows but no render, and views show \"No visual recipe yet\". The same stub is the starting point for a new component.",
+      "type": "boolean"
+    },
     "datasetRevision": {
       "description": "Dataset revision (git commit) the sheet and its changelog were generated from.",
       "type": ["string", "null"]
@@ -50,6 +54,8 @@
         "id",
         "page",
         "title",
+        "titleSource",
+        "records",
         "render",
         "rows",
         "notes",
@@ -60,10 +66,22 @@
         "id": { "type": "string" },
         "page": { "type": "string" },
         "title": {
-          "description": "The relationship context string the block documents.",
+          "description": "The relationship context string the block documents, or, when titleSource is \"property\", the relationship property written as words.",
           "type": "string"
         },
-        "render": { "$ref": "#/$defs/render" },
+        "titleSource": {
+          "description": "\"context\": titled by an authored relationship context. \"property\": generated for records without a context, one block per relationship property; views mark these so they read differently from authored groups. A generated block has an unmarked render (no highlight, markers or measurements) and no changes.",
+          "enum": ["context", "property"]
+        },
+        "records": {
+          "description": "Relationship records the block's rows show.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "render": {
+          "description": "The block's visual. Null on a table-only sheet (visual is false).",
+          "oneOf": [{ "$ref": "#/$defs/render" }, { "type": "null" }]
+        },
         "rows": { "type": "array", "items": { "$ref": "#/$defs/row" } },
         "notes": { "type": "array", "items": { "type": "string" } },
         "changes": {
@@ -150,7 +168,7 @@
           }
         },
         "measurements": {
-          "description": "Scene measurements the block shows: those whose relationship context is the block title. `index` points into scene.measurements and `label` is the relationship property.",
+          "description": "Scene measurements the block shows on the Layout page: those whose relationship context is the block title (kinds `height`, `width`, `padding`, `gap`, `radius`, `border`, `focus-thickness`, `focus-gap`, `press`). A block renders in the states and options its bindings need (a focus ring in `keyboard-focus`, a pressed scale in `down`). `index` points into scene.measurements and `label` is the relationship property.",
           "type": "array",
           "items": {
             "type": "object",
@@ -182,8 +200,20 @@
     },
     "item": {
       "type": "object",
-      "required": ["label", "marker", "size", "states", "token", "values"],
+      "required": [
+        "label",
+        "marker",
+        "size",
+        "states",
+        "source",
+        "token",
+        "values"
+      ],
       "properties": {
+        "source": {
+          "description": "\"token\": the record references a token with $ref. \"inline\": the record carries its own value and no token; token.uuid is null and token.name is the record's legacy key or property.",
+          "enum": ["token", "inline"]
+        },
         "label": {
           "description": "Option label from component options or the registry.",
           "type": "string"
@@ -205,7 +235,7 @@
           "additionalProperties": false
         },
         "values": {
-          "description": "Token value per scale (`desktop`, `mobile`), or `value` when the token has no scale. An alias shows as {\"alias\": name}.",
+          "description": "Token value per scale (`desktop`, `mobile`) or color scheme (`light`, `dark`, `wireframe`), or `value` when the token has neither. An alias shows as {\"alias\": name}.",
           "type": "object"
         }
       },

package/spec/component-changelog.md

@@ -19,7 +19,7 @@ A removed and an added option, state, anatomy part or slot that differ only by n
 
 ## Attribution
 
-Each change attaches to a component, to the relationship context (the spec-sheet block title) it appears under, and to a **source**: the PR number in the squash subject (`... (#123)`), otherwise the commit sha and subject. A global token reaches a component through the relationships that bind it. A token a component binds whose own record is unchanged but whose alias-resolved value moved is an **indirect** change. Registry and mode-set changes are not fanned out to components.
+Each change attaches to a component, to the relationship context (the spec-sheet block title) it appears under, and to a **source**: the PR number in the squash subject (`... (#123)`), otherwise the commit sha and subject. A global token reaches a component through the relationships that bind it. A token a component names only in `tokenBindings` (by token name) also reaches it; those entries carry `reachedBy: "tokenBinding"`. A token a component binds whose own record is unchanged but whose alias-resolved value moved is an **indirect** change. Registry and mode-set changes are not fanned out to components.
 
 A record's own `rationale` is copied into the entry when present. History comes from the diff; the source is the fallback reason.