@adobe/design-data-spec 4.2.0 → 4.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/component.schema.json +46 -0
- package/spec/agent-surface.md +3 -1
- package/spec/component-format.md +42 -13
package/package.json
CHANGED
|
@@ -37,6 +37,13 @@
|
|
|
37
37
|
"meta": {
|
|
38
38
|
"$ref": "#/$defs/meta"
|
|
39
39
|
},
|
|
40
|
+
"implementations": {
|
|
41
|
+
"type": "array",
|
|
42
|
+
"items": {
|
|
43
|
+
"$ref": "#/$defs/implementation"
|
|
44
|
+
},
|
|
45
|
+
"description": "Known platform implementations of this component. Foundation-owned canonical mappings; platform-specific overrides are not supported yet. See spec/component-format.md#implementations."
|
|
46
|
+
},
|
|
40
47
|
"options": {
|
|
41
48
|
"$ref": "#/$defs/optionsMap"
|
|
42
49
|
},
|
|
@@ -99,6 +106,45 @@
|
|
|
99
106
|
},
|
|
100
107
|
"additionalProperties": false
|
|
101
108
|
},
|
|
109
|
+
"implementation": {
|
|
110
|
+
"type": "object",
|
|
111
|
+
"required": ["platform", "componentName"],
|
|
112
|
+
"properties": {
|
|
113
|
+
"platform": {
|
|
114
|
+
"type": "string",
|
|
115
|
+
"minLength": 1,
|
|
116
|
+
"description": "Target platform identifier (for example, 'web', 'ios', or 'android'). Multiple implementations may target the same platform when they have distinct packages."
|
|
117
|
+
},
|
|
118
|
+
"componentName": {
|
|
119
|
+
"type": "string",
|
|
120
|
+
"minLength": 1,
|
|
121
|
+
"description": "Exported class, element, or component name used by the platform implementation."
|
|
122
|
+
},
|
|
123
|
+
"importPath": {
|
|
124
|
+
"type": "string",
|
|
125
|
+
"minLength": 1,
|
|
126
|
+
"description": "Importable module or source path for a platform implementation."
|
|
127
|
+
},
|
|
128
|
+
"package": {
|
|
129
|
+
"type": "string",
|
|
130
|
+
"minLength": 1,
|
|
131
|
+
"description": "Published package containing the platform implementation."
|
|
132
|
+
},
|
|
133
|
+
"notes": {
|
|
134
|
+
"type": "string",
|
|
135
|
+
"description": "Optional implementation-specific usage or mapping notes."
|
|
136
|
+
}
|
|
137
|
+
},
|
|
138
|
+
"oneOf": [
|
|
139
|
+
{
|
|
140
|
+
"required": ["importPath"]
|
|
141
|
+
},
|
|
142
|
+
{
|
|
143
|
+
"required": ["package"]
|
|
144
|
+
}
|
|
145
|
+
],
|
|
146
|
+
"additionalProperties": false
|
|
147
|
+
},
|
|
102
148
|
"optionsMap": {
|
|
103
149
|
"type": "object",
|
|
104
150
|
"description": "Component API options. Each key is a camelCase option name; each value is an option descriptor.",
|
package/spec/agent-surface.md
CHANGED
|
@@ -66,12 +66,14 @@ 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/)). 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:
|
|
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`, `export`) 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`.
|
|
73
73
|
* `design-data explain <token-uuid|component-id>` — invoke `get_guidance`. (Deferred — not yet shipped; pending `get_guidance` wire-up.)
|
|
74
74
|
|
|
75
|
+
`resolve`, `query`, and `export` all accept `--format dtcg` to emit [W3C DTCG](https://tr.designtokens.org/format/)-conformant `$value`/`$type` output, resolved for a given mode context (`--color-scheme`/`--scale`/`--contrast`) — `export` emits the whole dataset as one flat document, `query --format dtcg` a filtered subset, `resolve --format dtcg` a single property. See the [`sdk/` README](../../../sdk/README.md#cli-usage) for examples.
|
|
76
|
+
|
|
75
77
|
**NORMATIVE:** All RFC-C CLI output MUST default to JSON when stdout is not a TTY, and MUST emit human-friendly output when stdout is a TTY. This makes the CLI directly composable from agent shells without per-call format flags.
|
|
76
78
|
|
|
77
79
|
### MCP server
|
package/spec/component-format.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**Spec version:** `1.0.0-draft` (see [Overview](index.md))
|
|
4
4
|
|
|
5
|
-
This document defines the normative **component declaration** object: identity (`$id`, `name`, `displayName`), component metadata (`meta`), API options (`options`), named content slots (`slots`), anatomy parts (`anatomy`), state model (`states`), and lifecycle metadata.
|
|
5
|
+
This document defines the normative **component declaration** object: identity (`$id`, `name`, `displayName`), component metadata (`meta`), platform implementations (`implementations`), API options (`options`), named content slots (`slots`), anatomy parts (`anatomy`), state model (`states`), and lifecycle metadata.
|
|
6
6
|
|
|
7
7
|
Component declarations close the structural gap between the token name-object's `component`, `variant`, `anatomy`, and `state` fields and the declared surface of each component. Before this chapter, a token referencing `component: "button"` with `variant: "foo"` was undetectable as invalid because no machine-readable component contract existed in the same spec. After this chapter, validators enforce cross-reference rules (see [SPEC rules](#spec-rules)).
|
|
8
8
|
|
|
@@ -29,18 +29,19 @@ A component declaration **MUST** contain:
|
|
|
29
29
|
|
|
30
30
|
### Optional fields
|
|
31
31
|
|
|
32
|
-
| Field
|
|
33
|
-
|
|
|
34
|
-
| `specVersion`
|
|
35
|
-
| `description`
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
32
|
+
| Field | Type | Description |
|
|
33
|
+
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
34
|
+
| `specVersion` | string | Declares which spec version this document targets. Currently `"1.0.0-draft"`; future stable releases will accept their own version string. |
|
|
35
|
+
| `description` | string | Plain-text description of the component's purpose. |
|
|
36
|
+
| `implementations` | array | Known platform implementations — see [Implementations](#implementations). |
|
|
37
|
+
| `options` | object | Component API options — see [Options](#options). |
|
|
38
|
+
| `slots` | array | Named content injection points — see [Slots](#slots). |
|
|
39
|
+
| `anatomy` | array | Named anatomy parts — see [Anatomy (stub)](#anatomy-stub). |
|
|
40
|
+
| `states` | array | Per-component state declarations — see [States (stub)](#states-stub). |
|
|
41
|
+
| `lifecycle` | object | Version lifecycle metadata — see [Lifecycle](#lifecycle). |
|
|
42
|
+
| `tokenBindings` | array | Tokens this component uses — see [Token bindings](#token-bindings) (Phase 6.7). |
|
|
43
|
+
| `documentBlocks` | array | Typed prose blocks for this component — see [Document blocks](#document-blocks) (Phase 9). |
|
|
44
|
+
| `accessibility` | object | Semantic accessibility vocabulary — see [Accessibility](accessibility.md) (Phase 7). |
|
|
44
45
|
|
|
45
46
|
**NORMATIVE:** No properties beyond those listed above are permitted at the top level of a component declaration. Additional fields **MUST** cause a Layer 1 schema error.
|
|
46
47
|
|
|
@@ -78,6 +79,34 @@ where `{name}` matches the component's `name` field.
|
|
|
78
79
|
}
|
|
79
80
|
```
|
|
80
81
|
|
|
82
|
+
## Implementations
|
|
83
|
+
|
|
84
|
+
`implementations` declares the published platform implementations corresponding
|
|
85
|
+
to this design-system component. It is foundation-owned canonical data so
|
|
86
|
+
consumers, including Code Connect generators, can resolve an implementation
|
|
87
|
+
without platform-specific configuration.
|
|
88
|
+
|
|
89
|
+
Each entry **MUST** contain `platform` and `componentName`, plus exactly one
|
|
90
|
+
implementation reference: `package` for a published package or `importPath`
|
|
91
|
+
for an importable module/source path. `notes` is optional context for consumers.
|
|
92
|
+
Multiple entries MAY use the same `platform` when their packages distinguish
|
|
93
|
+
different implementations for that platform.
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
"implementations": [
|
|
97
|
+
{
|
|
98
|
+
"platform": "web",
|
|
99
|
+
"componentName": "Button",
|
|
100
|
+
"package": "@spectrum-web-components/button"
|
|
101
|
+
}
|
|
102
|
+
]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Platform manifests do not override `implementations` in this version. A future
|
|
106
|
+
extension may add platform-owned overrides after consumers need them; until
|
|
107
|
+
then, component declarations remain the canonical source of implementation
|
|
108
|
+
names and references.
|
|
109
|
+
|
|
81
110
|
## Options
|
|
82
111
|
|
|
83
112
|
The `options` block declares the component's API surface — the configurable properties that affect its appearance or behavior. It mirrors the shape of `@adobe/spectrum-component-api-schemas` for backward compatibility.
|