
design-data-agent
Skill: spec-conformant design token lookup, validation, diff, and authoring for any custom dataset via the design-data CLI.
- GitHub stars
- 157
Install
/plugin install design-data-agent@spectrum-design-dataRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/spectrum-design-data.
Contents
Discovered from sourceSkills 1
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, orcolorRoleto narrow the match, then checkambiguousanddeprecatedon the result.componentis sparsely populated in the current dataset, so prefer the other fields when available.resolve_tokenstill uses cascade ranking when multiple candidates remain; usequery_tokensto 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. Usedescribe_componentto 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 relationships (the component's token bindings).
Validation — validate_usage
Optional inputs:
path— dataset path (defaults toDESIGN_DATA_PATH)strict(boolean) — treat warnings as errorsschema_path— override schemas directory (defaults to@adobe/spectrum-tokensschemas)
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 thedesign-dataCLI 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:
start_authoring_session— start a session (returnssession_id)authoring_session_step_intent— provide natural-language intent; get token suggestionsauthoring_session_step_classification— set layer, property, name fieldsauthoring_session_step_values— set mode-specific value rowsauthoring_session_commit— validate and write the token to diskauthoring_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_tokentool calls the wasmsuggestAPI directly.authoring_session_step_intentstill delegates to thedesign-dataCLI for session-state-aware ranking within an authoring flow.
Component previews and fonts (CLI)
The design-data CLI draws a component's visual recipe. SVG needs no setup; PNG text uses
Adobe Clean Spectrum VF when it is installed.
design-data render button --format svg > button.svg
design-data render button --format png --output button.png # --pixel-ratio N, default 2
design-data fonts # exit 0: Spectrum VF found; exit 1: a fallback (Adobe Clean VF, else bundled) is used
design-data fonts --json # { found, fallback, using, family, installed, rejected, related, searched, help }
- The font is found by itself (font folders and Creative Cloud's font cache), or chosen
with
--font <file.ttf>(repeatable) orDESIGN_DATA_FONT=<file.ttf>. A chosen font also sets the layout text widths, so SVG output changes when--fontis passed. - Fallback order: Adobe Clean Spectrum VF Roman
.ttf, Adobe Clean VF Roman.ttf, bundled Source Sans 3. Whenrender --format pnguses either fallback it prints a warning naming the font and the install steps. Relay it: metrics, spacing and wrapping may differ from Adobe Clean Spectrum VF and the image is not exact. Do not tell the user to download anything whendesign-data fontsexits 0. - Adobe employees get the font from the Brand Center
(https://inside.corp.adobe.com/content/inside/en/brand-center/font.html, employees
only): install the
.ttf(not the.otf, which uses PostScript outlines and cannot be read). Creative Cloud's "Adobe Clean" is a different font and is not used. Someone outside Adobe cannot get it, so the fallback is the best result; say so. - If the user says the font is installed but
design-data fontssays it is not, ask for the file's path and use--fontorDESIGN_DATA_FONT. Never offer or attach the font file.
Gotchas
- Scale values:
desktopandmobile— notmedium/large. - Contrast values:
regularandhigh— notstandard/high. query_tokensreturns[]when no tokens match — not an error.diff_datasetsfilter 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
Sponsors
Details
- Marketplace
- adobe/spectrum-design-data
- Source
- tools/design-data-agent-mcp
- Category
- Community