@adobe/design-data-spec 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {
@@ -20,6 +20,7 @@
   },
   "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",

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,
@@ -102,7 +107,7 @@
     },
     "optionDescriptor": {
       "type": "object",
-      "description": "JSON Schema-compatible descriptor for a single component option.",
+      "description": "JSON Schema-compatible descriptor for a single component option. Standard JSON Schema keywords (type, enum, default, description, pattern, minimum, maximum, items, properties, etc.) are all permitted.",
       "properties": {
         "type": {
           "oneOf": [
@@ -154,7 +159,7 @@
           "description": "Reference to a shared type schema."
         }
       },
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "slotDeclaration": {
       "type": "object",
@@ -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:

package/spec/component-format.md

@@ -29,15 +29,16 @@ A component declaration **MUST** contain:
 
 ### Optional fields
 
-| Field         | Type   | Description                                                                                                                                |
-| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `specVersion` | string | Declares which spec version this document targets. Currently `"1.0.0-draft"`; future stable releases will accept their own version string. |
-| `description` | string | Plain-text description of the component's purpose.                                                                                         |
-| `options`     | object | Component API options — see [Options](#options).                                                                                           |
-| `slots`       | array  | Named content injection points — see [Slots](#slots).                                                                                      |
-| `anatomy`     | array  | Named anatomy parts — see [Anatomy (stub)](#anatomy-stub).                                                                                 |
-| `states`      | array  | Per-component state declarations — see [States (stub)](#states-stub).                                                                      |
-| `lifecycle`   | object | Version lifecycle metadata — see [Lifecycle](#lifecycle).                                                                                  |
+| Field           | Type   | Description                                                                                                                                |
+| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `specVersion`   | string | Declares which spec version this document targets. Currently `"1.0.0-draft"`; future stable releases will accept their own version string. |
+| `description`   | string | Plain-text description of the component's purpose.                                                                                         |
+| `options`       | object | Component API options — see [Options](#options).                                                                                           |
+| `slots`         | array  | Named content injection points — see [Slots](#slots).                                                                                      |
+| `anatomy`       | array  | Named anatomy parts — see [Anatomy (stub)](#anatomy-stub).                                                                                 |
+| `states`        | array  | Per-component state declarations — see [States (stub)](#states-stub).                                                                      |
+| `lifecycle`     | object | Version lifecycle metadata — see [Lifecycle](#lifecycle).                                                                                  |
+| `tokenBindings` | array  | Tokens this component uses — see [Token bindings](#token-bindings) (Phase 6.7).                                                            |
 
 **NORMATIVE:** No properties beyond those listed above are permitted at the top level of a component declaration. Additional fields **MUST** cause a Layer 1 schema error.
 
@@ -241,17 +242,41 @@ The `lifecycle` block tracks a component declaration's version history. It mirro
 }
 ```
 
+## Token bindings
+
+The optional `tokenBindings` array declares which tokens a component uses, including foundation and structure tokens that do not carry the component name in their name-object. This is the *component-declares-usage* direction; the *token-declares-scope* direction is expressed via name-object `component`/`anatomy`/`state` fields and validated by SPEC-018–022.
+
+```json
+"tokenBindings": [
+  { "token": "component-height-100",         "context": "Minimum height" },
+  { "token": "corner-radius-full",           "context": "Rounding" },
+  { "token": "button-background-color-accent", "context": "Fill background" }
+]
+```
+
+Each entry contains:
+
+| Field     | Required | Type   | Description                                                                                                                                             |
+| --------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token`   | yes      | string | Token name. **MUST** resolve to a declared token in the dataset when the dataset is present (rule SPEC-027). May reference structure/foundation tokens. |
+| `context` | no       | string | Human-readable label for how this token is used (maps to the Figma Token Group label in the S2 Token Specs Figma file).                                 |
+
+**NORMATIVE:** When the dataset includes token declarations, each `tokenBindings[].token` value **MUST** match the name of a declared token (rule SPEC-027). A missing token reference is a validation error.
+
+The `context` field is informative. It is used by `describe_component` (Phase 8 agent surface) to present token usage in grouped, human-readable form.
+
 ## SPEC rules
 
 The following rules are added to the Layer 2 rule catalog (`rules/rules.yaml`) by this chapter. New component cross-reference rules start at SPEC-018 to avoid collision with existing token rules (SPEC-001–SPEC-017).
 
-| Rule ID  | Name                        | Severity | Assert                                                                                                                                                                        |
-| -------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SPEC-018 | `component-name-exists`     | error    | Token `component` field value **MUST** match the `name` of a declared component in the dataset.                                                                               |
-| SPEC-019 | `component-variant-valid`   | error    | Token `variant` field value **MUST** match a value in the declared `variant` option enum for the referenced component (when that enum exists).                                |
-| SPEC-020 | `component-anatomy-valid`   | error    | Token `anatomy` field value **MUST** match the `name` of a declared anatomy part on the referenced component.                                                                 |
-| SPEC-021 | `component-slot-vocabulary` | warning  | Component `slots` entries with a `name` outside the canonical vocabulary **SHOULD** include a `description`. Custom slot names without descriptions are surfaced as warnings. |
-| SPEC-022 | `component-state-valid`     | error    | Token `state` field value **MUST** match the `name` of a declared state on the referenced component (when state declarations are present).                                    |
+| Rule ID  | Name                         | Severity | Assert                                                                                                                                                                        |
+| -------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SPEC-018 | `component-name-exists`      | error    | Token `component` field value **MUST** match the `name` of a declared component in the dataset.                                                                               |
+| SPEC-019 | `component-variant-valid`    | error    | Token `variant` field value **MUST** match a value in the declared `variant` option enum for the referenced component (when that enum exists).                                |
+| SPEC-020 | `component-anatomy-valid`    | error    | Token `anatomy` field value **MUST** match the `name` of a declared anatomy part on the referenced component.                                                                 |
+| SPEC-021 | `component-slot-vocabulary`  | warning  | Component `slots` entries with a `name` outside the canonical vocabulary **SHOULD** include a `description`. Custom slot names without descriptions are surfaced as warnings. |
+| SPEC-022 | `component-state-valid`      | error    | Token `state` field value **MUST** match the `name` of a declared state on the referenced component (when state declarations are present).                                    |
+| SPEC-027 | `token-binding-token-exists` | error    | Each `tokenBindings[].token` value **MUST** match the name of a declared token in the dataset (Phase 6.7).                                                                    |
 
 ## Full example
 

package/spec/token-format.md

@@ -218,6 +218,24 @@ Within a composite value, a string sub-value **MAY** be an **inline alias**: a r
 
 **NORMATIVE:** Inline aliases within composite values are subject to alias resolution rules. Validators **MUST** resolve inline aliases and report errors for missing targets (SPEC-014), type mismatches (SPEC-015), and circular references (SPEC-003, extended).
 
+## Component bindings
+
+The optional `componentBindings` array on a token is the **reverse index** of `tokenBindings` on a component declaration (Phase 6.7). It declares which components reference this token in their `tokenBindings` list.
+
+```json
+"componentBindings": [
+  { "component": "button",    "context": "Minimum height" },
+  { "component": "checkbox",  "context": "Height" }
+]
+```
+
+| Field       | Required | Type   | Description                                                          |
+| ----------- | -------- | ------ | -------------------------------------------------------------------- |
+| `component` | yes      | string | Component name (kebab-case). MUST match a declared component `name`. |
+| `context`   | no       | string | Human-readable label for how this token is used in the component.    |
+
+`componentBindings` is **informative and optional**. It is fully derivable from the `tokenBindings` arrays on component declarations and does not need to be hand-maintained. Tooling that generates component files may populate `componentBindings` as a convenience for consumers that query token files directly.
+
 ## Relationship to legacy Spectrum tokens
 
 The current `@adobe/spectrum-tokens` JSON uses **sets** (`color-set`, `scale-set`, …). This specification describes the **target** per-token model. Mapping from legacy to this format is out of scope for this document; see [#743](https://github.com/adobe/spectrum-design-data/issues/743).

package/src/validate.js

@@ -13,9 +13,9 @@ governing permissions and limitations under the License.
 /**
  * Layer 2 cross-reference validator for design-data-spec.
  *
- * Implements SPEC-018 through SPEC-024: semantic rules that validate token
- * name-object fields against component declarations, and validate component
- * declarations internally.
+ * Implements SPEC-018 through SPEC-027: semantic rules that validate token
+ * name-object fields against component declarations, validate component
+ * declarations internally, and validate tokenBindings references.
  *
  * @see spec/component-format.md#spec-rules
  * @see spec/anatomy-format.md#spec-rules
@@ -162,5 +162,29 @@ export function validateDataset(dataset) {
     }
   }
 
+  // --- Token binding rules ---
+
+  // SPEC-027: each tokenBindings[].token must resolve to a known token name.
+  // String-named tokens are matched directly. Name-object tokens are skipped
+  // here because tokenBindings always reference tokens by their string name.
+  const tokenNameSet = new Set(
+    tokens
+      .map((t) => (typeof t.name === "string" ? t.name : null))
+      .filter(Boolean),
+  );
+
+  for (const component of components) {
+    for (const binding of component.tokenBindings ?? []) {
+      if (!tokenNameSet.has(binding.token)) {
+        diagnostics.push({
+          ruleId: "SPEC-027",
+          severity: "error",
+          message: `Component '${component.name}' tokenBindings references unknown token '${binding.token}'`,
+          componentName: component.name,
+        });
+      }
+    }
+  }
+
   return diagnostics;
 }