@adobe/design-data-spec 1.2.0 → 1.4.0

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

@@ -0,0 +1,21 @@
+{
+  "tokens": [
+    {
+      "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/font-weight.json",
+      "name": {
+        "property": "font-weight",
+        "colorFamily": "blue"
+      },
+      "value": "bold"
+    },
+    {
+      "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+      "name": {
+        "property": "color",
+        "weight": "bold"
+      },
+      "value": "#0265dc"
+    }
+  ],
+  "components": []
+}

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

@@ -0,0 +1,15 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-042",
+      "severity": "warning",
+      "message_pattern": ".*colorFamily.*color-scoped.*font-weight.*"
+    },
+    {
+      "rule_id": "SPEC-042",
+      "severity": "warning",
+      "message_pattern": ".*weight.*typography-scoped.*color.*"
+    }
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "tokens": [
+    {
+      "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+      "name": {
+        "property": "color",
+        "state": "hover"
+      },
+      "value": "#0265dc"
+    },
+    {
+      "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/font-weight.json",
+      "name": {
+        "property": "font-weight"
+      },
+      "value": "bold"
+    }
+  ],
+  "components": []
+}

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

@@ -0,0 +1,15 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-043",
+      "severity": "warning",
+      "message_pattern": ".*color.*no domain-identifying field.*colorFamily.*"
+    },
+    {
+      "rule_id": "SPEC-043",
+      "severity": "warning",
+      "message_pattern": ".*typography.*no domain-identifying field.*family.*"
+    }
+  ]
+}

package/fields/colorFamily.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "colorFamily",
+  "description": "Hue family of a color token (e.g. blue, gray, celery, accent). Used on color palette and semantic color tokens. Paired with scaleIndex for ramp tokens (e.g. colorFamily=blue + scaleIndex=100 → blue-100).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/color-families.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 17
+  },
+  "scope": "color",
+  "required": false,
+  "valueType": "string"
+}

package/fields/easing.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "easing",
+  "description": "Easing curve identifier for a motion token (e.g. ease-in, ease-out, standard). Registry is provisional until motion tokens are added to the foundation.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/easing-curves.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 22
+  },
+  "scope": "motion",
+  "required": false,
+  "valueType": "string"
+}

package/fields/family.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "family",
+  "description": "Type family of a typography token (e.g. sans-serif, serif, cjk, code). Used to distinguish tokens that apply to different script or display contexts.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/typography-families.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 18
+  },
+  "scope": "typography",
+  "required": false,
+  "valueType": "string"
+}

package/fields/motionRole.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "motionRole",
+  "description": "Semantic role of a motion token — the interaction pattern it governs (e.g. enter, exit, transition, emphasis). Registry is provisional until motion tokens are added to the foundation.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/motion-roles.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 21
+  },
+  "scope": "motion",
+  "required": false,
+  "valueType": "string"
+}

package/fields/scaleIndex.json

@@ -7,7 +7,7 @@
   "registry": null,
   "validation": "none",
   "serialization": {
-    "position": 16
+    "position": 99
   },
   "scope": null,
   "required": false,

package/fields/style.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "style",
+  "description": "Typographic style of a typography token (e.g. italic, oblique). Corresponds to the CSS font-style axis. Normal style is omitted (default).",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/typography-styles.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 20
+  },
+  "scope": "typography",
+  "required": false,
+  "valueType": "string"
+}

