@adobe/design-data-skill 1.3.2 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,10 @@
1
1
  {
2
- "name": "design-data",
3
- "description": "Spectrum design tokens, component schemas, and design-system insights for Claude Code.",
4
- "author": { "name": "Adobe" },
2
+ "name": "spectrum-design-data",
3
+ "version": "2.0.1",
4
+ "description": "Read-only Spectrum lookup: find official design tokens, inspect component options, resolve values across modes, and read design guidelines. Bundles the @adobe/design-data-mcp server.",
5
+ "author": {
6
+ "name": "Adobe"
7
+ },
5
8
  "homepage": "https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-skill",
6
9
  "repository": "https://github.com/adobe/spectrum-design-data",
7
10
  "license": "Apache-2.0"
package/.mcp.json ADDED
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "design-data": {
4
+ "command": "npx",
5
+ "args": ["-y", "@adobe/design-data-mcp@1.10.2"]
6
+ }
7
+ }
8
+ }
package/README.md CHANGED
@@ -1,39 +1,55 @@
1
- # design-data Claude Code Skill
1
+ # spectrum-design-data Plugin
2
2
 
3
- A Claude Code plugin that gives agents access to Spectrum design tokens,
4
- component schemas, and design-system data via the `@adobe/design-data` CLI.
3
+ A read-only Spectrum lookup plugin for AI assistants. It bundles the `design-data`
4
+ skill and the [`@adobe/design-data-mcp`](https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-mcp)
5
+ server, so installing it gives the assistant working tools with no extra setup.
5
6
 
6
- Also published on npm as `@adobe/design-data-skill` for versioned skill installs.
7
+ It finds official tokens, inspects component options, resolves token values across
8
+ modes, and reads Spectrum design guidelines. It complements React Spectrum and
9
+ Spectrum Web Components implementation guidance; it does not generate components
10
+ or integrate with a framework.
11
+
12
+ Also published on npm as `@adobe/design-data-skill` for versioned installs.
7
13
 
8
14
  ## Structure
9
15
 
10
16
  ```
11
17
  tools/design-data-skill/
12
- .claude-plugin/plugin.json Plugin manifest (name, description, version)
18
+ .claude-plugin/plugin.json Plugin manifest
19
+ .mcp.json MCP server, pinned to an exact @adobe/design-data-mcp version
20
+ skills/design-data/SKILL.md Skill instructions
13
21
  package.json npm package (@adobe/design-data-skill)
14
- skills/design-data/SKILL.md Skill definition (frontmatter + workflow docs)
15
22
  README.md This file
16
23
  ```
17
24
 
18
- This is a pure-skills plugin with no build step or Node.js runtime dependencies.
19
- It wraps the external `@adobe/design-data` CLI that `npx` installs on first use.
20
-
21
25
  ## Installation
22
26
 
23
27
  ### Claude Code
24
28
 
25
- Add the marketplace, then install the Spectrum skill:
26
-
27
29
  ```
28
30
  /plugin marketplace add adobe/spectrum-design-data
29
- /plugin install design-data@spectrum-design-data
31
+ /plugin install spectrum-design-data@spectrum-design-data
30
32
  ```
31
33
 
32
- For custom or repo-local datasets (validate, diff, write), install
33
- `design-data-agent@spectrum-design-data` instead — see
34
- [`tools/design-data-agent-mcp/`](../design-data-agent-mcp/).
34
+ ### GitHub Copilot CLI
35
35
 
