@adobe/design-data-spec 4.4.0 → 4.6.0

package/conformance/manifest-extensions/valid/implementations-upsert-foundation-row/extensions/implementations/button.json

@@ -0,0 +1,12 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "package": "@adobe/spectrum-wc",
+      "importPath": "@adobe/spectrum-wc/components/button",
+      "notes": "Custom element: swc-button."
+    }
+  ]
+}

package/conformance/manifest-extensions/valid/implementations-upsert-foundation-row/manifest.json

@@ -0,0 +1,5 @@
+{
+  "specVersion": "1.0.0-draft",
+  "foundationVersion": "1.0.0",
+  "platform": "web-components"
+}

package/conformance/manifest-extensions/valid/injects-component-option-extension/expected.json

@@ -0,0 +1,18 @@
+{
+  "componentOptionExtensions": {
+    "present": [
+      {
+        "platform": "Web Components",
+        "component": "button",
+        "option": "style",
+        "platformProp": "fillStyle"
+      },
+      {
+        "platform": "Web Components",
+        "component": "button",
+        "option": "isDisabled",
+        "platformProp": "disabled"
+      }
+    ]
+  }
+}

package/conformance/manifest-extensions/valid/injects-component-option-extension/extensions/components/button.json

@@ -0,0 +1,20 @@
+{
+  "$id": "https://example.com/components/button",
+  "name": "button",
+  "displayName": "Button",
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://example.com"
+  },
+  "options": {
+    "style": {
+      "type": "string",
+      "default": "fill",
+      "values": [{ "value": "fill" }, { "value": "outline" }]
+    },
+    "isDisabled": {
+      "type": "boolean",
+      "default": false
+    }
+  }
+}

package/conformance/manifest-extensions/valid/injects-component-option-extension/extensions/platform-extensions/web-components-button.json

@@ -0,0 +1,18 @@
+{
+  "platform": "Web Components",
+  "componentOptions": [
+    {
+      "component": "button",
+      "option": "style",
+      "platformProp": "fillStyle",
+      "platformAttribute": "fill-style",
+      "values": [{ "value": "fill", "platformValue": "Fill" }]
+    },
+    {
+      "component": "button",
+      "option": "isDisabled",
+      "platformProp": "disabled",
+      "platformAttribute": "disabled"
+    }
+  ]
+}

package/conformance/manifest-extensions/valid/injects-component-option-extension/manifest.json

@@ -0,0 +1,4 @@
+{
+  "specVersion": "1.0.0-draft",
+  "foundationVersion": "1.0.0"
+}

package/llms.txt

