@adobe/design-data-spec 0.2.0 → 0.4.0

package/schemas/component.schema.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
+  "title": "Design data component declaration",
+  "description": "Layer 1 structural schema for a component declaration. Semantic cross-reference rules (component-name-exists, component-variant-valid, etc.) are Layer 2.",
+  "type": "object",
+  "required": ["$id", "name", "displayName", "meta"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "specVersion": {
+      "type": "string",
+      "description": "Spec version this document targets (e.g. '1.0.0-draft')."
+    },
+    "$id": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical identifier for this component declaration."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "description": "Machine identifier (kebab-case). Must match the value used in token name-object 'component' fields."
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable component name (e.g. 'Button')."
+    },
+    "description": {
+      "type": "string",
+      "description": "Plain-text description of the component's purpose."
+    },
+    "meta": {
+      "$ref": "#/$defs/meta"
+    },
+    "options": {
+      "$ref": "#/$defs/optionsMap"
+    },
+    "slots": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/slotDeclaration"
+      },
+      "description": "Named content injection points. See spec/component-format.md#slots."
+    },
+    "anatomy": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/anatomyPart"
+      },
+      "description": "Named visible parts of the component. Full spec in spec/anatomy-format.md (Phase 6.2)."
+    },
+    "states": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/stateDeclaration"
+      },
+      "description": "Per-component state declarations. Full spec in spec/state-model.md (Phase 6.3)."
+    },
+    "lifecycle": {
+      "$ref": "#/$defs/lifecycle"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "meta": {
+      "type": "object",
+      "required": ["category", "documentationUrl"],
+      "properties": {
+        "category": {
+          "type": "string",
+          "enum": [
+            "actions",
+            "containers",
+            "data visualization",
+            "feedback",
+            "inputs",
+            "navigation",
+            "status",
+            "typography"
+          ],
+          "description": "Design system category for this component."
+        },
+        "documentationUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL of the component's documentation page."
+        }
+      },
+      "additionalProperties": false
+    },
+    "optionsMap": {
+      "type": "object",
+      "description": "Component API options. Each key is a camelCase option name; each value is an option descriptor.",
+      "additionalProperties": {
+        "$ref": "#/$defs/optionDescriptor"
+      }
+    },
+    "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.",
+      "properties": {
+        "type": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "string",
+                "boolean",
+                "number",
+                "integer",
+                "object",
+                "array",
+                "null"
+              ]
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "string",
+                  "boolean",
+                  "number",
+                  "integer",
+                  "object",
+                  "array",
+                  "null"
+                ]
+              },
+              "minItems": 1
+            }
+          ]
+        },
+        "enum": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Exhaustive list of permitted values."
+        },
+        "default": {
+          "description": "Default value when the option is not specified."
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain-text description of what the option controls."
+        },
+        "$ref": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "Reference to a shared type schema."
+        }
+      },
+      "additionalProperties": true
+    },
+    "slotDeclaration": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Slot identifier. Should come from the canonical slot vocabulary."
+        },
+        "description": {
+          "type": "string",
+          "description": "What content belongs in this slot."
+        },
+        "required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether consumers must populate this slot."
+        }
+      },
+      "additionalProperties": false
+    },
+    "anatomyPart": {
+      "type": "object",
+      "required": ["name"],
+      "description": "Named visible part of a component. Full spec in spec/anatomy-format.md (Phase 6.2).",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Anatomy part identifier (e.g. 'icon', 'label', 'handle')."
+        },
+        "description": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean",
+          "default": false
+        },
+        "contains": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Informative: anatomy part names nested within this part."
+        }
+      },
+      "additionalProperties": false
+    },
+    "stateDeclaration": {
+      "type": "object",
+      "required": ["name"],
+      "description": "Per-component state declaration. Full spec in spec/state-model.md.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "State identifier (e.g. 'hover', 'focus', 'disabled')."
+        },
+        "description": {
+          "type": "string"
+        },
+        "trigger": {
+          "type": "string",
+          "enum": ["prop", "interaction"],
+          "description": "'prop' for persistent prop-driven states (isDisabled); 'interaction' for runtime states (hover, focus, pressed)."
+        },
+        "precedence": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Resolution precedence; higher integer wins when multiple states are active simultaneously."
+        },
+        "layered": {
+          "type": "boolean",
+          "default": false,
+          "description": "true for states that compose with others (e.g. focus ring layered over hover)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "lifecycle": {
+      "type": "object",
+      "description": "Version lifecycle metadata, mirroring the token lifecycle pattern.",
+      "properties": {
+        "introduced": {
+          "type": "string",
+          "description": "Spec version when this component declaration was added (e.g. '1.0.0-draft')."
+        },
+        "deprecated": {
+          "type": "string",
+          "description": "Spec version when this component was deprecated. Truthy = deprecated."
+        },
+        "deprecatedComment": {
+          "type": "string",
+          "description": "Human-readable explanation of the deprecation and migration path."
+        },
+        "replacedBy": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "minItems": 1
+            }
+          ],
+          "description": "name value(s) of the replacement component(s)."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/state-declaration.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/state-declaration.schema.json",
+  "title": "State declaration",
+  "description": "Layer 1 structural schema for a single state declaration object within a component declaration. Semantic rules (component-state-valid, state-custom-name-documented) are Layer 2.",
+  "type": "object",
+  "required": ["name"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 1,
+      "description": "Kebab-case state identifier. Must match the value used in token name-object 'state' fields."
+    },
+    "description": {
+      "type": "string",
+      "description": "Plain-text description of the state's semantics and the conditions under which it is active."
+    },
+    "trigger": {
+      "type": "string",
+      "enum": ["prop", "interaction"],
+      "description": "'prop' for persistent prop-driven states (e.g. isDisabled); 'interaction' for transient runtime interaction states (hover, focus, pressed)."
+    },
+    "precedence": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Resolution precedence. Higher value wins when multiple non-layered states are active simultaneously. Defaults to 0 when omitted."
+    },
+    "layered": {
+      "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."
+    }
+  },
+  "additionalProperties": false
+}

