/design-data

name: design-data-agent
description: >
  Validate, query, resolve, diff, and author spec-conformant design tokens and components using the
  design-data MCP tools against a local dataset. Use when the user asks about design tokens, a design
  system, token lookup, spec-conformance, drift detection, or token authoring on custom data.
metadata:
  author: adobe
  version: "1.15.3"
when_to_use: >
  Trigger on: design system, design tokens, spec-conformant, drift, validate tokens, token
  authoring, custom dataset, DESIGN_DATA_PATH, design-data validate, design-data diff,
  design-data write, product-context.json.
allowed-tools: mcp__design-data-agent__primer, mcp__design-data-agent__query_tokens, mcp__design-data-agent__suggest_token, mcp__design-data-agent__resolve_token, mcp__design-data-agent__describe_component, mcp__design-data-agent__validate_usage, mcp__design-data-agent__diff_datasets, mcp__design-data-agent__write, mcp__design-data-agent__start_authoring_session, mcp__design-data-agent__authoring_session_step_intent, mcp__design-data-agent__authoring_session_step_classification, mcp__design-data-agent__authoring_session_step_values, mcp__design-data-agent__authoring_session_commit, mcp__design-data-agent__authoring_session_cancel, mcp__design-data-agent__authoring_session_get, mcp__design-data-agent__authoring_session_list

design-data agent skill

`@adobe/design-data-agent-mcp` provides in-process wasm tools for validating, querying, resolving, diffing, and authoring spec-conformant tokens and components from any dataset on the local filesystem.

Set two path variables once and reference them throughout:

export DESIGN_DATA_PATH=./packages/design-data/tokens
export DESIGN_DATA_SPEC_PATH=./packages/design-data

For Spectrum tokens with zero setup (embedded snapshot), use the `design-data` skill instead — this skill targets custom or repo-local datasets.

Bootstrap

Add `@adobe/design-data-agent-mcp` to your `.cursor/mcp.json`:

{
  "mcpServers": {
    "design-data-agent": {
      "command": "npx",
      "args": ["-y", "@adobe/design-data-agent-mcp@latest"],
      "env": {
        "DESIGN_DATA_PATH": "./packages/tokens/src",
        "DESIGN_DATA_COMPONENTS": "./packages/design-data/components",
        "DESIGN_DATA_FIELDS": "./packages/design-data/fields"
      }
    }
  }
}

Adjust paths to match your dataset layout. Pin `@latest` — the embedded Spectrum snapshot is baked into the wasm at build time and travels with the package version, so there's no separate data update to run, but plain `npx -y <pkg>` (no tag) can reuse a cached older build.

***

Session start — call `primer` first

Call `primer` at the start of every session that touches design data. It returns the active dimensions, component list, taxonomy fields, and token count — structural context that scopes all subsequent lookups. No inputs required.

***

Token lookup

Resolve a token to its literal value — `resolve_token`

Required: `property` (string) — the bare `name.property` segment, e.g. `"background-color"` or `"corner-radius"` (see `primer().properties` for the full list). **Not** a flattened legacyKey like `"accent-background-color-default"` — that form never resolves. Optional context: `colorScheme` (`"light"` or `"dark"`), `scale` (`"desktop"` or `"mobile"`), `contrast` (`"regular"` or `"high"`). Optional narrowing: `component`, `variant`, `state`, and `colorRole`. Set `excludeDeprecated` to omit tokens with `lifecycle.deprecatedIn`.

> **Gotcha:** when several tokens share a property, use `variant`, `state`, or `colorRole` to > narrow the match, then check `ambiguous` and `deprecated` on the result. `component` is > sparsely populated in the current dataset, so prefer the other fields when available. > `resolve_token` still uses cascade ranking when multiple candidates remain; use `query_tokens` > to inspect the full candidate set.

Query tokens by filter expression — `query_tokens`

Required: `filter` (string)

Valid filter keys: `property`, `component`, `variant`, `state`, `colorScheme`, `scale`, `contrast`, `uuid`, `$schema`.

Filter syntax examples:

property=background-color
property=*background*
property=background-color|property=border-color
$schema=https://spectrum.adobe.com/page/design-token/

> **Gotcha:** `component=<id>` currently always returns `[]` — tokens aren't > component-indexed in this dataset. Use `describe_component` to see a component's known > token bindings instead.

> **Exit codes:** `0` = matches found; empty array = no matches (not an error).

Suggest a token from a description — `suggest_token`

Required: `intent` (string) — a natural-language description of the design need, such as `"primary CTA button background color"`.

Optional: `limit` (number, default `5`) — the maximum number of suggestions to return. Results are ranked by confidence using token names, name-object fields, and description text. Use this when the user describes what they need rather than knowing a token name.

***

Component info — `describe_component`

Required: `id` (string) — kebab-case component ID, e.g. `button`, `action-button`

Returns the component contract: `name`, `displayName`, `options`, `anatomy`, `states`, and `tokenBindings`.

***

Validation — `validate_usage`

Optional inputs:

• `path` — dataset path (defaults to `DESIGN_DATA_PATH`)
• `strict` (boolean) — treat warnings as errors
• `schema_path` — override schemas directory (defaults to `@adobe/spectrum-tokens` schemas)

Runs Layer-1 JSON-Schema structural validation and Layer-2 relational rules. Returns `{ valid, errors, warnings }`.

> **Note:** `--exceptions-path` (SPEC-007 naming allowlist) is not supported in the > in-process path. Use the `design-data` CLI directly if you need exceptions support.

***

Dataset diff — `diff_datasets`

Required: `oldPath`, `newPath` Optional: `filter` (substring to narrow results by token name)

Returns `{ renamed, deprecated, rever