@adobe/design-data-spec 4.7.0 → 4.8.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.
Files changed (6) hide show
  1. package/conformance/invalid/SPEC-072/dataset.json +50 -0
  2. package/conformance/invalid/SPEC-072/expected-errors.json +10 -0
  3. package/package.json +1 -1
  4. package/rules/rules.yaml +15 -0
  5. package/schemas/platform-extension.json +1 -1
  6. package/spec/manifest.md +36 -34
package/conformance/invalid/SPEC-072/dataset.json ADDED
@@ -0,0 +1,50 @@
1
+ {
2
+ "tokens": [
3
+ {
4
+ "name": {
5
+ "component": "accordion",
6
+ "property": "gap",
7
+ "scale": "desktop"
8
+ },
9
+ "value": "8px",
10
+ "uuid": "aaaaaaaa-0072-4000-8000-000000000001"
11
+ },
12
+ {
13
+ "name": {
14
+ "component": "accordion",
15
+ "property": "gap",
16
+ "scale": "mobile"
17
+ },
18
+ "value": "10px",
19
+ "uuid": "aaaaaaaa-0072-4000-8000-000000000002"
20
+ }
21
+ ],
22
+ "relationships": [
23
+ {
24
+ "scope": {
25
+ "component": "accordion",
26
+ "property": "gap"
27
+ },
28
+ "context": "Spacing",
29
+ "$ref": "aaaaaaaa-0072-4000-8000-000000000001"
30
+ },
31
+ {
32
+ "scope": {
33
+ "component": "accordion",
34
+ "property": "gap"
35
+ },
36
+ "context": "Spacing",
37
+ "$ref": "aaaaaaaa-0072-4000-8000-000000000001"
38
+ }
39
+ ],
40
+ "components": [
41
+ {
42
+ "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/accordion.json",
43
+ "name": "accordion",
44
+ "displayName": "Accordion",
45
+ "meta": {
46
+ "category": "actions"
47
+ }
48
+ }
49
+ ]
50
+ }
package/conformance/invalid/SPEC-072/expected-errors.json ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "layer": 2,
3
+ "errors": [
4
+ {
5
+ "rule_id": "SPEC-072",
6
+ "severity": "warning",
7
+ "message_pattern": ".*twice.*mobile counterpart.*aaaaaaaa-0072-4000-8000-000000000002.*"
8
+ }
9
+ ]
10
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adobe/design-data-spec",
3
- "version": "4.7.0",
3
+ "version": "4.8.1",
4
4
  "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
5
5
  "type": "module",
