@adobe/design-data-spec 0.14.0 → 1.0.0

package/rules/rules.yaml

@@ -168,7 +168,7 @@ rules:
     name: component-variant-valid
     severity: error
     category: reference-integrity
-    assert: Token name-object 'variant' field value MUST match a value in the declared 'variant' option enum for the referenced component, when that enum exists.
+    assert: Token name-object 'variant' field value MUST match a value in the declared 'variant' option `values` list for the referenced component, when that list exists.
     message: "Token '{token}' has variant '{variant}' which is not declared on component '{component}'"
     spec_ref: spec/component-format.md#options
     introduced_in: "1.0.0-draft"
@@ -355,3 +355,31 @@ rules:
     message: "Token '{token}' references deprecated component '{component}' (deprecated since {version}); update the reference or mark the token deprecated"
     spec_ref: spec/component-format.md#lifecycle
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-037
+    name: sub-entity-deprecation-cascade
+    severity: warning
+    category: reference-integrity
+    assert: >
+      Tokens SHOULD NOT reference a deprecated anatomy part, deprecated component state, or
+      deprecated option value via their `name` object unless the token is itself deprecated.
+      Non-deprecated tokens referencing deprecated sub-entities are surfaced as warnings to
+      prompt authors to update the reference or mark the token deprecated.
+      Deprecation is declared via `lifecycle.deprecated` on anatomy parts, states, and individual
+      option values within the `values` array on option descriptors.
+    message: "Token '{token}' references deprecated {kind} '{value}' on component '{component}' (deprecated since {version}); update the reference or mark the token deprecated"
+    spec_ref: spec/component-format.md#lifecycle
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-038
+    name: option-enum-obsolete
+    severity: warning
+    category: component-contract
+    assert: >
+      Option descriptors SHOULD NOT use the JSON Schema `enum` keyword. The `enum` field is
+      silently accepted at Layer 1 (optionDescriptor uses additionalProperties: true) but has
+      no effect on SDK rules or lifecycle cascade. Use `values` instead so per-value lifecycle
+      metadata can be attached to individual values.
+    message: "Component '{component}' option '{option}' uses the obsolete `enum` keyword; replace with a `values` array so per-value lifecycle metadata can be expressed"
+    spec_ref: spec/component-format.md#option-descriptor
+    introduced_in: "1.0.0-draft"

package/schemas/anatomy-part.schema.json

@@ -35,6 +35,10 @@
       "items": { "$ref": "document-block.schema.json" },
       "minItems": 1,
       "description": "Typed prose blocks for this anatomy part. See spec/document-blocks.md (Phase 9)."
+    },
+    "lifecycle": {
+      "$ref": "component.schema.json#/$defs/lifecycle",
+      "description": "Version lifecycle metadata for this anatomy part. Set lifecycle.deprecated to signal that tokens referencing this part should migrate."
     }
   },
   "additionalProperties": false

package/schemas/component.schema.json

