Spectrum Design Data
  • Components
  • Tokens
  • Registry
  • AI
  • Articles
  • Specification
  • Tools
  • Using AI

    Spectrum Design Data puts the official Spectrum dataset (design tokens, component schemas, and Spectrum documentation and usage guidelines) directly in your AI assistant, so it answers from real data instead of guessing. It ships as an MCP server, and as a plugin that bundles that server with a skill. Both carry an embedded snapshot of Spectrum, docs included, so there's no dataset to point at. They need Node.js 20.12 or later, and the first run downloads the package with npx; after that, lookups use the embedded snapshot.

    It's for anyone building with Spectrum: engineers, designers, PMs prototyping a screen, reviewing a PR, or wiring up a component who want to know "which token is this" or "what does this component support" without leaving the conversation.

    What you can do with it

    Ask in plain language. The assistant answers from the embedded Spectrum dataset instead of guessing.

    Look things up

    • Find a token: "what's the token for the default row background?" (the query tool filters by property, component, state, variant, and mode)
    • Suggest a token from a description: "I need a background for a selected, hovered row." It ranks existing tokens by confidence and surfaces real ones first, so you reuse before you invent.
    • Inspect a component's options: "what sizes and variants does Button support?" You get the actual schema: variants, sizes, states, and boolean props.
    • Resolve a value in context: "what's this token's hex in dark mode at high contrast?" Resolve takes a property name, optional color scheme, scale, and contrast, and can narrow by component, variant, or state. If several tokens still match, the result is marked ambiguous with a top pick plus the alternatives.
    • Read a guideline: "pull up the Colors guideline" or "what does the background layers guidance say?"
    • Get oriented: a primer with token counts, the component list, the registry vocabulary, and where the data came from.

    Use the shared vocabulary (the registry)

    The primer also exposes Spectrum's controlled vocabulary: variants (accent, quiet, negative, and so on), t-shirt sizes (xs through xxl, with medium as the default), interaction states (default, hover, focus, disabled), and component anatomy terms. Use it to name things the Spectrum way and to confirm which size, state, or variant names are real before you rely on them.

    Prototype and build custom components

    Working on something that isn't in Spectrum Web Components or React Spectrum yet? The dataset won't write the component for you, but it keeps a hand-built one on Spectrum foundations:

    • Pick real Spectrum tokens for color, spacing, and radius with suggest and query instead of hard-coding values.
    • Borrow the registry vocabulary for prop names (size, variant, state) so your component matches Spectrum conventions.
    • Use an existing component's schema as a model for how Spectrum organizes variants, sizes, and states.
    • Check the relevant guideline before you commit to a pattern.

    It answers from the data. It does not generate component code or plug into Spectrum Web Components or React Spectrum.

    Plugin vs. MCP server

    Same data, same read-only tools, two ways to install them:

    spectrum-design-data plugin MCP server only
    Includes The MCP server (pinned version) and a skill that teaches the assistant when and how to use it The MCP server
    Context cost Registers an MCP server, so the client may load all tool definitions every session Same: all tools loaded every session
    Best for Quick setup with usage guidance Always-available access, agent pipelines, clients without plugins
    Setup Install once per tool below; no MCP config Add to your MCP config, restart

    The plugin is not a lighter, skill-only install. A skill alone (for example a Cursor rule) costs only its description until used, but it has no tools until you add the MCP server.

    Install the MCP server

    The MCP server (@adobe/design-data-mcp) uses the same config shape in every MCP-capable tool: just npx, no environment variables.

    {
      "mcpServers": {
        "design-data": {
          "command": "npx",
          "args": ["-y", "@adobe/design-data-mcp@latest"]
        }
      }
    }

    (@latest avoids npx reusing a cached, older build. The plugin instead pins an exact version, so its data changes only when the pin is bumped.) Where that block goes:

    Tool Config location
    Claude Code .mcp.json
    GitHub Copilot CLI ~/.copilot/mcp-config.json (add "type": "local"), or run copilot mcp add design-data -- npx -y @adobe/design-data-mcp@latest
    GitHub Copilot app (desktop) Customize → MCP → add custom server. MCP servers configured in a repo or in Copilot CLI sync in automatically.
    VS Code .vscode/mcp.json (note the root key is servers, not mcpServers)
    Cursor .cursor/mcp.json

    Restart the tool after changing its MCP config.

    Install the plugin

    The plugin bundles the MCP server and the skill, so there is no separate MCP setup.

    Install it once, from one place. The plugin is published in the Design AI Marketplace and in this repository's marketplace; use one. Each copy registers a server and a skill named design-data, so a second copy, or a design-data entry in a repo's mcp.json, gives the client duplicates and it may expose none of them. If the assistant reports no design-data tools, look for extra copies, remove them and start a new session. If you install the plugin, remove any design-data entry you added by hand from an MCP config.

    Claude Code:

    /plugin marketplace add adobe/spectrum-design-data
    /plugin install spectrum-design-data@spectrum-design-data
    

    GitHub Copilot app (desktop): two links, two clicks each. The app asks you to confirm before it changes anything.

    1. Add the marketplace to the GitHub Copilot app (once). This lets the app find plugins from this repository.
    2. Install the plugin in the GitHub Copilot app. Click Allow when the app asks, then confirm the install under Customize.
    3. Start a new session. A session that was already open does not pick up the plugin's tools. In the new session, ask the assistant to use the design-data tools (for example, "use the design-data primer").

    Didn't work?

    • The link opened a web page and not the app. The app has to be installed. If the browser can't hand off to it, the link shows a fallback page; open the app yourself and use the manual steps below.
    • The app says the marketplace isn't found. Finish step 1, then try step 2 again.
    • The plugin is installed but the assistant says it has no design-data tool. Start a new session, check that Customize → Installed → spectrum-design-data is switched on, and make sure Node.js 20.12 or later is available to the app (the plugin starts its server with npx).

    To do the same by hand: Customize, use the marketplace settings next to the marketplace dropdown to add adobe/spectrum-design-data, then find spectrum-design-data on the Browse page and click Install. See Customizing the GitHub Copilot app.

    GitHub Copilot CLI: it reads the same marketplace.json Claude Code plugins use (it checks .claude-plugin/ alongside its own .github/plugin/), so this repo is already a Copilot plugin marketplace. No separate Copilot config is needed:

    copilot plugin marketplace add adobe/spectrum-design-data
    copilot plugin install spectrum-design-data@spectrum-design-data
    

    Installing the plugin adds its skill and registers its MCP server. Skills configured for a repo or via Copilot CLI are also available in the GitHub Copilot app; manage them there under Customize → Skills. You can also skip the marketplace and copy tools/design-data-skill/skills/design-data/ directly into ~/.copilot/skills/ or a repo's .github/skills/. Copilot also reads .claude/skills/.

    Cursor (skill only, no bundled MCP server; add the MCP config above as well): Settings → Rules → Add Rule → Remote Rule (GitHub):

    https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-skill/skills/design-data
    

    Update the plugin

    Plugins do not update themselves. After a new release, update by hand and start a new session (Claude Code needs a restart):

    • Copilot app: Customize → Installed → the plugin's menu → Update, or Update all.
    • Copilot CLI: copilot plugin marketplace update spectrum-design-data, then copilot plugin update spectrum-design-data@spectrum-design-data. A copy installed from the Design AI Marketplace uses @design-marketplace instead.
    • Claude Code: claude plugin marketplace update spectrum-design-data, then claude plugin update spectrum-design-data@spectrum-design-data.

    Data and limits

    The tools are read-only. The data is the public @adobe/spectrum-design-data snapshot embedded in the installed MCP release; the primer's provenance.designDataVersion shows which. It updates when you install a newer release, not automatically, and the primer makes a best-effort check for a newer one when online. Guidelines are an imported copy of public Spectrum site content and may lag it. Validating, diffing, and authoring custom datasets are handled by design-data-agent, not this plugin.

    Other AI resources

    • llms.txt, at the repo root: llms.txt describes the project layout, design tokens, component schemas, and common tasks for LLMs.
    • Generated markdown: the docs/markdown/ directory holds auto-generated markdown for tokens, component schemas, and the design-system registry, used for docs site chatbot indexing. Regenerate with moon run markdown-generator:generate.

    See also: React Spectrum: Using AI for React Spectrum's own AI integration (S2 component implementation docs, icons, illustrations).