@adobe/design-data-spec 3.2.0 → 3.3.0
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.
- package/package.json +1 -1
- package/schemas/manifest.schema.json +16 -0
- package/spec/agent-surface.md +14 -14
- package/spec/authoring-workflow.md +20 -20
- package/spec/dataset-layout.md +1 -1
package/package.json
CHANGED
|
@@ -87,6 +87,22 @@
|
|
|
87
87
|
"type": "object",
|
|
88
88
|
"description": "Platform-local tokens, mode sets, and formatting rules.",
|
|
89
89
|
"properties": {
|
|
90
|
+
"tokens": {
|
|
91
|
+
"$ref": "cascade-file.schema.json",
|
|
92
|
+
"description": "Platform-local token definitions, in cascade-format (same shape as a cascade token file)."
|
|
93
|
+
},
|
|
94
|
+
"components": {
|
|
95
|
+
"type": "array",
|
|
96
|
+
"items": { "$ref": "component.schema.json" },
|
|
97
|
+
"description": "Platform-local component specs, injected into the component catalog (add-or-replace by name)."
|
|
98
|
+
},
|
|
99
|
+
"platformExtensions": {
|
|
100
|
+
"type": "array",
|
|
101
|
+
"items": {
|
|
102
|
+
"$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/platform-extension.json"
|
|
103
|
+
},
|
|
104
|
+
"description": "Platform-local terminology extensions (e.g. iOS state vocabulary), annotating ids in an existing base registry."
|
|
105
|
+
},
|
|
90
106
|
"formatting": {
|
|
91
107
|
"type": "object",
|
|
92
108
|
"description": "Rules for serializing structured name objects into platform-specific token name strings.",
|
package/spec/agent-surface.md
CHANGED
|
@@ -25,19 +25,19 @@ The surface targets three consumer shapes:
|
|
|
25
25
|
|
|
26
26
|
**NORMATIVE:** A conforming implementation MUST expose the following operations. Transport-specific naming (CLI subcommand vs MCP tool name vs skill action) MAY differ; the semantics MUST NOT.
|
|
27
27
|
|
|
28
|
-
| Operation | Reads | Returns
|
|
29
|
-
| -------------------- | ------------------------------------------------------ |
|
|
30
|
-
| `resolve_token` | property + mode set context | winning token (literal or resolved alias) with file/UUID/specificity
|
|
31
|
-
| `query_tokens` | filter expression (see [Query](query.md)) | matching token list
|
|
32
|
-
| `validate_usage` | candidate token document or fragment | `ValidationReport` (Layer 1 + Layer 2 diagnostics)
|
|
33
|
-
| `describe_component` | component identifier | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape)
|
|
34
|
-
| `suggest_token` | natural-language intent + optional property hint | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1)
|
|
35
|
-
| `get_guidance` | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D
|
|
36
|
-
| `diff_datasets` | two dataset roots | `DiffReport` per [Diff](diff.md)
|
|
37
|
-
| `write_token` | token object + optional rationale string | updated
|
|
38
|
-
| `write_component` | component object + optional rationale string | updated dataset-root component file (RECOMMENDED, not NORMATIVE in v1; scheduled to become MUST — see [Scheduled promotion](authoring-workflow.md#scheduled-promotion))
|
|
39
|
-
|
|
40
|
-
**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, `diff_datasets`, and `
|
|
28
|
+
| Operation | Reads | Returns | Backed by |
|
|
29
|
+
| -------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| `resolve_token` | property + mode set context | winning token (literal or resolved alias) with file/UUID/specificity | `cascade::resolve` |
|
|
31
|
+
| `query_tokens` | filter expression (see [Query](query.md)) | matching token list | `query::filter` |
|
|
32
|
+
| `validate_usage` | candidate token document or fragment | `ValidationReport` (Layer 1 + Layer 2 diagnostics) | `validate::validate_*` |
|
|
33
|
+
| `describe_component` | component identifier | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract) |
|
|
34
|
+
| `suggest_token` | natural-language intent + optional property hint | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1) | registry + query |
|
|
35
|
+
| `get_guidance` | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D | document blocks |
|
|
36
|
+
| `diff_datasets` | two dataset roots | `DiffReport` per [Diff](diff.md) | `diff::semantic_diff` |
|
|
37
|
+
| `write_token` | token object + optional rationale string | updated dataset-root token file + `product-context.json` (**NORMATIVE** — MUST, promoted with the Phase B foundation-corpus write target; see [Scheduled promotion](authoring-workflow.md#scheduled-promotion)) | `write::write_token` — shipped: `design-data write-token` (CLI) / `authoring_session_commit` (MCP) |
|
|
38
|
+
| `write_component` | component object + optional rationale string | updated dataset-root component file (RECOMMENDED, not NORMATIVE in v1; scheduled to become MUST — see [Scheduled promotion](authoring-workflow.md#scheduled-promotion)) | `write::write_component` — Phase B scheduled; not yet implemented |
|
|
39
|
+
|
|
40
|
+
**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, `diff_datasets`, `describe_component`, and `write_token` MUST be implemented in a conforming agent surface. `suggest_token`, `get_guidance`, and `write_component` are RECOMMENDED. `write_token` was promoted to MUST now that the Phase B foundation-corpus write target has shipped; `write_component` remains RECOMMENDED pending component authoring support — see [Authoring workflow — Scheduled promotion](authoring-workflow.md#scheduled-promotion).
|
|
41
41
|
|
|
42
42
|
**RECOMMENDED:** When `write_token` or `write_component` is invoked, the implementation SHOULD capture a `rationale` argument from the agent session context and record it in both the token's inline `rationale` field and the product context document's `overrides[].rationale` or `extensions.tokens[].rationale`. See [Product context — Agent capture behavior](product-context.md#agent-capture-behavior).
|
|
43
43
|
|
|
@@ -66,7 +66,7 @@ An agent loop benefits from a small, structural overview at session start so tha
|
|
|
66
66
|
|
|
67
67
|
### CLI
|
|
68
68
|
|
|
69
|
-
The reference CLI is `design-data` (see [`sdk/cli/`](../../../sdk/cli/)). RFC-C extends the existing subcommands (`validate`, `resolve`, `diff`, `query`) with:
|
|
69
|
+
The reference CLI is `design-data` (see [`sdk/cli/`](../../../sdk/cli/)). Install it via Homebrew (macOS), `cargo install design-data-cli`, or a [GitHub Release download](https://github.com/adobe/spectrum-design-data/releases) — see the [`sdk/cli/` README](../../../sdk/cli/README.md#install). RFC-C extends the existing subcommands (`validate`, `resolve`, `diff`, `query`) with:
|
|
70
70
|
|
|
71
71
|
* `design-data primer [PATH]` — emit the [Session primer](#session-primer) payload.
|
|
72
72
|
* `design-data suggest "<intent>" [--property <hint>]` — invoke `suggest_token`.
|
|
@@ -35,20 +35,20 @@ Per [Evolution — Legacy format contract](evolution.md#legacy-format-contract),
|
|
|
35
35
|
|
|
36
36
|
The following tools constitute the normative authoring surface:
|
|
37
37
|
|
|
38
|
-
| Tool | Form
|
|
39
|
-
| -------------------------- |
|
|
40
|
-
| `design-data` CLI | `design-data write-token`
|
|
41
|
-
| `design-data-tui` | interactive token naming + creation wizard
|
|
42
|
-
| MCP authoring session | `start_authoring_session` / `authoring_session_commit` tools | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973))
|
|
43
|
-
| Design Data management app | future browser-based tool
|
|
38
|
+
| Tool | Form | Status | Scope |
|
|
39
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
40
|
+
| `design-data` CLI | `design-data write-token` + cascade mutation/mode-set subcommands (edit/deprecate/rename/alias-rewire/remove, add-mode/rename-mode/remove-mode/create-mode-set/remove-mode-set) | Shipped — cascade foundation-corpus token + mode-set authoring (Phase B, epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122)) | Component/field/registry authoring not yet shipped — see [Per-category authoring contracts](#per-category-authoring-contracts) |
|
|
41
|
+
| `design-data-tui` | interactive token naming + creation wizard | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)); writes cascade `*.tokens.json` directly (Phase B) | Component/field/registry authoring not yet shipped |
|
|
42
|
+
| MCP authoring session | `start_authoring_session` / `authoring_session_commit` tools, plus `edit_token`/`deprecate_token`/`rename_token`/`rewire_alias`/`remove_token`/mode-set tools | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)); writes cascade `*.tokens.json` directly (Phase B) | Component/field/registry authoring not yet shipped |
|
|
43
|
+
| Design Data management app | future browser-based tool | Not yet shipped | Full CRUD across all categories |
|
|
44
44
|
|
|
45
45
|
**RECOMMENDED:** Authors SHOULD use the TUI or MCP authoring session rather than editing cascade JSON files directly. Tooling enforces UUID uniqueness, name-object field decomposition, and referential integrity that is difficult to maintain manually.
|
|
46
46
|
|
|
47
47
|
### Scheduled promotion {#scheduled-promotion}
|
|
48
48
|
|
|
49
|
-
The
|
|
49
|
+
The CLI/TUI/MCP write path now targets the foundation Spectrum corpus (`packages/design-data/tokens/*.tokens.json`, via `design_data_core::write::cascade_target_filename`) rather than the legacy product-layer files (`foundation.json`, `platform.json`, `product.json`). This redirect was **Phase B** work and has shipped (epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122), closed).
|
|
50
50
|
|
|
51
|
-
**NORMATIVE:**
|
|
51
|
+
**NORMATIVE:** All authoring tools described above MUST write to the dataset root, not to legacy layer files. The `write_token` operation in [Agent-readable surface](agent-surface.md) is now **required** (MUST) for the foundation-corpus write target; `write_component` remains RECOMMENDED pending component authoring support (not yet shipped — see [Per-category authoring contracts](#per-category-authoring-contracts)). The promotion is tracked in RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625). This mirrors the SPEC-017 escalation precedent in [Token format](token-format.md#string-name-escape-hatch--spec-017-severity-schedule).
|
|
52
52
|
|
|
53
53
|
## Lifecycle operations
|
|
54
54
|
|
|
@@ -78,14 +78,14 @@ The following table defines the **target token-authoring contract**: the complet
|
|
|
78
78
|
|
|
79
79
|
The following per-category contracts specify what the authoring surface authors in each registered directory and which validation rules gate the output. Detailed authoring workflows per category are specified in separate subsections of this document as Phase A work progresses.
|
|
80
80
|
|
|
81
|
-
| Category | Directory | Authoring status
|
|
82
|
-
| ---------- | ------------- |
|
|
83
|
-
| Tokens | `tokens/` | Shipped
|
|
84
|
-
| Components | `components/` | Not yet shipped (`write_component` deferred — [Agent surface](agent-surface.md))
|
|
85
|
-
| Fields | `fields/` | Not yet shipped
|
|
86
|
-
| Mode sets | `mode-sets/` |
|
|
87
|
-
| Guidelines | `guidelines/` | Not yet shipped
|
|
88
|
-
| Registry | `registry/` | Not yet shipped (vocabulary is hand-maintained)
|
|
81
|
+
| Category | Directory | Authoring status | Validation gate |
|
|
82
|
+
| ---------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
|
|
83
|
+
| Tokens | `tokens/` | Shipped — create, edit, deprecate, rename, alias-rewire, remove (Phase B, epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122)) | SPEC-001–017, SPEC-041, SPEC-042, SPEC-043 |
|
|
84
|
+
| Components | `components/` | Not yet shipped (`write_component` deferred — [Agent surface](agent-surface.md)) | SPEC-018–040 |
|
|
85
|
+
| Fields | `fields/` | Not yet shipped | SPEC-042, SPEC-043 |
|
|
86
|
+
| Mode sets | `mode-sets/` | Shipped — add/rename/remove-mode, create/remove-mode-set (Phase B, epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122)) | SPEC-005, SPEC-008, SPEC-041 |
|
|
87
|
+
| Guidelines | `guidelines/` | Not yet shipped as a manual authoring surface; generated via extended transformer (Phase 10, beads `ek4`) | SPEC-045, SPEC-046 |
|
|
88
|
+
| Registry | `registry/` | Not yet shipped (vocabulary is hand-maintained) | SPEC-033, SPEC-034, SPEC-035 |
|
|
89
89
|
|
|
90
90
|
### Token authoring contract
|
|
91
91
|
|
|
@@ -106,9 +106,9 @@ Tokens are authored in `tokens/**/*.tokens.json`. Files may be nested arbitraril
|
|
|
106
106
|
**Validation gate:** SPEC-001–017 (name, value, lifecycle, tech-debt), SPEC-041 (mode-set
|
|
107
107
|
conformance), SPEC-042 (field-scope), SPEC-043 (domain-required-fields).
|
|
108
108
|
|
|
109
|
-
**Edit and lifecycle operations (Phase B):** Edit, deprecate, rename, alias-rewire, mode-set
|
|
109
|
+
**Edit and lifecycle operations (Phase B, shipped):** Edit, deprecate, rename, alias-rewire, mode-set
|
|
110
110
|
management, and remove are specified in [Lifecycle operations](#lifecycle-operations) and are
|
|
111
|
-
implemented
|
|
111
|
+
implemented (epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122), closed).
|
|
112
112
|
|
|
113
113
|
***
|
|
114
114
|
|
|
@@ -134,8 +134,8 @@ be named with the component's `name` field value (e.g. `button.json` for `name:
|
|
|
134
134
|
cross-references), SPEC-034 (category registry sync), SPEC-035 (anatomy-term registry sync),
|
|
135
135
|
SPEC-038–040 (lifecycle, display name, schema).
|
|
136
136
|
|
|
137
|
-
**Authoring status:** Not yet shipped — `write_component`
|
|
138
|
-
[Scheduled promotion](#scheduled-promotion)).
|
|
137
|
+
**Authoring status:** Not yet shipped — `write_component` was out of scope for Phase B (tokens and
|
|
138
|
+
mode-sets only; see [Scheduled promotion](#scheduled-promotion)) and remains unscheduled.
|
|
139
139
|
|
|
140
140
|
***
|
|
141
141
|
|
package/spec/dataset-layout.md
CHANGED
|
@@ -43,7 +43,7 @@ A dataset is rooted at a single **dataset root** directory. The following table
|
|
|
43
43
|
Tooling that operates on "the current dataset" (rather than an explicit path) **MUST** resolve the dataset root using the following precedence. The first match wins; later tiers are only consulted when an earlier tier does not resolve a value.
|
|
44
44
|
|
|
45
45
|
1. **Explicit override** — a path passed directly by the caller (CLI positional argument or `--*-path` flag, environment variable). Explicit overrides always win.
|
|
46
|
-
2. **Config file** — a `.design-data.toml` discovered by walking **up** the ancestor chain from the working directory. A `[source]` block
|
|
46
|
+
2. **Config file** — a `.design-data.toml` discovered by walking **up** the ancestor chain from the working directory. A `[source]` block names where the foundation dataset comes from: `type = "path"` (a dataset root resolved relative to the config file's directory) or `type = "github"` (a repo pinned by exactly one of `tag`, `branch`, or `sha`, fetched as a release tarball over HTTPS). An optional **top-level** `manifest` key (source-independent, resolved relative to the config file) points at a Layer 2 platform `manifest.json` that cascades on top of whichever source is used. This is the explicit, portable way to point a project at a dataset outside its own tree.
|
|
47
47
|
3. **In-repo probing** — when running inside a monorepo checkout, probe for the standard layout relative to the working directory (`packages/design-data/tokens` and one level up). This preserves the in-repo workflow with zero configuration.
|
|
48
48
|
4. **Embedded snapshot** — when no dataset is found on disk, tooling MAY fall back to a snapshot of the foundation dataset embedded in the binary, materialized to a local cache directory.
|
|
49
49
|
|