@adobe/design-data-spec 4.8.1 → 4.10.0

package/spec/manifest.md

@@ -8,26 +8,28 @@ This document defines the **platform manifest**: how a platform implementation r
 
 The manifest supports a fixed, enumerated set of operations against the foundation — it does **not** allow overriding, aliasing, or removing arbitrary foundation artifacts. Support is concentrated on tokens; translations and schemas have no manifest-level override mechanism at all.
 
-| Operation                                           | Supported?                                                   | Field                             | Applies to                     |
-| --------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | ------------------------------ |
-| Remove / exclude                                    | Yes                                                          | `exclude`                         | Tokens only                    |
-| Include / whitelist                                 | Yes                                                          | `include`                         | Tokens only                    |
-| Override value (type-preserving)                    | Yes                                                          | `overrides[].value`               | Tokens only                    |
-| Override → re-alias                                 | Yes                                                          | `overrides[].$ref`                | Tokens only                    |
-| Add new tokens (may alias via `$ref`)               | Yes                                                          | `extensions/tokens/`              | Tokens                         |
-| Add / replace components                            | Yes                                                          | `extensions/components/`          | Components                     |
-| Add / replace field declarations                    | Yes                                                          | `extensions/fields/`              | Fields                         |
-| Add / replace guideline documents                   | Yes                                                          | `extensions/guidelines/`          | Guidelines                     |
-| Declare / replace platform-local mode set           | Yes                                                          | `extensions/mode-sets/`           | Mode sets                      |
-| Add / remove / retarget a single mode; remove a set | Yes                                                          | `extensions/mode-sets/` (`op`)    | Mode sets                      |
-| Add relationships/CTRs; override/remove by `uuid`   | Yes                                                          | `extensions/relationships/`       | Relationships (CTRs)           |
-| Add / remove naming exceptions                      | Yes                                                          | `namingExceptions`                | Naming validation              |
-| Annotate existing terminology (cannot add new ids)  | Yes                                                          | `extensions/platform-extensions/` | Existing registry ids or modes |
-| Upsert / remove own implementation mappings         | Yes                                                          | `extensions/implementations/`     | Component `implementations`    |
-| Restrict allowed mode-set values                    | Yes                                                          | `modeSetRestrictions`             | Mode sets                      |
-| Reformat name serialization                         | Schema-declared only, not yet applied by the reference SDK   | `formatting`                      | Token name strings             |
-| Override/remove/alias translations                  | No                                                           | —                                 | —                              |
-| Override Layer-1 schemas                            | No (decided; see [spike](manifest-schema-override-spike.md)) | —                                 | —                              |
+| Operation                                                 | Supported?                                                   | Field                             | Applies to                                   |
+| --------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------- | -------------------------------------------- |
+| Remove / exclude                                          | Yes                                                          | `exclude`                         | Tokens only                                  |
+| Include / whitelist                                       | Yes                                                          | `include`                         | Tokens only                                  |
+| Override value (type-preserving)                          | Yes                                                          | `overrides[].value`               | Tokens only                                  |
+| Override → re-alias                                       | Yes                                                          | `overrides[].$ref`                | Tokens only                                  |
+| Add new tokens (may alias via `$ref`)                     | Yes                                                          | `extensions/tokens/`              | Tokens                                       |
+| Add / replace components                                  | Yes                                                          | `extensions/components/`          | Components                                   |
+| Add / replace field declarations                          | Yes                                                          | `extensions/fields/`              | Fields                                       |
+| Add / replace guideline documents                         | Yes                                                          | `extensions/guidelines/`          | Guidelines                                   |
+| Declare / replace platform-local mode set                 | Yes                                                          | `extensions/mode-sets/`           | Mode sets                                    |
+| Add / remove / retarget a single mode; remove a set       | Yes                                                          | `extensions/mode-sets/` (`op`)    | Mode sets                                    |
+| Add relationships/CTRs; override/remove by `uuid`         | Yes                                                          | `extensions/relationships/`       | Relationships (CTRs)                         |
+| Add / remove naming exceptions                            | Yes                                                          | `namingExceptions`                | Naming validation                            |
+| Annotate existing terminology (cannot add new ids)        | Yes                                                          | `extensions/platform-extensions/` | Existing registry ids or modes               |
+| Upsert / remove own implementation mappings               | Yes                                                          | `extensions/implementations/`     | Component `implementations`                  |
+| Add / replace a component's visual recipe                 | Yes (loaded into the graph; `render` and `site` read it)     | `extensions/visuals/`             | Visual recipes                               |
+| Alias a foundation component name to a platform component | Field and SPEC-081 enforced; renderers apply it              | `componentAliases`                | `render`, `site`, WASM render, recipe lookup |
+| Restrict allowed mode-set values                          | Yes                                                          | `modeSetRestrictions`             | Mode sets                                    |
+| Reformat name serialization                               | Schema-declared only, not yet applied by the reference SDK   | `formatting`                      | Token name strings                           |
+| Override/remove/alias translations                        | No                                                           | —                                 | —                                            |
+| Override Layer-1 schemas                                  | No (decided; see [spike](manifest-schema-override-spike.md)) | —                                 | —                                            |
 
 ## Manifest document
 