6
6
  "repository": {
package/rules/rules.yaml CHANGED
@@ -724,3 +724,18 @@ rules:
724
724
  message: "Alias {token} sets {field}={ownValue} but its $ref chain resolves to a token with {field}={leafValue}"
725
725
  spec_ref: spec/cascade.md#alias-resolution
726
726
  introduced_in: "1.0.0-draft"
727
+ - id: SPEC-072
728
+ name: relationship-duplicate-ref-scale-counterpart
729
+ severity: warning
730
+ layer: 2
731
+ category: relationship
732
+ note: >
733
+ Typically a desktop and a mobile record where the second was copied without repointing it,
734
+ so the other scale's token is never reachable through the relationship. A repeated record
735
+ on a token with no scale counterpart is not reported.
736
+ assert: >
737
+ Two relationship records with the same scope, context and `$ref` SHOULD NOT both point at
738
+ a token that has a scale counterpart (the same name with another `scale` value).
739
+ message: "Relationship {scope} references {ref} twice, but the token has a {scale} counterpart ({counterpart}); point one record at it"
740
+ spec_ref: spec/relationship-format.md
741
+ introduced_in: "1.0.0-draft"
package/schemas/platform-extension.json CHANGED
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "extends": {
30
30
  "type": "string",
31
- "description": "Which registry this extends (sizes, states, variants, etc.)"
31
+ "description": "Foundation registry (field name or file basename) or active mode-set name whose existing ids or modes this annotates (e.g. states or contrast)."
32
32
  },
33
33
  "extensions": {
34
34
  "type": "array",
package/spec/manifest.md CHANGED
@@ -8,26 +8,26 @@ This document defines the **platform manifest**: how a platform implementation r
8
8
 
9
9
  The manifest supports a fixed, enumerated set of operations against the foundation — it does **not** allow overriding, aliasing, or removing arbitrary foundation artifacts. Support is concentrated on tokens; translations and schemas have no manifest-level override mechanism at all.
10
10
 
11
- | Operation | Supported? | Field | Applies to |
12
- | --------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | --------------------------- |
13
- | Remove / exclude | Yes | `exclude` | Tokens only |
14
- | Include / whitelist | Yes | `include` | Tokens only |
15
- | Override value (type-preserving) | Yes | `overrides[].value` | Tokens only |
16
- | Override → re-alias | Yes | `overrides[].$ref` | Tokens only |
17
- | Add new tokens (may alias via `$ref`) | Yes | `extensions/tokens/` | Tokens |
18
- | Add / replace components | Yes | `extensions/components/` | Components |
19
- | Add / replace field declarations | Yes | `extensions/fields/` | Fields |
20
- | Add / replace guideline documents | Yes | `extensions/guidelines/` | Guidelines |
21
- | Declare / replace platform-local mode set | Yes | `extensions/mode-sets/` | Mode sets |
22
- | Add / remove / retarget a single mode; remove a set | Yes | `extensions/mode-sets/` (`op`) | Mode sets |
23
- | Add relationships/CTRs; override/remove by `uuid` | Yes | `extensions/relationships/` | Relationships (CTRs) |
24
- | Add / remove naming exceptions | Yes | `namingExceptions` | Naming validation |
25
- | Annotate existing terminology (cannot add new ids) | Yes | `extensions/platform-extensions/` | Existing registry ids |
26
- | Upsert / remove own implementation mappings | Yes | `extensions/implementations/` | Component `implementations` |
27
- | Restrict allowed mode-set values | Yes | `modeSetRestrictions` | Mode sets |
28
- | Reformat name serialization | Schema-declared only, not yet applied by the reference SDK | `formatting` | Token name strings |
29
- | Override/remove/alias translations | No | — | — |
30
- | Override Layer-1 schemas | No (decided; see [spike](manifest-schema-override-spike.md)) | — | — |
11
+ | Operation | Supported? | Field | Applies to |
12
+ | --------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | ------------------------------ |
13
+ | Remove / exclude | Yes | `exclude` | Tokens only |
14
+ | Include / whitelist | Yes | `include` | Tokens only |
15
+ | Override value (type-preserving) | Yes | `overrides[].value` | Tokens only |
16
+ | Override → re-alias | Yes | `overrides[].$ref` | Tokens only |
17
+ | Add new tokens (may alias via `$ref`) | Yes | `extensions/tokens/` | Tokens |
18
+ | Add / replace components | Yes | `extensions/components/` | Components |
19
+ | Add / replace field declarations | Yes | `extensions/fields/` | Fields |
20
+ | Add / replace guideline documents | Yes | `extensions/guidelines/` | Guidelines |
21
+ | Declare / replace platform-local mode set | Yes | `extensions/mode-sets/` | Mode sets |
22
+ | Add / remove / retarget a single mode; remove a set | Yes | `extensions/mode-sets/` (`op`) | Mode sets |
23
+ | Add relationships/CTRs; override/remove by `uuid` | Yes | `extensions/relationships/` | Relationships (CTRs) |
24
+ | Add / remove naming exceptions | Yes | `namingExceptions` | Naming validation |
25
+ | Annotate existing terminology (cannot add new ids) | Yes | `extensions/platform-extensions/` | Existing registry ids or modes |
26
+ | Upsert / remove own implementation mappings | Yes | `extensions/implementations/` | Component `implementations` |
27
+ | Restrict allowed mode-set values | Yes | `modeSetRestrictions` | Mode sets |
28
+ | Reformat name serialization | Schema-declared only, not yet applied by the reference SDK | `formatting` | Token name strings |
29
+ | Override/remove/alias translations | No | — | — |
30
+ | Override Layer-1 schemas | No (decided; see [spike](manifest-schema-override-spike.md)) | — | — |
31
31
 
32
32
  ## Manifest document
33
33
 
@@ -69,15 +69,16 @@ Each override object **MUST** include enough information to identify a target to
69
69
 
70
70
  **NORMATIVE:** Overrides **MUST NOT** change the resolved type of the token (aligns with [Cascade — type safety](cascade.md)).
71
71
 
72
- An override is applied as a new **platform-layer** record, not an in-place edit of the
73
- foundation record it targets — the original foundation record is left untouched.
74
- [Query](query.md) reports records across all cascade layers, so a query over an overridden
75
- token's selector returns both the untouched foundation record and the new platform-layer
76
- record (e.g. an override on a `state=disabled` token increases the matching count by one,
77
- rather than replacing an existing match). Only [`resolve` / `resolve_property`](cascade.md)
78
- apply `Foundation < Platform < Product` precedence to select a single winner. Tooling that
79
- counts "tokens a platform ships" from `query` output should resolve first, or it will
80
- double-count overridden tokens.
72
+ An override **replaces** the foundation record for that platform's graph: the replacement keeps the target's key and `uuid`, sits at the **platform** layer, and keeps every other field of the original record (`$schema`, `$valueType`, `lifecycle`, `description`, `conceptId`, and so on). Only `value` or `$ref` changes; an override that supplies `$ref` removes `value`, and one that supplies `value` removes `$ref`. The foundation package on disk is untouched. [Query](query.md) returns one record per token, and [`resolve` / `resolve_property`](cascade.md) still apply `Foundation < Platform < Product` precedence, so a platform override beats the foundation value and a product override beats both.
73
+
74
+ **Provenance.** A replaced record carries two in-memory markers so tooling can tell where it came from:
75
+
76
+ | Field | Value |
77
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
78
+ | `overriddenBy` | `{ "platform": "<manifest platform>" }` when the manifest sets `platform`; otherwise `{ "manifest": "manifest.json" }` (the literal file name; the manifest's real path is not recorded). |
79
+ | `overriddenFrom` | `{ "value": <foundation value> }` or `{ "$ref": <foundation $ref> }`. The first override's history is kept, so it is always the foundation value, even when a token is overridden more than once (the last override wins for the value). |
80
+
81
+ These markers exist only on the platform's in-memory records. They are not written to token files and are **not** serialized in legacy output.
81
82
 
82
83
  ### Identity fields
83
84
 
@@ -215,11 +216,12 @@ a new axis.
215
216
 
216
217
  #### `extensions/platform-extensions/`
217
218
 
218
- Platform terminology annotations layered onto **existing** foundation registry entries (for
219
- example, platform-specific state names). **NORMATIVE:** each file **MUST** validate against
220
- `platform-extension.json`, and every `termId` **MUST** already exist in the referenced
221
- foundation registry — this mechanism annotates existing ids, it does **NOT** introduce new
222
- ones.
219
+ Platform terminology annotations for **existing** registry entries or mode-set values (for
220
+ example, platform-specific state or contrast names). **NORMATIVE:** each file **MUST**
221
+ validate against `platform-extension.json`. `extends` **MUST** name a foundation registry
222
+ (by field name or registry-file basename) or an active mode set. Every `termId` **MUST**
223
+ exist in that registry or the mode set's `modes`, after applying the manifest's mode-set
224
+ edits. This mechanism annotates existing ids and modes; it does **NOT** introduce new ones.
223
225
 
224
226
  #### `extensions/implementations/`
225
227