@adobe/design-data-spec 0.1.1 → 0.3.0

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`.

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

@@ -84,7 +84,6 @@ The `@adobe/spectrum-tokens` package continues to publish tokens in the **legacy
 | `deprecated: "3.2.0"` (version string) | `deprecated: true` (boolean)          |
 | `replaced_by: "<uuid>"`                | `renamed: "<target-token-name>"`      |
 | `introduced`                           | Not emitted                           |
-| `lastModified`                         | Not emitted                           |
 | `plannedRemoval`                       | Not emitted                           |
 | `deprecated_comment`                   | `deprecated_comment` (passed through) |