@adobe/design-data-spec 0.4.0 → 0.5.0

package/components/tooltip.json

@@ -50,5 +50,91 @@
   },
   "lifecycle": {
     "introduced": "1.0.0-draft"
-  }
+  },
+  "tokenBindings": [
+    {
+      "token": "component-height-75",
+      "context": "Minimum height"
+    },
+    {
+      "token": "tooltip-maximum-width",
+      "context": "Maximum width"
+    },
+    {
+      "token": "corner-radius-500",
+      "context": "Rounding"
+    },
+    {
+      "token": "tooltip-tip-width",
+      "context": "Tip"
+    },
+    {
+      "token": "tooltip-tip-height",
+      "context": "Tip"
+    },
+    {
+      "token": "tooltip-tip-corner-radius",
+      "context": "Rounding (tip)"
+    },
+    {
+      "token": "component-edge-to-text-75",
+      "context": "Spacing (start/end edges)"
+    },
+    {
+      "token": "component-top-to-text-75",
+      "context": "Spacing (top/bottom edge to text)"
+    },
+    {
+      "token": "component-bottom-to-text-75",
+      "context": "Spacing (top/bottom edge to text)"
+    },
+    {
+      "token": "spacing-75",
+      "context": "Spacing (tip to source)"
+    },
+    {
+      "token": "spacing-100",
+      "context": "Container padding"
+    },
+    {
+      "token": "default-font-family",
+      "context": "Label"
+    },
+    {
+      "token": "regular-font-weight",
+      "context": "Label"
+    },
+    {
+      "token": "default-font-style",
+      "context": "Label"
+    },
+    {
+      "token": "font-size-75",
+      "context": "Label"
+    },
+    {
+      "token": "line-height-100",
+      "context": "Label"
+    },
+    {
+      "token": "cjk-line-height-100",
+      "context": "Label"
+    },
+    {
+      "token": "gray-25",
+      "context": "Text"
+    },
+    {
+      "token": "neutral-background-color-default",
+      "context": "Background (Neutral)"
+    },
+    {
+      "token": "informative-background-color-default",
+      "context": "Background (Informative)"
+    },
+    {
+      "token": "negative-background-color-default",
+      "context": "Background (Negative)"
+    }
+  ]
 }

package/components/tree-view.json