package/fields/weight.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
+  "specVersion": "1.0.0-draft",
+  "name": "weight",
+  "description": "Typographic weight of a typography token (e.g. regular, bold, light, black). Corresponds to the CSS font-weight axis.",
+  "kind": "semantic",
+  "registry": "packages/design-system-registry/registry/typography-weights.json",
+  "validation": "advisory",
+  "serialization": {
+    "position": 19
+  },
+  "scope": "typography",
+  "required": false,
+  "valueType": "string"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "1.2.0",
+  "version": "1.4.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,61 @@ 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"
+
+  - id: SPEC-042
+    name: field-scope-violation
+    severity: warning
+    layer: 2
+    category: taxonomy
+    rfc: "#806"
+    assert: >
+      When a token's name object contains a domain-scoped field (e.g. `colorFamily`,
+      `weight`, `motionRole`), the token's `$schema` MUST reference a compatible token
+      type for that domain. Using a color-scoped field on a typography token, or a
+      typography-scoped field on a color token, is a taxonomy violation. The set of
+      domain-scoped fields and their valid schema URL suffixes is declared in the field
+      catalog under `packages/design-data-spec/fields/` via the `scope` property.
+      Tokens without a `$schema` are skipped (domain cannot be determined).
+    message: "name.{field} is a {scope}-scoped field but token schema '{schema_url}' is not a {scope} token type"
+    spec_ref: spec/taxonomy.md#token-type-taxonomies
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-043
+    name: domain-required-fields
+    severity: warning
+    layer: 2
+    category: taxonomy
+    rfc: "#806"
+    assert: >
+      Tokens in a known domain SHOULD include at least one domain-identifying field in
+      their name object so tooling can group, sort, and validate them correctly.
+      Color tokens (schema: color.json, color-set.json) SHOULD have `colorFamily` or
+      `scaleIndex`. Typography tokens (schema: font-*.json, typography.json) SHOULD have
+      `family`, `weight`, or `style`. Motion tokens (schema: duration.json, motion.json)
+      SHOULD have `motionRole` or `easing`. String-named tokens and tokens without `$schema`
+      are skipped. Advisory severity: the existing corpus has not yet migrated to structured
+      name objects; this rule tracks progress rather than blocking.
+    message: "{domain} token has a name object but no domain-identifying field — add at least one of: {required_fields}"
+    spec_ref: spec/taxonomy.md#token-type-taxonomies
+    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.",
@@ -87,7 +108,13 @@
                   "size",
                   "density",
                   "shape",
-                  "state"
+                  "state",
+                  "colorFamily",
+                  "family",
+                  "weight",
+                  "style",
+                  "motionRole",
+                  "easing"
                 ]
               },
               "uniqueItems": true,

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)

package/spec/taxonomy.md

@@ -46,13 +46,17 @@ The taxonomy is designed with three guiding principles:
 2. **Agnostic (with compromises)** — Platform-agnostic terms are used except when platforms have specific terms for the same concept. In those cases, the most common or clear term is used.
 3. **Verified** — Multiple existing components must be rebuildable using the taxonomy system, and consumers must find them reasonably understandable or learnable.
 
-## Semantic / layout token taxonomy
+## Token-type taxonomies
 
-Concept categories for name-object fields are declared in the design system's **field catalog** — a set of field declarations in the `fields/` directory, each conforming to [`field.schema.json`](../schemas/field.schema.json). Each declaration specifies the field name, vocabulary registry, validation severity, and default serialization position.
+Concept categories for name-object fields are declared in the design system's **field catalog** — a set of field declarations in the `fields/` directory, each conforming to [`field.schema.json`](../schemas/field.schema.json). Each declaration specifies the field name, vocabulary registry, validation severity, default serialization position, and an optional **scope** that restricts the field to a specific token type.
 
 **NORMATIVE:** The field catalog is the authoritative source for what fields exist on the name object. Tools, validators, and serializers **SHOULD** read the catalog rather than hardcoding field knowledge.
 