@@ -108,7 +108,8 @@
     },
     "optionDescriptor": {
       "type": "object",
-      "description": "JSON Schema-compatible descriptor for a single component option. Standard JSON Schema keywords (type, enum, default, description, pattern, minimum, maximum, items, properties, etc.) are all permitted.",
+      "description": "Descriptor for a single component option. The `type` keyword follows JSON Schema conventions. Use `values` (not `enum`) to declare permitted values — the structured array allows per-value lifecycle metadata. Other JSON Schema keywords (default, description, pattern, minimum, maximum, items, properties, $ref) are permitted as needed.",
+      "$comment": "additionalProperties: true is required to allow JSON Schema passthrough keywords (pattern, minimum, etc.). This means the legacy `enum` keyword is silently accepted at Layer 1; SPEC-038 closes the gap at Layer 2 by warning when `enum` is present.",
       "properties": {
         "type": {
           "oneOf": [
@@ -142,10 +143,12 @@
             }
           ]
         },
-        "enum": {
+        "values": {
           "type": "array",
           "minItems": 1,
-          "description": "Exhaustive list of permitted values."
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/optionValue" },
+          "description": "Exhaustive list of permitted values for this option, each with optional per-value metadata. Use this instead of the JSON Schema `enum` keyword so that lifecycle annotations can be attached to individual values. Consumed by SPEC-019 (variant validation) and SPEC-037 (deprecation cascade)."
         },
         "default": {
           "description": "Default value when the option is not specified."
@@ -162,6 +165,25 @@
       },
       "additionalProperties": true
     },
+    "optionValue": {
+      "type": "object",
+      "required": ["value"],
+      "description": "A single permitted value for a component option, with optional per-value metadata.",
+      "properties": {
+        "value": {
+          "description": "The permitted option value. Typically a string; the schema does not constrain the type so booleans and numbers remain expressible."
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain-text description of what this value means."
+        },
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle",
+          "description": "Version lifecycle metadata for this value. Set lifecycle.deprecated to signal that tokens referencing this value should migrate (SPEC-037)."
+        }
+      },
+      "additionalProperties": false
+    },
     "slotDeclaration": {
       "type": "object",
       "required": ["name"],
@@ -209,6 +231,10 @@
           "type": "array",
           "items": { "$ref": "document-block.schema.json" },
           "description": "Typed prose blocks for this anatomy part. See spec/document-blocks.md (Phase 9)."
+        },
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle",
+          "description": "Version lifecycle metadata for this anatomy part. Set lifecycle.deprecated to signal that tokens referencing this part should migrate."
         }
       },
       "additionalProperties": false
@@ -255,6 +281,10 @@
           "type": "boolean",
           "default": false,
           "description": "Whether this state prevents all user interaction. See spec/accessibility.md."
+        },
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle",
+          "description": "Version lifecycle metadata for this state. Set lifecycle.deprecated to signal that tokens referencing this state should migrate."
         }
       },
       "additionalProperties": false

package/schemas/state-declaration.schema.json

@@ -30,6 +30,10 @@
       "type": "boolean",
       "default": false,
       "description": "When true, this state composes on top of the winning non-layered state rather than competing with it. Use for focus rings, selection overlays, and similar compositing states."
+    },
+    "lifecycle": {
+      "$ref": "component.schema.json#/$defs/lifecycle",
+      "description": "Version lifecycle metadata for this state. Set lifecycle.deprecated to signal that tokens referencing this state should migrate."
     }
   },
   "additionalProperties": false

package/spec/agent-surface.md