@@ -53,6 +55,7 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
 | `extensionsDir`       | string          | Path (relative to the manifest) to the platform's `extensions/` directory. Default: `"extensions"`. See [`extensions/` directory](#extensions-directory) below.                                             |
 | `namingExceptions`    | object          | Platform-local overlay on the base naming-exceptions set: names to add and/or remove for this platform's naming validation.                                                                                 |
 | `formatting`          | object          | Rules for serializing structured name objects into platform-specific token name strings.                                                                                                                    |
+| `componentAliases`    | object          | Maps a foundation component name to a component the platform declares. See [`componentAliases`](#componentaliases).                                                                                         |
 | `modeSetRestrictions` | object          | Mode set restrictions for this platform; see [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions).                                                                                       |
 
 ### `include` / `exclude`
@@ -75,7 +78,7 @@ An override **replaces** the foundation record for that platform's graph: the re
 
 | Field            | Value                                                                                                                                                                                                                                    |
 | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `overriddenBy`   | `{ "platform": "<manifest platform>" }` when the manifest sets `platform`; otherwise `{ "manifest": "manifest.json" }` (the literal file name; the manifest's real path is not recorded).                                                                                                                |
+| `overriddenBy`   | `{ "platform": "<manifest platform>" }` when the manifest sets `platform`; otherwise `{ "manifest": "manifest.json" }` (the literal file name; the manifest's real path is not recorded).                                                |
 | `overriddenFrom` | `{ "value": <foundation value> }` or `{ "$ref": <foundation $ref> }`. The first override's history is kept, so it is always the foundation value, even when a token is overridden more than once (the last override wins for the value). |
 
 These markers exist only on the platform's in-memory records. They are not written to token files and are **not** serialized in legacy output.
@@ -115,6 +118,7 @@ extensions/
   guidelines/             <topic>.json         one guideline per file
   platform-extensions/   <platform>-<registry>.json
   implementations/       <component>.json      one component's implementation rows
+  visuals/               <component>.json      one visual recipe per file
 ```
 
 **NORMATIVE:** Each subdirectory is discovered by a recursive glob for `*.json` files (for
@@ -268,6 +272,15 @@ a different `implementation` id are never modified or removed.
   `implementation`, `package`, `importPath`. It deletes every owned row whose values equal every
   selector field given. A remove that matches no owned row is a manifest error.
 
+### `componentAliases`
+
+The field, `TokenGraph::canonical_component` and SPEC-081 are implemented; `render`, `site`, WASM render and recipe lookup call it, so a request for the alias key draws the target's recipe ([Proposal 014](../../../docs/proposals/014-platform-owned-visual-recipes.md)). A map from a foundation component name to a component the platform declares in `extensions/components/`, for example `{ "button": "button-ios" }`.
+
+* **Applies to** commands that show a component by its user-facing name: `render`, `site`, WASM render and recipe lookup. The name resolves to the target.
+* **Does not apply to** `query`, `validate`, `diff` and `export`, which inspect data under real names. `query` prints a one-line hint when it names an aliased component.
+* **Never rewrites** a token, a relationship scope, a recipe file name or a diagnostic. Both components stay in the graph; diagnostics name the target.
+* SPEC-081 (error): the key **MUST** be a foundation component; the target **MUST** be declared by the platform; aliases **MUST NOT** chain or form a cycle; a key **MUST NOT** also be replaced by `extensions/components/<key>.json`.
+
 ### `namingExceptions`
 
 Platform-local overlay on the base naming-exceptions set used by naming validation.
@@ -300,6 +313,8 @@ A platform **MAY** declare formatting rules that control how structured name obj
 
 **NORMATIVE:** Manifests **MUST** pass Layer 1 JSON Schema validation.
 
+**NORMATIVE:** A manifest **MUST** apply to the foundation dataset. A validator that cannot apply it, for example because it extends a mode set that was not loaded, **MUST** report an error (SPEC-082 `platform-manifest-applies`) and not skip the platform rules silently.
+
 **RECOMMENDED:** Validators resolve `foundationVersion` against a registry or lockfile and report mismatches as errors or warnings per product policy.
 
 **RECOMMENDED:** Validators confirm the resolved `foundationVersion` provides a cascade-format
@@ -319,4 +334,5 @@ The platform manifest is the Layer 2 context document. For Layer 3 (product-laye
 
 * [#715 — Distributed Design Data Architecture](https://github.com/adobe/spectrum-design-data/discussions/715)
 * [#625 — Token Authoring Workflow](https://github.com/adobe/spectrum-design-data/discussions/625)
+* [Artifact moves](artifact-moves.md) — promoting and demoting one artifact between a platform and the foundation
 * [Schema-override spike](manifest-schema-override-spike.md) — why the manifest cascade does not allow platform overrides of Layer-1 schemas

package/spec/option-constraints.md

@@ -0,0 +1,87 @@
+<!-- Copyright 2026 Adobe. All rights reserved. -->
+
+# Option constraints
+
+## Problem
+
+A component's `options` block lists the values each option accepts ([Component format](component-format.md#options)). It cannot say which *combinations* are valid. Today that knowledge lives in prose (for example Button's `icon` description: "Required when `isLabelHidden` is true") or in implementation code. Visual rendering exposed three cases for Button:
+
+* `style: outline` is only designed for `primary` and `secondary`. Accent and negative outline have no spec.
+* `staticColor` only restyles `primary` and `secondary`. Accent and negative render as usual.
+* `icon` is required when `isLabelHidden` is true.
+
+Without a machine-readable form, recipes drift (an accent `fill` rule leaks onto outline buttons), matrices render undefined states, and validators cannot flag either.
+
+## Design
+
+An optional `constraints` array on the component object, next to `options`.
+
+```json
+"constraints": [
+  {
+    "when": { "style": "outline" },
+    "require": { "variant": ["primary", "secondary"] },
+    "severity": "error",
+    "description": "Outline style is only defined for primary and secondary.",
+    "source": "react-spectrum S2 Button.tsx"
+  },
+  {
+    "when": { "staticColor": ["white", "black"] },
+    "require": { "variant": ["primary", "secondary"] },
+    "severity": "advisory",
+    "description": "Static color only changes primary and secondary."
+  },
+  {
+    "when": { "isLabelHidden": true },
+    "require": { "icon": { "present": true } },
+    "severity": "error"
+  }
+]
+```
+
+### Constraint object
+
+| Field         | Type   | Required | Description                                                                                                                                                        |
+| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `when`        | object | REQUIRED | Option conditions that select the combinations the rule applies to. Keys are option names; a value is a literal, or an array meaning any of. Conditions are ANDed. |
+| `require`     | object | REQUIRED | What those combinations must satisfy. Keys are option names; a value is an array of permitted values, or `{ "present": true }` for presence.                       |
+| `severity`    | string | REQUIRED | `error` (combination is invalid or undefined) or `advisory` (valid, but no distinct design).                                                                       |
+| `description` | string | OPTIONAL | Plain-text rationale.                                                                                                                                              |
+| `source`      | string | OPTIONAL | Where the rule comes from (design file, implementation, spec page).                                                                                                |
+
+`when` uses the same option-matching form as visual-recipe `when` and relationship `scope.options`. A constraint is an "if this, then that" rule. Boolean composition (any/not across options) is out of scope and is answered together with the `visibleWhen` question in [Component visuals](component-visuals.md#open-questions).
+
+### Semantics
+
+**NORMATIVE:** A combination of option values that matches a constraint's `when` and violates its `require` is *excluded* at that constraint's severity.
+
+* `error`: Tools **MUST NOT** present the combination as a supported state (matrices skip it). Validators **MUST** report recipes, relationships, or tokens that target only excluded combinations.
+* `advisory`: Tools **SHOULD** still render the combination. Validators **SHOULD** warn only when a rule targets it as if it had distinct design.
+
+Constraints are additive. They never change which values an option declares; they only restrict combinations.
+
+## Rules
+
+| Rule     | Layer | Severity | Check                                                                                                                    |
+| -------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| SPEC-064 | 2     | error    | Every option name and value used in a constraint's `when` or `require` is declared in the component's `options`.         |
+| SPEC-065 | 2     | warning  | A visual recipe rule or relationship `scope.options` that matches *only* combinations excluded by an `error` constraint. |
+
+SPEC-064 is silent for value checks when an option declares no `values` list. SPEC-065 enumerates the combinations a rule matches; unpinned options range over their declared values (booleans over true and false), and an option with no known domain is never proven excluded. A rule that also matches a valid combination is not reported: a recipe that leaks onto an excluded combination while still serving a valid one is a recipe-scoping problem, not an SPEC-065 finding.
+
+Layer 1 (`component.schema.json`) checks the `constraints` shape only. It cannot check that names exist.
+
+## Consumers
+
+* **Visual matrix and renderer:** skip combinations excluded by an `error` constraint; render `advisory` ones.
+* **Hub and docs:** show excluded combinations as unavailable in option pickers.
+* **Platform extensions:** no override in v1. If a platform allows a combination another forbids, add a per-platform override later, following the extension layering.
+
+## Decisions
+
+* **Name:** `constraints`. Slot constraints, if needed later, can use a separate field.
+* **Severity:** `error` and `advisory` both ship in v1. "Valid but undesigned" combinations (Button accent with a static color) are common and need to be distinguishable from invalid ones.
+* **Composition:** "if this, then that" only. Boolean composition (any/not across options) is deferred and decided together with `visibleWhen` in [Component visuals](component-visuals.md#open-questions).
+* **Overrides:** an option that makes another irrelevant (checkbox `isIndeterminate` over `isSelected`) is an `advisory` constraint that requires the overridden option to hold its default. There is no separate "overrides" kind.
+* **Scope:** foundation component files only. Platform extensions do not declare constraints in v1.
+* **Accessible names:** not option constraints. They belong to [Accessibility](accessibility.md).

package/spec/relationship-format.md

@@ -43,15 +43,15 @@ Each CTR is one of two subtypes, mirroring the token `oneOf` split (see [token-f
 
 ## Scope fields
 
-| Field             | Required | Type   | Description                                                                                                                                                                                                                                                                                                                                                                          |
-| ----------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `scope.component` | yes      | string | Component name (kebab-case). **MUST** match the `name` of a declared component in the dataset (rule SPEC-051, mirrors SPEC-018).                                                                                                                                                                                                                                                     |
-| `scope.part`      | no       | string | Anatomy part name. **MUST** match a declared anatomy part on the referenced component when present (rule SPEC-052, mirrors SPEC-020).                                                                                                                                                                                                                                                |
-| `scope.property`  | yes      | string | The stylistic attribute this relationship describes (e.g. `color`, `width`, `padding`).                                                                                                                                                                                                                                                                                              |
-| `scope.options`   | no       | object | Option-scoped narrowing. Each `options.<key>` value **MUST** validate against the referenced component's `options.<key>.values` (rule SPEC-053 — the headline CTR rule, stricter than the token-side SPEC-040 warning). `options.state` is the exception: an ordered array of atomic state ids, validated against the component's declared states (rule SPEC-054, mirrors SPEC-022). |
-| `context`         | no       | string | Human-readable label for how this CTR is used (mirrors `tokenBindings[].context`; maps to a Figma Token Group label). Purely descriptive — not validated.                                                                                                                                                                                                                            |
+| Field             | Required | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ----------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scope.component` | yes      | string | Component name (kebab-case). **MUST** match the `name` of a declared component in the dataset (rule SPEC-051, mirrors SPEC-018).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `scope.part`      | no       | string | Anatomy part name. **MUST** match a declared anatomy part on the referenced component when present (rule SPEC-052, mirrors SPEC-020).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `scope.property`  | yes      | string | The stylistic attribute this relationship describes (e.g. `color`, `width`, `padding`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `scope.options`   | no       | object | Option-scoped narrowing. Each `options.<key>` value **MUST** validate against the referenced component's `options.<key>.values` (rule SPEC-053 — the headline CTR rule, stricter than the token-side SPEC-040 warning). A boolean option (for example `isSelected`) takes `true` or `false`; use it, not `state`, for conditions the component models as an option. An array value matches when any listed value matches. A relationship with no pinned options is the default for its `(property, context)`; a recipe uses the one that pins the most options matching the request. `scope.options.state` adds states to those of the token the relationship binds. `options.state` is the exception: an ordered array of atomic state ids, validated against the component's declared states (rule SPEC-054, mirrors SPEC-022). |
+| `context`         | no       | string | Human-readable label for how this CTR is used (mirrors `tokenBindings[].context`; maps to a Figma Token Group label). Purely descriptive — not validated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
-Layer 1 (`relationship.schema.json`) only enforces shape: `scope.options` is an object, `scope.options.state` (when present) is an array of strings, and other option values are typically strings. It does **not** enforce which option values are valid — that is a Layer 2 (Rust, `sdk/core`) relational rule, because it requires cross-referencing the component catalog.
+Layer 1 (`relationship.schema.json`) only enforces shape: `scope.options` is an object, `scope.options.state` (when present) is an array of strings, and other option values are strings, booleans (for boolean options) or arrays of either. It does **not** enforce which option values are valid — that is a Layer 2 (Rust, `sdk/core`) relational rule, because it requires cross-referencing the component catalog.
 
 ## Value-owning vs. relationship-only
 
@@ -64,9 +64,11 @@ A CTR **MUST NOT** declare both `value` and `$ref` (enforced at Layer 1 via `not
 
 ## Identity
 
-| Field  | Required | Type          | Description                                                                                                                                                                  |
-| ------ | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `uuid` | no       | string (uuid) | **MUST** be globally unique across all relationship entries within the same cascade layer (rule SPEC-056, mirrors SPEC-004). Required for a CTR to be a valid `$ref` target. |
+| Field  | Required | Type          | Description                                                                                                                                                                                                                                                              |
+| ------ | -------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `uuid` | yes      | string (uuid) | **MUST** be present (rule SPEC-084) and globally unique across all relationship entries within the same cascade layer (rule SPEC-056, mirrors SPEC-004). It is the stable identity changelogs, platform overrides and `$ref` use, and **MUST NOT** change once assigned. |
+
+A platform manifest overrides or removes a foundation relationship by this `uuid`, and a platform-local relationship (an `extensions/relationships/` file or an inline `extensions.relationships` add) carries its own. Authors can generate ids with `packages/design-data/scripts/backfill-relationship-uuid.mjs`, which derives a UUIDv5 from the record's identity and never changes an existing `uuid`.
 
 ## Legacy fields (interim)
 
@@ -101,3 +103,4 @@ The following rules are added to the Layer 2 rule catalog (`rules/rules.yaml`) b
 | SPEC-055 | `ctr-ref-resolves`                | error    | CTR `$ref` value **MUST** resolve to a declared token or relationship `uuid` in the dataset.                                                                                                                                                       |
 | SPEC-056 | `ctr-uuid-unique`                 | error    | CTR `uuid` values **MUST** be unique across all relationship entries within the same cascade layer.                                                                                                                                                |
 | SPEC-057 | `ctr-legacykey-present-if-legacy` | warning  | Advisory placeholder: a CTR that round-trips through the legacy generator **SHOULD** carry `legacyKey`. Generator-side "should have a legacy counterpart" detection is deferred; this rule documents intent rather than enforcing it structurally. |
+| SPEC-084 | `ctr-uuid-required`               | error    | Every CTR **MUST** have a `uuid`.                                                                                                                                                                                                                  |