@adobe/design-data-spec 4.2.1 → 4.4.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/schemas/manifest.schema.json +20 -0
- package/spec/authoring-workflow.md +1 -0
- package/spec/component-format.md +45 -14
- package/spec/index.md +2 -0
- package/spec/manifest.md +30 -9
- package/spec/taxonomy.md +2 -0
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.",
|
|
@@ -14,6 +14,21 @@
|
|
|
14
14
|
"minLength": 1,
|
|
15
15
|
"description": "Pin to a foundation release (semver or tag)."
|
|
16
16
|
},
|
|
17
|
+
"platform": {
|
|
18
|
+
"type": "string",
|
|
19
|
+
"minLength": 1,
|
|
20
|
+
"description": "Machine-readable platform implementation id (e.g. \"react-spectrum\", \"web-components\", \"ios\"), matching an id in the platform-implementations registry. Optional: a manifest MAY be anonymous (e.g. a single-platform repo where identity is implicit), but SHOULD declare it once the manifest is relocatable (fetched remotely, or one of several manifests in the same repo)."
|
|
21
|
+
},
|
|
22
|
+
"platformVersion": {
|
|
23
|
+
"type": "string",
|
|
24
|
+
"minLength": 1,
|
|
25
|
+
"description": "Human-readable description of the platform implementation this manifest targets, e.g. \"React Spectrum 3.x\" or \"Spectrum Web Components 0.x+\". Distinct from `foundationVersion` (the pinned foundation release)."
|
|
26
|
+
},
|
|
27
|
+
"repository": {
|
|
28
|
+
"type": "string",
|
|
29
|
+
"minLength": 1,
|
|
30
|
+
"description": "URL of the repository that owns (or, during incubation, will eventually own) this platform manifest, e.g. \"https://github.com/adobe/react-spectrum\"."
|
|
31
|
+
},
|
|
17
32
|
"include": {
|
|
18
33
|
"type": "array",
|
|
19
34
|
"items": {
|
|
@@ -138,6 +153,11 @@
|
|
|
138
153
|
"type": "string"
|
|
139
154
|
},
|
|
140
155
|
"description": "Map of full term to abbreviated form, applied after ordering and before casing."
|
|
156
|
+
},
|
|
157
|
+
"prefix": {
|
|
158
|
+
"type": "string",
|
|
159
|
+
"minLength": 1,
|
|
160
|
+
"description": "Literal string prepended to the fully-formatted token name (after casing/delimiter are applied), unaffected by `casing` itself. For platform naming conventions that wrap the token name rather than reshape it, e.g. CSS custom properties (`--spectrum-`) or other namespaced identifier prefixes."
|
|
141
161
|
}
|
|
142
162
|
},
|
|
143
163
|
"additionalProperties": false
|
|
@@ -20,6 +20,7 @@ The source-of-truth direction is already normative in [Evolution](evolution.md#l
|
|
|
20
20
|
|
|
21
21
|
* Specifying the *output format* of generated artifacts. Legacy format mapping is defined in [Evolution — Legacy format contract](evolution.md#legacy-format-contract); DTCG and StyleDictionary outputs are deferred (RFC [#627](https://github.com/adobe/spectrum-design-data/discussions/627)).
|
|
22
22
|
* Specifying the *consumer-facing API* of published packages (`@adobe/spectrum-tokens`, platform SDKs). Those are separately governed.
|
|
23
|
+
* Restating the full semantics of external implementation contracts already owned by their native standards or package ecosystems. This spec links to authoritative sources instead of duplicating their normative rules.
|
|
23
24
|
* Specifying the *UI* of the authoring tools; this document defines behavioral contracts, not user-interface design.
|
|
24
25
|
* Multi-user collaboration, permissions models, and Figma sync direction (open questions in RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625)).
|
|
25
26
|
|
package/spec/component-format.md
CHANGED
|
@@ -2,10 +2,12 @@
|
|
|
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
|
|
|
9
|
+
This chapter defines the Design Data contract for a component. It intentionally does not restate the full platform-native component API, story/example-format semantics, or other standards already owned elsewhere. When another authoritative specification already defines an implementation contract or format, this document points to that source instead of duplicating its normative rules.
|
|
10
|
+
|
|
9
11
|
Scoped under [RFC-A — Component Contract in Design Data Spec](https://github.com/adobe/spectrum-design-data/discussions/832). See also [rfc-coordination.md](../docs/rfc-coordination.md).
|
|
10
12
|
|
|
11
13
|
## Document shape
|
|
@@ -29,18 +31,19 @@ A component declaration **MUST** contain:
|
|
|
29
31
|
|
|
30
32
|
### Optional fields
|
|
31
33
|
|
|
32
|
-
| Field
|
|
33
|
-
|
|
|
34
|
-
| `specVersion`
|
|
35
|
-
| `description`
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
34
|
+
| Field | Type | Description |
|
|
35
|
+
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
36
|
+
| `specVersion` | string | Declares which spec version this document targets. Currently `"1.0.0-draft"`; future stable releases will accept their own version string. |
|
|
37
|
+
| `description` | string | Plain-text description of the component's purpose. |
|
|
38
|
+
| `implementations` | array | Known platform implementations — see [Implementations](#implementations). |
|
|
39
|
+
| `options` | object | Component API options — see [Options](#options). |
|
|
40
|
+
| `slots` | array | Named content injection points — see [Slots](#slots). |
|
|
41
|
+
| `anatomy` | array | Named anatomy parts — see [Anatomy (stub)](#anatomy-stub). |
|
|
42
|
+
| `states` | array | Per-component state declarations — see [States (stub)](#states-stub). |
|
|
43
|
+
| `lifecycle` | object | Version lifecycle metadata — see [Lifecycle](#lifecycle). |
|
|
44
|
+
| `tokenBindings` | array | Tokens this component uses — see [Token bindings](#token-bindings) (Phase 6.7). |
|
|
45
|
+
| `documentBlocks` | array | Typed prose blocks for this component — see [Document blocks](#document-blocks) (Phase 9). |
|
|
46
|
+
| `accessibility` | object | Semantic accessibility vocabulary — see [Accessibility](accessibility.md) (Phase 7). |
|
|
44
47
|
|
|
45
48
|
**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
49
|
|
|
@@ -78,9 +81,37 @@ where `{name}` matches the component's `name` field.
|
|
|
78
81
|
}
|
|
79
82
|
```
|
|
80
83
|
|
|
84
|
+
## Implementations
|
|
85
|
+
|
|
86
|
+
`implementations` declares the published platform implementations corresponding
|
|
87
|
+
to this design-system component. It is foundation-owned canonical data so
|
|
88
|
+
consumers, including Code Connect generators, can resolve an implementation
|
|
89
|
+
without platform-specific configuration.
|
|
90
|
+
|
|
91
|
+
Each entry **MUST** contain `platform` and `componentName`, plus exactly one
|
|
92
|
+
implementation reference: `package` for a published package or `importPath`
|
|
93
|
+
for an importable module/source path. `notes` is optional context for consumers.
|
|
94
|
+
Multiple entries MAY use the same `platform` when their packages distinguish
|
|
95
|
+
different implementations for that platform.
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
"implementations": [
|
|
99
|
+
{
|
|
100
|
+
"platform": "web",
|
|
101
|
+
"componentName": "Button",
|
|
102
|
+
"package": "@spectrum-web-components/button"
|
|
103
|
+
}
|
|
104
|
+
]
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Platform manifests do not override `implementations` in this version. A future
|
|
108
|
+
extension may add platform-owned overrides after consumers need them; until
|
|
109
|
+
then, component declarations remain the canonical source of implementation
|
|
110
|
+
names and references.
|
|
111
|
+
|
|
81
112
|
## Options
|
|
82
113
|
|
|
83
|
-
The `options` block declares the component's API surface — the configurable properties that affect its appearance or behavior. It
|
|
114
|
+
The `options` block declares the component's API surface — the configurable properties that affect its appearance or behavior. It is the Design Data contract for the component surface that this repo validates; it does not duplicate the entire implementation-owned API schema. For exhaustive platform-specific semantics, follow the authoritative implementation contract instead of restating it here.
|
|
84
115
|
|
|
85
116
|
**NORMATIVE:** `options` **MUST** be a JSON object. Each key is an option name; each value is an **option descriptor**.
|
|
86
117
|
|
package/spec/index.md
CHANGED
|
@@ -30,6 +30,8 @@ The specification defines:
|
|
|
30
30
|
16. **Authoring workflow** — normative contract for authoring design data via tooling: authoritative source location, lifecycle operations (create / edit / deprecate / rename / alias-rewire / mode-set management), taxonomy-aware decomposition requirement, and output-generation obligations ([Authoring workflow](authoring-workflow.md)).
|
|
31
31
|
17. **Relationship format** — Component/Token Relationship (CTR): the anonymous-token entity unifying `tokenBindings` and token name-object scope fields, explicit relationship context, options validation, and interim legacy-compatibility fields ([Relationship format](relationship-format.md)).
|
|
32
32
|
|
|
33
|
+
This specification intentionally defines the Design Data-owned contract and links to external standards for platform-native implementation semantics instead of restating those contracts as normative local rules. The repository owns taxonomy, validation, lifecycle, and schema rules; the authoritative source for native format behavior remains the external standard it describes.
|
|
34
|
+
|
|
33
35
|
## Conformance
|
|
34
36
|
|
|
35
37
|
The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY**, and **OPTIONAL** in this specification are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) \[[RFC2119](https://www.rfc-editor.org/rfc/rfc2119.html)] \[[RFC8174](https://www.rfc-editor.org/rfc/rfc8174.html)] when, and only when, they appear in all capitals, as shown here.
|
package/spec/manifest.md
CHANGED
|
@@ -41,15 +41,18 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
|
|
|
41
41
|
|
|
42
42
|
## Optional fields
|
|
43
43
|
|
|
44
|
-
| Field | Type | Description
|
|
45
|
-
| --------------------- | --------------- |
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
44
|
+
| Field | Type | Description |
|
|
45
|
+
| --------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| `platform` | string | Machine-readable platform implementation id (e.g. `"react-spectrum"`, `"web-components"`, `"ios"`), matching an id in the platform-implementations registry. See [Identity fields](#identity-fields) below. |
|
|
47
|
+
| `platformVersion` | string | Human-readable description of the platform implementation, e.g. `"React Spectrum 3.x"`. Distinct from `foundationVersion`. |
|
|
48
|
+
| `repository` | string | URL of the repository that owns (or will eventually own) this platform manifest. |
|
|
49
|
+
| `include` | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize. |
|
|
50
|
+
| `exclude` | array of string | Queries removing tokens from the included set. |
|
|
51
|
+
| `overrides` | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**. |
|
|
52
|
+
| `extensionsDir` | string | Path (relative to the manifest) to the platform's `extensions/` directory. Default: `"extensions"`. See [`extensions/` directory](#extensions-directory) below. |
|
|
53
|
+
| `namingExceptions` | object | Platform-local overlay on the base naming-exceptions set: names to add and/or remove for this platform's naming validation. |
|
|
54
|
+
| `formatting` | object | Rules for serializing structured name objects into platform-specific token name strings. |
|
|
55
|
+
| `modeSetRestrictions` | object | Mode set restrictions for this platform; see [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions). |
|
|
53
56
|
|
|
54
57
|
### `include` / `exclude`
|
|
55
58
|
|
|
@@ -75,6 +78,23 @@ apply `Foundation < Platform < Product` precedence to select a single winner. To
|
|
|
75
78
|
counts "tokens a platform ships" from `query` output should resolve first, or it will
|
|
76
79
|
double-count overridden tokens.
|
|
77
80
|
|
|
81
|
+
### Identity fields
|
|
82
|
+
|
|
83
|
+
`platform`, `platformVersion`, and `repository` are optional and have no effect on the
|
|
84
|
+
Foundation→Platform cascade — they exist so a manifest is self-describing wherever it
|
|
85
|
+
lives. This matters once a manifest is one of several configured in the same repo (via named
|
|
86
|
+
`[platforms.<id>]` profiles — see the SDK's `.design-data.toml` reference) or is fetched
|
|
87
|
+
from a remote repository: without `platform`, a manifest fetched by URL has no stable
|
|
88
|
+
identity of its own.
|
|
89
|
+
|
|
90
|
+
A single-platform repo with exactly one manifest **MAY** omit all three; the pattern
|
|
91
|
+
becomes worth adopting the moment a manifest is expected to move (incubating in a
|
|
92
|
+
monorepo ahead of a hand-off to its owning team) or coexist with siblings.
|
|
93
|
+
|
|
94
|
+
`platform`, when present, **SHOULD** match an id in the platform-implementations registry
|
|
95
|
+
(distinct from the token-level `platforms.json` registry, which enumerates *device
|
|
96
|
+
targets* like `desktop`/`mobile`, not *implementations* like `react-spectrum`).
|
|
97
|
+
|
|
78
98
|
### `extensions/` directory
|
|
79
99
|
|
|
80
100
|
**NORMATIVE:** Platform-local additions are declared as a sibling **directory** next to
|
|
@@ -216,6 +236,7 @@ A platform **MAY** declare formatting rules that control how structured name obj
|
|
|
216
236
|
| `casing` | string | One of: `kebab-case`, `camelCase`, `PascalCase`, `SCREAMING_SNAKE_CASE`. Default: `kebab-case`. |
|
|
217
237
|
| `delimiter` | string | Character(s) separating concepts in the serialized string (e.g. `-`, `_`, `.`, `/`). Default: `-`. |
|
|
218
238
|
| `abbreviations` | object | Map of full term → abbreviated form (e.g. `{ "background": "bg" }`). Abbreviations are applied after concept ordering and before casing. |
|
|
239
|
+
| `prefix` | string | Literal string prepended to the fully-formatted token name, applied after `casing`/`delimiter` and unaffected by either — for platform naming conventions that wrap the token name rather than reshape it (e.g. CSS custom properties like `--spectrum-`). |
|
|
219
240
|
|
|
220
241
|
**NORMATIVE:** When `formatting` is absent, the default serialization defined in [Taxonomy](taxonomy.md#default-serialization-legacy-format) is used.
|
|
221
242
|
|
package/spec/taxonomy.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
This document defines the **token taxonomy**: a hierarchical system of concept categories that classify design tokens, the **token term vocabulary** of allowed words within each category, and the **formatting style** rules that control serialization of structured token names into platform-consumable strings.
|
|
6
6
|
|
|
7
|
+
This chapter defines the Design Data-owned taxonomy contract. It intentionally does not restate platform-native naming semantics or external standards already owned elsewhere; when a platform or implementation standard defines those behaviors, this spec links to that authority instead of copying its normative rules.
|
|
8
|
+
|
|
7
9
|
## Motivation
|
|
8
10
|
|
|
9
11
|
"Naming convention" is too broad a term when discussing malleability across platform teams. A token name like `accent-background-color-hover` embeds multiple independent decisions:
|