@@ -59,5 +59,283 @@
   ],
   "lifecycle": {
     "introduced": "1.0.0-draft"
-  }
+  },
+  "tokenBindings": [
+    {
+      "token": "workflow-icon-size-100",
+      "context": "Icon"
+    },
+    {
+      "token": "tree-view-minimum-height",
+      "context": "Height (minimum)"
+    },
+    {
+      "token": "tree-view-minimum-width",
+      "context": "Width (minimum)"
+    },
+    {
+      "token": "corner-radius-medium-default",
+      "context": "Rounding"
+    },
+    {
+      "token": "tree-view-disclosure-indicator-height",
+      "context": "Spacing (disclosure indicator)"
+    },
+    {
+      "token": "tree-view-disclosure-indicator-width",
+      "context": "Spacing (disclosure indicator)"
+    },
+    {
+      "token": "tree-view-edge-to-checkbox",
+      "context": "Spacing (edge to checkbox, checkbox)"
+    },
+    {
+      "token": "tree-view-edge-to-drag-handle",
+      "context": "Spacing (edge to drag handle, drag handle)"
+    },
+    {
+      "token": "tree-view-drag-handle-to-checkbox",
+      "context": "Spacing (drag handle to checkbox, drag handle + checkbox)"
+    },
+    {
+      "token": "text-to-visual-100",
+      "context": "Spacing (context area to label)"
+    },
+    {
+      "token": "component-edge-to-text-100",
+      "context": "Spacing (label to edge)"
+    },
+    {
+      "token": "tree-view-label-to-action-area",
+      "context": "Spacing (label to action area)"
+    },
+    {
+      "token": "tree-view-end-edge-to-action-area",
+      "context": "Spacing (edge to action area, action button 1 + action button 2)"
+    },
+    {
+      "token": "tree-view-level-increment",
+      "context": "Spacing (indentation)"
+    },
+    {
+      "token": "vertical-align-items",
+      "context": "Spacing (vertical)"
+    },
+    {
+      "token": "stack-item-minimum-padding-vertical",
+      "context": "Spacing (vertical)"
+    },
+    {
+      "token": "border-width-100",
+      "context": "Border width (selected, highlight)"
+    },
+    {
+      "token": "focus-indicator-thickness",
+      "context": "Focus "
+    },
+    {
+      "token": "focus-indicator-gap",
+      "context": "Focus (drag handle)"
+    },
+    {
+      "token": "component-height-200",
+      "context": "Height"
+    },
+    {
+      "token": "stack-item-minimum-vertical-padding",
+      "context": "Spacing (vertical)"
+    },
+    {
+      "token": "stack-item-item-to-item",
+      "context": "Spacing (vertically, between tree view items)"
+    },
+    {
+      "token": "tree-view-item-to-header",
+      "context": "Spacing (vertically, between tree view item and tree view header)"
+    },
+    {
+      "token": "tree-view-header-to-item",
+      "context": "Spacing (vertically, between tree view item and tree view header)"
+    },
+    {
+      "token": "stack-item-header-to-item",
+      "context": "Spacing (vertically, between tree view item and tree view header)"
+    },
+    {
+      "token": "stack-item-background-color-hover",
+      "context": "Background (not selected)"
+    },
+    {
+      "token": "stack-item-background-color-down",
+      "context": "Background (not selected)"
+    },
+    {
+      "token": "stack-item-background-color-key-focus",
+      "context": "Background (not selected)"
+    },
+    {
+      "token": "tree-view-selected-row-background-default",
+      "context": "Background (selected, checkbox)"
+    },
+    {
+      "token": "tree-view-selected-row-background-hover",
+      "context": "Background (selected, checkbox)"
+    },
+    {
+      "token": "stack-item-selected-background-color-default",
+      "context": "Background (selected, checkbox)"
+    },
+    {
+      "token": "stack-item-selected-background-color-hover",
+      "context": "Background (selected, checkbox)"
+    },
+    {
+      "token": "stack-item-selected-background-color-down",
+      "context": "Background (selected, checkbox)"
+    },
+    {
+      "token": "stack-item-selected-background-color-key-focus",
+      "context": "Background (selected, checkbox)"
+    },
+    {
+      "token": "tree-view-selected-row-background-color-emphasized",
+      "context": "Background (selected, emphasized)"
+    },
+    {
+      "token": "tree-view-selected-row-background-opacity-emphasized-hover",
+      "context": "Background (selected, emphasized)"
+    },
+    {
+      "token": "stack-item-selected-background-color-highlight",
+      "context": "Background (selected + highlight)"
+    },
+    {
+      "token": "stack-item-selected-background-opacity-highlight-hover",
+      "context": "Background (selected + highlight)"
+    },
+    {
+      "token": "accent-content-color-selected",
+      "context": "Border (selected + highlight)"
+    },
+    {
+      "token": "neutral-subdued-content-color-default",
+      "context": "Label and icon (non-selected)"
+    },
+    {
+      "token": "neutral-subdued-content-color-hover",
+      "context": "Label and icon (non-selected)"
+    },
+    {
+      "token": "neutral-subdued-content-color-down",
+      "context": "Label and icon (non-selected)"
+    },
+    {
+      "token": "neutral-subdued-content-color-key-focus",
+      "context": "Label and icon (non-selected)"
+    },
+    {
+      "token": "neutral-content-color-default",
+      "context": "Label and icon (selected, checkbox and highlight)"
+    },
+    {
+      "token": "neutral-content-color-hover",
+      "context": "Label and icon (selected, checkbox and highlight)"
+    },
+    {
+      "token": "neutral-content-color-down",
+      "context": "Label and icon (selected, checkbox and highlight)"
+    },
+    {
+      "token": "neutral-content-color-key-focus",
+      "context": "Label and icon (selected, checkbox and highlight)"
+    },
+    {
+      "token": "disabled-content-color",
+      "context": "Label and icon (disabled)"
+    },
+    {
+      "token": "focus-indicator-color",
+      "context": "Focus indicator"
+    },
+    {
+      "token": "title-content-color",
+      "context": "Label and icon"
+    },
+    {
+      "token": "default-font-family",
+      "context": "Text (tree view item)"
+    },
+    {
+      "token": "regular-font-weight",
+      "context": "Text (tree view item)"
+    },
+    {
+      "token": "default-font-style",
+      "context": "Text (tree view item)"
+    },
+    {
+      "token": "font-size-100",
+      "context": "Text (tree view item)"
+    },
+    {
+      "token": "line-height-100",
+      "context": "Text (tree view item)"
+    },
+    {
+      "token": "cjk-line-height-100",
+      "context": "Text (tree view item)"
+    },
+    {
+      "token": "bold-font-weight",
+      "context": "Text (tree view title)"
+    },
+    {
+      "token": "thumbnail-size-75",
+      "context": "Size"
+    },
+    {
+      "token": "thumbnail-size-300",
+      "context": "Size"
+    },
+    {
+      "token": "thumbnail-size-1000",
+      "context": "Size"
+    },
+    {
+      "token": "thumbnail-corner-radius",
+      "context": "Rounding (default)"
+    },
+    {
+      "token": "spacing-75",
+      "context": "Opacity checkerboard (layer)"
+    },
+    {
+      "token": "corner-radius-0",
+      "context": "Rounding (layer)"
+    },
+    {
+      "token": "thumbnail-border-color",
+      "context": "Border (default)"
+    },
+    {
+      "token": "thumbnail-border-opacity",
+      "context": "Border (default)"
+    },
+    {
+      "token": "gray-500",
+      "context": "Border (layer)"
+    },
+    {
+      "token": "opacity-checkerboard-square-light",
+      "context": "Checkerboard colors "
+    },
+    {
+      "token": "opacity-checkerboard-square-dark",
+      "context": "Checkerboard colors "
+    },
+    {
+      "token": "thumbnail-opacity-disabled",
+      "context": "Disabled"
+    }
+  ]
 }

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

