@adobe/design-data-spec 4.8.0 → 4.8.1

package/conformance/invalid/SPEC-072/dataset.json

@@ -0,0 +1,50 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "accordion",
+        "property": "gap",
+        "scale": "desktop"
+      },
+      "value": "8px",
+      "uuid": "aaaaaaaa-0072-4000-8000-000000000001"
+    },
+    {
+      "name": {
+        "component": "accordion",
+        "property": "gap",
+        "scale": "mobile"
+      },
+      "value": "10px",
+      "uuid": "aaaaaaaa-0072-4000-8000-000000000002"
+    }
+  ],
+  "relationships": [
+    {
+      "scope": {
+        "component": "accordion",
+        "property": "gap"
+      },
+      "context": "Spacing",
+      "$ref": "aaaaaaaa-0072-4000-8000-000000000001"
+    },
+    {
+      "scope": {
+        "component": "accordion",
+        "property": "gap"
+      },
+      "context": "Spacing",
+      "$ref": "aaaaaaaa-0072-4000-8000-000000000001"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/accordion.json",
+      "name": "accordion",
+      "displayName": "Accordion",
+      "meta": {
+        "category": "actions"
+      }
+    }
+  ]
+}

package/conformance/invalid/SPEC-072/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-072",
+      "severity": "warning",
+      "message_pattern": ".*twice.*mobile counterpart.*aaaaaaaa-0072-4000-8000-000000000002.*"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "4.8.0",
+  "version": "4.8.1",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
   "type": "module",
   "repository": {

package/rules/rules.yaml

@@ -724,3 +724,18 @@ rules:
     message: "Alias {token} sets {field}={ownValue} but its $ref chain resolves to a token with {field}={leafValue}"
     spec_ref: spec/cascade.md#alias-resolution
     introduced_in: "1.0.0-draft"
+  - id: SPEC-072
+    name: relationship-duplicate-ref-scale-counterpart
+    severity: warning
+    layer: 2
+    category: relationship
+    note: >
+      Typically a desktop and a mobile record where the second was copied without repointing it,
+      so the other scale's token is never reachable through the relationship. A repeated record
+      on a token with no scale counterpart is not reported.
+    assert: >
+      Two relationship records with the same scope, context and `$ref` SHOULD NOT both point at
+      a token that has a scale counterpart (the same name with another `scale` value).
+    message: "Relationship {scope} references {ref} twice, but the token has a {scale} counterpart ({counterpart}); point one record at it"
+    spec_ref: spec/relationship-format.md
+    introduced_in: "1.0.0-draft"

package/spec/manifest.md

@@ -69,15 +69,16 @@ Each override object **MUST** include enough information to identify a target to
 
 **NORMATIVE:** Overrides **MUST NOT** change the resolved type of the token (aligns with [Cascade — type safety](cascade.md)).
 
-An override is applied as a new **platform-layer** record, not an in-place edit of the
-foundation record it targets — the original foundation record is left untouched.
-[Query](query.md) reports records across all cascade layers, so a query over an overridden
-token's selector returns both the untouched foundation record and the new platform-layer
-record (e.g. an override on a `state=disabled` token increases the matching count by one,
-rather than replacing an existing match). Only [`resolve` / `resolve_property`](cascade.md)
-apply `Foundation < Platform < Product` precedence to select a single winner. Tooling that
-counts "tokens a platform ships" from `query` output should resolve first, or it will
-double-count overridden tokens.
+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.
+
+**Provenance.** A replaced record carries two in-memory markers so tooling can tell where it came from:
+
+| Field            | Value                                                                                                                                                                                                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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).                                                                                                                |
+| `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). |
+
+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.
 
 ### Identity fields