@adobe/design-data-spec 0.9.0 → 0.10.0

package/conformance/valid/SPEC-029/dataset.json

@@ -0,0 +1,24 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "documentBlocks": [
+        {
+          "type": "purpose",
+          "content": "Triggers an action when clicked."
+        },
+        {
+          "type": "usage",
+          "content": "Place in forms and dialogs."
+        }
+      ]
+    }
+  ]
+}

package/conformance/valid/SPEC-030/dataset.json

@@ -0,0 +1,17 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "accessibility": {
+        "role": "button"
+      }
+    }
+  ]
+}

package/conformance/valid/SPEC-031/dataset.json

@@ -0,0 +1,24 @@
+{
+  "tokens": [],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "accessibility": {
+        "role": "button",
+        "wcag": [
+          {
+            "criterion": "1.4.3",
+            "level": "AA",
+            "notes": "Meets minimum contrast."
+          }
+        ]
+      }
+    }
+  ]
+}

package/conformance/valid/SPEC-032/dataset.json

@@ -0,0 +1,16 @@
+{
+  "tokens": [
+    {
+      "name": { "property": "background-color-default" },
+      "value": "#ffffff",
+      "uuid": "dddddddd-0032-4000-8000-000000000001"
+    },
+    {
+      "name": { "property": "background-color-default" },
+      "value": "#eeeeee",
+      "uuid": "dddddddd-0032-4000-8000-000000000001",
+      "$layer": "product"
+    }
+  ],
+  "components": []
+}

package/conformance/valid/component-refs/README.md

@@ -0,0 +1,5 @@
+# component-refs
+
+Regression fixture for the valid-fixture conformance harness. Not tied to a specific SPEC rule.
+
+Contains a realistic button component declaration paired with tokens that reference it, asserting that the full rule set produces zero errors against a well-formed component + token dataset. Guards against new rules accidentally flagging valid cross-reference patterns.

package/conformance/valid/component-with-accessibility.json

@@ -0,0 +1,32 @@
+{
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "accessibility": {
+        "role": "button",
+        "intents": ["trigger"],
+        "focusable": true,
+        "keyboardIntents": ["activate"],
+        "wcag": [
+          { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
+        ]
+      },
+      "states": [
+        {
+          "name": "disabled",
+          "trigger": "prop",
+          "precedence": 100,
+          "announce": "Button disabled",
+          "communicates": "disabled",
+          "blocksInteraction": true
+        }
+      ]
+    }
+  ]
+}

package/fields/color-scheme.json

@@ -2,8 +2,8 @@
   "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
   "specVersion": "1.0.0-draft",
   "name": "colorScheme",