@@ -0,0 +1,25 @@
+{
+  "tokens": [
+    {
+      "name": { "property": "background-color" },
+      "value": "#0265dc"
+    }
+  ],
+  "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/"
+      },
+      "tokenBindings": [
+        {
+          "token": "nonexistent-token-that-does-not-exist",
+          "context": "Background"
+        }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-027",
+      "severity": "error",
+      "message_pattern": ".*unknown token.*"
+    }
+  ]
+}

package/conformance/valid/token-bindings.json

@@ -0,0 +1,27 @@
+{
+  "tokens": [
+    {
+      "name": "button-background-color-accent",
+      "value": "#0265dc"
+    },
+    {
+      "name": "component-height-100",
+      "value": "32px"
+    }
+  ],
+  "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/"
+      },
+      "tokenBindings": [
+        { "token": "button-background-color-accent", "context": "Background" },
+        { "token": "component-height-100", "context": "Sizing (height)" }
+      ]
+    }
+  ]
+}

package/package.json

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

package/rules/rules.yaml

@@ -235,3 +235,12 @@ rules:
     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"
+
+  - id: SPEC-027
+    name: token-binding-token-exists
+    severity: error
+    category: reference-integrity
+    assert: Each tokenBindings[].token value in a component declaration MUST match the name of a declared token in the dataset.
+    message: "Component '{component}' tokenBindings references unknown token '{token}'"
+    spec_ref: spec/component-format.md#token-bindings
+    introduced_in: "1.0.0-draft"

package/schemas/component.schema.json

@@ -63,6 +63,11 @@
     },
     "lifecycle": {
       "$ref": "#/$defs/lifecycle"
+    },
+    "tokenBindings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/tokenBinding" },
+      "description": "Tokens this component uses, including foundation/structure tokens not scoped to the component in their name-object. See spec/component-format.md#token-bindings (Phase 6.7)."
     }
   },
   "additionalProperties": false,
@@ -233,6 +238,23 @@
       },
       "additionalProperties": false
     },
+    "tokenBinding": {
+      "type": "object",
+      "required": ["token"],
+      "description": "A single token usage binding on a component declaration.",
+      "properties": {
+        "token": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Token name string. MUST resolve to a known token in the dataset (rule SPEC-027)."
+        },
+        "context": {
+          "type": "string",
+          "description": "Human-readable label for how this token is used in the component (maps to Figma Token Group label)."
+        }
+      },
+      "additionalProperties": false
+    },
     "lifecycle": {
       "type": "object",
       "description": "Version lifecycle metadata, mirroring the token lifecycle pattern.",

package/schemas/token.schema.json

@@ -171,6 +171,11 @@
         "description": {
           "type": "string",
           "description": "Plain text describing the token's purpose (aligns with DTCG $description)."
+        },
+        "componentBindings": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/componentBinding" },
+          "description": "Reverse index: components that declare this token in their tokenBindings. Optional and derivable from component files."
         }
       },
       "additionalProperties": false