package/spec/agent-surface.md

@@ -0,0 +1,116 @@
+# Agent-readable surface
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))\
+**Status:** Draft — RFC-C / Phase 8. Surface and tool list are subject to change. No reference implementation exists yet.
+
+This document defines the **agent-readable surface**: the contract an external AI agent uses to consume design data conformant with this specification. It standardizes a small set of operations exposed through three transports — a CLI, a Model Context Protocol (MCP) server, and a Claude Code Agent Skill — all backed by the same resolver, validator, and query implementations that power the rest of the SDK.
+
+## Goals
+
+The surface targets three consumer shapes:
+
+1. **Authoring an external system.** A non-Spectrum design system being constructed inside an AI tool (e.g. a finance-dashboard prototype tool) wants to produce spec-conformant tokens, dimensions, and components without re-deriving the format from prose.
+2. **Extending Spectrum.** A product or platform team adds tokens, components, or overrides on top of the published Spectrum foundation and needs to validate that the additions cascade and resolve correctly.
+3. **Adhering to Spectrum.** A prototyping tool generates UI that should match Spectrum even where no bound component exists (e.g. CSS for a custom card). The agent needs to look up tokens by intent, validate proposed property values against the foundation, and report drift.
+
+**NORMATIVE:** A conforming agent surface implementation MUST support all three consumer shapes, parameterized by the manifest provided at session start (see [Session primer](#session-primer)).
+
+## Non-goals
+
+* Generating finished platform code (Swift, CSS, etc.). Output formatting is the consumer's responsibility; the surface returns structured tokens.
+* Hosting design data. The surface operates on local datasets reachable from the consumer's filesystem, plus optionally a remote published manifest.
+* Replacing the existing Spectrum-bound tools (`@adobe/spectrum-design-data-mcp`, `@adobe/s2-docs-mcp`). Those expose Spectrum-specific shapes; this surface is generic to any spec-conformant dataset.
+
+## Tool catalog
+
+**NORMATIVE:** A conforming implementation MUST expose the following operations. Transport-specific naming (CLI subcommand vs MCP tool name vs skill action) MAY differ; the semantics MUST NOT.
+
+| Operation            | Reads                                                  | Returns                                                                                                                  | Backed by              |
+| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `resolve_token`      | property + dimension context                           | winning token (literal or resolved alias) with file/UUID/specificity                                                     | `cascade::resolve`     |
+| `query_tokens`       | filter expression (see [Query](query.md))              | matching token list                                                                                                      | `query::filter`        |
+| `validate_usage`     | candidate token document or fragment                   | `ValidationReport` (Layer 1 + Layer 2 diagnostics)                                                                       | `validate::validate_*` |
+| `describe_component` | component identifier                                   | component contract (anatomy, options, states); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) | (Phase 6 contract)     |
+| `suggest_token`      | natural-language intent + optional property hint       | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1)                                                | registry + query       |
+| `get_guidance`       | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D                                           | document blocks        |
+| `diff_datasets`      | two dataset roots                                      | `DiffReport` per [Diff](diff.md)                                                                                         | `diff::semantic_diff`  |
+
+**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, and `diff_datasets` MUST be implemented in a conforming agent surface. `suggest_token` and `get_guidance` are RECOMMENDED. `describe_component` becomes NORMATIVE once [#832](https://github.com/adobe/spectrum-design-data/discussions/832) reaches implemented status.
+
+## Session primer
+
+An agent loop benefits from a small, structural overview at session start so that subsequent calls are well-scoped. The **session primer** is a single operation that returns a serialized summary of the active dataset.
+
+**NORMATIVE:** A conforming implementation MUST expose a `primer` operation returning a JSON object with at least:
+
+| Field            | Type           | Meaning                                                           |
+| ---------------- | -------------- | ----------------------------------------------------------------- |
+| `specVersion`    | string         | The spec version the dataset declares (see [Overview](index.md)). |
+| `manifest`       | object \| null | Resolved platform manifest, if any (see [Manifest](manifest.md)). |
+| `dimensions`     | array          | Declared dimensions with modes and defaults.                      |
+| `components`     | array          | Component identifiers exposed by the dataset (post Phase 6).      |
+| `taxonomyFields` | array          | Active name-object fields and their declared vocabulary.          |
+| `tokenCount`     | integer        | Total tokens in the merged cascade.                               |
+
+**RECOMMENDED:** The primer payload SHOULD fit within 2,000 tokens of LLM context for typical Spectrum-scale datasets. Implementations that produce larger payloads SHOULD provide a `--summary` mode.
+
+**RATIONALE:** The primer replaces the "DESIGN.md emit" approach explored in earlier RFC-C drafts. A live, queryable primer keeps the agent's session context current without requiring the agent to maintain a frozen prose summary that can drift from the dataset.
+
+## Transports
+
+**NORMATIVE:** A conforming implementation MUST expose the [Tool catalog](#tool-catalog) through at least one of the following transports.
+
+### CLI
+
+The reference CLI is `design-data` (see [`sdk/cli/`](../../../sdk/cli/)). RFC-C extends the existing subcommands (`validate`, `resolve`, `diff`, `query`) with:
+
+* `design-data primer [PATH]` — emit the [Session primer](#session-primer) payload.
+* `design-data suggest "<intent>" [--property <hint>]` — invoke `suggest_token`.
+* `design-data explain <token-uuid|component-id>` — invoke `get_guidance`.
+
+**NORMATIVE:** All RFC-C CLI output MUST default to JSON when stdout is not a TTY, and MUST emit human-friendly output when stdout is a TTY. This makes the CLI directly composable from agent shells without per-call format flags.
+
+### MCP server
+
+A reference MCP server is RECOMMENDED to ship as `@adobe/design-data-agent-mcp` (separate from the existing Spectrum-bound `@adobe/spectrum-design-data-mcp` to avoid coupling to a specific dataset).
+
+**NORMATIVE:** The MCP server MUST register one tool per [Tool catalog](#tool-catalog) operation. Tool names MUST match the operation name in the table verbatim. Each tool's input schema MUST mirror the CLI flag set; agents that learn one transport SHOULD work with the other.
+
+### Agent skill
+
+A reference Claude Code Agent Skill is RECOMMENDED at `tools/design-data-agent-mcp/skills/design-data/SKILL.md`. The skill SHOULD trigger on intent words covering all three [Goals](#goals) — for example "design system", "design tokens", "drift", "spec-conformant", and explicit Spectrum mentions when the active manifest binds Spectrum.
+
+**RECOMMENDED:** The skill SHOULD shell out to the CLI rather than embedding tool calls, so its description (the only persistent context cost) stays small and the heavy lifting happens out-of-band.
+
+## Conformance
+
+**NORMATIVE:** An agent surface implementation that claims conformance MUST:
+
+1. Implement all NORMATIVE operations in the [Tool catalog](#tool-catalog).
+2. Implement the [Session primer](#session-primer) operation.
+3. Expose the catalog through at least one transport in [Transports](#transports).
+4. Emit `validate_usage` diagnostics that match the structure produced by `validate::validate_all_with_options` (see `sdk/core/src/report.rs`): each diagnostic MUST include `rule_id`, `severity`, `message`, `instance_path`, `schema_path`, `file`, and `token` where applicable.
+5. Honor manifest-based filtering: when a manifest is present in the session, `query_tokens` and `resolve_token` MUST respect `include`/`exclude` and MUST apply manifest overrides before returning results.
+
+## Worked example
+
+The following sketch shows an agent loop that adheres-to-Spectrum while authoring a non-bound component.
+
+1. Agent calls `primer ./spectrum-data` and learns that `colorScheme` and `scale` are the active dimensions and that `button`, `picker`, and `card` are exposed components.
+2. User asks for a "subtle hover background for a card on dark mode".
+3. Agent calls `suggest_token "subtle hover background for card" --property background-color`.
+4. Surface returns a ranked list including `background-color-hover` from Spectrum foundation and `background-color-card-hover` from a card component group.
+5. Agent calls `resolve_token background-color-card-hover --color-scheme dark`.
+6. Surface returns the resolved literal value for the dark-mode card hover background.
+7. Agent emits CSS using that value and calls `validate_usage` against the proposed token document fragment to confirm no SPEC-NNN diagnostics fire.
+
+The same loop, with a different manifest passed at primer time, authors a non-Spectrum system: the surface returns whatever tokens that dataset declares, and `validate_usage` enforces the same spec rules independent of which design system is in play.
+
+## References
+
+* [#714 — Design Data Specification (umbrella)](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#625 — Token Authoring Workflow](https://github.com/adobe/spectrum-design-data/discussions/625)
+* [#832 — Component Contract in Design Data Spec](https://github.com/adobe/spectrum-design-data/discussions/832) — supplies `describe_component` once implemented
+* [Document blocks](document-blocks.md) (forthcoming, RFC-D / Phase 9) — supplies `get_guidance` payloads
+* [`sdk/cli/src/main.rs`](../../../sdk/cli/src/main.rs) — CLI surface to extend
+* [`sdk/core/src/report.rs`](../../../sdk/core/src/report.rs) — diagnostic shape

package/spec/anatomy-format.md

@@ -0,0 +1,167 @@
+# Anatomy format
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the normative **anatomy part declaration** object: the named visual sub-parts of a component that appear as values of the `anatomy` field in token name objects. Anatomy declarations complete the machine-readable contract introduced by the component declaration (see [Component format — Anatomy stub](component-format.md#anatomy-stub)) and enable cross-reference validation between tokens and component surfaces.
+
+Scoped under [RFC-A — Component Contract in Design Data Spec](https://github.com/adobe/spectrum-design-data/discussions/832). See also [Component format](component-format.md).
+
+## Anatomy part object
+
+An anatomy part is a **JSON object** that appears as an element of a component declaration's `anatomy` array. Each anatomy part object **MUST** validate against the standalone schema [`anatomy-part.schema.json`](../schemas/anatomy-part.schema.json) (canonical `$id`: `https://opensource.adobe.com/spectrum-design-data/schemas/v0/anatomy-part.schema.json`).
+
+**NORMATIVE:** `anatomy` **MUST** be a JSON array within the component declaration. Each element **MUST** be an anatomy part object.
+
+### Fields
+
+| Field         | Type             | Required | Description                                                                                                              |
+| ------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | string           | REQUIRED | Kebab-case identifier. **MUST** match the pattern `^[a-z][a-z0-9-]*$`.                                                   |
+| `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"]`). |
+
+**NORMATIVE:** No properties beyond those listed above are permitted in an anatomy part object. Additional fields **MUST** cause a Layer 1 schema error.
+
+### `name`
+
+**NORMATIVE:** `name` **MUST** match the pattern `^[a-z][a-z0-9-]*$` — lower-case kebab-case, non-empty.
+
+**NORMATIVE:** `name` **MUST** be unique within the `anatomy` array of a single component declaration (rule SPEC-024). Duplicate `name` values on the same component are a validation error.
+
+**NORMATIVE:** Token name-object `anatomy` field values referencing a component **MUST** match the `name` of a declared anatomy part on that component (rule SPEC-020). An undeclared `anatomy` value is a validation error.
+
+### `description`
+
+**OPTIONAL.** A plain-text description of the anatomy part's visual role (e.g. `"Background fill track behind the progress indicator."`).
+
+**RECOMMENDED:** Custom anatomy part names (those outside the [canonical anatomy vocabulary](#canonical-anatomy-vocabulary)) **SHOULD** include a `description` to document intent (rule SPEC-023 fires a warning for undocumented custom names).
+
+### `required`
+
+**OPTIONAL.** A boolean indicating whether the anatomy part is always present in the component's rendered output, regardless of its configuration options. Defaults to `false`.
+
+When `required` is `true`, the anatomy part is unconditionally rendered (e.g. a `label` that cannot be hidden). When `false` or omitted, the part may or may not appear depending on component props.
+
+### `contains`
+
+**OPTIONAL.** An informative list of child anatomy part `name` values that are visually or structurally nested within this part. This field is for documentation and tooling assistance; it does not carry enforcement semantics.
+
+**RECOMMENDED:** When a part logically encloses other declared anatomy parts, authors **SHOULD** use `contains` to make the nesting explicit.
+
+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.
+
+```json
+"anatomy": [
+  {
+    "name": "field",
+    "description": "Input field wrapper enclosing the label and help text.",
+    "contains": ["label", "help-text"]
+  },
+  { "name": "label",     "description": "Primary text label.", "required": true },
+  { "name": "help-text", "description": "Guidance text below the field." }
+]
+```
+
+## Canonical anatomy vocabulary
+
+The following anatomy part names are defined by the cross-platform design audit and **SHOULD** be used in preference to custom names when their semantics match. Using canonical names enables cross-component tooling, documentation generation, and token audits.
+
+| Name                  | Semantics                                                                |
+| --------------------- | ------------------------------------------------------------------------ |
+| `body`                | Primary content area of a component (e.g. card body, dialog body).       |
+| `checkmark`           | Selection indicator used in checkbox or radio components.                |
+| `disclosure-triangle` | Expand/collapse indicator for accordion, tree, or disclosure components. |
+| `field`               | Input field wrapper (encloses label, input surface, and help text).      |
+| `handle`              | Drag handle for resizable or sortable components.                        |
+| `header`              | Top section of a panel, card, or dialog.                                 |
+| `icon`                | Decorative or semantic icon placed within a component.                   |
+| `label`               | Primary text label identifying the component or its value.               |
+| `picker`              | Dropdown trigger area (the visible affordance, not the overlay).         |
+| `progress-bar`        | Visual progress fill track indicating completion level.                  |
+| `swatch`              | Color or pattern preview area.                                           |
+| `thumbnail`           | Image preview area within a component.                                   |
+| `track`               | Background rail for slider or progress bar components.                   |
+| `value`               | Numeric or text display value shown within a component.                  |
+
+Custom part names are permitted. When a custom name is used, the anatomy part object **SHOULD** include a `description` field explaining its visual role (rule SPEC-023).
+
+## Cross-reference with token name objects
+
+Token name objects use an `anatomy` field to scope a token to a specific visible part of a component. The `anatomy` field value must correspond to a part declared in the component's `anatomy` array.
+
+**NORMATIVE:** A token name-object `anatomy` field value **MUST** match the `name` of a declared anatomy part on the component identified by the token's `component` field (rule SPEC-020). An `anatomy` value that does not match any declared part name is a validation error.
+
+See [Token format — Name object](token-format.md#name-object) for the full name object field catalog.
+
+**NORMATIVE:** The `anatomy` field in a token name object **MUST NOT** be present unless the token's `component` field is also present (rule SPEC-025). Anatomy is always scoped to a component.
+
+```json
+{
+  "name": {
+    "component": "slider",
+    "anatomy": "handle",
+    "property": "background-color",
+    "state": "hover"
+  },
+  "value": "#0265dc"
+}
+```
+
+## SPEC rules
+
+The following rules in the Layer 2 rule catalog (`rules/rules.yaml`) apply to anatomy part declarations. SPEC-020 was introduced in Phase 6.1 (component-format); SPEC-023, SPEC-024, and SPEC-025 are introduced by this chapter.
+
+| Rule ID  | Name                             | Severity | Assert                                                                                                                                                    |
+| -------- | -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SPEC-020 | `component-anatomy-valid`        | error    | Token `anatomy` field value **MUST** match the `name` of a declared anatomy part on the referenced component.                                             |
+| SPEC-023 | `anatomy-custom-part-documented` | warning  | Anatomy part declarations with a `name` outside the canonical anatomy vocabulary **SHOULD** include a `description` field documenting the part's purpose. |
+| 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.                                                   |
+
+## Full example
+
+A complete `anatomy` array for a slider component, demonstrating canonical names, a custom name, and `contains` usage:
+
+```json
+"anatomy": [
+  {
+    "name": "track",
+    "description": "Background rail spanning the slider's full range.",
+    "required": true
+  },
+  {
+    "name": "progress-bar",
+    "description": "Filled portion of the track indicating the current value.",
+    "required": true
+  },
+  {
+    "name": "handle",
+    "description": "Draggable thumb positioned at the current value.",
+    "required": true
+  },
+  {
+    "name": "label",
+    "description": "Text label identifying the slider.",
+    "required": false
+  },
+  {
+    "name": "value",
+    "description": "Numeric display of the current slider value.",
+    "required": false
+  },
+  {
+    "name": "tick-marks",
+    "description": "Discrete step indicators along the track. Present only when step markers are enabled.",
+    "required": false
+  },
+  {
+    "name": "range-group",
+    "description": "Wrapper grouping the track and both handles for a range slider variant.",
+    "required": false,
+    "contains": ["track", "progress-bar", "handle"]
+  }
+]
+```
+
+In this example, `tick-marks` and `range-group` are custom names outside the canonical vocabulary. Both include a `description` to satisfy rule SPEC-023. The `range-group` part uses `contains` to declare that it encloses `track`, `progress-bar`, and `handle`.