@@ -96,7 +96,7 @@ The `describe_component` tool returns the component declaration object as stored
   "displayName": "Button",
   "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
   "options": {
-    "variant": { "type": "string", "enum": ["accent", "negative", "primary", "secondary"], "default": "accent" }
+    "variant": { "type": "string", "values": [{"value": "accent"}, {"value": "negative"}, {"value": "primary"}, {"value": "secondary"}], "default": "accent" }
   },
   "anatomy": [
     { "name": "icon",  "description": "Leading icon." },

package/spec/anatomy-format.md

@@ -20,6 +20,7 @@ An anatomy part is a **JSON object** that appears as an element of a component d
 | `description` | string           | OPTIONAL | Plain-text description of the part's visual role and boundaries.                                                         |
 | `required`    | boolean          | OPTIONAL | Whether this part is always rendered regardless of configuration. Default: `false`.                                      |
 | `contains`    | array of strings | OPTIONAL | Informative list of child anatomy part names nested within this part (e.g. a `field` contains `["label", "help-text"]`). |
+| `lifecycle`   | object           | OPTIONAL | Version lifecycle metadata for this anatomy part — see [lifecycle](#lifecycle).                                          |
 
 **NORMATIVE:** No properties beyond those listed above are permitted in an anatomy part object. Additional fields **MUST** cause a Layer 1 schema error.
 
@@ -51,6 +52,18 @@ When `required` is `true`, the anatomy part is unconditionally rendered (e.g. a
 
 Each string in `contains` **MUST** match the pattern `^[a-z][a-z0-9-]*$`. References to anatomy part names not declared on the same component are permitted (they may refer to sub-component anatomy in layered designs) but validators **MAY** surface a warning for unresolved references.
 
+### `lifecycle`
+
+**OPTIONAL.** A version lifecycle object tracking the history of this anatomy part. Uses the same shape as the component-level `lifecycle` block (see [Component format — Lifecycle](component-format.md#lifecycle)).
+
+| Field               | Type   | Description                                                                                    |
+| ------------------- | ------ | ---------------------------------------------------------------------------------------------- |
+| `deprecated`        | string | Spec version when this anatomy part was deprecated. A truthy string signals deprecation.       |
+| `deprecatedComment` | string | Human-readable explanation of the deprecation and migration path (e.g. `"Renamed to thumb."`). |
+| `replacedBy`        | string | `name` of the replacement anatomy part.                                                        |
+
+**ADVISORY:** When an anatomy part carries a `lifecycle.deprecated` value, non-deprecated tokens that reference this anatomy part via `name.anatomy` **SHOULD** be updated to remove or replace the reference. Rule SPEC-037 fires an advisory warning for such references to prompt migration.
+
 ```json
 "anatomy": [
   {
@@ -121,6 +134,7 @@ The following rules in the Layer 2 rule catalog (`rules/rules.yaml`) apply to an
 | SPEC-024 | `anatomy-part-name-unique`        | error    | Anatomy part `name` values **MUST** be unique within a single component's `anatomy` array.                                                                |
 | SPEC-025 | `anatomy-requires-component`      | error    | A token name object **MUST NOT** include an `anatomy` field unless a `component` field is also present.                                                   |
 | SPEC-035 | `anatomy-part-name-registry-sync` | warning  | A component anatomy part's `name` **SHOULD** appear in the canonical anatomy-terms registry (`anatomy-terms.json`).                                       |
+| SPEC-037 | `sub-entity-deprecation-cascade`  | warning  | A non-deprecated token **SHOULD NOT** reference a deprecated anatomy part via `name.anatomy`. Advisory warning prompts migration.                         |
 
 ## Full example
 

package/spec/component-format.md

@@ -88,31 +88,72 @@ The `options` block declares the component's API surface — the configurable pr
 
 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`).                   |
+| Field         | Type            | Required | Description                                                                                                                                                                                                          |
+| ------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`        | string or array | OPTIONAL | JSON Schema primitive type(s): `"string"`, `"boolean"`, `"number"`, `"integer"`.                                                                                                                                     |
+| `values`      | array           | OPTIONAL | Exhaustive list of permitted values, each an [`optionValue`](#optionvalue) object. Use this instead of JSON Schema's `enum` keyword so per-value lifecycle metadata can be expressed without a separate sidecar map. |
+| `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`).                                                                                                                                                       |
+
+### optionValue
+
+Each entry in `values` is an object:
+
+| Field         | Type   | Required | Description                                                                              |
+| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
+| `value`       | any    | REQUIRED | The permitted option value.                                                              |
+| `description` | string | OPTIONAL | Plain-text description of what this value means.                                         |
+| `lifecycle`   | object | OPTIONAL | Version lifecycle metadata. Set `lifecycle.deprecated` to signal migration via SPEC-037. |
 
 **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.
+**NORMATIVE:** When `values` is present, token name-object `variant` field values referencing this component **MUST** be drawn from the declared `variant` option `values` list (rule SPEC-019). Other option `values` lists are informative for tooling but do not currently drive SPEC rules.
+
+**ADVISORY:** When a value in `values` carries a `lifecycle.deprecated` string and a non-deprecated token references that value via its `name` object field, SPEC-037 fires an advisory warning prompting migration or token deprecation.
+
+Example with a deprecated option value:
+
+```json
+"variant": {
+  "type": "string",
+  "values": [
+    { "value": "primary" },
+    { "value": "secondary" },
+    {
+      "value": "cta",
+      "lifecycle": {
+        "deprecated": "1.0.0-draft",
+        "deprecatedComment": "Use primary instead."
+      }
+    }
+  ]
+}
+```
 
 ```json
 "options": {
   "variant": {
     "type": "string",
-    "enum": ["accent", "negative", "primary", "secondary"],
+    "values": [
+      { "value": "accent" },
+      { "value": "negative" },
+      { "value": "primary" },
+      { "value": "secondary" }
+    ],
     "default": "accent",
     "description": "Visual emphasis level."
   },
   "size": {
     "type": "string",
-    "enum": ["s", "m", "l", "xl"],
+    "values": [
+      { "value": "s" },
+      { "value": "m" },
+      { "value": "l" },
+      { "value": "xl" }
+    ],
     "default": "m"
   },
   "isDisabled": {
@@ -186,12 +227,13 @@ The `anatomy` block declares the component's named **visual parts** — the anat
 
 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. |
+| 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.                                                      |
+| `lifecycle`   | object           | OPTIONAL | Version lifecycle metadata for this part. When `lifecycle.deprecated` is set, SPEC-037 fires on referencing tokens. |
 
 See [`spec/anatomy-format.md`](anatomy-format.md) for constraints, cross-field validation, and the full anatomy part schema.
 
@@ -216,6 +258,7 @@ Each state carries at minimum:
 | `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`.                                                |
+| `lifecycle`  | object  | OPTIONAL | Version lifecycle metadata for this state. When `lifecycle.deprecated` is set, SPEC-037 fires on referencing tokens.                      |
 
 See [`spec/state-model.md`](state-model.md) for the full state resolution algorithm, trigger semantics, and precedence rules.
 
@@ -271,14 +314,17 @@ The `context` field is informative. It is used by `describe_component` (Phase 8
 
 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).                                    |
-| SPEC-027 | `token-binding-token-exists` | error    | Each `tokenBindings[].token` value **MUST** match the name of a declared token in the dataset (Phase 6.7).                                                                    |
+| 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 `values` list for the referenced component (when that list 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).                                                                                                                        |
+| SPEC-027 | `token-binding-token-exists`     | error    | Each `tokenBindings[].token` value **MUST** match the name of a declared token in the dataset (Phase 6.7).                                                                                                                                                        |
+| SPEC-036 | `component-deprecation-cascade`  | warning  | A non-deprecated token **SHOULD NOT** reference a deprecated component via `name.component`. Advisory warning prompts updating the component reference or marking the token deprecated.                                                                           |
+| SPEC-037 | `sub-entity-deprecation-cascade` | warning  | A non-deprecated token **SHOULD NOT** reference a deprecated anatomy part, state, or option value via `name.*`. Advisory warning prompts migration. Requires `lifecycle` on anatomy/state or `lifecycle` on the matching `values` entry on the option descriptor. |
+| SPEC-038 | `option-enum-obsolete`           | warning  | An option descriptor **SHOULD NOT** use the JSON Schema `enum` keyword. `additionalProperties: true` silently accepts `enum` at Layer 1; SPEC-038 flags it at Layer 2 so authors replace it with the `values` array.                                              |
 
 ## Full example
 
@@ -299,18 +345,28 @@ A complete button component declaration:
   "options": {
     "variant": {
       "type": "string",
-      "enum": ["accent", "negative", "primary", "secondary"],
+      "values": [
+        { "value": "accent" },
+        { "value": "negative" },
+        { "value": "primary" },
+        { "value": "secondary" }
+      ],
       "default": "accent",
       "description": "Visual emphasis level."
     },
     "style": {
       "type": "string",
-      "enum": ["fill", "outline"],
+      "values": [{ "value": "fill" }, { "value": "outline" }],
       "default": "fill"
     },
     "size": {
       "type": "string",
-      "enum": ["s", "m", "l", "xl"],
+      "values": [
+        { "value": "s" },
+        { "value": "m" },
+        { "value": "l" },
+        { "value": "xl" }
+      ],
       "default": "m"
     },
     "isDisabled": { "type": "boolean", "default": false },
@@ -322,7 +378,7 @@ A complete button component declaration:
     },
     "staticColor": {
       "type": "string",
-      "enum": ["white", "black"],
+      "values": [{ "value": "white" }, { "value": "black" }],
       "description": "Static color for use on colored backgrounds. Must not be set for the default variant."
     }
   },

package/spec/state-model.md

@@ -34,6 +34,7 @@ A state declaration is a **JSON object** that appears as an element of a compone
 | `trigger`     | string  | OPTIONAL | `"prop"` for persistent prop-driven states; `"interaction"` for runtime interaction states. See [Trigger semantics](#trigger-semantics).   |
 | `precedence`  | integer | OPTIONAL | Resolution precedence; higher value wins when multiple non-layered states are active simultaneously. Defaults to `0` if omitted.           |
 | `layered`     | boolean | OPTIONAL | When `true`, this state composes on top of the winning non-layered state rather than competing with it. Default: `false`.                  |
+| `lifecycle`   | object  | OPTIONAL | Version lifecycle metadata for this state — see [lifecycle](#lifecycle).                                                                   |
 
 **NORMATIVE:** No properties beyond those listed above are permitted in a state declaration object. Additional fields **MUST** cause a Layer 1 schema error.
 
@@ -76,6 +77,18 @@ When `layered: true`, the state does not participate in the non-layered preceden
 
 Typical use: focus ring states (`focus`, `focus-visible`) that must be visible regardless of whether the component is also in a `hover` or `selected` state.
 
+### `lifecycle`
+
+**OPTIONAL.** A version lifecycle object tracking the history of this state declaration. Uses the same shape as the component-level `lifecycle` block (see [Component format — Lifecycle](component-format.md#lifecycle)).
+
+| Field               | Type   | Description                                                                                      |
+| ------------------- | ------ | ------------------------------------------------------------------------------------------------ |
+| `deprecated`        | string | Spec version when this state was deprecated. A truthy string signals deprecation.                |
+| `deprecatedComment` | string | Human-readable explanation of the deprecation and migration path (e.g. `"Use active instead."`). |
+| `replacedBy`        | string | `name` of the replacement state.                                                                 |
+
+**ADVISORY:** When a state carries a `lifecycle.deprecated` value, non-deprecated tokens that reference this state via `name.state` **SHOULD** be updated to remove or replace the reference. Rule SPEC-037 fires an advisory warning for such references to prompt migration.
+
 ## Trigger semantics
 
 ### `prop` trigger
@@ -185,10 +198,11 @@ See [Token format — Name object](token-format.md#name-object) for the full nam
 
 The following rules in the Layer 2 rule catalog (`rules/rules.yaml`) apply to state declarations. SPEC-022 was introduced in Phase 6.1 (component-format); SPEC-026 is introduced by this chapter.
 
-| Rule ID  | Name                           | Severity | Assert                                                                                                                                              |
-| -------- | ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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).          |
-| SPEC-026 | `state-custom-name-documented` | warning  | State declarations with a `name` outside the canonical state vocabulary **SHOULD** include a `description` field documenting the state's semantics. |
+| Rule ID  | Name                             | Severity | Assert                                                                                                                                              |
+| -------- | -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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).          |
+| SPEC-026 | `state-custom-name-documented`   | warning  | State declarations with a `name` outside the canonical state vocabulary **SHOULD** include a `description` field documenting the state's semantics. |
+| SPEC-037 | `sub-entity-deprecation-cascade` | warning  | A non-deprecated token **SHOULD NOT** reference a deprecated state via `name.state`. Advisory warning prompts migration.                            |
 
 ## Full example