design-data-agent

# 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: ```bash 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`: ```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, reverted, added, deleted, updated }`. *** ## Product-layer authoring — `write` Write or update the product context document in the dataset. Optional inputs: `output` (defaults to `$DESIGN_DATA_PATH/product-context.json`), `rationale` (string) *** ## Token authoring session Use the following tools in sequence to create a new token through the wizard: 1. **`start_authoring_session`** — start a session (returns `session_id`) 2. **`authoring_session_step_intent`** — provide natural-language intent; get token suggestions 3. **`authoring_session_step_classification`** — set layer, property, name fields 4. **`authoring_session_step_values`** — set mode-specific value rows 5. **`authoring_session_commit`** — validate and write the token to disk 6. **`authoring_session_cancel`** — cancel without writing Helper tools: `authoring_session_get` (inspect state), `authoring_session_list` (all active sessions). `authoring_session_commit` accepts an optional `schema_path` to override the schemas directory for Layer-1 JSON-Schema validation before writing. > **Note:** The standalone `suggest_token` tool calls the wasm `suggest` API directly. > `authoring_session_step_intent` still delegates to the `design-data` CLI for > session-state-aware ranking within an authoring flow. *** ## Gotchas * **Scale values:** `desktop` and `mobile` — not `medium`/`large`. * **Contrast values:** `regular` and `high` — not `standard`/`high`. * **`query_tokens` returns `[]`** when no tokens match — not an error. * **`diff_datasets` filter** matches by token name substring (case-insensitive). ## When working in Cursor Cursor Settings → Rules → **Add Rule** → **Remote Rule (GitHub)** → paste this URL: ``` https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-mcp/skills/design-data ```