-The following concept categories are defined in Spectrum's foundation field catalog for semantic and layout tokens, ordered by default serialization position. This ordering is the **default serialization order** for legacy format output; it is not a conformance requirement for stored name objects.
+**NORMATIVE:** A field with a non-null `scope` declaration **MUST** only appear on tokens of that type. Using a scoped field on a mismatched token type triggers rule SPEC-042 (`field-scope-violation`, warning).
+
+### Semantic / layout token taxonomy
+
+The following concept categories are defined in Spectrum's foundation field catalog for semantic and layout tokens (`scope: null` — universal), ordered by default serialization position. This ordering is the **default serialization order** for legacy format output; it is not a conformance requirement for stored name objects.
 
 **NORMATIVE:** Each category listed below corresponds to a field on the token [name object](token-format.md). Tokens **MAY** use any subset of these fields. Exception: `property` is REQUIRED on every name object — see [token-format.md](token-format.md#name-object).
 
@@ -77,7 +81,67 @@ Additional categories for variant and state are inherited from the existing name
 | Variant  | `variant`         | Variant within a component (e.g. accent, negative, primary). |
 | State    | `state`           | Interactive or semantic state (e.g. hover, focus, disabled). |
 
-**NOTE:** The categories above are filtered for semantic and layout token taxonomies. Additional taxonomies for other token types (color, typography, motion) will be defined in future spec versions — see the open follow-up RFC discussion [#806](https://github.com/adobe/spectrum-design-data/discussions/806) (Q3, taxonomy scoping). The taxonomy is built to scale as new concepts and terms are identified.
+### Color token taxonomy
+
+Color tokens describe palette entries and semantic color assignments. Their name objects use `scope: "color"` fields alongside the universal `property` and `state` fields.
+
+**NORMATIVE:** Color tokens SHOULD include `colorFamily`, `scaleIndex`, or both to allow tooling to group and sort palette entries. Tokens missing both are flagged by rule SPEC-043 (`domain-required-fields`, warning).
+
+| Category     | Name object field | Answers | Description                                                                                                                                                                                 |
+| ------------ | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Color Family | `colorFamily`     | What?   | Hue family of the color (e.g. `blue`, `gray`, `celery`, `transparent-black`). Values come from [`color-families.json`](../../packages/design-system-registry/registry/color-families.json). |
+| Ramp Index   | `scaleIndex`      | Which?  | Numeric perceptual ramp step (e.g. `100`, `400`, `900`, `1600`). Shared with layout tokens; see [scaleIndex field declaration](../fields/scaleIndex.json). Not scope-restricted.            |
+
+**Default serialization order for color tokens:**
+
+```
+{variant}-{colorFamily}-{scaleIndex}
+```
+
+Example: `colorFamily=blue` + `scaleIndex=100` → `blue-100`.
+
+### Typography token taxonomy
+
+Typography tokens describe typeface attributes: family, weight, style, and numeric scale. Their name objects use `scope: "typography"` fields alongside the universal `property` field.
+
+**NORMATIVE:** Typography tokens SHOULD include at least one of `family`, `weight`, or `style`. Tokens missing all three are flagged by rule SPEC-043 (`domain-required-fields`, warning).
+
+| Category | Name object field | Answers | Description                                                                                                                                                                                                             |
+| -------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Family   | `family`          | What?   | Type family of the token (e.g. `sans-serif`, `serif`, `cjk`, `code`). Values come from [`typography-families.json`](../../packages/design-system-registry/registry/typography-families.json).                           |
+| Weight   | `weight`          | How?    | Typographic weight (e.g. `regular`, `bold`, `light`, `black`). Values come from [`typography-weights.json`](../../packages/design-system-registry/registry/typography-weights.json).                                    |
+| Style    | `style`           | How?    | Typographic style when non-default (e.g. `italic`, `oblique`). Omit the field when style is normal. Values come from [`typography-styles.json`](../../packages/design-system-registry/registry/typography-styles.json). |
+| Scale    | `scaleIndex`      | Which?  | Numeric size scale step (e.g. `75`, `100`, `200`). Shared with other token types; not scope-restricted.                                                                                                                 |
+
+**Default serialization order for typography tokens:**
+
+```
+{family}-{weight}-{style}-{scaleIndex}
+```
+
+Example: `family=sans-serif` + `weight=bold` → `sans-serif-bold`. `family=sans-serif` + `style=italic` + `scaleIndex=100` → `sans-serif-italic-100`.
+
+### Motion token taxonomy
+
+Motion tokens describe timing, easing, and animation role for UI animation. Their name objects use `scope: "motion"` fields alongside the universal `property` field.
+
+**NOTE:** No motion tokens exist in the foundation dataset at the time of this writing. This taxonomy is normative but the registry values for `motionRole` and `easing` are provisional — they will be refined when motion tokens are added to the foundation. Validators emit SPEC-043 at warning severity so provisional tokens are not blocked.
+
+**NORMATIVE:** Motion tokens SHOULD include `motionRole` or `easing`. Tokens missing both are flagged by rule SPEC-043 (`domain-required-fields`, warning).
+
+| Category    | Name object field | Answers | Description                                                                                                                                                                                |
+| ----------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Motion Role | `motionRole`      | What?   | Semantic role of the animation (e.g. `enter`, `exit`, `transition`, `emphasis`). Values come from [`motion-roles.json`](../../packages/design-system-registry/registry/motion-roles.json). |
+| Easing      | `easing`          | How?    | Easing curve identifier (e.g. `ease-in`, `ease-out`, `standard`). Values come from [`easing-curves.json`](../../packages/design-system-registry/registry/easing-curves.json).              |
+| Duration    | `scaleIndex`      | Which?  | Numeric duration bucket index (e.g. `100` for 100ms, `200` for 200ms). Shared with other token types; not scope-restricted.                                                                |
+
+**Default serialization order for motion tokens:**
+
+```
+{motionRole}-{easing}-{scaleIndex}
+```
+
+Example: `motionRole=enter` + `easing=ease-out` → `enter-ease-out`. `motionRole=transition` + `scaleIndex=100` → `transition-100`.
 
 ### Structure vs. component — when does the line move?
 
@@ -177,7 +241,7 @@ The taxonomy and terms are built to scale as new concepts and terms are identifi
 
 * New concept categories **MAY** be added by creating a new field declaration file in the field catalog — no spec version change is required for the mechanism itself.
 * New terms **MAY** be added to the vocabulary registry without spec version changes.
-* New token type taxonomies (beyond semantic/layout) **MAY** be defined in future spec versions.
+* New token type taxonomies **MAY** be added by creating scoped field declarations (non-null `scope`) and a corresponding registry section in taxonomy.md. Color, typography, and motion taxonomies are defined above.
 * Platform manifests **MAY** extend the vocabulary with platform-specific terms and formatting.
 
 ## References

package/spec/token-format.md

@@ -51,6 +51,10 @@ Fields are divided into **semantic fields** (identity, structure, intent) and **
 
 #### Semantic fields
 
+The table below lists all semantic fields. Fields marked with a scope are domain-restricted — see [Taxonomy — Token-type taxonomies](taxonomy.md#token-type-taxonomies) for the normative per-domain field rules and serialization orders. Validators enforce scope restrictions via rule SPEC-042.
+
+**Universal semantic fields** (`scope: null` — apply to all token types):
+
 | Field          | Status   | Taxonomy category | Description                                                                                                                                                              |
 | -------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `property`     | REQUIRED | Property          | The stylistic attribute being defined (e.g. `color`, `width`, `padding`, `gap`).                                                                                         |
@@ -66,6 +70,18 @@ Fields are divided into **semantic fields** (identity, structure, intent) and **
 | `size`         | OPTIONAL | Size              | Relative t-shirt sizing for relationships across tokens (e.g. `small`, `medium`, `large`).                                                                               |
 | `density`      | OPTIONAL | Density           | Space within or around component parts (e.g. `spacious`, `compact`).                                                                                                     |
 | `shape`        | OPTIONAL | Shape             | Relative to overall component shape (e.g. `uniform`).                                                                                                                    |
+| `scaleIndex`   | OPTIONAL | —                 | Numeric scale index appended at the end of the serialized name (e.g. `100`, `200`, `900`). Used by color palette, spacing, font-size, and motion duration tokens.        |
+
+**Domain-scoped semantic fields** (only valid on the indicated token type):
+
+| Field         | Status   | Scope        | Description                                                                                                                                 |
+| ------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `colorFamily` | OPTIONAL | `color`      | Hue family of the color (e.g. `blue`, `gray`, `cyan`). See [Taxonomy — Color token taxonomy](taxonomy.md#color-token-taxonomy).             |
+| `family`      | OPTIONAL | `typography` | Type family (e.g. `sans-serif`, `serif`, `cjk`, `code`). See [Taxonomy — Typography token taxonomy](taxonomy.md#typography-token-taxonomy). |
+| `weight`      | OPTIONAL | `typography` | Typographic weight (e.g. `regular`, `bold`, `light`). See [Taxonomy — Typography token taxonomy](taxonomy.md#typography-token-taxonomy).    |
+| `style`       | OPTIONAL | `typography` | Typographic style when non-default (e.g. `italic`). See [Taxonomy — Typography token taxonomy](taxonomy.md#typography-token-taxonomy).      |
+| `motionRole`  | OPTIONAL | `motion`     | Semantic animation role (e.g. `enter`, `exit`, `transition`). See [Taxonomy — Motion token taxonomy](taxonomy.md#motion-token-taxonomy).    |
+| `easing`      | OPTIONAL | `motion`     | Easing curve identifier (e.g. `ease-out`, `standard`). See [Taxonomy — Motion token taxonomy](taxonomy.md#motion-token-taxonomy).           |
 
 #### Mode-set fields