@adobe/design-data-spec 3.4.0 → 3.5.0

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

@@ -0,0 +1,38 @@
+{
+  "tokens": [
+    {
+      "name": {
+        "component": "accordion",
+        "property": "top-to-text-compact-medium"
+      },
+      "value": "5px",
+      "uuid": "aaaaaaaa-0058-4000-8000-000000000001",
+      "lifecycle": {
+        "deprecatedIn": "14.3.0",
+        "replacedBy": "aaaaaaaa-0058-4000-8000-000000000002"
+      }
+    },
+    {
+      "name": { "property": "base-padding-vertical-medium" },
+      "value": "5px",
+      "uuid": "aaaaaaaa-0058-4000-8000-000000000002"
+    }
+  ],
+  "relationships": [
+    {
+      "scope": {
+        "component": "accordion",
+        "property": "top-to-text-compact-medium"
+      },
+      "$ref": "aaaaaaaa-0058-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-058/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-058",
+      "severity": "warning",
+      "message_pattern": ".*deprecated in 14.3.0.*aaaaaaaa-0058-4000-8000-000000000002.*"
+    }
+  ]
+}

package/package.json

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

package/rules/rules.yaml

@@ -690,3 +690,20 @@ rules:
     message: "Relationship '{relationship}' may need a legacyKey to round-trip through the legacy generator"
     spec_ref: spec/relationship-format.md#legacy-fields-interim
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-058
+    name: ctr-ref-not-deprecated
+    severity: warning
+    layer: 2
+    category: naming-consistency
+    note: >
+      Warning, not error: some deprecated targets have no `replacedBy` (or an ambiguous
+      array-form one) and can't be auto-corrected without manual triage, so this can't be
+      a hard gate yet.
+    assert: >
+      A relationship-only CTR's `$ref` (no `uuid`/`legacyKey`) SHOULD NOT resolve to a
+      token whose `lifecycle.deprecatedIn` is set. A value-owning CTR (`uuid`/`legacyKey`
+      present) is exempt — it legitimately *is* the deprecated token record.
+    message: "Relationship $ref {ref} resolves to a token deprecated in {deprecatedIn}"
+    spec_ref: spec/relationship-format.md#legacy-fields-interim
+    introduced_in: "1.0.0-draft"

package/spec/manifest.md

@@ -61,6 +61,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.
+
 ### `extensions`
 
 **RECOMMENDED:** `extensions` follows the same structural conventions as foundation token files (tokens, mode sets) and **SHOULD** be validated with the same Layer 1 and Layer 2 rules.
@@ -132,6 +142,11 @@ A platform **MAY** declare formatting rules that control how structured name obj
 
 **RECOMMENDED:** Validators resolve `foundationVersion` against a registry or lockfile and report mismatches as errors or warnings per product policy.
 
+**RECOMMENDED:** Validators confirm the resolved `foundationVersion` provides a cascade-format
+dataset (`packages/design-data/*`), not a pre-cascade legacy release predating the structured
+`name` object, mode sets, and UUIDs — a manifest cascaded against a pre-cascade pin is not
+meaningful. Report a pre-cascade pin as an error per product policy.
+
 ## Automated upgrades
 
 **OPTIONAL:** Workflows **MAY** open upgrade PRs when `foundationVersion` lags the latest release; details are out of scope for this document (see [#715](https://github.com/adobe/spectrum-design-data/discussions/715)).

package/spec/mode-sets.md

@@ -27,11 +27,11 @@ A **mode set declaration** is a JSON object describing one axis of variation. It
 
 These mode sets are declared in the `mode-sets/` catalog (see [Mode Set catalog](#mode-set-catalog)) and **SHOULD** be used consistently across Spectrum-compatible datasets:
 
-| `name`        | `modes`                      | `default` | Notes                                                                             |
-| ------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------- |
-| `colorScheme` | `light`, `dark`, `wireframe` | `light`   | Theme / appearance.                                                               |
-| `scale`       | `desktop`, `mobile`          | `desktop` | Density scale. Legacy names; desktop = medium, mobile = large in W3C terminology. |
-| `contrast`    | `regular`, `high`            | `regular` | Accessibility contrast level.                                                     |
+| `name`        | `modes`                      | `default` | Notes                                                                                                                                                        |
+| ------------- | ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `colorScheme` | `light`, `dark`, `wireframe` | `light`   | Theme / appearance.                                                                                                                                          |
+| `scale`       | `desktop`, `mobile`          | `desktop` | Density scale. Legacy names; desktop = medium, mobile = large in W3C terminology.                                                                            |
+| `contrast`    | `regular`, `high`            | `regular` | Accessibility contrast level. iOS platform data authors `increased` as a synonym for `high` — treat the two as the same crosswalk term, not distinct values. |
 
 ## Mode Set catalog