@adobe/design-data-spec 2.0.0 → 2.2.0

package/conformance/invalid/SPEC-044/empty-optional-dir/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-044",
+      "severity": "warning",
+      "message_pattern": ".*components/.*contains no.*json.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-044/empty-optional-dir/tokens/base.tokens.json

@@ -0,0 +1 @@
+{}

package/conformance/invalid/SPEC-044/missing-tokens/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-044",
+      "severity": "error",
+      "message_pattern": ".*tokens/.*not found.*"
+    }
+  ]
+}

package/conformance/valid/SPEC-044/components/button.json

@@ -0,0 +1,9 @@
+{
+  "$id": "https://opensource.adobe.com/spectrum-design-data/conformance/valid/SPEC-044/button.json",
+  "name": "button",
+  "displayName": "Button",
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://spectrum.adobe.com/page/button/"
+  }
+}

package/conformance/valid/SPEC-044/expected-errors.json

@@ -0,0 +1,4 @@
+{
+  "layer": 2,
+  "errors": []
+}

package/conformance/valid/SPEC-044/tokens/base.tokens.json

@@ -0,0 +1 @@
+{}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
   "type": "module",
   "repository": {
@@ -30,7 +30,8 @@
     "./schemas/state-declaration.schema.json": "./schemas/state-declaration.schema.json",
     "./rules/rules.yaml": "./rules/rules.yaml",
     "./schemas/registry-value.json": "./schemas/registry-value.json",
-    "./schemas/platform-extension.json": "./schemas/platform-extension.json"
+    "./schemas/platform-extension.json": "./schemas/platform-extension.json",
+    "./schemas/dataset.schema.json": "./schemas/dataset.schema.json"
   },
   "files": [
     "conformance",

package/rules/rules.yaml

@@ -477,3 +477,22 @@ rules:
     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"
+
+  - id: SPEC-044
+    name: dataset-structure
+    severity: error
+    layer: 2
+    category: structure
+    assert: >
+      A conformant dataset MUST contain a `tokens/` directory holding at least one
+      `*.tokens.json` file. This structural pre-check fires before token- and
+      component-level rules so that downstream rules can assume the dataset structure
+      is present, and an incomplete dataset produces a clear "structure is incomplete"
+      diagnostic rather than a cascade of confusing per-file errors. A registered
+      optional directory (`components/`, `fields/`, `mode-sets/`, `registry/`) that is
+      present SHOULD contain at least one conformant `*.json` file; an empty registered
+      directory is reported as a warning. Because this rule inspects the on-disk
+      directory layout it runs as a filesystem pre-pass, not against the in-memory graph.
+    message: "Dataset structure incomplete: {detail}"
+    spec_ref: spec/dataset-layout.md#structural-validation
+    introduced_in: "1.0.0-draft"

package/schemas/dataset.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/dataset.schema.json",
+  "title": "Dataset root descriptor",
+  "description": "Optional root descriptor (dataset.json) a design-data dataset MAY carry to declare which optional directories are present, pin the targeted spec version, and override default discovery paths. Absence of this file is not an error; see spec/dataset-layout.md.",
+  "type": "object",
+  "properties": {
+    "specVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The spec version this dataset targets (e.g. \"1.0.0-draft\")."
+    },
+    "directories": {
+      "type": "object",
+      "description": "Declares which registered directories the dataset provides. List a directory key with the value true to declare it present and authoritative; omit the key otherwise. The value is constrained to true so the flag cannot be used to negate a directory's presence (in particular it cannot waive the required tokens/ directory).",
+      "properties": {
+        "tokens": { "const": true },
+        "components": { "const": true },
+        "fields": { "const": true },
+        "modeSets": { "const": true },
+        "registry": { "const": true }
+      },
+      "additionalProperties": false
+    },
+    "paths": {
+      "type": "object",
+      "description": "Optional overrides for the default discovery paths, relative to the dataset root. When omitted, tooling uses the conventional directory names defined in spec/dataset-layout.md.",
+      "properties": {
+        "tokens": { "type": "string", "minLength": 1 },
+        "components": { "type": "string", "minLength": 1 },
+        "fields": { "type": "string", "minLength": 1 },
+        "modeSets": { "type": "string", "minLength": 1 },
+        "registry": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/mode-set.schema.json

@@ -6,6 +6,10 @@
   "type": "object",
   "required": ["name", "modes", "default"],
   "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
     "specVersion": {
       "const": "1.0.0-draft"
     },

package/spec/dataset-layout.md

@@ -0,0 +1,72 @@
+# Dataset layout
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the normative **directory layout** of a conformant design-data **dataset**: which directories are required, which are optional but registered, how files in each directory are named and validated, how tooling **discovers** a dataset on disk, and the optional root **descriptor** a dataset MAY carry.
+
+A **dataset** is a directory tree that holds design tokens and the optional catalogs (components, fields, mode sets, registry vocabulary) that describe them. The Spectrum foundation dataset lives at `packages/design-data/`, but any design system MAY publish a dataset in this layout.
+
+## Directory layout
+
+A dataset is rooted at a single **dataset root** directory. The following table defines the directories tooling recognizes:
+
+| Directory     | Status                | Contents                                                             | Schema                                                            |
+| ------------- | --------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `tokens/`     | **Required**          | Cascade-format token files, named `*.tokens.json`.                   | [`cascade-file.schema.json`](../schemas/cascade-file.schema.json) |
+| `components/` | Optional (registered) | One component declaration per `*.json` file.                         | [`component.schema.json`](../schemas/component.schema.json)       |
+| `fields/`     | Optional (registered) | Name-object field declarations, one or more `*.json` files.          | [`field.schema.json`](../schemas/field.schema.json)               |
+| `mode-sets/`  | Optional (registered) | Mode set declarations, one per `*.json` file.                        | [`mode-set.schema.json`](../schemas/mode-set.schema.json)         |
+| `registry/`   | Optional (registered) | Registry value collections (vocabulary), one or more `*.json` files. | [`registry-value.json`](../schemas/registry-value.json)           |
+
+**NORMATIVE:** A conformant dataset **MUST** contain a `tokens/` directory holding at least one `*.tokens.json` file. A dataset with no `tokens/` directory, or a `tokens/` directory containing no `*.tokens.json` file, is **not** conformant.
+
+**NORMATIVE:** When a **registered** directory name (`components/`, `fields/`, `mode-sets/`, `registry/`) is present, the files it contains **MUST** validate against the schema named above. Tooling validating a dataset **MUST** validate the files in every registered directory that is present.
+
+**RECOMMENDED:** A registered directory that exists **SHOULD** contain at least one conformant `*.json` file. An empty registered directory is permitted but **SHOULD** produce a warning, since it usually indicates incomplete data rather than intent.
+
+**NORMATIVE:** Directory names not listed above carry no special meaning and are ignored by dataset-layout validation. Tooling **MUST NOT** treat an unrecognized sibling directory as an error.
+
+### File-naming patterns
+
+| Directory     | Pattern            | Notes                                                                          |
+| ------------- | ------------------ | ------------------------------------------------------------------------------ |
+| `tokens/`     | `**/*.tokens.json` | May be nested in subdirectories; only `*.tokens.json` files are token sources. |
+| `components/` | `*.json`           | One declaration per file.                                                      |
+| `fields/`     | `*.json`           | The catalog MAY be split across multiple files.                                |
+| `mode-sets/`  | `*.json`           | One declaration per file.                                                      |
+| `registry/`   | `*.json`           | One value collection per file.                                                 |
+
+## Dataset discovery
+
+Tooling that operates on "the current dataset" (rather than an explicit path) **MUST** resolve the dataset root using the following precedence. The first match wins; later tiers are only consulted when an earlier tier does not resolve a value.
+
+1. **Explicit override** — a path passed directly by the caller (CLI positional argument or `--*-path` flag, environment variable). Explicit overrides always win.
+2. **Config file** — a `.design-data.toml` discovered by walking **up** the ancestor chain from the working directory. A `[source]` block of `type = "path"` names the dataset root (resolved relative to the config file's directory). This is the explicit, portable way to point a project at a dataset outside its own tree.
+3. **In-repo probing** — when running inside a monorepo checkout, probe for the standard layout relative to the working directory (`packages/design-data/tokens` and one level up). This preserves the in-repo workflow with zero configuration.
+4. **Embedded snapshot** — when no dataset is found on disk, tooling MAY fall back to a snapshot of the foundation dataset embedded in the binary, materialized to a local cache directory.
+
+**NORMATIVE:** The required directory (`tokens/`) and registered optional directories are resolved **relative to the dataset root** determined above. A discovery tier that resolves a dataset root **MUST** look for `tokens/`, `components/`, `fields/`, `mode-sets/`, and `registry/` directly under that root.
+
+The reference implementation of this algorithm lives in the SDK at `sdk/core/src/data_source/mod.rs` (`resolve`, `from_root`, and `probe_cwd`).
+
+## Root descriptor
+
+A dataset **MAY** carry a root **descriptor** to make its structure and target spec version explicit. Two forms are recognized:
+
+* **`.design-data.toml`** — a project-level config (TOML) that primarily declares where the dataset lives (`[source]`) and cache overrides. It is consumed during [discovery](#dataset-discovery) tier 2.
+* **`dataset.json`** — an OPTIONAL JSON descriptor placed at the dataset root that **MAY** declare which optional directories are present, pin the spec version the dataset targets, and override default discovery paths. It **MUST** conform to [`dataset.schema.json`](../schemas/dataset.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/dataset.schema.json`).
+
+**NORMATIVE:** Neither descriptor is required. A dataset with a conformant `tokens/` directory and no descriptor is fully conformant. When a `dataset.json` is present it **MUST** validate against `dataset.schema.json`, but its absence **MUST NOT** be treated as an error.
+
+## Structural validation
+
+**NORMATIVE:** Validators implementing rule **`SPEC-044`** (`dataset-structure`) **MUST** report an **error** when a dataset path lacks a `tokens/` directory containing at least one `*.tokens.json` file. The check **MUST** fire **before** token- and component-level rules so that downstream rules can assume the dataset structure is present, and so that an incomplete dataset produces a clear "dataset structure is incomplete" diagnostic rather than a cascade of confusing per-file errors.
+
+**RECOMMENDED:** Validators implementing `SPEC-044` **SHOULD** emit a **warning** when a registered optional directory is present but contains no conformant `*.json` file. See `rules/rules.yaml` for the full rule definition.
+
+## References
+
+* [#1114 — Define normative dataset-directory layout and add SPEC-044 structural pre-check](https://github.com/adobe/spectrum-design-data/issues/1114)
+* [#1113 — Consolidate Spectrum design data into a single package](https://github.com/adobe/spectrum-design-data/pull/1113)
+* [#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)

package/spec/index.md

@@ -25,6 +25,7 @@ The specification defines:
 11. **Document blocks** — typed prose blocks attachable to tokens, components, and anatomy parts; makes design guidance machine-readable and agent-queryable ([Document blocks](document-blocks.md)).
 12. **Agent-readable surface** — operations and transport contracts (CLI, MCP server, Agent Skill) for AI agents consuming spec-conformant design data; covers session primer, token resolution, validation, query, and component description ([Agent-readable surface](agent-surface.md)).
 13. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
+14. **Dataset layout** — normative directory structure of a dataset (`tokens/`, `components/`, `fields/`, `mode-sets/`, `registry/`), discovery algorithm, and optional root descriptor ([Dataset layout](dataset-layout.md)).
 
 ## Conformance
 
@@ -77,6 +78,7 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | [Document blocks](document-blocks.md)               | Typed prose blocks (purpose, guideline, accessibility, do-dont, examples) attachable to any entity.                               |
 | [Agent-readable surface](agent-surface.md)          | Transport contracts (CLI, MCP, Agent Skill) and operation catalog for AI agents consuming spec-conformant design data.            |
 | [Evolution](evolution.md)                           | Deprecation lifecycle, migration windows, change classification.                                                                  |
+| [Dataset layout](dataset-layout.md)                 | Normative dataset directory structure, discovery algorithm, optional root descriptor, and SPEC-044 structural pre-check.          |
 
 ## JSON Schema `$id` and versioning
 

package/spec/taxonomy.md

@@ -104,15 +104,16 @@ Example: `colorFamily=blue` + `scaleIndex=100` → `blue-100`.
 
 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-data/registry/typography-families.json).                                                                  |
-| Weight    | `weight`          | How?    | Typographic weight (e.g. `regular`, `bold`, `light`, `black`). Values come from [`typography-weights.json`](../../packages/design-data/registry/typography-weights.json).                                                                           |
-| Style     | `style`           | How?    | Typographic style (e.g. `italic`, `oblique`, `normal`). Include `normal` when the token explicitly declares a normal style (e.g. a reset). Values come from [`typography-styles.json`](../../packages/design-data/registry/typography-styles.json). |
-| Alignment | `alignment`       | How?    | Horizontal text-alignment direction (e.g. `start`, `center`, `end`). Corresponds to the CSS `text-align` axis. Values come from [`alignments.json`](../../packages/design-data/registry/alignments.json).                                           |
-| Scale     | `scaleIndex`      | Which?  | Numeric size scale step (e.g. `75`, `100`, `200`). Shared with other token types; not scope-restricted.                                                                                                                                             |
+**NORMATIVE:** Typography tokens SHOULD include at least one of `family`, `weight`, `style`, `scaleIndex`, or `structure`. Tokens missing all five are flagged by rule SPEC-043 (`domain-required-fields`, warning). `family`, `weight`, and `style` are the primary identifiers; `scaleIndex` and `structure` satisfy the rule for scale-indexed and structural typography tokens respectively.
+
+| 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-data/registry/typography-families.json).                                                                                                                |
+| Weight    | `weight`          | How?    | Typographic weight (e.g. `regular`, `bold`, `light`, `black`). Values come from [`typography-weights.json`](../../packages/design-data/registry/typography-weights.json).                                                                                                                         |
+| Style     | `style`           | How?    | Typographic style (e.g. `italic`, `oblique`, `normal`). Include `normal` when the token explicitly declares a normal style (e.g. a reset). Values come from [`typography-styles.json`](../../packages/design-data/registry/typography-styles.json).                                               |
+| Alignment | `alignment`       | How?    | Horizontal text-alignment direction (e.g. `start`, `center`, `end`). Corresponds to the CSS `text-align` axis. Values come from [`alignments.json`](../../packages/design-data/registry/alignments.json).                                                                                         |
+| Scale     | `scaleIndex`      | Which?  | Numeric size scale step (e.g. `75`, `100`, `200`). Shared with other token types; not scope-restricted.                                                                                                                                                                                           |
+| Structure | `structure`       | Where?  | Structural typography scale this token belongs to (e.g. `body`, `detail`, `heading`). Used for tokens that apply within a named typographic structure rather than a specific family/weight/style axis. Values come from [`structures.json`](../../packages/design-data/registry/structures.json). |
 
 **Default serialization order for typography tokens:**