36
- ### Cursor
36
+ ```
37
+ copilot plugin marketplace add adobe/spectrum-design-data
38
+ copilot plugin install spectrum-design-data@spectrum-design-data
39
+ ```
40
+
41
+ Copilot should not prompt for this plugin's tools: all eight are read-only and
42
+ declare it. If a client or setting still asks for approval, you can pre-approve
43
+ the server by name (`design-data`, from the plugin's `.mcp.json`):
44
+
45
+ ```
46
+ copilot --allow-tool='design-data'
47
+ ```
48
+
49
+ Use `--deny-tool='design-data'` to block it. Skill frontmatter (`allowed-tools`)
50
+ does not pre-approve MCP tools in Copilot CLI 1.0.109 (tested non-interactively).
51
+
52
+ ### Cursor (skill only)
37
53
 
38
54
  Cursor Settings → Rules → **Add Rule** → **Remote Rule (GitHub)** → paste:
39
55
 
@@ -41,9 +57,68 @@ Cursor Settings → Rules → **Add Rule** → **Remote Rule (GitHub)** → past
41
57
  https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-skill/skills/design-data
42
58
  ```
43
59
 
44
- For always-available MCP tool access, see [`@adobe/design-data-mcp`](../design-data-mcp/).
60
+ This installs only the skill. Add the MCP server to `.cursor/mcp.json` yourself:
61
+
62
+ ```json
63
+ {
64
+ "mcpServers": {
65
+ "design-data": {
66
+ "command": "npx",
67
+ "args": ["-y", "@adobe/design-data-mcp@1.10.2"]
68
+ }
69
+ }
70
+ }
71
+ ```
72
+
73
+ ## What the plugin includes
74
+
75
+ * **Skill + MCP server.** The plugin registers the MCP server itself (`.mcp.json`);
76
+ no manual MCP configuration is needed. Because it is an MCP server, the client
77
+ may load all eight tool definitions each session. This differs from a
78
+ skill-only install, which costs only the skill description until used.
79
+ * **Runtime:** Node.js `>=20.12.0`.
80
+ * **npm install size:** `@adobe/design-data-skill` depends on `@adobe/design-data-mcp`
81
+ (and its embedded dataset), so `npm i @adobe/design-data-skill` installs both. A
82
+ plugin install from the marketplace does not use npm for the skill.
83
+ * **Network:** the first run downloads `@adobe/design-data-mcp` with `npx`
84
+ (pinned to the exact version above). Lookups then use the Spectrum snapshot
85
+ embedded in that package. The primer also makes a best-effort registry check for
86
+ a newer data version and stays silent if offline; set
87
+ `DESIGN_DATA_SKIP_VERSION_CHECK=1` to disable it.
88
+ * **Tools:** `design-data-primer`, `design-data-query`, `design-data-suggest`,
89
+ `design-data-component`, `design-data-component-search`, `design-data-resolve`,
90
+ `design-data-guideline-list`, `design-data-guideline`. Inputs are documented in
91
+ [SKILL.md](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/skills/design-data/SKILL.md).
92
+
93
+ ## Data and freshness
94
+
95
+ The data is the public `@adobe/spectrum-design-data` snapshot baked into the pinned
96
+ MCP release (`provenance.designDataVersion` in the primer shows which). It is
97
+ updated by releasing a new MCP version and bumping the pin, not automatically.
98
+ Guidelines are imported from public Spectrum site content and may lag it. The
99
+ plugin is read-only.
100
+
101
+ ## Not included
102
+
103
+ Custom datasets, validation, diffing, and authoring: use
104
+ [`design-data-agent`](https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-mcp)
105
+ (`design-data-agent@spectrum-design-data`).
106
+
107
+ ## Maintenance
108
+
109
+ `moon run :version` (after `changeset version`) syncs the pinned MCP version and the
110
+ plugin version. Tests check the pin, manifest, tool names, and packed contents. The pin comes from the
111
+ workspace version, so between merging the Version Packages PR and the npm publish the
112
+ pinned release may not exist yet; installs from `main` fail in that window.
113
+
114
+ To test on Copilot, install the plugin (`copilot plugin marketplace add <path>`, then
115
+ `copilot plugin install spectrum-design-data@spectrum-design-data`).
116
+ `copilot --plugin-dir <dir>` does not load the bundled MCP server. Keep
117
+ `readOnlyHint: true` on every tool in `design-data-mcp`: it is why Copilot runs them
118
+ without approval, and removing it makes non-interactive runs fail with "no interactive
119
+ user response was available".
45
120
 
46
121
  ## Usage
47
122
 
48
- See [`skills/design-data/SKILL.md`](skills/design-data/SKILL.md) for the
49
- full command reference and workflow.
123
+ See [SKILL.md](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/skills/design-data/SKILL.md)
124
+ for the tool reference and workflow.
package/llms.txt CHANGED
@@ -1,11 +1,17 @@
1
1
  # @adobe/design-data-skill
2
2
 
3
- > Claude Code skill for Spectrum design tokens and component schemas via the design-data CLI
3
+ > Read-only Spectrum design-data lookup plugin: a skill plus the bundled @adobe/design-data-mcp server
4
4
 
5
- A Claude Code plugin that gives agents access to Spectrum design tokens,
6
- component schemas, and design-system data via the `@adobe/design-data` CLI.
5
+ A read-only Spectrum lookup plugin for AI assistants. It bundles the `design-data`
6
+ skill and the [`@adobe/design-data-mcp`](https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-mcp)
7
+ server, so installing it gives the assistant working tools with no extra setup.
7
8
 
8
- Also published on npm as `@adobe/design-data-skill` for versioned skill installs.
9
+ It finds official tokens, inspects component options, resolves token values across
10
+ modes, and reads Spectrum design guidelines. It complements React Spectrum and
11
+ Spectrum Web Components implementation guidance; it does not generate components
12
+ or integrate with a framework.
13
+
14
+ Also published on npm as `@adobe/design-data-skill` for versioned installs.
9
15
 
10
16
  ## Install
11
17
 
@@ -16,6 +22,10 @@ Also published on npm as `@adobe/design-data-skill` for versioned skill installs
16
22
  - [README](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md): usage and API overview
17
23
  - [Structure](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md#structure)
18
24
  - [Installation](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md#installation)
25
+ - [What the plugin includes](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md#what-the-plugin-includes)
26
+ - [Data and freshness](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md#data-and-freshness)
27
+ - [Not included](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md#not-included)
28
+ - [Maintenance](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md#maintenance)
19
29
  - [Usage](https://github.com/adobe/spectrum-design-data/blob/main/tools/design-data-skill/README.md#usage)
20
30
  - [Repository index](https://github.com/adobe/spectrum-design-data/blob/main/docs/repo-index.md): how this package fits in the repository
21
31
 
package/package.json CHANGED
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "name": "@adobe/design-data-skill",
3
- "version": "1.3.2",
4
- "description": "Claude Code skill for Spectrum design tokens and component schemas via the design-data CLI",
3
+ "version": "2.0.1",
4
+ "description": "Read-only Spectrum design-data lookup plugin: a skill plus the bundled @adobe/design-data-mcp server",
5
5
  "type": "module",
6
6
  "files": [
7
7
  "skills/",
8
8
  ".claude-plugin/",
9
+ ".mcp.json",
9
10
  "llms.txt",
10
11
  "README.md",
11
12
  "LICENSE"
@@ -32,6 +33,9 @@
32
33
  "design-tokens",
33
34
  "design-data"
34
35
  ],
36
+ "dependencies": {
37
+ "@adobe/design-data-mcp": "1.10.2"
38
+ },
35
39
  "devDependencies": {
36
40
  "ava": "^6.0.1"
37
41
  },
@@ -3,132 +3,123 @@ name: design-data
3
3
  description: >
4
4
  Look up Spectrum design tokens, component schemas, and design-system decisions
5
5
  when building with or extending Adobe Spectrum. Use when the user asks about
6
- token values, component options, naming conventions, or wants to
7
- validate/explore design-token data. Also triggers when a .design-data.toml
8
- config is involved or the user mentions the design-data CLI.
6
+ token values, component options, naming conventions, or Spectrum design
7
+ guidelines. Read-only lookup against an embedded Spectrum
8
+ snapshot; it does not generate component code.
9
9
  metadata:
10
10
  author: adobe
11
- version: "1.3.2"
12
- designDataVersion: "3.5.0"
11
+ version: "2.0.1"
12
+ designDataVersion: "3.11.2"
13
13
  when_to_use: >
14
14
  Trigger on: token names (color, spacing, typography, dimension), "which token",
15
- "Spectrum component options", validate tokens, design-data primer, query tokens,
16
- suggest token, resolve token value, component schema, design system config,
17
- @adobe/design-data, design-data CLI.
18
- allowed-tools: mcp__design-data__design-data-primer, mcp__design-data__design-data-query, mcp__design-data__design-data-suggest, mcp__design-data__design-data-component, mcp__design-data__design-data-resolve
15
+ "Spectrum component options", design-data primer, query tokens, suggest token,
16
+ resolve token value, component schema, Spectrum guideline, @adobe/design-data-mcp.
17
+ allowed-tools: mcp__plugin_spectrum-design-data_design-data__design-data-primer, mcp__plugin_spectrum-design-data_design-data__design-data-query, mcp__plugin_spectrum-design-data_design-data__design-data-suggest, mcp__plugin_spectrum-design-data_design-data__design-data-component, mcp__plugin_spectrum-design-data_design-data__design-data-component-search, mcp__plugin_spectrum-design-data_design-data__design-data-resolve, mcp__plugin_spectrum-design-data_design-data__design-data-guideline-list, mcp__plugin_spectrum-design-data_design-data__design-data-guideline
19
18
  ---
20
19
 
21
20
  # Spectrum Design Data
22
21
 
23
- Access Spectrum design tokens, component schemas, and design-system structure
24
- via the `@adobe/design-data-mcp` MCP server (in-process wasm — no CLI binary required).
22
+ Read-only lookup of Spectrum design tokens, component schemas, and design
23
+ guidelines through the `@adobe/design-data-mcp` MCP server. The server runs
24
+ in-process against a Spectrum snapshot embedded in the package.
25
25
 
26
- ## Bootstrap
26
+ This skill complements React Spectrum and Spectrum Web Components guidance. It
27
+ answers from data; it does not generate components or integrate with a framework.
27
28
 
28
- Add `@adobe/design-data-mcp` to your project's `.cursor/mcp.json` (or equivalent
29
- MCP config) to activate the tools:
29
+ ## Setup
30
+
31
+ Installing the `spectrum-design-data` **plugin** (Claude Code or GitHub Copilot) registers
32
+ the MCP server for you: no manual MCP configuration. Requires Node.js `>=20.12.0`.
33
+ The first run downloads the pinned package with `npx`; after that, lookups use the
34
+ embedded snapshot.
35
+
36
+ If you installed only this skill folder (for example as a Cursor rule), the tools
37
+ are not available until you add the server yourself, pinned to the version this
38
+ skill was written for:
30
39
 
31
40
  ```json
32
41
  {
33
42
  "mcpServers": {
34
43
  "design-data": {
35
44
  "command": "npx",
36
- "args": ["-y", "@adobe/design-data-mcp"]
45
+ "args": ["-y", "@adobe/design-data-mcp@1.10.2"]
37
46
  }
38
47
  }
39
48
  }
40
49
  ```
41
50
 
42
- The server uses an embedded Spectrum snapshot — no environment variables or
43
- dataset path configuration required for read operations.
51
+ ## Tool names
52
+
53
+ Tools are listed below by their server names. Clients prefix them: Claude Code
54
+ exposes the plugin's tools as `mcp__plugin_spectrum-design-data_design-data__<tool>`, and a
55
+ manually configured server as `mcp__design-data__<tool>`. Use whichever the client
56
+ lists.
44
57
 
45
58
  ## Tools
46
59
 
47
60
  ### `design-data-primer`
48
61
 
49
- Get a structural overview of the embedded Spectrum dataset: token count,
50
- available mode-sets (color-scheme, scale, contrast), component list, taxonomy
51
- fields, and data provenance. **Call this at the start of a design-token session.**
52
-
53
- No required inputs.
62
+ Overview of the embedded dataset: token count, mode-sets, component list, taxonomy
63
+ fields, guidelines, and provenance (`provenance.designDataVersion` is the snapshot
64
+ version). **Call this first in a session.** No required inputs.
54
65
 
55
66
  ### `design-data-query`
56
67
 
57
- Filter Spectrum tokens by a query expression. Returns an array of matching token objects.
58
-
59
- Required input: `filter` (string)
60
-
61
- Expression syntax examples:
62
-
63
- * `"component=button"` — all button tokens
64
- * `"component=button,state=hover"` — button hover tokens
65
- * `"property=color-*"` — all color property tokens
66
- * `"colorScheme=dark"` — dark-scheme tokens
67
-
68
- Returns an empty array when no tokens match.
68
+ Filter tokens by expression. Required: `filter` (string), e.g. `component=button`,
69
+ `component=button,state=hover`, `property=*color*`, `state=hover,colorScheme=dark`.
70
+ Filterable fields: `property`, `component`, `variant`, `state`, `colorScheme`, `scale`,
71
+ `contrast`, `uuid`. `component` matches the tokens a component's relationships bind to.
72
+ Returns an array of matching tokens (empty when none match).
69
73
 
70
74
  ### `design-data-suggest`
71
75
 
72
- Suggest Spectrum tokens matching a natural-language intent using keyword-overlap
73
- scoring. Returns matches ranked by confidence.
74
-
75
- Required input: `intent` (string) — e.g. `"primary CTA button background color"`
76
- Optional input: `limit` (number, default 5)
76
+ Rank tokens against a natural-language intent. Required: `intent` (string), e.g.
77
+ `"primary CTA button background color"`. Optional: `limit` (number, default 5).
77
78
 
78
79
  ### `design-data-component`
79
80
 
80
- Get the full component declaration for a Spectrum component by ID. Returns the
81
- component's displayName, description, and all available options (variants, sizes,
82
- states, boolean props, etc.).
81
+ Full component declaration (displayName, description, options such as variants,
82
+ sizes, states, booleans). Required: `id` (kebab-case, e.g. `action-button`).
83
83
 
84
- Required input: `id` (string) — kebab-case component ID, e.g. `button`, `action-button`
84
+ ### `design-data-component-search`
85
85
 
86
- Call `design-data-primer` first to see available component IDs.
86
+ Find components by name, description, or docs text. Required: `query` (string).
87
+ Optional: `category` (string), `limit` (integer, default 10). Returns id,
88
+ displayName, category, and a snippet; pass the id to `design-data-component`.
87
89
 
88
90
  ### `design-data-resolve`
89
91
 
90
- Resolve the concrete value of a Spectrum token property for a given mode-set context.
91
- Returns the winning token with its resolved value.
92
-
93
- Required input: `property` (string) — token property name, e.g. `background-color-default`
94
- Optional inputs: `colorScheme` (`"light"` or `"dark"`), `scale` (`"desktop"` or `"mobile"`),
95
- `contrast` (`"regular"` or `"high"`)
96
-
97
- ## Workflow
92
+ Resolve a token property to its value for a mode context. Required: `property`
93
+ (string, e.g. `corner-radius`). Optional: `colorScheme` (`light`/`dark`),
94
+ `scale` (`desktop`/`mobile`), `contrast` (`regular`/`high`), and narrowing by
95
+ `component`, `variant`, `state`, `colorRole`, or `excludeDeprecated`. Errors when no
96
+ token matches. Active tokens rank above deprecated ones. Ambiguity can still occur:
97
+ when `ambiguous: true`, the `token` is only the top pick; narrow further or report the
98
+ `alternatives` instead of presenting one value as definitive.
98
99
 
99
- 1. **Start with `design-data-primer`** to understand what data is available.
100
- 2. **Use `design-data-query`** when you know the component/property/state.
101
- 3. **Use `design-data-suggest`** when the user describes an intent in natural language.
102
- 4. **Use `design-data-component`** to check all available options for a specific component.
103
- 5. **Use `design-data-resolve`** to get the concrete value for a token in a given context.
100
+ ### `design-data-guideline-list` and `design-data-guideline`
104
101
 
105
- ## When working in Cursor
102
+ `design-data-guideline-list` lists guideline pages (optional `category`:
103
+ `designing`, `fundamentals`, `developing`, `support`). `design-data-guideline`
104
+ returns one page by `id`, the `slug` from the list (e.g. `colors`).
106
105
 
107
- Install this skill as a **Remote Rule (GitHub)** — same pattern as the s2-docs skill:
108
-
109
- Cursor Settings → Rules → **Add Rule** → **Remote Rule (GitHub)** → paste:
110
-
111
- ```
112
- https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-skill/skills/design-data
113
- ```
114
-
115
- For always-available tool access (higher context cost), add the MCP server to
116
- `.cursor/mcp.json` as shown in the Bootstrap section above.
117
-
118
- For custom datasets with validate/diff/write, use the `design-data-agent` skill or
119
- `@adobe/design-data-agent-mcp` instead — see
120
- [`tools/design-data-agent-mcp/skills/design-data/SKILL.md`](../../design-data-agent-mcp/skills/design-data/SKILL.md).
121
-
122
- ## Using a custom dataset
123
-
124
- To point at a specific Spectrum version or a custom design-data fork, add
125
- a `.design-data.toml` to your project root:
126
-
127
- ```toml
128
- [source]
129
- type = "github"
130
- repo = "adobe/spectrum-design-data"
131
- tag = "@adobe/spectrum-tokens@14.11.0"
132
- ```
106
+ ## Workflow
133
107
 
134
- Without a config file, the embedded Spectrum snapshot is used automatically.
108
+ 1. `design-data-primer` to see what data exists.
109
+ 2. `design-data-query` when you know the property, component, or state.
110
+ 3. `design-data-suggest` when the user describes an intent.
111
+ 4. `design-data-component-search`, then `design-data-component`, for component options.
112
+ 5. `design-data-resolve` for a concrete value in a given mode.
113
+ 6. `design-data-guideline-list`, then `design-data-guideline`, for design guidance.
114
+
115
+ ## Limits
116
+
117
+ * Read-only; nothing is written or validated.
118
+ * Answers reflect the embedded snapshot, not the live Spectrum site. Report
119
+ `provenance.designDataVersion` when the version matters. The primer makes a
120
+ best-effort registry check and adds `provenance.datasetStatus` when a newer data
121
+ package exists (set `DESIGN_DATA_SKIP_VERSION_CHECK=1` to disable it).
122
+ * Guidelines are an imported copy of public Spectrum site content and may lag it.
123
+ * Custom datasets, validation, diffing, and authoring are out of scope; use the
124
+ `design-data-agent` skill from the
125
+ [spectrum-design-data repository](https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-mcp).