@adobe/design-data-spec 4.1.0 → 4.2.0

package/conformance/manifest-extensions/README.md

@@ -4,7 +4,7 @@ Exercises the Layer 2 platform manifest's `extensions/` **directory** loader
 (`packages/design-data-spec/spec/manifest.md#extensions-directory`): a sibling
 `extensions/` tree (or a custom name via the manifest's `extensionsDir` field)
 whose category subdirectories (`tokens/`, `components/`, `fields/`,
-`guidelines/`, `platform-extensions/`, `relationships/`) are discovered,
+`guidelines/`, `mode-sets/`, `platform-extensions/`, `relationships/`) are discovered,
 glob+merged in sorted path order, per-fragment schema-validated, and spliced
 into the manifest before it's applied to the graph.
 
@@ -23,6 +23,7 @@ into the manifest before it's applied to the graph.
     },
     "components": { "present": ["tab-bar-ios"] },
     "fields": { "present": ["hapticStyle"] },
+    "modeSets": { "present": ["interfaceLevel"] },
     "guidelines": { "present": ["ios-haptics"] },
     "tokens": { "orderByUuid": ["<uuid-1>", "<uuid-2>"] }
   }
@@ -42,6 +43,7 @@ Rust SDK drives these fixtures in `sdk/core/src/lib.rs` via the
 | `valid/injects-platform-extension`             | A `platform-extensions/` fragment is injected.                                                                           |
 | `valid/injects-field`                          | A `fields/` fragment is injected.                                                                                        |
 | `valid/injects-guideline`                      | A `guidelines/` fragment is injected.                                                                                    |
+| `valid/injects-mode-set`                       | A `mode-sets/` fragment is injected (declare-or-replace by name).                                                        |
 | `valid/injects-relationship`                   | A `relationships/` plain-add fragment is injected.                                                                       |
 | `valid/override-relationship-by-uuid`          | An `op: "override"` entry replaces a plain add sharing its `uuid`, regardless of file sort order.                        |
 | `valid/plain-add-uuid-collision-append`        | Two plain adds sharing a `uuid` both append rather than one overwriting the other.                                       |
@@ -55,6 +57,7 @@ Rust SDK drives these fixtures in `sdk/core/src/lib.rs` via the
 | `invalid/component-missing-name`               | A `components/` fragment missing `name` fails Layer 1 fragment schema validation.                                        |
 | `invalid/field-invalid-kind`                   | A `fields/` fragment with an invalid `kind` enum value fails schema validation.                                          |
 | `invalid/guideline-invalid-category`           | A `guidelines/` fragment with an invalid `category` enum value fails schema validation.                                  |
+| `invalid/mode-set-missing-default`             | A `mode-sets/` fragment missing the required `default` field fails Layer 1 fragment schema validation.                   |
 | `invalid/platform-extension-missing-extends`   | A `platform-extensions/` fragment missing `extends` fails schema validation.                                             |
 | `invalid/token-invalid-uuid`                   | A `tokens/*.tokens.json` fragment with a malformed `uuid` fails schema validation.                                       |
 | `invalid/relationship-missing-scope`           | A `relationships/` plain-add fragment missing `scope` fails schema validation.                                           |

package/conformance/manifest-extensions/invalid/mode-set-missing-default/expected-errors.json

@@ -0,0 +1,7 @@
+{
+  "errors": [
+    { "message_pattern": "broken\\.json" },
+    { "message_pattern": "mode-set\\.schema\\.json" },
+    { "message_pattern": "\"default\"" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-missing-default/extensions/mode-sets/broken.json

@@ -0,0 +1 @@
+{ "name": "interfaceLevel", "modes": ["base", "elevated"] }

package/conformance/manifest-extensions/invalid/mode-set-missing-default/manifest.json

@@ -0,0 +1,4 @@
+{
+  "specVersion": "1.0.0-draft",
+  "foundationVersion": "1.0.0"
+}

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "removeMode" },
+    { "message_pattern": "current default" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/extensions/mode-sets/remove-desktop.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "removeMode", "mode": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-remove-mode-of-default/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "setDefault" },
+    { "message_pattern": "not in its modes" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/extensions/mode-sets/default-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "setDefault", "default": "tv" }

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-set-default-nonmember/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/invalid/mode-set-target-not-found/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "\"scale\"" },
+    { "message_pattern": "does not exist" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-target-not-found/extensions/mode-sets/add-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "addMode", "mode": "tv" }

package/conformance/manifest-extensions/invalid/mode-set-target-not-found/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/expected-errors.json

@@ -0,0 +1,6 @@
+{
+  "errors": [
+    { "message_pattern": "unknown op" },
+    { "message_pattern": "\"bogus\"" }
+  ]
+}

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/extensions/mode-sets/bogus.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "bogus" }

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/invalid/mode-set-unknown-op/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/injects-mode-set/expected.json

