@adobe/design-data-spec 1.3.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.3.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

@@ -436,3 +436,40 @@ rules:
     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

@@ -108,7 +108,13 @@
                   "size",
                   "density",
                   "shape",
-                  "state"
+                  "state",
+                  "colorFamily",
+                  "family",
+                  "weight",
+                  "style",
+                  "motionRole",
+                  "easing"
                 ]
               },
               "uniqueItems": true,

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