-  "description": "Theme / appearance dimension. Controls which color scheme a token applies to (e.g. light, dark, wireframe). Drives cascade resolution.",
-  "kind": "dimension",
+  "description": "Theme / appearance mode set. Controls which color scheme a token applies to (e.g. light, dark, wireframe). Drives cascade resolution.",
+  "kind": "mode-set",
   "registry": null,
   "validation": "strict",
   "serialization": {

package/fields/contrast.json

@@ -2,8 +2,8 @@
   "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
   "specVersion": "1.0.0-draft",
   "name": "contrast",
-  "description": "Contrast level dimension (e.g. regular, high). Drives cascade resolution.",
-  "kind": "dimension",
+  "description": "Contrast level mode set (e.g. regular, high). Drives cascade resolution.",
+  "kind": "mode-set",
   "registry": null,
   "validation": "strict",
   "serialization": {

package/fields/density.json

@@ -2,7 +2,7 @@
   "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
   "specVersion": "1.0.0-draft",
   "name": "density",
-  "description": "Space density within or around component parts (e.g. spacious, compact). Distinct from the dimension scale field.",
+  "description": "Space density within or around component parts (e.g. spacious, compact). Distinct from the `scale` mode set.",
   "kind": "semantic",
   "registry": "packages/design-system-registry/registry/densities.json",
   "validation": "advisory",

package/fields/scale.json

@@ -2,8 +2,8 @@
   "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
   "specVersion": "1.0.0-draft",
   "name": "scale",
-  "description": "Platform density scale dimension (e.g. desktop, mobile). Drives cascade resolution.",
-  "kind": "dimension",
+  "description": "Platform density scale mode set (e.g. desktop, mobile). Drives cascade resolution.",
+  "kind": "mode-set",
   "registry": null,
   "validation": "strict",
   "serialization": {

package/fields/size.json

@@ -2,7 +2,7 @@
   "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/field.schema.json",
   "specVersion": "1.0.0-draft",
   "name": "size",
-  "description": "Relative t-shirt sizing of a component or token (e.g. small, medium, large, extra-large). Distinct from dimension scale.",
+  "description": "Relative t-shirt sizing of a component or token (e.g. small, medium, large, extra-large). Distinct from the `scale` mode set.",
   "kind": "semantic",
   "registry": "packages/design-system-registry/registry/sizes.json",
   "validation": "advisory",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {
@@ -22,16 +22,14 @@
     "./package.json": "./package.json",
     "./components/*.json": "./components/*.json",
     "./schemas/token.schema.json": "./schemas/token.schema.json",
-    "./schemas/dimension.schema.json": "./schemas/dimension.schema.json",
+    "./schemas/mode-set.schema.json": "./schemas/mode-set.schema.json",
     "./schemas/field.schema.json": "./schemas/field.schema.json",
     "./schemas/manifest.schema.json": "./schemas/manifest.schema.json",
     "./schemas/value-types/color.schema.json": "./schemas/value-types/color.schema.json",
     "./schemas/component.schema.json": "./schemas/component.schema.json",
     "./schemas/anatomy-part.schema.json": "./schemas/anatomy-part.schema.json",
     "./schemas/state-declaration.schema.json": "./schemas/state-declaration.schema.json",
-    "./rules/rules.yaml": "./rules/rules.yaml",
-    "./src/validate.js": "./src/validate.js",
-    "./src/canonical.js": "./src/canonical.js"
+    "./rules/rules.yaml": "./rules/rules.yaml"
   },
   "files": [
     "components",
@@ -40,13 +38,6 @@
     "rules",
     "schemas",
     "spec",
-    "src",
     "README.md"
-  ],
-  "devDependencies": {
-    "ava": "^6.0.1"
-  },
-  "scripts": {
-    "test": "ava"
-  }
+  ]
 }

package/rules/rules.yaml

@@ -42,9 +42,9 @@ rules:
     name: cascade-coverage
     severity: error
     category: completeness
-    assert: Dimension declarations MUST satisfy coverage rules (e.g. default ∈ modes; peer mode requirements from coverage metadata).
-    message: "Dimension coverage violation for {dimension}"
-    spec_ref: spec/dimensions.md#coverage-validation
+    assert: Mode set declarations MUST satisfy coverage rules (e.g. default ∈ modes; peer mode requirements from coverage metadata).
+    message: "Mode-set coverage violation for {mode_set}"
+    spec_ref: spec/mode-sets.md#coverage-validation
     introduced_in: "1.0.0-draft"
 
   - id: SPEC-006
@@ -69,7 +69,7 @@ rules:
     name: cascade-completeness
     severity: warning
     category: completeness
-    assert: For every cascade token that has a non-default mode variant, a base/default variant (name object with no dimension fields for that dimension, or explicitly the default mode value) MUST also exist in the dataset. Ensures all consumers can resolve without a fallback gap.
+    assert: For every cascade token that has a non-default mode variant, a base/default variant (name object with no mode set fields for that mode set, or explicitly the default mode value) MUST also exist in the dataset. Ensures all consumers can resolve without a fallback gap.
     message: "Token property '{property}' has mode variant '{mode}' but no base/default variant"
     spec_ref: spec/cascade.md#coverage
     introduced_in: "1.0.0-draft"
@@ -268,3 +268,39 @@ rules:
     message: "'{entity}' has documentBlocks but no purpose block — add a block with type 'purpose'"
     spec_ref: spec/document-blocks.md
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-030
+    name: accessibility-empty
+    severity: warning
+    category: completeness
+    assert: >
+      A component declaration that carries an accessibility object SHOULD populate at least one
+      of the five known fields (role, intents, focusable, keyboardIntents, wcag). An entirely
+      empty accessibility object provides no semantic value and should be populated or removed.
+    message: "Component '{entity}' has an empty accessibility object — populate at least one field or remove the property"
+    spec_ref: spec/accessibility.md
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-031
+    name: accessibility-wcag-missing
+    severity: warning
+    category: completeness
+    assert: >
+      A component whose accessibility declaration includes a role SHOULD also include a non-empty
+      wcag array listing applicable WCAG 2.x success criteria. WCAG citations improve audit
+      traceability for components with a named semantic role.
+    message: "Component '{entity}' accessibility has a role but no wcag entries — add applicable WCAG 2.x success criteria"
+    spec_ref: spec/accessibility.md
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-032
+    name: product-layer-override-type-compat
+    severity: error
+    category: cascade
+    assert: >
+      A Platform- or Product-layer token that overrides a Foundation token (matched by UUID)
+      MUST NOT change the JSON value type of the `value` field. Overrides may change the value
+      but must preserve its JSON kind (string, number, object, array, boolean).
+    message: "Token '{entity}' override changes value type from '{foundationType}' to '{overrideType}' — overrides MUST NOT change the resolved token's value type"
+    spec_ref: spec/cascade.md
+    introduced_in: "1.0.0-draft"

package/schemas/accessibility.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/accessibility.schema.json",
+  "title": "Accessibility declaration",
+  "description": "Semantic accessibility vocabulary for a component declaration. See spec/accessibility.md.",
+  "type": "object",
+  "properties": {
+    "role": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Semantic role from the canonical vocabulary (e.g. 'button', 'checkbox', 'dialog')."
+    },
+    "intents": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Semantic interaction intents (e.g. 'trigger', 'select', 'expand')."
+    },
+    "focusable": {
+      "type": "boolean",
+      "description": "Whether the component receives keyboard focus via the Tab key by default."
+    },
+    "keyboardIntents": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Keyboard interaction intents when focused (e.g. 'activate', 'expand', 'dismiss')."
+    },
+    "wcag": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/wcagEntry" },
+      "uniqueItems": true,
+      "description": "Applicable WCAG 2.x success criteria."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "wcagEntry": {
+      "type": "object",
+      "required": ["criterion", "level"],
+      "properties": {
+        "criterion": {
+          "type": "string",
+          "pattern": "^[1-4]\\.[0-9]+\\.[0-9]+$",
+          "description": "WCAG 2.x criterion number (e.g. '1.3.1')."
+        },
+        "level": {
+          "type": "string",
+          "enum": ["A", "AA", "AAA"],
+          "description": "WCAG conformance level."
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable criterion title (e.g. 'Info and Relationships')."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/component.schema.json

@@ -74,6 +74,10 @@
       "items": { "$ref": "document-block.schema.json" },
       "minItems": 1,
       "description": "Typed prose blocks for this component. See spec/document-blocks.md (Phase 9)."
+    },
+    "accessibility": {
+      "$ref": "accessibility.schema.json",
+      "description": "Semantic accessibility vocabulary for this component. See spec/accessibility.md (Phase 7)."
     }
   },
   "additionalProperties": false,
@@ -245,6 +249,21 @@
           "type": "boolean",
           "default": false,
           "description": "true for states that compose with others (e.g. focus ring layered over hover)."
+        },
+        "announce": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Screen-reader announcement hint for this state transition. See spec/accessibility.md."
+        },
+        "communicates": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Semantic meaning conveyed to AT when this state is active (e.g. 'expanded', 'disabled'). See spec/accessibility.md."
+        },
+        "blocksInteraction": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this state prevents all user interaction. See spec/accessibility.md."
         }
       },
       "additionalProperties": false

package/schemas/field.schema.json

@@ -23,8 +23,8 @@
     },
     "kind": {
       "type": "string",
-      "enum": ["semantic", "dimension", "numeric"],
-      "description": "Whether this field participates in serialization ordering or cascade resolution. 'semantic' fields describe identity and appear in the standard serialization order; 'dimension' fields drive cascade specificity; 'numeric' fields hold integer indices appended at the end of the serialized name."
+      "enum": ["semantic", "mode-set", "numeric"],
+      "description": "Whether this field participates in serialization ordering or cascade resolution. 'semantic' fields describe identity and appear in the standard serialization order; 'mode-set' fields drive cascade specificity; 'numeric' fields hold integer indices appended at the end of the serialized name."
     },
     "registry": {
       "oneOf": [

package/schemas/manifest.schema.json

@@ -64,7 +64,7 @@
     },
     "extensions": {
       "type": "object",
-      "description": "Platform-local tokens, dimensions, and formatting rules.",
+      "description": "Platform-local tokens, mode sets, and formatting rules.",
       "properties": {
         "formatting": {
           "type": "object",

package/schemas/{dimension.schema.json → mode-set.schema.json}

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/dimension.schema.json",
-  "title": "Dimension declaration",
-  "description": "Layer 1 — declares a dimension name, allowed modes, and default. default ∈ modes is validated in Layer 2 (SPEC-005) where needed.",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/mode-set.schema.json",
+  "title": "Mode Set declaration",
+  "description": "Layer 1 — declares a mode set name, allowed modes, and default. default ∈ modes is validated in Layer 2 (SPEC-005) where needed.",
   "type": "object",
   "required": ["name", "modes", "default"],
   "properties": {

package/schemas/token.schema.json

@@ -15,7 +15,7 @@
   "$defs": {
     "nameObject": {
       "type": "object",
-      "description": "Structured token identity. Semantic fields describe identity and structure; dimension fields drive cascade resolution. See spec/taxonomy.md and spec/token-format.md. Additional dimension keys MUST be strings.",
+      "description": "Structured token identity. Semantic fields describe identity and structure; mode-set fields drive cascade resolution. See spec/taxonomy.md and spec/token-format.md. Additional mode-set keys MUST be strings.",
       "required": ["property"],
       "properties": {
         "property": {
@@ -61,7 +61,7 @@
         },
         "size": {
           "type": "string",
-          "description": "Semantic: relative t-shirt sizing (e.g. small, medium, large). Distinct from dimension scale."
+          "description": "Semantic: relative t-shirt sizing (e.g. small, medium, large). Distinct from the `scale` mode set."
         },
         "density": {
           "type": "string",
@@ -73,15 +73,15 @@
         },
         "colorScheme": {
           "type": "string",
-          "description": "Dimension: color scheme mode (e.g. light, dark, wireframe)."
+          "description": "Mode set: color scheme mode (e.g. light, dark, wireframe)."
         },
         "scale": {
           "type": "string",
-          "description": "Dimension: platform density scale (e.g. desktop, mobile)."
+          "description": "Mode set: platform density scale (e.g. desktop, mobile)."
         },
         "contrast": {
           "type": "string",
-          "description": "Dimension: contrast level (e.g. regular, high)."
+          "description": "Mode set: contrast level (e.g. regular, high)."
         }
       },
       "additionalProperties": {

package/schemas/value-types/README.md

@@ -0,0 +1,20 @@
+# Value-Type Schemas
+
+JSON Schema files under this directory define the shape of token `value` fields for each value-type. They are referenced by the `$valueType` field on tokens and validated by SPEC-016.
+
+## Composite sub-key type annotations (`x-valueType`)
+
+Each property within a composite value-type schema (e.g. typography, drop-shadow) carries an `x-valueType` extension keyword that declares the expected scalar value-type of that sub-value when it is an inline alias reference (`{token-name}`).
+
+* **Type**: string or array of strings. Array form means any of the listed types is acceptable.
+* **Recognized scalar type names**: `color`, `dimension`, `number`, `font-family`, `font-weight`.
+* **Consumer**: `sdk/core/src/validate/rules/spec015.rs` (SPEC-015 — composite inline alias type compatibility).
+
+Example from `typography.schema.json`:
+
+```json
+"fontSize": { "type": "string", "x-valueType": "dimension" },
+"lineHeight": { "type": "string", "x-valueType": ["dimension", "number"] }
+```
+
+The scalar type names are an interim vocabulary. Once individual primitive value-type schemas exist under this directory (e.g. `dimension.schema.json`), `x-valueType` values will migrate to schema-relative paths matching the `$valueType` convention (e.g. `"value-types/dimension.schema.json"`).

package/schemas/value-types/drop-shadow.schema.json

@@ -7,11 +7,11 @@
   "items": {
     "type": "object",
     "properties": {
-      "x": { "type": "string" },
-      "y": { "type": "string" },
-      "blur": { "type": "string" },
-      "spread": { "type": "string" },
-      "color": { "type": "string" }
+      "x": { "type": "string", "x-valueType": "dimension" },
+      "y": { "type": "string", "x-valueType": "dimension" },
+      "blur": { "type": "string", "x-valueType": "dimension" },
+      "spread": { "type": "string", "x-valueType": "dimension" },
+      "color": { "type": "string", "x-valueType": "color" }
     },
     "required": ["x", "y", "blur", "spread", "color"],
     "additionalProperties": false

package/schemas/value-types/typography-scale.schema.json

@@ -5,8 +5,8 @@
   "description": "Pairs a font size with its corresponding line height at a single typographic tier.",
   "type": "object",
   "properties": {
-    "fontSize": { "type": "string" },
-    "lineHeight": { "type": "string" }
+    "fontSize": { "type": "string", "x-valueType": "dimension" },
+    "lineHeight": { "type": "string", "x-valueType": ["dimension", "number"] }
   },
   "required": ["fontSize", "lineHeight"],
   "additionalProperties": false

package/schemas/value-types/typography.schema.json

@@ -5,11 +5,11 @@
   "description": "Object bundling font properties for a typographic style. Sub-values may be literal strings or inline alias references ({token-name}).",
   "type": "object",
   "properties": {
-    "fontFamily": { "type": "string" },
-    "fontSize": { "type": "string" },
-    "fontWeight": { "type": "string" },
-    "letterSpacing": { "type": "string" },
-    "lineHeight": { "type": "string" }
+    "fontFamily": { "type": "string", "x-valueType": "font-family" },
+    "fontSize": { "type": "string", "x-valueType": "dimension" },
+    "fontWeight": { "type": "string", "x-valueType": "font-weight" },
+    "letterSpacing": { "type": "string", "x-valueType": "dimension" },
+    "lineHeight": { "type": "string", "x-valueType": ["dimension", "number"] }
   },
   "required": ["fontFamily", "fontSize", "fontWeight", "lineHeight"],
   "additionalProperties": false