@adobe/design-data-spec 1.2.0 → 1.3.0

package/package.json

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

package/rules/rules.yaml

@@ -415,3 +415,24 @@ rules:
     message: "Token '{token}' has {field} '{value}' which is not declared on component '{component}'"
     spec_ref: spec/component-format.md#options
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-041
+    name: mode-set-restriction-coverage
+    severity: error
+    layer: 2
+    category: completeness
+    rfc: "#806"
+    assert: >
+      When a manifest declares modeSetRestrictions, every token group (tokens sharing the same
+      non-mode-set name object fields) MUST have at least one candidate that survives ALL
+      restrictions simultaneously — i.e. at least one token whose name object either omits
+      each restricted mode set field (wildcard) or sets it to an allowed mode value for every
+      restriction. Restrictions are applied as a conjunction (matching cascade step 0), so a
+      group that satisfies each restriction individually but has no single token satisfying
+      all restrictions at once is also a coverage gap.
+      Sub-checks: (a) a modeSetRestrictions key that names an unknown mode set MUST emit a
+      Warning; (b) an allowed list that excludes the mode set's declared default MUST emit
+      an Error, since the resolver would return None for the default context on that platform.
+    message: "Token group '{base_name}' has no resolvable candidate under manifest mode-set restrictions ({restrictions})"
+    spec_ref: spec/mode-sets.md#platform-restrictions
+    introduced_in: "1.0.0-draft"

package/schemas/manifest.schema.json

@@ -62,6 +62,27 @@
         ]
       }
     },
+    "modeSetRestrictions": {
+      "type": "object",
+      "description": "Restricts the valid mode values for each named mode set on this platform. Keys are mode set names; values declare which modes are allowed.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["allowed"],
+        "properties": {
+          "allowed": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "uniqueItems": true,
+            "description": "Allowed mode values for this mode set. Must be a subset of the mode set's declared modes and must include the mode set's default."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "extensions": {
       "type": "object",
       "description": "Platform-local tokens, mode sets, and formatting rules.",

package/spec/cascade.md

@@ -41,6 +41,7 @@ A **resolution context** is a set of mode set key/value pairs (e.g. `colorScheme
 
 The following outline is **RECOMMENDED** for conforming resolvers:
 
+0. If the manifest declares `modeSetRestrictions`, **drop any candidate** whose name object sets a mode set field to a value not in the manifest’s `allowed` list for that mode set. Candidates that omit a restricted mode set field (wildcard) are **not** dropped. See [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions).
 1. Collect all token candidates whose name object **matches** the context (every specified mode set in the context equals the name object’s mode set field, or the name object omits that mode set where omission means “matches any” per mode set rules).
 2. Filter to candidates at or below the requested layer.
 3. Select the maximum **layer** precedence.

package/spec/manifest.md

@@ -17,12 +17,13 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
 
 ## Optional fields
 
-| Field        | Type            | Description                                                                      |
-| ------------ | --------------- | -------------------------------------------------------------------------------- |
-| `include`    | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize.      |
-| `exclude`    | array of string | Queries removing tokens from the included set.                                   |
-| `overrides`  | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**. |
-| `extensions` | object          | New tokens or mode sets introduced at the platform layer.                        |
+| Field                 | Type            | Description                                                                                                           |
+| --------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `include`             | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize.                                           |
+| `exclude`             | array of string | Queries removing tokens from the included set.                                                                        |
+| `overrides`           | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**.                                      |
+| `extensions`          | object          | New tokens or mode sets introduced at the platform layer.                                                             |
+| `modeSetRestrictions` | object          | Mode set restrictions for this platform; see [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions). |
 
 ### `include` / `exclude`
 

package/spec/mode-sets.md

@@ -57,8 +57,25 @@ Additional mode sets (e.g. `language`, `motion`) **MAY** be declared in a datase
 
 **RECOMMENDED:** Explicit **combination** tokens are used for rare cross-mode-set cases instead of inferring Cartesian products.
 
+## Platform restrictions
+
+A platform manifest **MAY** declare which mode values are valid for a given mode set on that platform. This allows a platform (e.g. iOS) to express that it only supports a subset of modes (e.g. `colorScheme: light`, not `dark`).
+
+**NORMATIVE:** A manifest's `modeSetRestrictions` value **MUST** be an object whose keys are mode set names declared in the dataset. Each value **MUST** be an object with a required `allowed` array of mode value strings. Every mode value in `allowed` **MUST** be a member of the named mode set's `modes`. The mode set's `default` **MUST** be included in `allowed`.
+
+### Resolution semantics
+
+**NORMATIVE:** At resolution time, any token candidate whose name object sets a mode set field to a value **not** in the manifest's `allowed` list for that mode set **MUST** be filtered out before specificity tie-breaking. Tokens whose name object **omits** a restricted mode set field (wildcard) are **not** affected.
+
+This is a pre-filter step, inserted at the start of the [resolution algorithm](cascade.md#resolution-algorithm-informative-outline) before step 1 (context matching).
+
+### Coverage validation
+
+**NORMATIVE:** Validators implementing rule **`SPEC-041`** (`mode-set-restriction-coverage`) **MUST** report an error when a platform manifest's mode set restrictions leave a token group with no resolvable candidate — i.e. every token sharing the same non-mode-set name object fields references a restricted mode value, with no wildcard or allowed-mode alternative available. See `rules/rules.yaml` for the full rule definition.
+
 ## References
 
 * [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
 * [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
 * [#746 — Phase 2: Mode Set declarations (machine-readable)](https://github.com/adobe/spectrum-design-data/issues/746)
+* [#943 — RFC #806: platform mode-set restriction behavior](https://github.com/adobe/spectrum-design-data/issues/943)