@adobe/design-data-spec 4.8.0 → 4.9.0

package/spec/artifact-moves.md

@@ -0,0 +1,157 @@
+# Artifact moves
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines how one artifact moves between a platform manifest and the foundation: **promotion** (platform to foundation) and **demotion** (foundation to one platform). Moving a whole platform out of this repo is a different operation; see the ejection contract in [`platforms/README.md`](../../../platforms/README.md#the-ejection-contract).
+
+**Principle.** A move is a data operation that changes no one's output unless they choose it. The artifact keeps its identity, has one owner at a time, and other platforms lose nothing without notice.
+
+This chapter is separate from [Manifest](manifest.md) because a move happens over time, like the deprecation policy in [Evolution](evolution.md), while the manifest describes one static cascade.
+
+## What can move
+
+Identity decides what can move. A move keeps the artifact's identity, so it needs a stable one.
+
+| Artifact                             | Identity         | Moves?                  | Notes                                                                                                                                                                                                                                            |
+| ------------------------------------ | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Token                                | `uuid`           | Yes                     |                                                                                                                                                                                                                                                  |
+| Relationship (CTR)                   | `uuid`           | Yes                     | Moves with its component, or on its own when the component is foundation-owned.                                                                                                                                                                  |
+| Component                            | `name`           | Yes                     | Moves as a unit: anatomy, states, relationships, visual recipe and guidelines move with it.                                                                                                                                                      |
+| Mode set                             | `name`           | Yes                     | Promotion adds the set, or its extra modes, to the foundation set of that name. A mode set gets an optional `lifecycle` so a move is visible on the set itself (the schema change is tracked separately; see [Open questions](#open-questions)). |
+| Visual recipe (planned)              | component `name` | Yes                     | A file move between `extensions/visuals/` and the foundation `visuals/`. It has no `uuid`. A recipe of a platform-only component moves with the component and its relationships. See below.                                                      |
+| Guideline                            | `name`           | Only with its component | A guideline is not moved on its own. It follows the component it describes.                                                                                                                                                                      |
+| Field declaration                    | `name`           | No                      | Fields are the shared naming vocabulary. A platform asks the foundation team to add a value or field. They stay foundation-owned.                                                                                                                |
+| Implementation mapping               | n/a              | No                      | Always platform-owned by definition (`extensions/implementations/`).                                                                                                                                                                             |
+| Platform extension (term annotation) | `termId`         | No                      | It annotates a foundation term for one platform. It has no foundation form.                                                                                                                                                                      |
+
+A component is identified by `name`. Its move record says where it came from and when; the identity is separate and does not change.
+
+**NORMATIVE (when platform recipes are implemented):** A recipe moves in the same change as its component. If a manifest `componentAliases` entry points at the component, the alias is manifest data, not an artifact: it is removed in that same change, and the impact check lists it. A recipe never moves alone when its component is platform-only. A recipe that replaces a foundation recipe of a foundation-owned component moves as a plain file move. The verify step (`validate --platform <id> --visuals-path`) then also covers platform-owned recipes (SPEC-079).
+
+**NORMATIVE:** Things a moved component only *uses* (tokens, mode sets) do not move with it. Each is checked separately in the impact check; one that is still needed in the old place stays there, or is promoted in its own move.
+
+## Who decides
+
+**NORMATIVE:** The foundation team decides every move. The platform team that owns the manifest **SHOULD** be part of the discussion.
+
+A proposal is a tracked issue (a bead or a GitHub issue) that states:
+
+1. What moves, and in which direction.
+2. Why.
+3. Evidence from two or more platforms (promotion), or the design decision (promotion with one platform).
+4. For a promotion, the foundation values. The foundation team sets them; see [Foundation defaults](#foundation-defaults).
+
+The issue's id is recorded in `lifecycle.moves[].proposal` when the move lands.
+
+## Promotion criteria
+
+**NORMATIVE:** An artifact **MAY** be promoted when either holds:
+
+* Two or more platforms need it.
+* One platform needs it and the foundation team records a design decision that it belongs in the foundation.
+
+One platform alone is not enough. An artifact stays platform-local until there is evidence.
+
+Demotion has no evidence threshold. The foundation team demotes an artifact when it turns out only one platform uses it, or when the design decision behind it is reversed.
+
+## The six steps
+
+The steps are the same in both directions. Where they differ, each direction is written out.
+
+1. **Proposal.** Open and agree the issue above.
+2. **Impact check.** List every platform and product that resolves, overrides or references the artifact. List everything the artifact references that is not moving with it. List product-layer overrides ([Product context](product-context.md)) in a separate, clearly marked list. A move cannot fix them, since neither the foundation nor a platform owns them, so the check names them as affected consumers to notify. They do not block the move. The planned `design-data platform move --dry-run` reports this.
+3. **Move.** Put the artifact in its new place, with the same identity, and remove it from the old place **in the same change**. Never leave a state where both places own it.
+4. **Compatibility.** Keep other platforms' output unchanged. See [Other platforms](#other-platforms).
+5. **Verify.** Run dataset validation, snapshot and legacy-output parity, and SPEC-076 for each affected platform (`validate --platform <id> --visuals-path`).
+6. **Record provenance.** Add a `lifecycle.moves` entry.
+
+### Promotion
+
+* **3.** Move the file content from `platforms/<id>/extensions/<kind>/` into the matching foundation directory under `packages/design-data/`. Delete the extension file.
+* **Mode added to a set.** **NORMATIVE:** A promotion that adds a mode to a foundation mode set **MUST** declare a fallback mode for it, and validation **MUST** check that the fallback exists in the set. A token that omits a mode field applies under the set's default, which for `colorScheme` is `light`, a poor stand-in for `dark-elevated`. Without a declared fallback, platforms with no values for the new mode would silently resolve to the wrong thing. SPEC-005 already checks peer-mode coverage; the fallback check is proposed as SPEC-078 below.
+* **4.** The foundation record carries the values the foundation team set. A platform whose values differ keeps them as an `overrides` entry (tokens) or a platform replacement (mode sets, components). Its output does not change.
+* **Version.** **NORMATIVE:** A promotion adds foundation content, so it is a **minor** change ([Evolution: Change classification](evolution.md#change-classification)). The release that contains it is the `version` recorded in the move.
+
+### Demotion
+
+* **3.** Move the record into `platforms/<id>/extensions/<kind>/` with the same identity. In the foundation, replace it with a **deprecated stub**: the same identity and value, `lifecycle.deprecatedIn` set to the current foundation version, a `deprecatedComment` naming the platform, and the `lifecycle.moves` entry. The stub is the announcement.
+* **4.** Other platforms keep resolving the stub for the whole notice period, so their output does not change.
+* **Notice period.** **NORMATIVE:** The stub **MUST** stay in the published dataset for at least the window in [Evolution: Migration windows](evolution.md#migration-windows): two minor versions after `deprecatedIn`, or a later `plannedRemoval`. A demotion is a deprecation, not a removal, so the stub is a **minor** change. Removing the stub afterward is the breaking step. [Evolution](evolution.md) lists removal as a major change but also permits it two minors after `deprecatedIn`. These do not conflict: removal after the window is allowed in a minor release because the deprecation already gave notice, and removal before the window ends needs a major release. A demotion does not use `replacedBy`, because the successor has the *same* identity and lives outside the foundation.
+* A platform that wants to keep the artifact **MUST** copy it into its own `extensions/` before the stub is removed. The `lifecycle.moves` entry names which platform received it.
+
+## Other platforms
+
+Overrides and extensions in other platforms are kept, not rewritten.
+
+* **Promotion.** An existing override still replaces the foundation record for that platform ([Manifest: overrides](manifest.md#overrides)). Its `overriddenFrom` now holds the **new** foundation value, because `overriddenFrom` is computed from whatever the foundation holds at load time. Platforms that already carried a copy of the artifact in `extensions/` **MUST** remove it in the same change, or SPEC-077 (below) would flag the duplicate.
+* **Demotion.** An override of the demoted token keeps working while the stub exists, because the stub has the same `uuid`. When the stub is removed the override has no target. The impact check lists these overrides so their owners can act during the notice period.
+* `overriddenBy` and `overriddenFrom` stay in-memory only. They say who is overriding a record now. They are not history; `lifecycle.moves` is.
+
+### Foundation defaults
+
+**NORMATIVE:** When platforms disagree on a promoted artifact's values, the foundation team chooses the foundation values in the proposal. This specification does not pick a default.
+
+## Recording a move
+
+**NORMATIVE:** Every move **MUST** add one entry to `lifecycle.moves` on the artifact (the foundation record, or the platform record after a demotion), keeping earlier entries. The array is a history, oldest first.
+
+| Field       | Type                  | Required | Meaning                                     |
+| ----------- | --------------------- | -------- | ------------------------------------------- |
+| `direction` | `promote` or `demote` | Yes      | Which way it moved.                         |
+| `from`      | place                 | Yes      | Where it was.                               |
+| `to`        | place                 | Yes      | Where it is now.                            |
+| `version`   | string (version)      | Yes      | Foundation version that contains the move.  |
+| `proposal`  | string                | Yes      | Issue id of the proposal.                   |
+| `date`      | string (date)         | No       | Date the change landed.                     |
+| `decidedBy` | string                | No       | Who decided, for example `foundation team`. |
+| `evidence`  | array of string       | No       | Platform ids that needed it (promotion).    |
+| `comment`   | string                | No       | Free text.                                  |
+
+A **place** is `{ "foundation": true }` or `{ "platform": "<id>", "platformVersion": "<version>" }`. `platformVersion` is optional.
+
+```json
+"lifecycle": {
+  "moves": [{
+    "direction": "promote",
+    "from": { "platform": "ios", "platformVersion": "0.3.0" },
+    "to": { "foundation": true },
+    "version": "3.8.0",
+    "proposal": "spectrum-design-data-p6ga.8.19",
+    "date": "2026-11-12",
+    "decidedBy": "foundation team",
+    "evidence": ["ios", "android"]
+  }]
+}
+```
+
+How these fields relate to the existing ones:
+
+| Field                            | Where it lives                 | Relationship                                            |
+| -------------------------------- | ------------------------------ | ------------------------------------------------------- |
+| `lifecycle.moves`                | Authored, in the data file     | Permanent history of moves.                             |
+| `lifecycle.deprecatedIn`         | Authored, on the demotion stub | Starts the notice period. A promotion does not set it.  |
+| `lifecycle.replacedBy`           | Authored                       | Not used by moves; the successor has the same identity. |
+| `overriddenBy`, `overriddenFrom` | In memory only                 | Current override state. Never written, never history.   |
+
+## Detecting a half-finished move
+
+**PROPOSED, not implemented.** Two rules.
+
+`SPEC-077` (`artifact-single-owner`, error): when a dataset is loaded with a platform manifest, the same identity (token or relationship `uuid`, or component, mode set or guideline `name`) **MUST NOT** be *defined* in both the foundation and the platform's `extensions/`, with one exception. During a demotion window the artifact exists in both places on purpose: the foundation record is a deprecated stub (it has `lifecycle.deprecatedIn` and a `lifecycle.moves` entry whose `from` is the foundation) and the platform copy overrides it. The rule fires when both records are active and not deprecated, or when the stub outlives its window. A manifest `overrides` entry is not a definition and is always allowed.
+
+`SPEC-078` (`promoted-mode-fallback`, error): a mode added to a foundation mode set by a promotion **MUST** have a declared fallback mode that exists in the same set. The field that declares it is decided in its implementation bead.
+
+## Open questions
+
+Settled in this chapter: version bumps, the fallback for a promoted mode, the `lifecycle.moves` shape for components, the stub-and-copy overlap during a demotion window, and product-layer overrides in the impact check.
+
+1. **Mode-set schema.** This chapter says mode sets carry an optional `lifecycle`. The mode-set schema has none and allows no extra properties, so adding it is a published schema change with its own changeset. Tracked as a follow-up bead.
+2. **Fallback field.** Where the fallback mode is declared (on the mode set, or per mode) is not decided.
+3. **`platformVersion` on `overriddenBy`.** Deferred in p6ga.8.9. Add it only if diff tooling or the iOS Figma work needs it.
+
+## References
+
+* [Manifest](manifest.md): capability matrix, overrides and `extensions/`.
+* [Evolution](evolution.md): deprecation lifecycle and migration windows.
+* [Token format: Lifecycle and metadata](token-format.md#lifecycle-and-metadata).
+* [Cascade](cascade.md): layer precedence.

package/spec/component-changelog.md

@@ -0,0 +1,49 @@
+# Component changelog
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+A **component changelog** is the generated, committed history of one component: what changed in its records between releases, why (source), and the component version that follows. `design-data changelog` writes `changelog/<component>.json` next to the dataset; the format is `schemas/component-changelog.schema.json`.
+
+## Records compared
+
+Two dataset revisions are compared record by record. Formatting and key order never produce a change.
+
+| Layer          | Identity                                                                                                   |
+| -------------- | ---------------------------------------------------------------------------------------------------------- |
+| Tokens         | The [semantic diff](diff.md) (uuid, then name object, then replacement link)                               |
+| Relationships  | `uuid`; then scope + context + target; a leftover pair with the same scope and context is a **re-binding** |
+| Components     | Options, option values, anatomy parts, states, slots by name; document blocks, implementations, lifecycle  |
+| Visual recipes | The component's recipe file and its parts                                                                  |
+
+A removed and an added option, state, anatomy part or slot that differ only by name are one **rename**.
+
+## Attribution
+
+Each change attaches to a component, to the relationship context (the spec-sheet block title) it appears under, and to a **source**: the PR number in the squash subject (`... (#123)`), otherwise the commit sha and subject. A global token reaches a component through the relationships that bind it. A token a component binds whose own record is unchanged but whose alias-resolved value moved is an **indirect** change. Registry and mode-set changes are not fanned out to components.
+
+A record's own `rationale` is copied into the entry when present. History comes from the diff; the source is the fallback reason.
+
+## Classes
+
+| Class           | Meaning                                                                                                |
+| --------------- | ------------------------------------------------------------------------------------------------------ |
+| `visual`        | How the component looks or behaves: token values, relationship bindings, visual recipes                |
+| `api`           | Options, option values, states, anatomy, slots, constraints, relationships added or removed, lifecycle |
+| `documentation` | Descriptions, document blocks, rationale, relationship context text                                    |
+| `metadata`      | Legacy keys, ids, ordering, implementations, spec bookkeeping (summarized, not listed)                 |
+
+**Metadata-class changes are not entries.** Each commit records them as `metadata: {count, fields}`: how many changes, and which field paths changed (a record added or removed is named `<kind> <change>`, e.g. `implementation added`). They count as a patch.
+
+In the committed file every entry, source and metadata summary is written on one line.
+
+A token entry is a **Values updated** change; a relationship entry that changes only its target is a **Bindings changed** change. They are never merged.
+
+## Component version
+
+The version is derived from the entries of each release; it is never authored. A component's first release is `1.0.0`. Each release applies the highest bump among its entries:
+
+* **major**: an option, option value, state, anatomy part, slot or relationship removed; an option, state, anatomy part or slot renamed; an option `type` changed; the component deprecated or removed.
+* **minor**: anything added, including a visual recipe (metadata-class additions are patch).
+* **patch**: value changes (direct or indirect), documentation, metadata, rationale.
+
+Each release lists its changes per commit, each commit with its source. Releases are append-only: a release already recorded is never rewritten, and generating the same release again changes nothing. The exception is the pending release named `unreleased`, which holds changes not yet in a package release: the next release takes over its commits (adding newer ones) and the version is worked out again from the version before it.

package/spec/component-format.md

@@ -208,6 +208,10 @@ Example with a deprecated option value:
 }
 ```
 
+### Constraints
+
+A component MAY declare `constraints`, an array of if-then rules restricting which option value combinations are valid. Each rule has `when`, `require`, and `severity` (`error` or `advisory`), and optionally `description` and `source`. Layer 1 checks shape only. See [Option constraints](option-constraints.md).
+
 ## 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).

package/spec/component-visuals.md

@@ -0,0 +1,210 @@
+# Component visuals
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **component visual recipe**: a renderer-neutral description of how a component looks, bound to design tokens. A recipe lets tooling produce SVG, PNG, and Figma output, plus anatomy and spec overlays, from one source. It is not tied to Figma, React, or any other platform.
+
+Status: **draft / RFC**. The schema is [`component-visual.schema.json`](../schemas/component-visual.schema.json). A pilot recipe lives at `packages/design-data/visuals/action-button.json`.
+
+## Goals and non-goals
+
+**Goals**
+
+* One data source drives three views of a component: a variant × state matrix (usage), anatomy callouts, and token-labelled measurements (specs).
+* Every geometric or paint value is token-bound, so overlays can name the token behind each measurement.
+* Output targets are plural: SVG first, then PNG, then Figma.
+
+**Non-goals**
+
+* Pixel parity with every platform implementation. Recipes describe the Spectrum design spec, not a browser's rendering of it.
+* Replacing component declarations. Options, states, slots and anatomy stay in [component format](component-format.md).
+* Describing interaction, motion or accessibility behavior.
+
+## Layers
+
+| Layer                 | Owns                                                                      | Where                                  |
+| --------------------- | ------------------------------------------------------------------------- | -------------------------------------- |
+| Component declaration | Options, states, slots, anatomy names                                     | `components/<name>.json`               |
+| **Visual recipe**     | Part tree, layout, shape, paint, text, token bindings                     | `visuals/<name>.json` (this spec)      |
+| Render request        | Which component, option values, states and modes to draw; matrices        | Tool input (not stored in the dataset) |
+| Scene graph           | Resolved rects, paths, text, groups, measurements with part and token ids | Renderer output; backends consume it   |
+
+**NORMATIVE:** A recipe **MUST** name exactly one component through `component`, and that component **MUST** be declared. *Planned Layer 2 rule; not yet enforced.*
+
+**NORMATIVE:** Every key of `parts` **MUST** be a declared anatomy part of the component. *Planned Layer 2 rule; not yet enforced.* Recipes therefore require components to declare anatomy.
+
+## Recipe object
+
+| Field         | Type   | Required    | Description                                                                                                                                                                                   |
+| ------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `specVersion` | string | RECOMMENDED | Spec version label.                                                                                                                                                                           |
+| `component`   | string | REQUIRED    | Component `name`.                                                                                                                                                                             |
+| `root`        | string | REQUIRED    | Key of the root part in `parts`.                                                                                                                                                              |
+| `sizeScale`   | object | OPTIONAL    | Maps each `size` option value to a numeric scale index (e.g. `m` → `100`). Enables `{sizeIndex}` in selectors. A component with no `size` option declares one entry, the size renderers draw. |
+| `notVisual`   | array  | OPTIONAL    | Component options and states that deliberately have no visual in this recipe (for example `["isReadOnly"]`). SPEC-066.                                                                        |
+| `parts`       | object | REQUIRED    | Map of anatomy part name → part definition.                                                                                                                                                   |
+
+### Part
+
+| Field         | Type             | Description                                                                                                                                                                                            |
+| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `kind`        | enum             | `box`, `text`, `icon`, `ring`. `ring` is an outline drawn outside the parent box (focus indicator).                                                                                                    |
+| `children`    | array of strings | Ordered child part names. Child order is layout order. Children **MUST** be declared parts.                                                                                                            |
+| `visibleWhen` | condition        | The part is drawn only when the condition holds. Absent means always drawn.                                                                                                                            |
+| `placement`   | object           | For a child that is positioned rather than flowed: `anchor` (`top-start`, `top-end`, `bottom-start`, `bottom-end`, `center`) and optional `inset` value. `start`/`end` are logical and flip under RTL. |
+| `around`      | string           | For a `ring`: the part it outlines. Defaults to the root.                                                                                                                                              |
+| `glyph`       | enum             | For an `icon` nested in a box: the built-in glyph to draw (`checkmark`, `dash`, `chevron`). Unset draws a placeholder. A `chevron` points to the end; `rotation` turns it.                             |
+| `pressTarget` | string           | For the root: the part the pressed scale applies to (for example a switch handle). Parts nested inside it scale with it (a checkbox `box` scales with its mark). Defaults to the whole scene.          |
+| `props`       | object           | Map of **visual property** → value source or conditional list.                                                                                                                                         |
+
+### Visual properties
+
+| Property                                                                                       | Applies to | Meaning                                                                                                                        |
+| ---------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `direction`, `align`, `justify`                                                                | box        | Root layout: `direction` `row` (default) or `column`; `align` and `justify` `start`, `center` (default) or `end`.              |
+| `gap`                                                                                          | box        | Space between flowed children.                                                                                                 |
+| `paddingInlineStart`, `paddingInlineEnd`, `paddingBlockStart`, `paddingBlockEnd`               | box        | Inner padding.                                                                                                                 |
+| `height`, `minWidth`, `width`                                                                  | box, icon  | Dimensions. Box width defaults to content.                                                                                     |
+| `cornerRadius`                                                                                 | box, ring  | Corner radius.                                                                                                                 |
+| `cornerRadiusStartStart`, `cornerRadiusStartEnd`, `cornerRadiusEndStart`, `cornerRadiusEndEnd` | box        | Per-corner radius (block-inline). Each falls back to `cornerRadius`. Renderers draw left-to-right, so start-start is top-left. |
+| `fill`, `stroke`, `strokeWidth`, `opacity`                                                     | box, ring  | Paint.                                                                                                                         |
+| `color`                                                                                        | text, icon | Content color.                                                                                                                 |
+| `trackColor`                                                                                   | progress   | Color of the progress track behind the arc.                                                                                    |
+| `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`                                           | text       | Text style. `lineHeight` sets the line box height.                                                                             |
+| `gapToParent`                                                                                  | ring       | Distance between the ring and the parent box.                                                                                  |
+| `rotation`                                                                                     | icon       | Clockwise rotation in degrees about the icon's center (a `chevron` is 90 when open).                                           |
+
+**Text height.** A `text` part is as high as its line box: a `lineHeight` ending in `px` is that height, a unitless `lineHeight` multiplies `fontSize`, and with no `lineHeight` it is 1.3 times `fontSize`. A bound `fontFamily` leads the SVG font stack, so a family the viewer lacks falls back to the default stack.
+
+**Opacity.** Renderers read `opacity` only on the root part. It dims the whole component as one group (SVG `<g opacity>`), so overlapping parts do not show through each other, the way iOS dims a disabled control. On any other part `opacity` is ignored (SPEC-083).
+
+**Height.** A root `box` with no `height` is 32 high, unless the recipe binds `paddingBlockStart` or `paddingBlockEnd`: then its height is the tallest flowed child plus the block padding, and the children sit between the paddings. An explicit `height` always wins and the block padding then only offsets the children.
+
+**NORMATIVE:** A renderer **MUST** clamp a uniform `cornerRadius` that is larger than half the shorter side of its box to that value, on all four corners, so the corner stays circular (like CSS `border-radius`).
+
+**Row boxes.** A flowed `box` that binds `direction: "row"` lays its `children` out in a row instead of insetting them: `icon`, `text` and `box` children in order, `gap` apart, between its `paddingInlineStart` and `paddingInlineEnd`, centered across (`align` moves them). Without a `width` it is as wide as its children plus padding; without a `height` it is as tall as the tallest child plus its block padding. A `text` child may bind its own padding props, which add to its cell. Only `row` is supported.
+
+**Column stretch.** In a column root, a flowed `box` with no `width` and no row content fills the column's inner width (a divider or a content region). A flowed `box` with no `height` and no children is as tall as its block padding.
+
+**Nested boxes.** A flowed `box` child paints itself (`fill`, `stroke`, `strokeWidth`, `cornerRadius`) and may list its own `children`, which are boxes laid out inside it. A nested child is centered across the parent. Along the inline axis its `justify` prop (`start`, `center`, `end`) places it, with an inset equal to the cross-axis gap. A nested child with no `width` or `height` fills the parent. A `cornerRadius` of `0.5` with `relativeTo: "height"` draws a pill, or a circle for a square box. The switch uses this for its track and handle. A nested `icon` is centered on both axes and draws its `glyph`; the checkbox uses this for its checkmark and dash.
+
+### Value sources
+
+A property value is either one **value source** or an ordered list of **conditional value sources**. A value source is exactly one of:
+
+* `{"value": <literal>}`: a literal. Use only for geometry that no token describes (e.g. a glyph path).
+* `{"token": {<name-object fields>}}`: a token selected by name-object fields, resolved with the [cascade](cascade.md).
+* `{"relationship": {"property": "...", "context": "..."}}`: a token chosen through the component's [relationships](relationship-format.md). `property` and `context` match the relationship's `scope.property` and `context`.
+
+Selector strings **MAY** contain `{size}` (the request's `size` option value, e.g. `m`), `{sizeIndex}` (that size's entry in `sizeScale`) and `{<option>}` for any other option the component declares (for example `{style}`). A `{<option>}` placeholder expands to each value the option declares, and a candidate found for one value applies only when the request's option equals that value, so one selector serves every value. A brace pair whose content is not a plain identifier (letters and digits) is literal text. A scalar `token` selector value matches an array-valued name field that contains it (e.g. `"state": "disabled"` matches `["disabled"]`).
+
+**NORMATIVE:** A relationship may pin component options in its `scope.options` (a value, or an array of values that match when any listed value matches). For a `relationship` selector the renderer **MUST** keep only the matching relationships whose pinned options all match the request, and **MUST** prefer the ones that pin the most options. A relationship that pins no options is the default: it applies only when no relationship that pins options matches. Keys that are not declared options of the component, and the reserved keys `state`, `scale` and `colorScheme`, are not pinned options. A relationship's `scope.options.state` adds states to those of the token it binds, so a hover color that is a plain palette token can still be selected by state. This lets the component data, not the recipe, say which token applies under which options (for example a badge label is white by default, black for the light variants, and gray for subtle).
+
+**NORMATIVE:** `token` and `relationship` selectors yield a set of candidate tokens. The renderer **MUST** narrow the candidates with the request's mode context (for example `colorScheme`, `scale`) using the [cascade](cascade.md), and **MUST** report a diagnostic if zero or more than one candidate remains.
+
+A conditional entry is a value source plus `when`. A condition has optional `options` (option name → value, or array of values), `states` (state names that must all be active) and `modes` (mode-set name → mode). An array matches when any listed value matches, and counts as one condition.
+
+**NORMATIVE:** When several entries match a request, the renderer **MUST** choose the one with the most conditions (options + states + modes). Ties go to the later entry in document order. An entry without `when` is the default. An entry **MAY** set an integer `priority` (default 0); a higher priority wins before condition count is compared. Use it for states that override every other combination, such as `disabled`.
+
+An entry on `cornerRadius` **MAY** set `relativeTo: "height"`, making its numeric value a ratio of the container height (a pill is `0.5`). A `stroke` on a `box` is drawn inside its bounds, so `strokeWidth` does not change the layout size.
+
+**NORMATIVE:** A renderer **MUST NOT** substitute a literal for a value source it cannot resolve. It **MUST** emit a diagnostic naming the part, property and selector, and omit that property.
+
+### Interim: relationship `context` strings
+
+Relationship `context` is free text today (for example `Background (selected, emphasized)`). Recipes bind to those strings so the pilot can ship without changing relationship data. This is brittle: a reworded context breaks a recipe, and SPEC-062 reports a `relationship` selector that matches no relationship. **RECOMMENDED:** a follow-up adds structured `options` to relationships so recipes can select by option and state instead of by label.
+
+## Validation
+
+The recipe schema checks one file's structure (Layer 1). A JSON Schema cannot read other files, so cross-file checks against component and relationship data are Layer 2 rules. They run only when the recipe catalog is loaded (`design-data validate --visuals-path`) and are skipped when no component catalog is loaded.
+
+| Rule     | Checks                                                                                                                                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SPEC-060 | `component` is declared; `parts` keys are anatomy parts; `root` is a top-level anatomy part; `children` appear in the anatomy part's `contains`; `around` and `pressTarget` resolve                          |
+| SPEC-061 | `when` and `visibleWhen` options exist with allowed values and types; states exist on the component; a `{<option>}` placeholder in a selector names a declared option that lists its values                  |
+| SPEC-062 | `relationship` selectors resolve to a record scoped to the component; `token` selectors match a token (`{size}` and `{sizeIndex}` expand over `sizeScale`, and `{<option>}` over the option's values, first) |
+| SPEC-063 | `sizeScale` keys equal the component's `size` option values (one entry when it has none)                                                                                                                     |
+| SPEC-066 | Warning. Every option and state the component declares drives the recipe or is listed in `notVisual`; `notVisual` names are declared and unused                                                              |
+| SPEC-067 | Warning. A `token` selector does not bind a token that one of the component's relationships already binds                                                                                                    |
+| SPEC-068 | Warning. A literal does not supply a color or a non-zero size (layout keywords, `transparent`, zero and ratio radii are fine)                                                                                |
+| SPEC-069 | Warning. A `token` or `relationship` selector does not resolve only to deprecated tokens (extends SPEC-058 to recipes)                                                                                       |
+| SPEC-070 | Warning. Recipes name the focus ring part (`kind: "ring"`) alike                                                                                                                                             |
+| SPEC-071 | Info. Counts relationship contexts of the component that the recipe never binds                                                                                                                              |
+| SPEC-075 | Error. A part's `visibleWhen.states` agrees with the `presentIn` of its anatomy part (info when either lists more than one state; see [Anatomy format](anatomy-format.md#presentin))                         |
+| SPEC-076 | Warning. Runs only with a platform manifest (`validate --platform <id> --visuals-path`). Every binding that resolves on the foundation also resolves once the manifest's cascade is applied                  |
+| SPEC-079 | Warning. A platform-owned recipe renders over the request grid with no scene diagnostic. Planned to become an error in a later minor release                                                                 |
+| SPEC-080 | Info. A platform recipe replaces the foundation recipe of the same component name                                                                                                                            |
+| SPEC-083 | Warning. A part binds only props the renderer reads for it (the root, its `kind`, or a `placement`); the schema accepts more, and the renderer ignores the rest                                              |
+
+SPEC-066 to SPEC-070 are warnings, so `validate` stays green while recipes are migrated. A ratchet keeps the debt from growing: `sdk/core/tests/recipe_lint_baseline.rs` compares each (rule, recipe) warning count with `sdk/core/tests/fixtures/recipe-lint-baseline.json`. A new warning fails the test, an improvement must lower the baseline, and a recipe that is not in the baseline must have none.
+
+## Platform-owned recipes
+
+Implemented for `render`, `site` and the Rust core (see [Proposal 014](../../../docs/proposals/014-platform-owned-visual-recipes.md)). `render` and `site` load the foundation recipes into the graph, then apply the platform's `extensions/visuals/` over them, and look recipes up through `componentAliases`.
+
+* **Location.** **NORMATIVE (when implemented):** A platform recipe is `extensions/visuals/<component>.json`, one recipe per file, in the platform's extensions directory (honoring `extensionsDir`, see [Manifest](manifest.md#extensions-directory)). The file name **MUST** equal `component`. It validates against the same recipe schema as a foundation recipe, so promoting or demoting it is a file move ([Artifact moves](artifact-moves.md)).
+* **Precedence.** A platform recipe **replaces** the foundation recipe of the same component name as a whole file. There is no layering. A foundation recipe stays the default for platforms that have none. A replaced recipe is a copy that can drift; SPEC-080 reports the pair.
+* **Resolution.** A recipe's selectors resolve against the platform-merged graph (the manifest's tokens, relationships, components and anatomy). A recipe replaces only the look; anatomy stays neutral, so a recipe may use only the parts the platform-merged component declares (SPEC-060).
+* **Validation.** `validate --platform <id>` runs SPEC-060 to SPEC-075 and SPEC-083 over platform-owned recipes against the platform-merged graph, plus SPEC-079 (every request in the grid renders). SPEC-076 keeps its foundation comparison and covers only foundation recipes the platform did not replace.
+
+## Authoring conventions
+
+These are the conventions the lints above enforce, plus the decisions made while adding the first five recipes. Follow them in a new recipe; a change to an existing recipe that breaks one needs a reason.
+
+1. **Bind through relationships.** A recipe takes a value from the component's relationships by default (SPEC-067). Use a `token` selector only when no relationship covers the value, and a literal only for layout keywords, `transparent`, zero, ratio radii or geometry no token describes (SPEC-068). If the token you need is missing, file the gap; do not hide it behind a literal. Put option-dependent choices in the relationships, not in the recipe: pin `scope.options` on the relationship records (a default with no options, overrides that pin them) and bind the role once, so a variant added later is a data change. **Exception: platform-owned components.** A recipe for a component that a platform manifest declares (for example `button-ios`) MAY bind platform tokens directly with `token` selectors, because the platform's own code binds tokens by name and has no relationship layer. This applies to platform-owned components only; foundation components stay relationship-first. SPEC-062 and, for platform recipes, SPEC-079 keep checking that every selected token resolves. Watch the recipe size: the mapping from option to token then lives in the recipe, so name the platform's tokens so that selectors can template the option values, and measure the recipe's line count (see [Proposal 014](../../../docs/proposals/014-platform-owned-visual-recipes.md)).
+2. **Bind current tokens.** Do not bind a deprecated token (SPEC-069; SPEC-058 covers relationships). When the only token is deprecated, bind it and record the gap, so the lint keeps showing it.
+3. **Selection is an option, not a state.** Model "selected" as the `isSelected` option and scope relationships with `options.isSelected: true`. The renderer treats `isSelected` as the `selected` state and `isDisabled` as `disabled` when choosing between tokens that carry a state.
+4. **Cover the component.** Every option and state the component declares either changes the recipe or is listed in `notVisual` (SPEC-066). `notVisual` records a deliberate absence, for example `isReadOnly` (it only suppresses hover and press) or `icon` until a shared icon registry exists.
+5. **Press scales the part the design scales.** Set `pressTarget` to the part the design source scales when pressed: the checkbox scales its `box` (with its mark), the switch scales its `handle`. Parts nested inside the target scale with it, and the label does not.
+6. **Priorities.** Disabled overrides interaction states with `priority: 10` (11 where a more specific disabled case must win). Error uses `priority: 5`.
+7. **Relationship contexts are the design token group label,** with no `S1` or `S2` prefix, and the same label names the same concept in every component (for example `Control (disabled)`).
+8. **Name the focus ring part alike** across recipes (SPEC-070).
+9. **Prove a change.** `sdk/core/tests/recipe_snapshots.rs` renders every valid option, state, size, color scheme and scale combination of every recipe and compares a hash per option set with `tests/fixtures/recipe-snapshots.json`. It also fails on any render diagnostic. After a recipe, relationship, token or renderer change, review the option sets it reports with `design-data render`, then regenerate with `UPDATE_RECIPE_SNAPSHOTS=1`. A new recipe is covered automatically.
+
+New recipes **MUST** be free of SPEC-066 to SPEC-070 warnings. Existing recipes are held at their baseline until they are migrated.
+
+## Render request and scene graph
+
+A render request is tool input, not dataset content: `{component, options, states, modes, overlays}`. A **matrix** is a list of requests plus a layout (rows × columns by option or state).
+
+The scene graph is the contract between resolution and output:
+
+* Nodes: `group`, `rect` (with corner radii), `path`, `text`, `ring`.
+* Every node carries `part` (anatomy name) and, for each token-bound property, `tokens` (property → token name or uuid and resolved value).
+* Measurements (height, padding, gap, radius) are recorded as dimension annotations with their token. Overlay backends draw dimension lines and callouts from these; recipes do not author overlays.
+
+**NORMATIVE:** A backend **MUST** produce the same scene graph input for the same request and dataset version (deterministic output).
+
+### Compiled recipes
+
+A build step **MAY** pre-resolve every `token` and `relationship` binding per `size|colorScheme|scale` into a ranked list of candidates (`{value, token, states}`), so a renderer needs no token graph. Only state-dependent selection remains at render time: take the first candidate whose `states` all apply, else the first. Backends that consume compiled recipes (for example the dependency-free JS runtime emitted by `design-data site`) **MUST** produce the same scene as the Rust reference renderer; the reference renderer is the source of truth and parity is tested.
+
+## Backend and tooling decisions (research outcomes)
+
+These record the research behind this draft and are not normative.
+
+**R1 — Playground (Domino) fit: reference only for now.** Domino models component *instances* (`componentType`, props, `items`/`itemsOrder`, slots). It has no geometry, paint, layout or token-binding concepts, no JSON Schema for the node envelope, and no document-format versioning. Its `0react-spectrum/s2` schemas are generated from React Spectrum, and prop names (`isQuiet`, `isDisabled`, `staticColor`) mostly match ours. The repository is private (`"private": true`; MIT metadata but no LICENSE file), so a public spec must not depend on its schemas. Its Figma plugin maps Figma → Domino, the opposite of our Figma output. Decision: keep recipes independent. A render request can later be converted to or from a Domino instance by an adapter, because option names align. Revisit when Domino publishes a versioned envelope schema.
+
+**R2 — Text measurement: approximate metrics with Source Sans 3.** Adobe Clean is proprietary and cannot be redistributed in this repository. Source Sans 3 (SIL OFL) is the open fallback. Renderers ship a width table for the fallback font and emit SVG `<text>` with the stack `adobe-clean-spectrum-vf, Adobe Clean, Source Sans 3, sans-serif`, so viewers with Adobe Clean available see it. Overlay positions use the measured width and may differ slightly from the viewer's font. SVG output maps font-weight names from tokens (`medium`, `bold`, and so on) to numeric weights. Exact shaping (rustybuzz or similar) is deferred until a licensed-font story exists. Outlining text to paths is **not** used for SVG, since it would require the proprietary font. **RECOMMENDED:** a page that embeds the SVG inline loads Adobe Clean through its own web font (for example the Typekit kit the docs site uses, family `adobe-clean-spectrum-vf`). Standalone `.svg` files, SVG used as an `<img>` or CSS background, and rasterized PNG output cannot load web fonts. They use the installed font or fall back to Source Sans 3, so exports **MAY** look slightly different from the live view. Outlining text at export time with a locally licensed font is a possible later option.
+
+**R3 — Layout: minimal flex first.** The pilot box model needs row direction, centering, gap, padding and one absolutely placed child. A purpose-built layout of that size avoids a dependency and keeps WASM small. Revisit `taffy` when text-field (wrapping, stacked label and help text) is piloted.
+
+**R4 — Icons.** Glyph geometry is sourced as SVG path data keyed by icon name (`workflow-icon`) and by the pilot's fixed glyphs (hold-icon corner triangle, checkmark). Literal paths are the one allowed use of `{"value": ...}`. A shared icon registry is follow-up work.
+
+**R5 — Figma.** The Figma backend consumes the scene graph and emits node JSON for a plugin to create frames bound to Figma Variables by token id, reusing the Variable mapping in `sdk/plugins/figma`. It requires no Figma-specific data in recipes.
+
+## Open questions
+
+* **Structured relationships.** Newer relationships already carry a `part` field and structured `options` (for example `state`, `size`, `scale`). Recipes should prefer them over `context` strings as more components adopt them; action-button's relationships still use labels only.
+
+* **Deprecated tokens.** The pilot's icon sizes bind to `workflow-icon-size-*` tokens that validation (SPEC-058) reports as deprecated in 14.5.0 with no `replacedBy`. The recipe follows the relationships until a replacement is mapped.
+
+* **Switch.** The switch recipe covers default, hover, down, keyboard-focus, and disabled, across selected and emphasized. Its track and handle colors come from relationships added for it, taken from the Figma token spec. They await design sign-off.
+
+* **Pilot coverage.** The action-button recipe covers default, hover, down, focus, disabled, and static black/white. Quiet, selected, and emphasized fills are not yet authored.
+
+* Should render requests (presets, matrices) be stored in the dataset for the Hub site, or stay tool input?
+
+* Which gaps in component-scoped tokens block recipes beyond the pilot? action-button binds only through relationships; many components have none.
+
+* Does `visibleWhen` need boolean composition (any/not), or are single conditions enough?

package/spec/index.md

@@ -25,10 +25,12 @@ The specification defines:
 11. **Document blocks** — typed prose blocks attachable to tokens, components, and anatomy parts; makes design guidance machine-readable and agent-queryable ([Document blocks](document-blocks.md)).
 12. **Agent-readable surface** — operations and transport contracts (CLI, MCP server, Agent Skill) for AI agents consuming spec-conformant design data; covers session primer, token resolution, validation, query, and component description ([Agent-readable surface](agent-surface.md)).
 13. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
+    * **Artifact moves** — promoting and demoting one artifact between a platform and the foundation ([Artifact moves](artifact-moves.md)).
 14. **Dataset layout** — normative directory structure of a dataset (`tokens/`, `components/`, `fields/`, `mode-sets/`, `registry/`, `guidelines/`), discovery algorithm, and optional root descriptor ([Dataset layout](dataset-layout.md)).
 15. **Guideline documents** — standalone JSON files representing non-component design guidance pages (color, typography, motion, spacing, principles, etc.); each wraps page metadata and a `documentBlocks` body ([Guideline format](guideline-format.md)).
 16. **Authoring workflow** — normative contract for authoring design data via tooling: authoritative source location, lifecycle operations (create / edit / deprecate / rename / alias-rewire / mode-set management), taxonomy-aware decomposition requirement, and output-generation obligations ([Authoring workflow](authoring-workflow.md)).
 17. **Relationship format** — Component/Token Relationship (CTR): the anonymous-token entity unifying `tokenBindings` and token name-object scope fields, explicit relationship context, options validation, and interim legacy-compatibility fields ([Relationship format](relationship-format.md)).
+18. **Component visuals** — renderer-neutral visual recipes (part tree, layout, token-bound paint) that drive SVG, PNG, and Figma output ([Component visuals](component-visuals.md); draft RFC).
 
 This specification intentionally defines the Design Data-owned contract and links to external standards for platform-native implementation semantics instead of restating those contracts as normative local rules. The repository owns taxonomy, validation, lifecycle, and schema rules; the authoritative source for native format behavior remains the external standard it describes.
 
@@ -70,6 +72,7 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | [Taxonomy](taxonomy.md)                             | Concept categories, vocabulary, formatting, anatomy vs objects.                                                                                       |
 | [Registry](registry.md)                             | Named value collections for vocabulary validation; three-registry boundary (anatomy, token objects, categories) and packaging.                        |
 | [Component format](component-format.md)             | Component declaration: options, slots, anatomy (→ anatomy-format.md), states (→ state-model.md), lifecycle.                                           |
+| [Option constraints](option-constraints.md)         | If-then rules restricting valid option combinations on a component.                                                                                   |
 | [Anatomy format](anatomy-format.md)                 | Anatomy part declarations: field constraints, canonical vocabulary, SPEC-020/SPEC-023/SPEC-024/SPEC-025.                                              |
 | [State model](state-model.md)                       | State declarations: trigger semantics, precedence algorithm, canonical vocabulary, SPEC-022/SPEC-026.                                                 |
 | [Cascade](cascade.md)                               | Layers, specificity, resolution algorithm.                                                                                                            |
@@ -83,10 +86,12 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | [Document blocks](document-blocks.md)               | Typed prose blocks (purpose, guideline, accessibility, do-dont, examples) attachable to any entity.                                                   |
 | [Agent-readable surface](agent-surface.md)          | Transport contracts (CLI, MCP, Agent Skill) and operation catalog for AI agents consuming spec-conformant design data.                                |
 | [Evolution](evolution.md)                           | Deprecation lifecycle, migration windows, change classification.                                                                                      |
+| [Artifact moves](artifact-moves.md)                 | Promote and demote one artifact between a platform manifest and the foundation: criteria, steps, notice period, provenance.                           |
 | [Dataset layout](dataset-layout.md)                 | Normative dataset directory structure, discovery algorithm, optional root descriptor, and SPEC-044 structural pre-check.                              |
 | [Guideline format](guideline-format.md)             | Standalone guideline document shape: metadata fields, `category` enum, `related` cross-references, and required `documentBlocks` body (SPEC-045/046). |
 | [Authoring workflow](authoring-workflow.md)         | Normative authoring contract: authoritative source location, lifecycle operations, taxonomy-aware decomposition, and output-generation obligations.   |
 | [Relationship format](relationship-format.md)       | Component/Token Relationship (CTR): shape, explicit relationship context, options validation, and interim legacy-compatibility fields (SPEC-051–057). |
+| [Component visuals](component-visuals.md)           | Draft RFC: visual recipe shape, value sources and conditions, scene graph, and renderer decisions.                                                    |
 
 ## JSON Schema `$id` and versioning