@@ -0,0 +1 @@
+{ "modeSets": { "present": ["interfaceLevel"] } }

package/conformance/manifest-extensions/valid/injects-mode-set/extensions/mode-sets/interface-level.json

@@ -0,0 +1,5 @@
+{
+  "name": "interfaceLevel",
+  "modes": ["base", "elevated"],
+  "default": "base"
+}

package/conformance/manifest-extensions/valid/injects-mode-set/manifest.json

@@ -0,0 +1,4 @@
+{
+  "specVersion": "1.0.0-draft",
+  "foundationVersion": "1.0.0"
+}

package/conformance/manifest-extensions/valid/mode-set-add-mode/expected.json

@@ -0,0 +1,8 @@
+{
+  "modeSets": {
+    "present": ["scale"],
+    "modes": {
+      "scale": { "modes": ["desktop", "mobile", "tv"], "default": "desktop" }
+    }
+  }
+}

package/conformance/manifest-extensions/valid/mode-set-add-mode/extensions/mode-sets/add-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "addMode", "mode": "tv" }

package/conformance/manifest-extensions/valid/mode-set-add-mode/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile"], "default": "desktop" }

package/conformance/manifest-extensions/valid/mode-set-add-mode/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/mode-set-remove/expected.json

@@ -0,0 +1 @@
+{ "modeSets": { "absent": ["contrast"] } }

package/conformance/manifest-extensions/valid/mode-set-remove/extensions/mode-sets/contrast.json

@@ -0,0 +1 @@
+{ "name": "contrast", "modes": ["regular", "high"], "default": "regular" }

package/conformance/manifest-extensions/valid/mode-set-remove/extensions/mode-sets/remove-contrast.json

@@ -0,0 +1 @@
+{ "name": "contrast", "op": "remove" }

package/conformance/manifest-extensions/valid/mode-set-remove/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/mode-set-remove-mode/expected.json

@@ -0,0 +1,8 @@
+{
+  "modeSets": {
+    "present": ["colorScheme"],
+    "modes": {
+      "colorScheme": { "modes": ["light", "dark"], "default": "light" }
+    }
+  }
+}

package/conformance/manifest-extensions/valid/mode-set-remove-mode/extensions/mode-sets/color-scheme.json

@@ -0,0 +1,5 @@
+{
+  "name": "colorScheme",
+  "modes": ["light", "dark", "wireframe"],
+  "default": "light"
+}

package/conformance/manifest-extensions/valid/mode-set-remove-mode/extensions/mode-sets/remove-wireframe.json

@@ -0,0 +1 @@
+{ "name": "colorScheme", "op": "removeMode", "mode": "wireframe" }

package/conformance/manifest-extensions/valid/mode-set-remove-mode/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/conformance/manifest-extensions/valid/mode-set-set-default/expected.json

@@ -0,0 +1,6 @@
+{
+  "modeSets": {
+    "present": ["scale"],
+    "modes": { "scale": { "default": "tv" } }
+  }
+}

package/conformance/manifest-extensions/valid/mode-set-set-default/extensions/mode-sets/default-tv.json

@@ -0,0 +1 @@
+{ "name": "scale", "op": "setDefault", "default": "tv" }

package/conformance/manifest-extensions/valid/mode-set-set-default/extensions/mode-sets/scale.json

@@ -0,0 +1 @@
+{ "name": "scale", "modes": ["desktop", "mobile", "tv"], "default": "desktop" }

package/conformance/manifest-extensions/valid/mode-set-set-default/manifest.json

@@ -0,0 +1 @@
+{ "specVersion": "1.0.0-draft", "foundationVersion": "1.0.0" }

package/package.json

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

package/spec/manifest.md

@@ -8,23 +8,25 @@ This document defines the **platform manifest**: how a platform implementation r
 
 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.
 
-| Operation                                          | Supported?                                                   | Field                             | Applies to            |
-| -------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | --------------------- |
-| Remove / exclude                                   | Yes                                                          | `exclude`                         | Tokens only           |
-| Include / whitelist                                | Yes                                                          | `include`                         | Tokens only           |
-| Override value (type-preserving)                   | Yes                                                          | `overrides[].value`               | Tokens only           |
-| Override → re-alias                                | Yes                                                          | `overrides[].$ref`                | Tokens only           |
-| Add new tokens (may alias via `$ref`)              | Yes                                                          | `extensions/tokens/`              | Tokens                |
-| Add / replace components                           | Yes                                                          | `extensions/components/`          | Components            |
-| Add / replace field declarations                   | Yes                                                          | `extensions/fields/`              | Fields                |
-| Add / replace guideline documents                  | Yes                                                          | `extensions/guidelines/`          | Guidelines            |
-| Add relationships/CTRs; override/remove by `uuid`  | Yes                                                          | `extensions/relationships/`       | Relationships (CTRs)  |
-| Add / remove naming exceptions                     | Yes                                                          | `namingExceptions`                | Naming validation     |
-| Annotate existing terminology (cannot add new ids) | Yes                                                          | `extensions/platform-extensions/` | Existing registry ids |
-| Restrict allowed mode-set values                   | Yes                                                          | `modeSetRestrictions`             | Mode sets             |
-| Reformat name serialization                        | Schema-declared only, not yet applied by the reference SDK   | `formatting`                      | Token name strings    |
-| Override/remove/alias translations                 | No                                                           | —                                 | —                     |
-| Override Layer-1 schemas                           | No (decided; see [spike](manifest-schema-override-spike.md)) | —                                 | —                     |
+| Operation                                           | Supported?                                                   | Field                             | Applies to            |
+| --------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | --------------------- |
+| Remove / exclude                                    | Yes                                                          | `exclude`                         | Tokens only           |
+| Include / whitelist                                 | Yes                                                          | `include`                         | Tokens only           |
+| Override value (type-preserving)                    | Yes                                                          | `overrides[].value`               | Tokens only           |
+| Override → re-alias                                 | Yes                                                          | `overrides[].$ref`                | Tokens only           |
+| Add new tokens (may alias via `$ref`)               | Yes                                                          | `extensions/tokens/`              | Tokens                |
+| Add / replace components                            | Yes                                                          | `extensions/components/`          | Components            |
+| Add / replace field declarations                    | Yes                                                          | `extensions/fields/`              | Fields                |
+| Add / replace guideline documents                   | Yes                                                          | `extensions/guidelines/`          | Guidelines            |
+| Declare / replace platform-local mode set           | Yes                                                          | `extensions/mode-sets/`           | Mode sets             |
+| Add / remove / retarget a single mode; remove a set | Yes                                                          | `extensions/mode-sets/` (`op`)    | Mode sets             |
+| Add relationships/CTRs; override/remove by `uuid`   | Yes                                                          | `extensions/relationships/`       | Relationships (CTRs)  |
+| Add / remove naming exceptions                      | Yes                                                          | `namingExceptions`                | Naming validation     |
+| Annotate existing terminology (cannot add new ids)  | Yes                                                          | `extensions/platform-extensions/` | Existing registry ids |
+| Restrict allowed mode-set values                    | Yes                                                          | `modeSetRestrictions`             | Mode sets             |
+| Reformat name serialization                         | Schema-declared only, not yet applied by the reference SDK   | `formatting`                      | Token name strings    |
+| Override/remove/alias translations                  | No                                                           | —                                 | —                     |
+| Override Layer-1 schemas                            | No (decided; see [spike](manifest-schema-override-spike.md)) | —                                 | —                     |
 
 ## Manifest document
 
@@ -86,6 +88,7 @@ extensions/
   tokens/               *.tokens.json          cascade-format token files
   components/           <component>.json       one component per file
   fields/                <field>.json          one field declaration per file
+  mode-sets/             <mode-set>.json       one mode set per file
   relationships/         <component>.json      one CTR set per file
   guidelines/             <topic>.json         one guideline per file
   platform-extensions/   <platform>-<registry>.json
@@ -103,7 +106,7 @@ or empty subdirectory contributes nothing and is not an error.
   cascade token file) and **MUST** validate against `cascade-file.schema.json`. Files are
   **deep-merged** into one tokens object, in sorted path order. Entries **MAY** carry a `$ref`
   to alias an existing token instead of a literal value.
-* **`components/`, `fields/`, `guidelines/`, `platform-extensions/`** — one artifact per file.
+* **`components/`, `fields/`, `guidelines/`, `mode-sets/`, `platform-extensions/`** — one artifact per file.
   Entries across all files in the subdirectory are concatenated, in sorted path order, and
   injected into the corresponding catalog **add-or-replace by name** (for
   `platform-extensions/`, by `termId`; see below). When two files declare the same name,