@@ -240,6 +245,28 @@
         "description": {
           "type": "string",
           "description": "Plain text describing the token's purpose (aligns with DTCG $description)."
+        },
+        "componentBindings": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/componentBinding" },
+          "description": "Reverse index: components that declare this token in their tokenBindings. Optional and derivable from component files."
+        }
+      },
+      "additionalProperties": false
+    },
+    "componentBinding": {
+      "type": "object",
+      "required": ["component"],
+      "description": "A single component usage binding on a token — the reverse of tokenBindings on the component.",
+      "properties": {
+        "component": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Component name (kebab-case). MUST match a declared component name."
+        },
+        "context": {
+          "type": "string",
+          "description": "Human-readable label for how this token is used in the component."
         }
       },
       "additionalProperties": false

package/spec/agent-surface.md

@@ -25,15 +25,15 @@ The surface targets three consumer shapes:
 
 **NORMATIVE:** A conforming implementation MUST expose the following operations. Transport-specific naming (CLI subcommand vs MCP tool name vs skill action) MAY differ; the semantics MUST NOT.
 
-| Operation            | Reads                                                  | Returns                                                                                                                  | Backed by              |
-| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
-| `resolve_token`      | property + dimension context                           | winning token (literal or resolved alias) with file/UUID/specificity                                                     | `cascade::resolve`     |
-| `query_tokens`       | filter expression (see [Query](query.md))              | matching token list                                                                                                      | `query::filter`        |
-| `validate_usage`     | candidate token document or fragment                   | `ValidationReport` (Layer 1 + Layer 2 diagnostics)                                                                       | `validate::validate_*` |
-| `describe_component` | component identifier                                   | component contract (anatomy, options, states); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) | (Phase 6 contract)     |
-| `suggest_token`      | natural-language intent + optional property hint       | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1)                                                | registry + query       |
-| `get_guidance`       | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D                                           | document blocks        |
-| `diff_datasets`      | two dataset roots                                      | `DiffReport` per [Diff](diff.md)                                                                                         | `diff::semantic_diff`  |
+| Operation            | Reads                                                  | Returns                                                                                                                                                                                   | Backed by              |
+| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `resolve_token`      | property + dimension context                           | winning token (literal or resolved alias) with file/UUID/specificity                                                                                                                      | `cascade::resolve`     |
+| `query_tokens`       | filter expression (see [Query](query.md))              | matching token list                                                                                                                                                                       | `query::filter`        |
+| `validate_usage`     | candidate token document or fragment                   | `ValidationReport` (Layer 1 + Layer 2 diagnostics)                                                                                                                                        | `validate::validate_*` |
+| `describe_component` | component identifier                                   | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract)     |
+| `suggest_token`      | natural-language intent + optional property hint       | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1)                                                                                                                 | registry + query       |
+| `get_guidance`       | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D                                                                                                            | document blocks        |
+| `diff_datasets`      | two dataset roots                                      | `DiffReport` per [Diff](diff.md)                                                                                                                                                          | `diff::semantic_diff`  |
 
 **NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, and `diff_datasets` MUST be implemented in a conforming agent surface. `suggest_token` and `get_guidance` are RECOMMENDED. `describe_component` becomes NORMATIVE once [#832](https://github.com/adobe/spectrum-design-data/discussions/832) reaches implemented status.
 
@@ -82,6 +82,36 @@ A reference Claude Code Agent Skill is RECOMMENDED at `tools/design-data-agent-m
 
 **RECOMMENDED:** The skill SHOULD shell out to the CLI rather than embedding tool calls, so its description (the only persistent context cost) stays small and the heavy lifting happens out-of-band.
 
+## `describe_component` return shape
+
+The `describe_component` tool returns the component declaration object as stored in the dataset, extended with `tokenBindings` when Phase 6.7 data is present. A conforming implementation MUST include `tokenBindings` in the response when the component declaration contains that field.
+
+```json
+{
+  "name": "button",
+  "displayName": "Button",
+  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
+  "options": {
+    "variant": { "type": "string", "enum": ["accent", "negative", "primary", "secondary"], "default": "accent" }
+  },
+  "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 }
+  ],
+  "tokenBindings": [
+    { "token": "component-height-100", "context": "Minimum height" },
+    { "token": "corner-radius-full",   "context": "Rounding" }
+  ]
+}
+```
+
+`tokenBindings` enables agents to retrieve a complete picture of a component's token usage — including shared structure and foundation tokens that do not carry the component name in their name-object — without issuing a second `query_tokens` call.
+
 ## Conformance
 
 **NORMATIVE:** An agent surface implementation that claims conformance MUST: