@adobe/design-data-spec 0.0.1

package/README.md

@@ -0,0 +1,24 @@
+# [**@adobe/design-data-spec**](https://github.com/adobe/spectrum-design-data/tree/main/packages/design-data-spec)
+
+Normative **Design Data Specification** artifacts for Spectrum: human-readable spec (`spec/`), JSON Schemas (`schemas/`), validation rule catalog (`rules/`), and conformance fixtures (`conformance/`).
+
+**Spec version:** `1.0.0-draft` — see [`spec/index.md`](spec/index.md).
+
+## Layers
+
+1. **JSON Schemas** (Draft 2020-12) — structural (per-file) validation; canonical `$id` under `https://opensource.adobe.com/spectrum-design-data/schemas/v0/`.
+2. **Rule catalog** (`rules/rules.yaml`) — semantic rules (`SPEC-001` … `SPEC-006`).
+3. **Conformance fixtures** — valid/invalid examples and expected diagnostics for implementors.
+
+## Package exports
+
+`package.json` `exports` expose root schemas, `value-types/color.schema.json`, and `rules/rules.yaml` for tooling.
+
+## Tasks
+
+- `moon run designDataSpec:check` — verify required paths exist (layout guard).
+
+## References
+
+- [Design Data Specification project](https://github.com/orgs/adobe/projects/89)
+- Discussion [#714](https://github.com/adobe/spectrum-design-data/discussions/714) — umbrella spec

package/conformance/README.md

@@ -0,0 +1,19 @@
+# Conformance fixtures (Layer 3)
+
+Each **invalid** case lives under `invalid/<RULE_ID>/` with:
+
+- One or more JSON **fixture** files (structurally valid for Layer 1 when targeting Layer 2 rules).
+- **`expected-errors.json`** — expected diagnostics after Layer 2 validation (see `errors[].rule_id`, `severity`, optional `message_pattern`).
+
+**Valid** baselines live under `valid/`.
+
+| Folder             | Rule     | Intent                                            |
+| ------------------ | -------- | ------------------------------------------------- |
+| `invalid/SPEC-001` | SPEC-001 | Alias target does not exist.                      |
+| `invalid/SPEC-002` | SPEC-002 | Alias resolves to incompatible type (semantic).   |
+| `invalid/SPEC-003` | SPEC-003 | Circular alias chain.                             |
+| `invalid/SPEC-004` | SPEC-004 | Duplicate `uuid` across tokens.                   |
+| `invalid/SPEC-005` | SPEC-005 | Dimension `default` not in `modes`.               |
+| `invalid/SPEC-006` | SPEC-006 | Ambiguous resolution / specificity tie (warning). |
+
+Implementors SHOULD run these fixtures once the Rust validator exposes rule IDs ([#724](https://github.com/adobe/spectrum-design-data/issues/724), [#725](https://github.com/adobe/spectrum-design-data/issues/725)).

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-001",
+      "severity": "error",
+      "message_pattern": ".*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-001/fixture.json

@@ -0,0 +1,6 @@
+{
+  "name": {
+    "property": "alias-missing-target"
+  },
+  "$ref": "tokens/nonexistent-token.json"
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-002",
+      "severity": "error",
+      "message_pattern": ".*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-002/token-bad-alias.json

@@ -0,0 +1,7 @@
+{
+  "name": {
+    "property": "spacing-alias"
+  },
+  "$ref": "token-color.json",
+  "uuid": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
+}

package/conformance/invalid/SPEC-002/token-color.json

@@ -0,0 +1,7 @@
+{
+  "name": {
+    "property": "base-color"
+  },
+  "value": "rgb(0, 128, 255)",
+  "uuid": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-003",
+      "severity": "error",
+      "message_pattern": ".*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-003/token-a.json

@@ -0,0 +1,7 @@
+{
+  "name": {
+    "property": "cycle-a"
+  },
+  "$ref": "token-b.json",
+  "uuid": "cccccccc-cccc-4ccc-8ccc-cccccccccccc"
+}

package/conformance/invalid/SPEC-003/token-b.json

@@ -0,0 +1,7 @@
+{
+  "name": {
+    "property": "cycle-b"
+  },
+  "$ref": "token-a.json",
+  "uuid": "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-004",
+      "severity": "error",
+      "message_pattern": ".*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-004/token-one.json

@@ -0,0 +1,7 @@
+{
+  "name": {
+    "property": "first"
+  },
+  "value": "rgb(1, 2, 3)",
+  "uuid": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
+}

package/conformance/invalid/SPEC-004/token-two.json

@@ -0,0 +1,7 @@
+{
+  "name": {
+    "property": "second"
+  },
+  "value": "rgb(4, 5, 6)",
+  "uuid": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
+}

package/conformance/invalid/SPEC-005/dimension.json

@@ -0,0 +1,6 @@
+{
+  "specVersion": "1.0.0-draft",
+  "name": "scale",
+  "modes": ["medium", "large"],
+  "default": "xlarge"
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-005",
+      "severity": "error",
+      "message_pattern": ".*"
+    }
+  ]
+}

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

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-006",
+      "severity": "warning",
+      "message_pattern": ".*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-006/token-high.json

@@ -0,0 +1,8 @@
+{
+  "name": {
+    "property": "ambiguous",
+    "colorScheme": "dark"
+  },
+  "value": "rgb(20, 20, 20)",
+  "uuid": "11111111-1111-4111-8111-111111111111"
+}

package/conformance/invalid/SPEC-006/token-low.json

@@ -0,0 +1,8 @@
+{
+  "name": {
+    "property": "ambiguous",
+    "colorScheme": "dark"
+  },
+  "value": "rgb(10, 10, 10)",
+  "uuid": "ffffffff-ffff-4fff-8fff-ffffffffffff"
+}

package/conformance/valid/baseline-token.json

@@ -0,0 +1,7 @@
+{
+  "name": {
+    "property": "background-color",
+    "colorScheme": "light"
+  },
+  "value": "rgb(255, 255, 255)"
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@adobe/design-data-spec",
+  "version": "0.0.1",
+  "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adobe/spectrum-design-data.git",
+    "directory": "packages/design-data-spec"
+  },
+  "author": "Garth Braithwaite <garthdb@gmail.com> (https://garthdb.com/)",
+  "bugs": {
+    "url": "https://github.com/adobe/spectrum-design-data/issues"
+  },
+  "homepage": "https://github.com/adobe/spectrum-design-data/tree/main/packages/design-data-spec#readme",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.12.0",
+    "pnpm": ">=10.17.1"
+  },
+  "packageManager": "pnpm@10.17.1",
+  "exports": {
+    "./package.json": "./package.json",
+    "./schemas/token.schema.json": "./schemas/token.schema.json",
+    "./schemas/dimension.schema.json": "./schemas/dimension.schema.json",
+    "./schemas/manifest.schema.json": "./schemas/manifest.schema.json",
+    "./schemas/value-types/color.schema.json": "./schemas/value-types/color.schema.json",
+    "./rules/rules.yaml": "./rules/rules.yaml"
+  },
+  "files": [
+    "spec",
+    "schemas",
+    "rules",
+    "conformance",
+    "README.md"
+  ],
+  "scripts": {}
+}

package/rules/rules.yaml

@@ -0,0 +1,66 @@
+# Validation rule catalog (Layer 2) — stable IDs for diagnostics and conformance.
+# spec_version aligns with the human-readable spec (see spec/index.md).
+spec_version: "1.0.0-draft"
+rules:
+  - id: SPEC-001
+    name: alias-target-exists
+    severity: error
+    category: reference-integrity
+    assert: Every alias $ref MUST resolve to an existing token in the dataset.
+    message: "Alias target not found for $ref: {path}"
+    spec_ref: spec/token-format.md#alias-ref
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-002
+    name: alias-type-compatibility
+    severity: error
+    category: type-safety
+    assert: Resolved alias target MUST have a value type compatible with the referencing token’s expected type.
+    message: "Alias {path} resolves to incompatible type"
+    spec_ref: spec/token-format.md#literal-value
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-003
+    name: no-circular-aliases
+    severity: error
+    category: reference-integrity
+    assert: Alias chains MUST NOT contain cycles.
+    message: "Circular alias chain detected involving {path}"
+    spec_ref: spec/token-format.md#alias-ref
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-004
+    name: uuid-global-uniqueness
+    severity: error
+    category: completeness
+    assert: Token uuid values MUST be unique across all token documents in the dataset.
+    message: "Duplicate uuid {uuid}"
+    spec_ref: spec/token-format.md#lifecycle-and-metadata
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-005
+    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
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-006
+    name: specificity-correctness
+    severity: warning
+    category: type-safety
+    assert: When two tokens from the same layer match a context, the more specific name object MUST win; ties MUST be reported.
+    message: "Ambiguous cascade resolution (specificity tie) for context {context}"
+    spec_ref: spec/cascade.md#semantic-specificity
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-007
+    name: name-roundtrip
+    severity: warning
+    category: naming-consistency
+    assert: Every legacy token name MUST be reproducible from a structured name object via deterministic generation rules, unless listed in naming-exceptions.json.
+    message: "Token '{token}' does not roundtrip through name-object generation rules"
+    spec_ref: spec/token-format.md#name-object
+    introduced_in: "1.0.0-draft"

package/schemas/dimension.schema.json

@@ -0,0 +1,39 @@
+{
+  "$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.",
+  "type": "object",
+  "required": ["name", "modes", "default"],
+  "properties": {
+    "specVersion": {
+      "const": "1.0.0-draft"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "modes": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "default": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string"
+    },
+    "coverage": {
+      "type": "object",
+      "description": "Optional machine-readable coverage hints (interpreted by Layer 2).",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/manifest.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/manifest.schema.json",
+  "title": "Platform manifest",
+  "description": "Layer 1 — platform repo declaration of foundation pin and optional filters/overrides.",
+  "type": "object",
+  "required": ["specVersion", "foundationVersion"],
+  "properties": {
+    "specVersion": {
+      "const": "1.0.0-draft"
+    },
+    "foundationVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Pin to a foundation release (semver or tag)."
+    },
+    "include": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "exclude": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "overrides": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["target", "value"],
+            "properties": {
+              "target": {
+                "type": "string",
+                "minLength": 1
+              },
+              "value": true
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "required": ["target", "$ref"],
+            "properties": {
+              "target": {
+                "type": "string",
+                "minLength": 1
+              },
+              "$ref": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Platform-local tokens or dimensions; structure validated by separate documents.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/token.schema.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/token.schema.json",
+  "title": "Design data token",
+  "description": "Layer 1 — structural token shape (name + value or alias). Graph rules are Layer 2.",
+  "type": "object",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/tokenWithValue"
+    },
+    {
+      "$ref": "#/$defs/tokenWithRef"
+    }
+  ],
+  "$defs": {
+    "nameObject": {
+      "type": "object",
+      "description": "Structured token identity; additional dimension keys MUST be strings.",
+      "required": ["property"],
+      "properties": {
+        "property": {
+          "type": "string",
+          "minLength": 1
+        },
+        "component": {
+          "type": "string"
+        },
+        "variant": {
+          "type": "string"
+        },
+        "state": {
+          "type": "string"
+        },
+        "colorScheme": {
+          "type": "string"
+        },
+        "scale": {
+          "type": "string"
+        },
+        "contrast": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "tokenWithValue": {
+      "type": "object",
+      "required": ["name", "value"],
+      "not": {
+        "required": ["$ref"]
+      },
+      "properties": {
+        "specVersion": {
+          "const": "1.0.0-draft"
+        },
+        "name": {
+          "$ref": "#/$defs/nameObject"
+        },
+        "value": {
+          "description": "Literal value; type narrowed by value-type schemas where applicable.",
+          "anyOf": [
+            {
+              "$ref": "value-types/color.schema.json"
+            },
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object"
+            },
+            {
+              "type": "array"
+            }
+          ]
+        },
+        "uuid": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "introduced": {
+          "type": "string"
+        },
+        "deprecated": {
+          "type": "boolean"
+        },
+        "deprecated_comment": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string"
+        },
+        "renamed": {
+          "type": "string"
+        },
+        "private": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "tokenWithRef": {
+      "type": "object",
+      "required": ["name", "$ref"],
+      "not": {
+        "required": ["value"]
+      },
+      "properties": {
+        "specVersion": {
+          "const": "1.0.0-draft"
+        },
+        "name": {
+          "$ref": "#/$defs/nameObject"
+        },
+        "$ref": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Alias target path or stable token id (resolution is Layer 2)."
+        },
+        "uuid": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "introduced": {
+          "type": "string"
+        },
+        "deprecated": {
+          "type": "boolean"
+        },
+        "deprecated_comment": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string"
+        },
+        "renamed": {
+          "type": "string"
+        },
+        "private": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/value-types/color.schema.json",
+  "title": "Color value",
+  "description": "RGB or RGBA color string (aligned with legacy Spectrum token color pattern).",
+  "type": "string",
+  "pattern": "^rgba\\((([0-1]?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5]),\\s?){3}(0|1|0?\\.\\d+)\\)|rgb\\(([0-1]?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5]){1,3}(,\\s?\\d{1,3}%?){2}\\)$"
+}

package/spec/cascade.md

@@ -0,0 +1,54 @@
+# Cascade resolution
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **cascade model**: three **layers**, **semantic specificity**, and the **resolution algorithm** used to pick a single winning token value for a given **context**.
+
+## Layers
+
+Design data is organized in three layers, ordered from lowest to highest precedence when values conflict:
+
+| Layer | Name           | Description                                                                                 |
+| ----- | -------------- | ------------------------------------------------------------------------------------------- |
+| 1     | **Foundation** | Canonical design system data (e.g. Spectrum foundation).                                    |
+| 2     | **Platform**   | Platform-specific adjustments; **MUST** remain type-compatible with foundation.             |
+| 3     | **Product**    | Product-specific overrides; **MUST** remain type-compatible with the resolved lower layers. |
+
+**NORMATIVE:** When two candidates match the same context, the candidate from the **higher** layer (larger number above) **MUST** win.
+
+**NORMATIVE:** Overrides **MUST NOT** change the resolved token’s **value type** (e.g. color alias cannot resolve to a non-color).
+
+## Semantic specificity
+
+**Specificity** counts how many **non-default** dimension fields in the token’s **name object** are set for the dimensions declared in the dataset.
+
+**NORMATIVE:** Default dimension values (see [Dimensions](dimensions.md)) **MUST NOT** contribute to specificity.
+
+**NORMATIVE:** When two candidates from the **same layer** match the context, the candidate with **higher** specificity **MUST** win.
+
+**NORMATIVE:** Ties on layer and specificity **MUST** be broken by a deterministic **document order** rule defined by the manifest or dataset index (implementation-defined in this draft; validators **SHOULD** emit a warning on ambiguous ties).
+
+## Context
+
+A **resolution context** is a set of dimension key/value pairs (e.g. `colorScheme: dark`, `scale: medium`, `contrast: regular`) plus the **target layer** being resolved (usually product → platform → foundation).
+
+## Resolution algorithm (informative outline)
+
+The following outline is **RECOMMENDED** for conforming resolvers:
+
+1. Collect all token candidates whose name object **matches** the context (every specified dimension in the context equals the name object’s dimension field, or the name object omits that dimension where omission means “matches any” per dimension rules).
+2. Filter to candidates at or below the requested layer.
+3. Select the maximum **layer** precedence.
+4. Within that layer, select the maximum **specificity**.
+5. Break remaining ties by deterministic ordering.
+
+Exact matching rules for omitted dimensions are defined alongside dimension declarations in [Dimensions](dimensions.md).
+
+## Cross-dimensional overrides
+
+**NORMATIVE:** Overrides that combine multiple dimensions in a way not expressible by a single name object alone **MUST** use **explicit combination tokens** (tokens whose name object sets multiple non-default dimensions) as defined in the dataset; magic merging of unrelated tokens is **NOT** allowed.
+
+## 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)

package/spec/dimensions.md

@@ -0,0 +1,55 @@
+# Dimensions
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines how **dimensions** (modes such as color scheme, scale, contrast) are **declared**, assigned **defaults**, and validated for **coverage**.
+
+## Dimension declaration
+
+A **dimension declaration** is a JSON object describing one axis of variation. It **MUST** conform to [`dimension.schema.json`](../schemas/dimension.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/dimension.schema.json`).
+
+### Required fields
+
+| Field     | Description                                               |
+| --------- | --------------------------------------------------------- |
+| `name`    | Stable identifier for the dimension (e.g. `colorScheme`). |
+| `modes`   | Array of allowed mode values (strings).                   |
+| `default` | Default mode; **MUST** be a member of `modes`.            |
+
+### Optional fields
+
+| Field         | Description                          |
+| ------------- | ------------------------------------ |
+| `description` | Human-readable documentation.        |
+| `coverage`    | Rules for mode coverage (see below). |
+
+## Built-in dimensions
+
+These dimensions **SHOULD** be used consistently across Spectrum-compatible datasets:
+
+| `name`        | Typical `modes`                 | Notes                         |
+| ------------- | ------------------------------- | ----------------------------- |
+| `colorScheme` | `light`, `dark`, `wireframe`, … | Theme / appearance.           |
+| `scale`       | `medium`, `large`, …            | Density / t-shirt scale.      |
+| `contrast`    | `regular`, `high`, …            | Accessibility contrast level. |
+
+## Optional dimensions
+
+Additional dimensions (e.g. `language`, `motion`) **MAY** be declared in a dataset’s dimension catalog. Token name objects **MAY** include keys matching declared dimension names.
+
+## Defaults and specificity
+
+**NORMATIVE:** A token name object **omitting** a dimension field implies the token applies under the dimension’s **`default`** mode for specificity and matching purposes unless the spec for that dimension states otherwise.
+
+**NORMATIVE:** Only **non-default** dimension fields on the name object increase **semantic specificity** (see [Cascade](cascade.md)).
+
+## Coverage validation
+
+**RECOMMENDED:** If a dimension’s `coverage` requires **peer modes** (e.g. defining `dark` requires `light`), validators implement rule **`SPEC-005`** (see `rules/rules.yaml`).
+
+**RECOMMENDED:** Explicit **combination** tokens are used for rare cross-dimensional cases instead of inferring Cartesian products.
+
+## 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)

package/spec/index.md

@@ -0,0 +1,86 @@
+# Design Data Specification
+
+**Version:** `1.0.0-draft`\
+**Status:** Draft — normative text and schemas may change before `1.0.0`.
+
+This document is the top-level overview for the **Design Data Specification**: a machine-readable model for Spectrum design tokens, dimensions, platform manifests, and validation.
+
+## Scope
+
+The specification defines:
+
+1. **Token format** — structured token identity (`name`), literal `value` or alias `$ref`, and lifecycle metadata ([Token format](token-format.md)).
+2. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
+3. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
+4. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
+
+Out of scope for this draft (tracked elsewhere):
+
+* Exact query syntax for `include` / `exclude` in manifests (placeholder fields only).
+* Full evolution, migration windows, and SDK version negotiation — see [discussion #735](https://github.com/adobe/spectrum-design-data/discussions/735).
+
+## Conformance
+
+The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY**, and **OPTIONAL** in this specification are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) \[[RFC2119](https://www.rfc-editor.org/rfc/rfc2119.html)] \[[RFC8174](https://www.rfc-editor.org/rfc/rfc8174.html)] when, and only when, they appear in all capitals, as shown here.
+
+### Conformance levels
+
+| Level           | Meaning                                                 |
+| --------------- | ------------------------------------------------------- |
+| **NORMATIVE**   | Required for a conforming document or tool.             |
+| **RECOMMENDED** | Strong default; deviations SHOULD be documented.        |
+| **OPTIONAL**    | May be omitted unless a feature explicitly requires it. |
+
+### Validation layers
+
+Conformance is checked in three layers (all under `@adobe/design-data-spec`):
+
+| Layer | Artifact           | Responsibility                                             |
+| ----- | ------------------ | ---------------------------------------------------------- |
+| 1     | `schemas/*.json`   | Per-instance structural shape (JSON Schema Draft 2020-12). |
+| 2     | `rules/rules.yaml` | Semantic rules with stable IDs (e.g. `SPEC-001`).          |
+| 3     | `conformance/`     | Fixtures and expected diagnostics for implementors.        |
+
+A **conforming validator** MUST implement Layer 1 for supported document types and SHOULD implement Layer 2 rules whose `introduced_in` is less than or equal to the validator’s claimed spec version.
+
+## Spec version and SemVer
+
+This document set carries the **spec version** `1.0.0-draft`. Published artifacts (schemas, rule catalog) are expected to align with [Semantic Versioning](https://semver.org/) once `1.0.0` is released: **MAJOR** for incompatible schema or rule behavior, **MINOR** for backward-compatible additions, **PATCH** for clarifications and compatible fixes.
+
+Full governance (compatibility tiers, migration, CLI `--spec-version`) is discussed in [discussion #735 — Versioning and Evolution](https://github.com/adobe/spectrum-design-data/discussions/735).
+
+## Normative references (sibling documents)
+
+| Document                        | Role                                                             |
+| ------------------------------- | ---------------------------------------------------------------- |
+| [Token format](token-format.md) | Token `name`, `value` / `$ref`, value types, lifecycle metadata. |
+| [Cascade](cascade.md)           | Layers, specificity, resolution algorithm.                       |
+| [Dimensions](dimensions.md)     | Dimension declarations, built-in dimensions, coverage.           |
+| [Manifest](manifest.md)         | Platform manifest fields and validation expectations.            |
+
+## JSON Schema `$id` and versioning
+
+**NORMATIVE:** Canonical schema documents use **versioned path** `$id` URIs so major revisions can coexist on the documentation host:
+
+* Base: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/`
+* Examples: `.../v0/token.schema.json`, `.../v0/dimension.schema.json`, `.../v0/manifest.schema.json`
+
+The **`v0`** segment denotes the **draft / pre-1.0** schema family aligned with spec version `1.0.0-draft`. A future **1.0.0** stable release MAY introduce `v1` paths without reusing `v0` URLs for incompatible shapes.
+
+**RECOMMENDED:** Each root schema document includes a top-level string property `specVersion` (const matching this spec’s version label) when the instance is a design-data document that should self-identify; see individual schemas.
+
+Packaged copies in this repository live under `packages/design-data-spec/schemas/`; their `$id` still identifies the canonical published URL above.
+
+## Relationship to existing Adobe packages
+
+| Package / area                          | Relationship                                                                                                                                                                                                                                                            |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@adobe/spectrum-tokens`                | **Current** token JSON under `packages/tokens/` is the **legacy** shape (e.g. `color-set`, `scale-set`). This spec defines the **target** format; backward-compat schemas and migration are Phase 1 ([#723](https://github.com/adobe/spectrum-design-data/issues/723)). |
+| `@adobe/design-system-registry`         | Registry enums and component metadata MAY be referenced by validation rules (e.g. component association); exact coupling is Layer 2.                                                                                                                                    |
+| `@adobe/spectrum-component-api-schemas` | Component schemas MAY be cross-checked by graph rules; not required for Layer 1 structural validation.                                                                                                                                                                  |
+
+## Umbrella discussions
+
+* [#714 — Design Data Specification (umbrella)](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#715 — Distributed Design Data Architecture](https://github.com/adobe/spectrum-design-data/discussions/715)
+* [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)

package/spec/manifest.md

@@ -0,0 +1,54 @@
+# Platform manifest
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **platform manifest**: how a platform implementation repository declares its relationship to **foundation** design data — version pin, inclusion filters, typed overrides, and extensions.
+
+## Manifest document
+
+A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/manifest.schema.json`).
+
+## Required fields
+
+| Field               | Type   | Description                                                   |
+| ------------------- | ------ | ------------------------------------------------------------- |
+| `specVersion`       | string | **MUST** be `1.0.0-draft` for documents targeting this draft. |
+| `foundationVersion` | string | Pin to a released foundation version (semver or tag string).  |
+
+## 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 dimensions introduced at the platform layer.                       |
+
+### `include` / `exclude`
+
+**NORMATIVE:** Entries **MUST** be non-empty strings. The **query language** is **not** normative in `1.0.0-draft`; treat values as opaque identifiers for tooling until a future spec version defines syntax.
+
+### `overrides`
+
+Each override object **MUST** include enough information to identify a target token and supply a replacement **value** or **$ref** compatible with the target’s type.
+
+**NORMATIVE:** Overrides **MUST NOT** change the resolved type of the token (aligns with [Cascade — type safety](cascade.md)).
+
+### `extensions`
+
+**RECOMMENDED:** `extensions` follows the same structural conventions as foundation token files (tokens, dimensions) and **SHOULD** be validated with the same Layer 1 and Layer 2 rules.
+
+## Validation
+
+**NORMATIVE:** Manifests **MUST** pass Layer 1 JSON Schema validation.
+
+**RECOMMENDED:** Validators resolve `foundationVersion` against a registry or lockfile and report mismatches as errors or warnings per product policy.
+
+## Automated upgrades
+
+**OPTIONAL:** Workflows **MAY** open upgrade PRs when `foundationVersion` lags the latest release; details are out of scope for this document (see [#715](https://github.com/adobe/spectrum-design-data/discussions/715)).
+
+## References
+
+* [#715 — Distributed Design Data Architecture](https://github.com/adobe/spectrum-design-data/discussions/715)
+* [#625 — Token Authoring Workflow](https://github.com/adobe/spectrum-design-data/discussions/625)

package/spec/token-format.md

@@ -0,0 +1,80 @@
+# Token format
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the normative **token** object: identity (`name`), either a literal **value** or an alias **`$ref`**, optional **metadata**, and **value types** validated by JSON Schema.
+
+## Token object
+
+A **token** is a JSON object that satisfies the Layer 1 schema [`token.schema.json`](../schemas/token.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/token.schema.json`).
+
+### Required shape
+
+A token **MUST** contain:
+
+1. **`name`** — a JSON object (the **name object**) as defined below.
+2. Exactly one of:
+   * **`value`** — a literal token value (type depends on value-type schema), or
+   * **`$ref`** — a string reference to another token (alias).
+
+A token **MUST NOT** include both `value` and `$ref`.
+
+### Name object
+
+The **name object** identifies the token in a structured way. Implementations use it for cascade matching, specificity, and tooling.
+
+**NORMATIVE fields** (all string unless noted):
+
+| Field           | Status   | Description                                                                                     |
+| --------------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `property`      | REQUIRED | Stable property key (e.g. semantic role of the token).                                          |
+| `component`     | OPTIONAL | Component name when the token is component-scoped.                                              |
+| `variant`       | OPTIONAL | Variant within a component.                                                                     |
+| `state`         | OPTIONAL | Interactive or semantic state.                                                                  |
+| `colorScheme`   | OPTIONAL | Dimension: light / dark / wireframe / etc.                                                      |
+| `scale`         | OPTIONAL | Dimension: t-shirt size or density scale.                                                       |
+| `contrast`      | OPTIONAL | Dimension: contrast level.                                                                      |
+| Additional keys | OPTIONAL | Other dimensions declared in the dataset’s dimension catalog (see [Dimensions](dimensions.md)). |
+
+**RECOMMENDED:** Name objects use a consistent key ordering in authored files for diffs; this is not a conformance requirement.
+
+### Alias (`$ref`)
+
+When **`$ref`** is present, the token is an **alias**. The value **MUST** be a non-empty string interpreted as a **token path** or **stable identifier** resolvable by the validator (resolution rules are Layer 2; see rule `SPEC-001` in `rules/rules.yaml`).
+
+### Literal `value`
+
+When **`value`** is present, it **MUST** conform to the declared value type for that token. Value types are defined under `schemas/value-types/` and referenced from the token schema.
+
+### Lifecycle and metadata
+
+The following OPTIONAL fields align with token lifecycle discussions (e.g. [#623](https://github.com/adobe/spectrum-design-data/discussions/623)):
+
+| Field                | Type          | Description                                     |
+| -------------------- | ------------- | ----------------------------------------------- |
+| `uuid`               | string (UUID) | Stable unique id for rename tracking and diffs. |
+| `introduced`         | string        | Version or date token was introduced.           |
+| `deprecated`         | boolean       | Marked deprecated.                              |
+| `deprecated_comment` | string        | Human-readable deprecation note.                |
+| `status`             | string        | e.g. `experimental`, `stable`.                  |
+| `renamed`            | string        | Previous name or id if renamed.                 |
+| `private`            | boolean       | Not part of public API surface.                 |
+
+**NORMATIVE:** If `deprecated` is `true`, `deprecated_comment` **SHOULD** be present.
+
+### `specVersion`
+
+**RECOMMENDED:** Root token documents (when stored as standalone JSON files) include `specVersion` with const `1.0.0-draft` for self-identification. Embedded tokens inside larger files **MAY** omit it if the parent document carries version metadata.
+
+## Value types
+
+Individual types (color, dimension, opacity, etc.) **MUST** be defined as JSON Schemas under `schemas/value-types/` and **MUST** use `$id` under the same `v0` base path as [Overview — JSON Schema `$id`](index.md).
+
+## Relationship to legacy Spectrum tokens
+
+The current `@adobe/spectrum-tokens` JSON uses **sets** (`color-set`, `scale-set`, …). This specification describes the **target** per-token model. Mapping from legacy to this format is out of scope for this document; see [#723](https://github.com/adobe/spectrum-design-data/issues/723).
+
+## References
+
+* [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
+* [#623 — Token Lifecycle Metadata](https://github.com/adobe/spectrum-design-data/discussions/623)