@@ -115,6 +118,7 @@ load time — this is enforced reference-SDK behavior, not an aspirational goal:
 * **`components/`** → `component.schema.json`
 * **`fields/`** → `field.schema.json` (see [`extensions/fields/`](#extensionsfields) below)
 * **`guidelines/`** → `guideline.schema.json`
+* **`mode-sets/`** → `mode-set.schema.json` (see [`extensions/mode-sets/`](#extensionsmode-sets) below)
 * **`relationships/`** → `relationship.schema.json` (see the Add/Override/remove rules above)
 * **`platform-extensions/`** → `platform-extension.json` (see
   [`extensions/platform-extensions/`](#extensionsplatform-extensions) below)
@@ -143,6 +147,45 @@ declared) references field names by string — a platform that renames or remove
 also references there is self-inconsistent; that is a manifest-authoring concern, not enforced
 by the reference SDK.
 
+#### `extensions/mode-sets/`
+
+Platform-local mode-set declarations and edits, injected into the mode-set catalog for this
+platform's resolution. A mode set's `name` is its stable key (there is no separate `uuid`, unlike
+relationships) — every entry, add or op alike, identifies its target by `name`:
+
+* **Add / replace:** an entry with no `op` field is a full mode-set object (**NORMATIVE:** MUST
+  validate against `mode-set.schema.json`, requiring `name`, `modes`, `default`). A `name` not
+  already in the foundation catalog is a clean new platform axis (e.g. `interfaceLevel: [base,
+  elevated]`); a `name` matching a foundation mode set replaces it, for this platform only — the
+  foundation catalog is untouched.
+* **`"op": "addMode"`** — appends one mode value (`mode`) to an existing set, without restating its
+  other modes. **NORMATIVE:** the target set (by `name`) MUST already exist and MUST NOT already
+  contain `mode`; either condition failing is a manifest error.
+* **`"op": "removeMode"`** — drops one mode value (`mode`) from an existing set. **NORMATIVE:** the
+  target MUST exist, MUST contain `mode`, `mode` MUST NOT be the set's current default (retarget the
+  default first with `setDefault`), the set MUST have more than one mode remaining afterward, and no
+  token in the resolved graph MAY still carry `mode` as that mode set's value — each violation is a
+  manifest error. (This mirrors the reference SDK's authoring-time `remove_mode` guard, which checks
+  the same "still referenced" condition against cascade token files.)
+* **`"op": "setDefault"`** — retargets an existing set's default mode (`default`). **NORMATIVE:**
+  the target MUST exist and `default` MUST already be one of its modes.
+* **`"op": "remove"`** — drops the whole set (by `name`) from this platform's resolution.
+  **NORMATIVE:** the target MUST exist, and no token in the resolved graph MAY still carry this mode
+  set's `name` as a key — either violation is a manifest error.
+
+Add/replace entries are applied before op entries, regardless of file sort order, so a set declared
+in one file can be edited by an op in another file within the same `extensions/mode-sets/`
+directory. Ops within each group apply in sorted path order. Any other `op` value, or an op entry
+missing its required field (`mode` for `addMode`/`removeMode`, `default` for `setDefault`), is a
+manifest error — the reference SDK rejects the load rather than silently skipping it, consistent
+with `extensions/relationships/`'s override/remove ops above. `default ∈ modes` remains a Layer 2
+concern for the resolved graph as a whole, enforced by SPEC-005 against whichever mode sets end up
+there, foundation or platform-declared alike.
+
+Contrast with `modeSetRestrictions` ([Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions)), a top-level manifest field that only *narrows* the allowed values of an
+existing mode set at resolution time — it cannot add, remove, or retarget a mode value, or declare
+a new axis.
+
 #### `extensions/platform-extensions/`
 
 Platform terminology annotations layered onto **existing** foundation registry entries (for

package/spec/mode-sets.md

@@ -45,6 +45,16 @@ The Spectrum foundation publishes mode set declarations as JSON files under `pac
 
 Additional mode sets (e.g. `language`, `motion`) **MAY** be declared in a dataset's mode set catalog. Token name objects **MAY** include keys matching declared mode set names.
 
+A platform manifest **MAY** also declare or edit mode sets local to that platform, one entry per
+file under `extensions/mode-sets/` (see [Platform manifest — `extensions/`
+directory](manifest.md#extensions-directory)). An entry with no `op` uses **declare-or-replace-by-name** semantics, same as `extensions/fields/`: a new `name` adds a platform-local axis (e.g.
+`interfaceLevel`), while a `name` matching a foundation mode set replaces it for that platform only,
+leaving the foundation catalog untouched. `op: "addMode"` / `"removeMode"` / `"setDefault"` /
+`"remove"` instead edit an existing set in place — adding or dropping a single mode value,
+retargeting its default, or dropping the whole set — without restating its other modes. This is
+distinct from `modeSetRestrictions` (below), which only *narrows* the allowed values of an existing
+mode set at resolution time rather than editing the declared set itself.
+
 ## Defaults and specificity
 
 **NORMATIVE:** A token name object **omitting** a mode set field implies the token applies under the mode set's **`default`** mode for specificity and matching purposes unless the spec for that mode set states otherwise.