@@ -0,0 +1,29 @@
+# @adobe/design-data-spec
+
+> Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format
+
+Normative **Design Data Specification** artifacts for Spectrum: human-readable spec (`spec/`), JSON Schemas (`schemas/`), validation rule catalog (`rules/`), and conformance fixtures (`conformance/`).
+
+**Spec version:** `1.0.0-draft` — see [`spec/index.md`](spec/index.md).
+
+See [`spec/manifest.md`](spec/manifest.md) for the platform manifest spec, including the
+`extensions/` directory model.
+
+## Install
+
+`npm install @adobe/design-data-spec`
+
+## Documentation
+
+- [README](https://github.com/adobe/spectrum-design-data/blob/main/packages/design-data-spec/README.md): usage and API overview
+- [Layers](https://github.com/adobe/spectrum-design-data/blob/main/packages/design-data-spec/README.md#layers)
+- [Package exports](https://github.com/adobe/spectrum-design-data/blob/main/packages/design-data-spec/README.md#package-exports)
+- [Tasks](https://github.com/adobe/spectrum-design-data/blob/main/packages/design-data-spec/README.md#tasks)
+- [References](https://github.com/adobe/spectrum-design-data/blob/main/packages/design-data-spec/README.md#references)
+- [Repository index](https://github.com/adobe/spectrum-design-data/blob/main/docs/repo-index.md): how this package fits in the repository
+
+## Optional
+
+- [Changelog](https://github.com/adobe/spectrum-design-data/blob/main/packages/design-data-spec/CHANGELOG.md)
+- [npm package](https://www.npmjs.com/package/@adobe/design-data-spec)
+- [Source](https://github.com/adobe/spectrum-design-data/blob/main/packages/design-data-spec/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
   "type": "module",
   "repository": {
@@ -26,6 +26,7 @@
     "./schemas/manifest.schema.json": "./schemas/manifest.schema.json",
     "./schemas/value-types/color.schema.json": "./schemas/value-types/color.schema.json",
     "./schemas/component.schema.json": "./schemas/component.schema.json",
+    "./schemas/implementation-mapping.schema.json": "./schemas/implementation-mapping.schema.json",
     "./schemas/anatomy-part.schema.json": "./schemas/anatomy-part.schema.json",
     "./schemas/state-declaration.schema.json": "./schemas/state-declaration.schema.json",
     "./rules/rules.yaml": "./rules/rules.yaml",
@@ -39,6 +40,7 @@
     "rules",
     "schemas",
     "spec",
+    "llms.txt",
     "README.md"
   ]
 }

package/schemas/component.schema.json

@@ -42,7 +42,7 @@
       "items": {
         "$ref": "#/$defs/implementation"
       },
-      "description": "Known platform implementations of this component. Foundation-owned canonical mappings; platform-specific overrides are not supported yet. See spec/component-format.md#implementations."
+      "description": "Known platform implementations of this component. Foundation data carries canonical default mappings; a platform manifest refines its own rows through extensions/implementations/. See spec/component-format.md#implementations."
     },
     "options": {
       "$ref": "#/$defs/optionsMap"
@@ -115,6 +115,11 @@
           "minLength": 1,
           "description": "Target platform identifier (for example, 'web', 'ios', or 'android'). Multiple implementations may target the same platform when they have distinct packages."
         },
+        "implementation": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Implementation project id from the platform-implementations registry (for example, 'react-spectrum' or 'web-components'). Distinguishes implementations that share a `platform` device target. A platform manifest stamps its own `platform` id here when merging extensions/implementations/ entries that omit it."
+        },
         "componentName": {
           "type": "string",
           "minLength": 1,
@@ -123,7 +128,7 @@
         "importPath": {
           "type": "string",
           "minLength": 1,
-          "description": "Importable module or source path for a platform implementation."
+          "description": "Importable module or source path for a platform implementation. When `package` is also set, this SHOULD be a subpath export of that package."
         },
         "package": {
           "type": "string",
@@ -135,7 +140,7 @@
           "description": "Optional implementation-specific usage or mapping notes."
         }
       },
-      "oneOf": [
+      "anyOf": [
         {
           "required": ["importPath"]
         },

package/schemas/implementation-mapping.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/implementation-mapping.schema.json",
+  "title": "Platform implementation mapping",
+  "description": "Layer 1 schema for one platform manifest extensions/implementations/ fragment: the platform's own implementation rows for a single component, merged into that component's `implementations` array. See spec/manifest.md#extensionsimplementations.",
+  "type": "object",
+  "required": ["component", "implementations"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "component": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Name of the component (foundation or platform-local) whose `implementations` this fragment refines."
+    },
+    "implementations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "if": {
+          "required": ["op"]
+        },
+        "then": {
+          "$ref": "#/$defs/removeEntry"
+        },
+        "else": {
+          "$ref": "component.schema.json#/$defs/implementation"
+        }
+      },
+      "description": "Rows to upsert (implementation objects) or remove (`op: \"remove\"` selectors), applied in order."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "removeEntry": {
+      "type": "object",
+      "description": "Removes every existing row of the component whose fields equal each selector field given here.",
+      "required": ["op", "componentName"],
+      "properties": {
+        "op": {
+          "const": "remove"
+        },
+        "platform": {
+          "type": "string",
+          "minLength": 1
+        },
+        "implementation": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "componentName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "package": {
+          "type": "string",
+          "minLength": 1
+        },
+        "importPath": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/platform-extension.json

@@ -4,7 +4,11 @@
   "title": "Platform Extension",
   "description": "Schema for platform-specific terminology extensions",
   "type": "object",
-  "required": ["platform", "extends", "extensions"],
+  "required": ["platform"],
+  "anyOf": [
+    { "required": ["extends", "extensions"] },
+    { "required": ["componentOptions"] }
+  ],
   "properties": {
     "$schema": {
       "type": "string",
@@ -32,9 +36,77 @@
       "items": {
         "$ref": "#/$defs/extension"
       }
+    },
+    "componentOptions": {
+      "type": "array",
+      "description": "Per-component option/value aliasing for this platform. Unlike `extensions` (which aliases a shared registry term everywhere it's used), these entries scope to one component's own `options` map — the right home for a naming difference that isn't backed by a shared registry (e.g. Button's `style` option vs. React's `fillStyle` prop).",
+      "items": {
+        "$ref": "#/$defs/componentOptionExtension"
+      }
     }
   },
   "$defs": {
+    "componentOptionExtension": {
+      "type": "object",
+      "required": ["component", "option"],
+      "properties": {
+        "component": {
+          "type": "string",
+          "description": "Component `name` (as declared in its component.schema.json file, e.g. 'button') this extension applies to."
+        },
+        "option": {
+          "type": "string",
+          "description": "Canonical option name from the component's `options` map (e.g. 'style')."
+        },
+        "platformProp": {
+          "type": "string",
+          "description": "This platform's name for the option (e.g. 'fillStyle')."
+        },
+        "platformAttribute": {
+          "type": "string",
+          "description": "This platform's HTML/DOM attribute name, when it differs from platformProp (e.g. Web Components' fill-style attribute vs. its fillStyle JS property). Omit if not applicable or identical to platformProp."
+        },
+        "platformAliases": {
+          "type": "array",
+          "description": "Other names this platform has used for the same concept (e.g. during a migration).",
+          "items": { "type": "string" }
+        },
+        "notes": {
+          "type": "string",
+          "description": "Free-text context for why the names differ."
+        },
+        "values": {
+          "type": "array",
+          "description": "Per-value aliasing, for options whose values differ in casing or spelling across platforms (e.g. size 's'|'m'|'l'|'xl' canonical vs. React's 'S'|'M'|'L'|'XL').",
+          "items": {
+            "type": "object",
+            "required": ["value", "platformValue"],
+            "properties": {
+              "value": {
+                "type": "string",
+                "description": "Canonical value, from the component's options[option].values."
+              },
+              "platformValue": {
+                "type": "string",
+                "description": "This platform's value for the same concept."
+              }
+            }
+          }
+        },
+        "platformOnlyValues": {
+          "type": "array",
+          "description": "Values this platform's implementation accepts that have NO canonical/Figma counterpart (e.g. React Button's 'premium'/'genai' variants). Recorded here — not silently mapped to the nearest lookalike — so design-system drift between platforms is visible rather than papered over. A generator producing Code Connect templates from this data MUST NOT emit a figma.enum() entry for these; they can never appear in a Figma-driven example because no Figma variant represents them.",
+          "items": {
+            "type": "object",
+            "required": ["platformValue"],
+            "properties": {
+              "platformValue": { "type": "string" },
+              "notes": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "extension": {
       "type": "object",
       "required": ["termId"],

package/spec/component-format.md

@@ -84,30 +84,40 @@ where `{name}` matches the component's `name` field.
 ## Implementations
 
 `implementations` declares the published platform implementations corresponding
-to this design-system component. It is foundation-owned canonical data so
-consumers, including Code Connect generators, can resolve an implementation
-without platform-specific configuration.
+to this design-system component, so consumers such as Code Connect generators
+can resolve an implementation without platform-specific configuration.
 
-Each entry **MUST** contain `platform` and `componentName`, plus exactly one
-implementation reference: `package` for a published package or `importPath`
-for an importable module/source path. `notes` is optional context for consumers.
-Multiple entries MAY use the same `platform` when their packages distinguish
-different implementations for that platform.
+Each entry **MUST** contain `platform` and `componentName`, plus at least one
+implementation reference: `package` for a published package and/or
+`importPath` for an importable module or source path. When both are present,
+`importPath` **SHOULD** be a subpath export of `package`. `notes` is optional
+context for consumers.
+
+`platform` is a device target (`web`, `ios`, `android`), so several
+implementations may share it. The optional `implementation` field names the
+implementation project from the platform-implementations registry (for example
+`react-spectrum` or `web-components`) to tell them apart.
 
 ```json
 "implementations": [
   {
     "platform": "web",
+    "implementation": "web-components",
     "componentName": "Button",
-    "package": "@spectrum-web-components/button"
+    "package": "@adobe/spectrum-wc",
+    "importPath": "@adobe/spectrum-wc/components/button"
   }
 ]
 ```
 
-Platform manifests do not override `implementations` in this version. A future
-extension may add platform-owned overrides after consumers need them; until
-then, component declarations remain the canonical source of implementation
-names and references.
+### Layering
+
+Foundation component data carries canonical **default** rows. A platform
+manifest refines its own rows through
+[`extensions/implementations/`](manifest.md#extensionsimplementations):
+upserting rows it owns and removing stale ones, without restating the rest of
+the component. Rows owned by another implementation are left untouched, so the
+merged catalog still lists every implementation of the component.
 
 ## Options
 
@@ -426,13 +436,18 @@ A complete button component declaration:
     }
   ],
   "anatomy": [
-    { "name": "icon",  "description": "Leading icon." },
+    { "name": "icon", "description": "Leading icon." },
     { "name": "label", "description": "Button text.", "required": true }
   ],
   "states": [
-    { "name": "hover",    "trigger": "interaction", "precedence": 50 },
-    { "name": "focus",    "trigger": "interaction", "precedence": 60, "layered": true },
-    { "name": "disabled", "trigger": "prop",        "precedence": 100 }
+    { "name": "hover", "trigger": "interaction", "precedence": 50 },
+    {
+      "name": "focus",
+      "trigger": "interaction",
+      "precedence": 60,
+      "layered": true
+    },
+    { "name": "disabled", "trigger": "prop", "precedence": 100 }
   ],
   "lifecycle": {
     "introduced": "1.0.0-draft"
@@ -448,7 +463,10 @@ A complete button component declaration:
 {
   "name": "button",
   "displayName": "Button",
-  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://spectrum.adobe.com/page/button/"
+  },
   "accessibility": {
     "role": "button",
     "intents": ["trigger"],
@@ -479,7 +497,10 @@ A complete button component declaration:
 {
   "name": "button",
   "displayName": "Button",
-  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://spectrum.adobe.com/page/button/"
+  },
   "documentBlocks": [
     {
       "type": "purpose",

package/spec/manifest.md

@@ -8,25 +8,26 @@ 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 |
-| 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       |
+| 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)) | —                                 | —                           |
 
 ## Manifest document
 
@@ -112,6 +113,7 @@ extensions/
   relationships/         <component>.json      one CTR set per file
   guidelines/             <topic>.json         one guideline per file
   platform-extensions/   <platform>-<registry>.json
+  implementations/       <component>.json      one component's implementation rows
 ```
 
 **NORMATIVE:** Each subdirectory is discovered by a recursive glob for `*.json` files (for
@@ -131,6 +133,9 @@ or empty subdirectory contributes nothing and is not an error.
   injected into the corresponding catalog **add-or-replace by name** (for
   `platform-extensions/`, by `termId`; see below). When two files declare the same name,
   **the entry from the later file (in sorted path order) wins.**
+* **`implementations/`** — one component's implementation rows per file, merged row-by-row into
+  that component's existing `implementations` array (never whole-array replaced). See
+  [`extensions/implementations/`](#extensionsimplementations) below.
 
 **NORMATIVE:** Each fragment file **MUST** validate against its category's real JSON schema at
 load time — this is enforced reference-SDK behavior, not an aspirational goal:
@@ -142,6 +147,8 @@ load time — this is enforced reference-SDK behavior, not an aspirational goal:
 * **`relationships/`** → `relationship.schema.json` (see the Add/Override/remove rules above)
 * **`platform-extensions/`** → `platform-extension.json` (see
   [`extensions/platform-extensions/`](#extensionsplatform-extensions) below)
+* **`implementations/`** → `implementation-mapping.schema.json` (see
+  [`extensions/implementations/`](#extensionsimplementations) below)
 * **`tokens/`** → `cascade-file.schema.json` (see above)
 
 A fragment that fails validation against its category schema is a manifest error — the
@@ -214,6 +221,51 @@ example, platform-specific state names). **NORMATIVE:** each file **MUST** valid
 foundation registry — this mechanism annotates existing ids, it does **NOT** introduce new
 ones.
 
+#### `extensions/implementations/`
+
+Platform-owned refinements of a component's
+[`implementations`](component-format.md#implementations) — the packages, import paths, and
+exported names a platform ships. Foundation component data carries canonical **default** rows;
+a platform manifest refines only its own rows, so the implementation team that owns the
+manifest also owns its mappings, and they travel with the manifest when it is ejected.
+
+```json
+{
+  "component": "button",
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "package": "@react-spectrum/s2"
+    },
+    {
+      "op": "remove",
+      "componentName": "Button",
+      "package": "@react-spectrum/button"
+    }
+  ]
+}
+```
+
+**NORMATIVE:** each file **MUST** validate against `implementation-mapping.schema.json`.
+`component` **MUST** name a component in the catalog after `extensions/components/` has been
+applied (so a fragment may target a platform-local component); an unknown component is a
+manifest error. Entries apply in array order, files in sorted path order.
+
+**NORMATIVE:** each entry has an *owner*: its own `implementation` field if present, otherwise
+the manifest's top-level `platform` id. A manifest only matches rows its owner owns — rows
+stamped with the same `implementation` id, or unstamped foundation defaults. Rows stamped with
+a different `implementation` id are never modified or removed.
+
+* **Upsert** (no `op`) — a full implementation row. When the entry omits `implementation` and
+  the manifest declares `platform`, the stored row is stamped with that id. The row replaces the
+  first existing row with the same `platform` and `componentName` that either carries the same
+  `implementation` id, or is an unstamped foundation default sharing a `package` or `importPath`
+  value. Otherwise it is appended.
+* **Remove** (`"op": "remove"`) — a selector of `componentName` plus any of `platform`,
+  `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.
+
 ### `namingExceptions`
 
 Platform-local overlay on the base naming-exceptions set used by naming validation.