@adobe/design-data-spec 0.2.0 → 0.3.0

package/spec/component-format.md

@@ -0,0 +1,326 @@
+# Component format
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the normative **component declaration** object: identity (`$id`, `name`, `displayName`), component metadata (`meta`), API options (`options`), named content slots (`slots`), anatomy parts (`anatomy`), state model (`states`), and lifecycle metadata.
+
+Component declarations close the structural gap between the token name-object's `component`, `variant`, `anatomy`, and `state` fields and the declared surface of each component. Before this chapter, a token referencing `component: "button"` with `variant: "foo"` was undetectable as invalid because no machine-readable component contract existed in the same spec. After this chapter, validators enforce cross-reference rules (see [SPEC rules](#spec-rules)).
+
+Scoped under [RFC-A — Component Contract in Design Data Spec](https://github.com/adobe/spectrum-design-data/discussions/832). See also [rfc-coordination.md](../docs/rfc-coordination.md).
+
+## Document shape
+
+A component declaration is a **single JSON object** in a `.json` file. One file per component. Files live under a `components/` directory within a design-data package.
+
+**NORMATIVE:** Each component declaration file **MUST** validate against the Layer 1 schema [`component.schema.json`](../schemas/component.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json`). Layer 1 and Layer 2 validation are defined in the [validation layers](index.md#validation-layers) section of the overview.
+
+## Component object
+
+### Required fields
+
+A component declaration **MUST** contain:
+
+| Field         | Type              | Description                                                                           |
+| ------------- | ----------------- | ------------------------------------------------------------------------------------- |
+| `$id`         | URI string        | Canonical identifier for this component declaration.                                  |
+| `name`        | kebab-case string | Machine identifier; used as the value of the `component` field in token name objects. |
+| `displayName` | string            | Human-readable component name (e.g. `"Button"`).                                      |
+| `meta`        | object            | Category and documentation link — see [Meta](#meta).                                  |
+
+### Optional fields
+
+| Field         | Type   | Description                                                                                                                                |
+| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `specVersion` | string | Declares which spec version this document targets. Currently `"1.0.0-draft"`; future stable releases will accept their own version string. |
+| `description` | string | Plain-text description of the component's purpose.                                                                                         |
+| `options`     | object | Component API options — see [Options](#options).                                                                                           |
+| `slots`       | array  | Named content injection points — see [Slots](#slots).                                                                                      |
+| `anatomy`     | array  | Named anatomy parts — see [Anatomy (stub)](#anatomy-stub).                                                                                 |
+| `states`      | array  | Per-component state declarations — see [States (stub)](#states-stub).                                                                      |
+| `lifecycle`   | object | Version lifecycle metadata — see [Lifecycle](#lifecycle).                                                                                  |
+
+**NORMATIVE:** No properties beyond those listed above are permitted at the top level of a component declaration. Additional fields **MUST** cause a Layer 1 schema error.
+
+### `$id`
+
+**NORMATIVE:** The `$id` **MUST** be a valid URI identifying this component declaration document. The recommended pattern is:
+
+```
+https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/{name}.json
+```
+
+where `{name}` matches the component's `name` field.
+
+### `name`
+
+**NORMATIVE:** `name` **MUST** match the pattern `^[a-z][a-z0-9-]*$` — lower-case kebab-case, non-empty.
+
+**NORMATIVE:** `name` **MUST** be unique within a dataset. No two component declarations in the same design-data package may share a `name` value.
+
+**NORMATIVE:** Token name-object `component` field values **MUST** match the `name` of a declared component in the dataset (rule SPEC-018). An undeclared `component` value is a validation error.
+
+### Meta
+
+**NORMATIVE:** `meta` **MUST** contain:
+
+| Field              | Type          | Values                                                                                                    |
+| ------------------ | ------------- | --------------------------------------------------------------------------------------------------------- |
+| `category`         | string (enum) | `actions`, `containers`, `data visualization`, `feedback`, `inputs`, `navigation`, `status`, `typography` |
+| `documentationUrl` | URI string    | Link to the component's documentation page.                                                               |
+
+```json
+"meta": {
+  "category": "actions",
+  "documentationUrl": "https://spectrum.adobe.com/page/button/"
+}
+```
+
+## Options
+
+The `options` block declares the component's API surface — the configurable properties that affect its appearance or behavior. It mirrors the shape of `@adobe/spectrum-component-api-schemas` for backward compatibility.
+
+**NORMATIVE:** `options` **MUST** be a JSON object. Each key is an option name; each value is an **option descriptor**.
+
+### Option descriptor
+
+An option descriptor is a JSON object with the following fields:
+
+| Field         | Type            | Required | Description                                                                      |
+| ------------- | --------------- | -------- | -------------------------------------------------------------------------------- |
+| `type`        | string or array | OPTIONAL | JSON Schema primitive type(s): `"string"`, `"boolean"`, `"number"`, `"integer"`. |
+| `enum`        | array           | OPTIONAL | Exhaustive list of permitted values.                                             |
+| `default`     | any             | OPTIONAL | Default value when the option is not specified.                                  |
+| `description` | string          | OPTIONAL | Plain-text description of what the option controls.                              |
+| `$ref`        | URI string      | OPTIONAL | Reference to a shared type schema (e.g. `workflow-icon.json`).                   |
+
+**NORMATIVE:** Each key in `options` **MUST** be camelCase.
+
+**NORMATIVE:** Boolean option names **MUST** begin with `is` or `has` (e.g. `isDisabled`, `hasIcon`).
+
+**NORMATIVE:** When `enum` is present, token name-object `variant` field values referencing this component **MUST** be drawn from the declared `variant` option enum (rule SPEC-019). Other option enums are informative for tooling but do not currently drive SPEC rules.
+
+```json
+"options": {
+  "variant": {
+    "type": "string",
+    "enum": ["accent", "negative", "primary", "secondary"],
+    "default": "accent",
+    "description": "Visual emphasis level."
+  },
+  "size": {
+    "type": "string",
+    "enum": ["s", "m", "l", "xl"],
+    "default": "m"
+  },
+  "isDisabled": {
+    "type": "boolean",
+    "default": false
+  },
+  "icon": {
+    "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
+    "description": "Icon placed at the start of the button. Required when hideLabel is true."
+  }
+}
+```
+
+## Slots
+
+The `slots` block declares the component's named **content injection points** — the positions where consumers place child content. Slot declarations are derived from the cross-platform audit in [`audits/slots.audit.md`](../audits/slots.audit.md).
+
+**NORMATIVE:** `slots` **MUST** be a JSON array. Each element is a **slot declaration**.
+
+### Slot declaration
+
+| Field         | Type    | Required | Description                                                                 |
+| ------------- | ------- | -------- | --------------------------------------------------------------------------- |
+| `name`        | string  | REQUIRED | Slot identifier. **SHOULD** come from the canonical vocabulary (see below). |
+| `description` | string  | OPTIONAL | Plain-text description of what content goes in this slot.                   |
+| `required`    | boolean | OPTIONAL | Whether consumers **MUST** populate this slot. Default: `false`.            |
+
+### Canonical slot vocabulary
+
+The following slot names are defined by the cross-platform audit and **SHOULD** be used in preference to custom names:
+
+| Name                 | Semantics                                                               |
+| -------------------- | ----------------------------------------------------------------------- |
+| `default`            | Primary content (text, children). The main content slot.                |
+| `icon`               | Decorative icon at the leading edge of the component.                   |
+| `label`              | Human-readable identifier / placeholder text (distinct from `default`). |
+| `help-text`          | Non-error guidance text below a form field.                             |
+| `negative-help-text` | Validation error message for a form field.                              |
+| `action`             | Secondary interactive button or call-to-action.                         |
+| `heading`            | Section or dialog heading.                                              |
+| `description`        | Section or dialog body text (distinct from `help-text`).                |
+| `hero`               | Large header media (e.g. dialog hero image).                            |
+| `footer`             | Below-content supplemental area (e.g. dialog footer).                   |
+| `tooltip`            | Floating annotation attached to the component.                          |
+
+**NORMATIVE:** Custom slot names are permitted but **SHOULD** be documented in the slot's `description` field (rule SPEC-021 fires a warning for undocumented custom names).
+
+**RECOMMENDED:** Components **SHOULD** declare a `default` slot when they accept primary child content.
+
+```json
+"slots": [
+  {
+    "name": "default",
+    "description": "Text label of the button.",
+    "required": false
+  },
+  {
+    "name": "icon",
+    "description": "Icon placed at the start of the button. Required when isLabelHidden is true."
+  }
+]
+```
+
+## Anatomy (stub)
+
+The `anatomy` block declares the component's named **visual parts** — the anatomy terms used in token name-object `anatomy` fields. Full normative definition is in [`spec/anatomy-format.md`](anatomy-format.md) (Phase 6.2).
+
+**NORMATIVE:** `anatomy` **MUST** be a JSON array. Each element is an anatomy part object.
+
+**NORMATIVE:** Token name-object `anatomy` field values referencing this component **MUST** match the `name` of a declared anatomy part (rule SPEC-020).
+
+Each anatomy part carries at minimum:
+
+| Field         | Type             | Required | Description                                                    |
+| ------------- | ---------------- | -------- | -------------------------------------------------------------- |
+| `name`        | string           | REQUIRED | Anatomy part identifier (e.g. `icon`, `label`, `handle`).      |
+| `description` | string           | OPTIONAL | Plain-text description of the part.                            |
+| `required`    | boolean          | OPTIONAL | Whether this part is always present. Default: `false`.         |
+| `contains`    | array of strings | OPTIONAL | Informative: other anatomy part names nested within this part. |
+
+See [`spec/anatomy-format.md`](anatomy-format.md) for constraints, cross-field validation, and the full anatomy part schema.
+
+```json
+"anatomy": [
+  { "name": "icon", "description": "Leading icon." },
+  { "name": "label", "description": "Button text.", "required": true }
+]
+```
+
+## States (stub)
+
+The `states` block declares the component's **interactive and semantic states** — the state terms used in token name-object `state` fields. Full normative definition is in [`spec/state-model.md`](state-model.md) (Phase 6.3).
+
+**NORMATIVE:** `states` **MUST** be a JSON array. Each element is a state declaration object.
+
+Each state carries at minimum:
+
+| Field        | Type    | Required | Description                                                                                                                               |
+| ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`       | string  | REQUIRED | State identifier (e.g. `hover`, `focus`, `disabled`).                                                                                     |
+| `trigger`    | string  | OPTIONAL | `"prop"` for persistent prop-driven states (e.g. `isDisabled`) or `"interaction"` for runtime interaction states (hover, focus, pressed). |
+| `precedence` | integer | OPTIONAL | Resolution precedence; higher integer wins when multiple states are active.                                                               |
+| `layered`    | boolean | OPTIONAL | `true` for states that compose with others (e.g. focus ring over hover). Default: `false`.                                                |
+
+See [`spec/state-model.md`](state-model.md) for the full state resolution algorithm, trigger semantics, and precedence rules.
+
+```json
+"states": [
+  { "name": "hover",    "trigger": "interaction", "precedence": 50 },
+  { "name": "focus",    "trigger": "interaction", "precedence": 60, "layered": true },
+  { "name": "disabled", "trigger": "prop",        "precedence": 100 }
+]
+```
+
+## Lifecycle
+
+The `lifecycle` block tracks a component declaration's version history. It mirrors the per-token lifecycle pattern from [`spec/token-format.md`](token-format.md#lifecycle-and-metadata).
+
+| Field               | Type            | Description                                                                    |
+| ------------------- | --------------- | ------------------------------------------------------------------------------ |
+| `introduced`        | string          | Spec version when this component declaration was added (e.g. `"1.0.0-draft"`). |
+| `deprecated`        | string          | Spec version when this component was deprecated. Truthy = deprecated.          |
+| `deprecatedComment` | string          | Human-readable explanation of the deprecation and migration path.              |
+| `replacedBy`        | string or array | `name` value(s) of the replacement component(s).                               |
+
+```json
+"lifecycle": {
+  "introduced": "1.0.0-draft"
+}
+```
+
+## SPEC rules
+
+The following rules are added to the Layer 2 rule catalog (`rules/rules.yaml`) by this chapter. New component cross-reference rules start at SPEC-018 to avoid collision with existing token rules (SPEC-001–SPEC-017).
+
+| Rule ID  | Name                        | Severity | Assert                                                                                                                                                                        |
+| -------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SPEC-018 | `component-name-exists`     | error    | Token `component` field value **MUST** match the `name` of a declared component in the dataset.                                                                               |
+| SPEC-019 | `component-variant-valid`   | error    | Token `variant` field value **MUST** match a value in the declared `variant` option enum for the referenced component (when that enum exists).                                |
+| SPEC-020 | `component-anatomy-valid`   | error    | Token `anatomy` field value **MUST** match the `name` of a declared anatomy part on the referenced component.                                                                 |
+| SPEC-021 | `component-slot-vocabulary` | warning  | Component `slots` entries with a `name` outside the canonical vocabulary **SHOULD** include a `description`. Custom slot names without descriptions are surfaced as warnings. |
+| SPEC-022 | `component-state-valid`     | error    | Token `state` field value **MUST** match the `name` of a declared state on the referenced component (when state declarations are present).                                    |
+
+## Full example
+
+A complete button component declaration:
+
+```json
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+  "specVersion": "1.0.0-draft",
+  "name": "button",
+  "displayName": "Button",
+  "description": "Buttons allow users to perform an action or to navigate to another page.",
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://spectrum.adobe.com/page/button/"
+  },
+  "options": {
+    "variant": {
+      "type": "string",
+      "enum": ["accent", "negative", "primary", "secondary"],
+      "default": "accent",
+      "description": "Visual emphasis level."
+    },
+    "style": {
+      "type": "string",
+      "enum": ["fill", "outline"],
+      "default": "fill"
+    },
+    "size": {
+      "type": "string",
+      "enum": ["s", "m", "l", "xl"],
+      "default": "m"
+    },
+    "isDisabled": { "type": "boolean", "default": false },
+    "isPending": { "type": "boolean", "default": false },
+    "isLabelHidden": { "type": "boolean", "default": false },
+    "icon": {
+      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
+      "description": "Icon placed at the start of the button. Required when isLabelHidden is true."
+    },
+    "staticColor": {
+      "type": "string",
+      "enum": ["white", "black"],
+      "description": "Static color for use on colored backgrounds. Must not be set for the default variant."
+    }
+  },
+  "slots": [
+    {
+      "name": "default",
+      "description": "Text label of the button.",
+      "required": false
+    },
+    {
+      "name": "icon",
+      "description": "Icon placed at the start of the button."
+    }
+  ],
+  "anatomy": [
+    { "name": "icon",  "description": "Leading icon." },
+    { "name": "label", "description": "Button text.", "required": true }
+  ],
+  "states": [
+    { "name": "hover",    "trigger": "interaction", "precedence": 50 },
+    { "name": "focus",    "trigger": "interaction", "precedence": 60, "layered": true },
+    { "name": "disabled", "trigger": "prop",        "precedence": 100 }
+  ],
+  "lifecycle": {
+    "introduced": "1.0.0-draft"
+  }
+}
+```

package/spec/evolution.md

@@ -12,13 +12,13 @@ Tokens progress through the following lifecycle stages:
 introduced → active → deprecated → planned removal → removed
 ```
 
-| Stage               | Token state                                                                     |
-| ------------------- | ------------------------------------------------------------------------------- |
-| **Introduced**      | Token first appears in the dataset. `introduced` field records the version.     |
-| **Active**          | Token is current and recommended for use. No `deprecated` field.                |
+| Stage               | Token state                                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Introduced**      | Token first appears in the dataset. `introduced` field records the version.                                                                                                    |
+| **Active**          | Token is current and recommended for use. No `deprecated` field.                                                                                                               |
 | **Deprecated**      | Token is no longer recommended. `deprecated` records the version. Consumers receive warnings. `replaced_by` points to the successor token(s) when a direct replacement exists. |
-| **Planned removal** | `plannedRemoval` records the target version. The token remains in the dataset but consumers should complete migration. |
-| **Removed**         | Token is deleted from the dataset. Consumers that still reference it will break. |
+| **Planned removal** | `plannedRemoval` records the target version. The token remains in the dataset but consumers should complete migration.                                                         |
+| **Removed**         | Token is deleted from the dataset. Consumers that still reference it will break.                                                                                               |
 
 ### Lifecycle fields
 
@@ -28,10 +28,10 @@ See [Token format — Lifecycle and metadata](token-format.md#lifecycle-and-meta
 
 When a token carries `replaced_by`:
 
-- Each target UUID **MUST** resolve to an existing token in the dataset (rule `SPEC-010`).
-- The target token **SHOULD NOT** itself be deprecated. Chains of replacements (A replaced by B, B replaced by C) are discouraged; authors should point directly to the final replacement.
-- For a single UUID (1:1 replacement), consumers can mechanically rewrite references.
-- For an array of UUIDs (one-to-many split), the `deprecated_comment` **MUST** explain which replacement applies in which context.
+* Each target UUID **MUST** resolve to an existing token in the dataset (rule `SPEC-010`).
+* The target token **SHOULD NOT** itself be deprecated. Chains of replacements (A replaced by B, B replaced by C) are discouraged; authors should point directly to the final replacement.
+* For a single UUID (1:1 replacement), consumers can mechanically rewrite references.
+* For an array of UUIDs (one-to-many split), the `deprecated_comment` **MUST** explain which replacement applies in which context.
 
 ## Migration windows
 
@@ -49,27 +49,27 @@ The specification follows [Semantic Versioning](https://semver.org/) for its pub
 
 ### Minor changes (backward compatible)
 
-- New tokens added to the dataset
-- New optional fields added to token schema
-- New validation rules added to the rule catalog
-- Tokens deprecated (with `deprecated` field)
-- Rule severity relaxed (error → warning)
-- New enum values added to registries
+* New tokens added to the dataset
+* New optional fields added to token schema
+* New validation rules added to the rule catalog
+* Tokens deprecated (with `deprecated` field)
+* Rule severity relaxed (error → warning)
+* New enum values added to registries
 
 ### Major changes (breaking)
 
-- Tokens removed from the dataset
-- Required fields added to token schema
-- Existing fields removed or type-changed
-- Rule severity tightened (warning → error)
-- Enum values removed from registries
-- Constraint tightening (e.g. stricter value validation)
+* Tokens removed from the dataset
+* Required fields added to token schema
+* Existing fields removed or type-changed
+* Rule severity tightened (warning → error)
+* Enum values removed from registries
+* Constraint tightening (e.g. stricter value validation)
 
 ### Patch changes (clarifications)
 
-- Typo fixes in spec prose
-- Clarifications to normative text that do not change conformance behavior
-- Test fixture additions or corrections
+* Typo fixes in spec prose
+* Clarifications to normative text that do not change conformance behavior
+* Test fixture additions or corrections
 
 ## Legacy format contract
 
@@ -79,13 +79,13 @@ The `@adobe/spectrum-tokens` package continues to publish tokens in the **legacy
 
 ### Lifecycle field mapping
 
-| Cascade format                          | Legacy format                        |
-| --------------------------------------- | ------------------------------------ |
-| `deprecated: "3.2.0"` (version string) | `deprecated: true` (boolean)         |
-| `replaced_by: "<uuid>"`                | `renamed: "<target-token-name>"`     |
-| `introduced`                            | Not emitted                          |
-| `plannedRemoval`                        | Not emitted                          |
-| `deprecated_comment`                    | `deprecated_comment` (passed through)|
+| Cascade format                         | Legacy format                         |
+| -------------------------------------- | ------------------------------------- |
+| `deprecated: "3.2.0"` (version string) | `deprecated: true` (boolean)          |
+| `replaced_by: "<uuid>"`                | `renamed: "<target-token-name>"`      |
+| `introduced`                           | Not emitted                           |
+| `plannedRemoval`                       | Not emitted                           |
+| `deprecated_comment`                   | `deprecated_comment` (passed through) |
 
 ### Coexistence during migration
 

package/spec/index.md

@@ -11,12 +11,15 @@ The specification defines:
 
 1. **Token format** — structured token identity (`name`), literal `value` or alias `$ref`, and lifecycle metadata ([Token format](token-format.md)).
 2. **Taxonomy** — concept categories, token term vocabulary, formatting style, and the distinction between component anatomy and token objects ([Taxonomy](taxonomy.md)).
-3. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
-4. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
-5. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
-6. **Semantic diff** — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions ([Diff](diff.md)).
-7. **Query notation** — filter syntax for selecting tokens by structured fields ([Query](query.md)).
-8. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
+3. **Component format** — component declaration shape: API options, named content slots, anatomy parts, state model, and cross-reference validation rules ([Component format](component-format.md)).
+   3a. **Anatomy format** — anatomy part declaration shape: field constraints, canonical anatomy vocabulary, and cross-reference rules for token `anatomy` field values ([Anatomy format](anatomy-format.md)).
+   3b. **State model** — state declaration shape: trigger semantics, precedence and resolution algorithm, canonical state vocabulary, and cross-reference rules for token `state` field values ([State model](state-model.md)).
+4. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
+5. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
+6. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
+7. **Semantic diff** — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions ([Diff](diff.md)).
+8. **Query notation** — filter syntax for selecting tokens by structured fields ([Query](query.md)).
+9. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
 
 ## Conformance
 
@@ -50,16 +53,19 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 
 ## Normative references (sibling documents)
 
-| Document                        | Role                                                             |
-| ------------------------------- | ---------------------------------------------------------------- |
-| [Token format](token-format.md) | Token `name`, `value` / `$ref`, value types, lifecycle metadata. |
-| [Taxonomy](taxonomy.md)         | Concept categories, vocabulary, formatting, anatomy vs objects.  |
-| [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.            |
-| [Diff](diff.md)                 | Semantic diff change taxonomy, token identity, property changes. |
-| [Query](query.md)               | Filter notation for selecting tokens by structured fields.       |
-| [Evolution](evolution.md)       | Deprecation lifecycle, migration windows, change classification. |
+| Document                                | Role                                                                                                        |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| [Token format](token-format.md)         | Token `name`, `value` / `$ref`, value types, lifecycle metadata.                                            |
+| [Taxonomy](taxonomy.md)                 | Concept categories, vocabulary, formatting, anatomy vs objects.                                             |
+| [Component format](component-format.md) | Component declaration: options, slots, anatomy (→ anatomy-format.md), states (→ state-model.md), lifecycle. |
+| [Anatomy format](anatomy-format.md)     | Anatomy part declarations: field constraints, canonical vocabulary, SPEC-020/SPEC-023/SPEC-024/SPEC-025.    |
+| [State model](state-model.md)           | State declarations: trigger semantics, precedence algorithm, canonical vocabulary, SPEC-022/SPEC-026.       |
+| [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.                                                       |
+| [Diff](diff.md)                         | Semantic diff change taxonomy, token identity, property changes.                                            |
+| [Query](query.md)                       | Filter notation for selecting tokens by structured fields.                                                  |
+| [Evolution](evolution.md)               | Deprecation lifecycle, migration windows, change classification.                                            |
 
 ## JSON Schema `$id` and versioning
 
@@ -76,11 +82,11 @@ Packaged copies in this repository live under `packages/design-data-spec/schemas
 
 ## 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.                                                                                                                                                                  |
+| 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` | Will become a thin adapter over component declarations in `packages/design-data-spec/components/` (Phase 6.5). Until migration, existing schemas remain authoritative. Cross-reference rules SPEC-018–SPEC-020 apply when component declarations are present in the dataset. |
 
 ## Umbrella discussions
 

package/spec/manifest.md

@@ -26,7 +26,9 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
 
 ### `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.
+**NORMATIVE:** Entries **MUST** be non-empty strings.
+
+> **Note:** Query notation syntax is fully defined in [Query](query.md) and is normative for programmatic use. Its normative use in manifest `include`/`exclude` is deferred to a post-`1.0.0-draft` revision pending conformance fixtures; until then, implementations **MUST** treat manifest query values as opaque identifiers.
 
 ### `overrides`