@adobe/design-data-spec 4.4.0 → 4.5.0

package/conformance/manifest-extensions/README.md

@@ -4,12 +4,14 @@ Exercises the Layer 2 platform manifest's `extensions/` **directory** loader
 (`packages/design-data-spec/spec/manifest.md#extensions-directory`): a sibling
 `extensions/` tree (or a custom name via the manifest's `extensionsDir` field)
 whose category subdirectories (`tokens/`, `components/`, `fields/`,
-`guidelines/`, `mode-sets/`, `platform-extensions/`, `relationships/`) are discovered,
+`guidelines/`, `mode-sets/`, `platform-extensions/`, `relationships/`,
+`implementations/`) are discovered,
 glob+merged in sorted path order, per-fragment schema-validated, and spliced
 into the manifest before it's applied to the graph.
 
 * `base/dataset.json` — a shared minimal seed graph (three foundation tokens:
-  `btn-bg`, `btn-fg`, `chk-bg` on the `button`/`checkbox` components), loaded
+  `btn-bg`, `btn-fg`, `chk-bg` on the `button`/`checkbox` components, plus a
+  foundation `button` component with two default `implementations` rows), loaded
   once per case before that case's `manifest.json` is applied via
   `apply_configured`.
 * `valid/<case>/` — `manifest.json` + an `extensions/` (or custom-named) tree
@@ -19,13 +21,18 @@ into the manifest before it's applied to the graph.
   {
     "relationships": {
       "byUuid": { "<uuid>": { "count": 1, "value": "8px" } },
-      "absent": ["<uuid>"]
+      "absent": ["<uuid>"],
     },
     "components": { "present": ["tab-bar-ios"] },
     "fields": { "present": ["hapticStyle"] },
     "modeSets": { "present": ["interfaceLevel"] },
     "guidelines": { "present": ["ios-haptics"] },
-    "tokens": { "orderByUuid": ["<uuid-1>", "<uuid-2>"] }
+    "tokens": { "orderByUuid": ["<uuid-1>", "<uuid-2>"] },
+    "implementations": {
+      "<component>": [
+        /* exact merged rows */
+      ],
+    },
   }
   ```
   A case that only needs to prove "loads clean" uses `{}`.
@@ -37,30 +44,39 @@ Rust SDK drives these fixtures in `sdk/core/src/lib.rs` via the
 `manifest_extensions_conformance` (pass/fail + error message matching) and
 `manifest_extensions_behavior` (post-apply graph predicates) test modules.
 
-| Case                                           | Intent                                                                                                                   |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `valid/injects-component`                      | A `components/` fragment is injected as a Platform-layer component.                                                      |
-| `valid/injects-platform-extension`             | A `platform-extensions/` fragment is injected.                                                                           |
-| `valid/injects-field`                          | A `fields/` fragment is injected.                                                                                        |
-| `valid/injects-guideline`                      | A `guidelines/` fragment is injected.                                                                                    |
-| `valid/injects-mode-set`                       | A `mode-sets/` fragment is injected (declare-or-replace by name).                                                        |
-| `valid/injects-relationship`                   | A `relationships/` plain-add fragment is injected.                                                                       |
-| `valid/override-relationship-by-uuid`          | An `op: "override"` entry replaces a plain add sharing its `uuid`, regardless of file sort order.                        |
-| `valid/plain-add-uuid-collision-append`        | Two plain adds sharing a `uuid` both append rather than one overwriting the other.                                       |
-| `valid/remove-relationship-by-uuid`            | An `op: "remove"` entry deletes the matching relationship.                                                               |
-| `valid/tokens-sorted-order`                    | Multiple `tokens/*.tokens.json` files concatenate in sorted path order.                                                  |
-| `valid/later-file-wins`                        | Two `components/` fragments declaring the same component name dedupe to one, later file wins.                            |
-| `valid/custom-extensions-dir`                  | The manifest's `extensionsDir` field is honored in place of the default `extensions/` name.                              |
-| `valid/override-entry-skips-schema-validation` | An `op: "override"` relationship entry is not schema-validated against `relationship.schema.json` (only plain adds are). |
-| `invalid/override-missing-uuid`                | An `op: "override"` relationship entry missing `uuid` fails loudly.                                                      |
-| `invalid/unknown-term-id`                      | A `platform-extensions/` fragment referencing a non-existent `termId` fails loudly.                                      |
-| `invalid/component-missing-name`               | A `components/` fragment missing `name` fails Layer 1 fragment schema validation.                                        |
-| `invalid/field-invalid-kind`                   | A `fields/` fragment with an invalid `kind` enum value fails schema validation.                                          |
-| `invalid/guideline-invalid-category`           | A `guidelines/` fragment with an invalid `category` enum value fails schema validation.                                  |
-| `invalid/mode-set-missing-default`             | A `mode-sets/` fragment missing the required `default` field fails Layer 1 fragment schema validation.                   |
-| `invalid/platform-extension-missing-extends`   | A `platform-extensions/` fragment missing `extends` fails schema validation.                                             |
-| `invalid/token-invalid-uuid`                   | A `tokens/*.tokens.json` fragment with a malformed `uuid` fails schema validation.                                       |
-| `invalid/relationship-missing-scope`           | A `relationships/` plain-add fragment missing `scope` fails schema validation.                                           |
-| `invalid/extensions-dir-parent-traversal`      | `extensionsDir` containing a `..` component is rejected.                                                                 |
-| `invalid/extensions-dir-absolute-path`         | An absolute `extensionsDir` path is rejected.                                                                            |
-| `invalid/unknown-subdir-name`                  | An unrecognized subdirectory directly under `extensions/` (not one of the six known categories) is rejected by name.     |
+| Case                                             | Intent                                                                                                                          |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `valid/injects-component`                        | A `components/` fragment is injected as a Platform-layer component.                                                             |
+| `valid/injects-platform-extension`               | A `platform-extensions/` fragment is injected.                                                                                  |
+| `valid/injects-field`                            | A `fields/` fragment is injected.                                                                                               |
+| `valid/injects-guideline`                        | A `guidelines/` fragment is injected.                                                                                           |
+| `valid/injects-mode-set`                         | A `mode-sets/` fragment is injected (declare-or-replace by name).                                                               |
+| `valid/injects-relationship`                     | A `relationships/` plain-add fragment is injected.                                                                              |
+| `valid/override-relationship-by-uuid`            | An `op: "override"` entry replaces a plain add sharing its `uuid`, regardless of file sort order.                               |
+| `valid/plain-add-uuid-collision-append`          | Two plain adds sharing a `uuid` both append rather than one overwriting the other.                                              |
+| `valid/remove-relationship-by-uuid`              | An `op: "remove"` entry deletes the matching relationship.                                                                      |
+| `valid/tokens-sorted-order`                      | Multiple `tokens/*.tokens.json` files concatenate in sorted path order.                                                         |
+| `valid/later-file-wins`                          | Two `components/` fragments declaring the same component name dedupe to one, later file wins.                                   |
+| `valid/custom-extensions-dir`                    | The manifest's `extensionsDir` field is honored in place of the default `extensions/` name.                                     |
+| `valid/override-entry-skips-schema-validation`   | An `op: "override"` relationship entry is not schema-validated against `relationship.schema.json` (only plain adds are).        |
+| `valid/implementations-upsert-foundation-row`    | An `implementations/` row replaces the foundation default sharing its `importPath` and is stamped with the manifest `platform`. |
+| `valid/implementations-later-file-wins`          | Two fragments upserting the same stamped row dedupe by `implementation` id; the later file wins.                                |
+| `valid/implementations-remove-row`               | An `op: "remove"` selector deletes the matching foundation default.                                                             |
+| `valid/implementations-platform-local-component` | A fragment may target a component added by the same manifest's `components/`.                                                   |
+| `valid/implementations-other-owner-untouched`    | A row stamped with a different `implementation` id is never matched by another owner's upsert.                                  |
+| `invalid/override-missing-uuid`                  | An `op: "override"` relationship entry missing `uuid` fails loudly.                                                             |
+| `invalid/unknown-term-id`                        | A `platform-extensions/` fragment referencing a non-existent `termId` fails loudly.                                             |
+| `invalid/component-missing-name`                 | A `components/` fragment missing `name` fails Layer 1 fragment schema validation.                                               |
+| `invalid/field-invalid-kind`                     | A `fields/` fragment with an invalid `kind` enum value fails schema validation.                                                 |
+| `invalid/guideline-invalid-category`             | A `guidelines/` fragment with an invalid `category` enum value fails schema validation.                                         |
+| `invalid/mode-set-missing-default`               | A `mode-sets/` fragment missing the required `default` field fails Layer 1 fragment schema validation.                          |
+| `invalid/platform-extension-missing-extends`     | A `platform-extensions/` fragment missing `extends` fails schema validation.                                                    |
+| `invalid/token-invalid-uuid`                     | A `tokens/*.tokens.json` fragment with a malformed `uuid` fails schema validation.                                              |
+| `invalid/relationship-missing-scope`             | A `relationships/` plain-add fragment missing `scope` fails schema validation.                                                  |
+| `invalid/extensions-dir-parent-traversal`        | `extensionsDir` containing a `..` component is rejected.                                                                        |
+| `invalid/extensions-dir-absolute-path`           | An absolute `extensionsDir` path is rejected.                                                                                   |
+| `invalid/unknown-subdir-name`                    | An unrecognized subdirectory directly under `extensions/` (not one of the known categories) is rejected by name.                |
+| `invalid/implementations-unknown-component`      | An `implementations/` fragment naming a component absent from the catalog fails loudly.                                         |
+| `invalid/implementations-remove-no-match`        | An `op: "remove"` matching no owned row fails loudly.                                                                           |
+| `invalid/implementations-row-missing-reference`  | A row with neither `package` nor `importPath` fails schema validation.                                                          |
+| `invalid/implementations-unknown-op`             | An `op` other than `"remove"` fails schema validation.                                                                          |

package/conformance/manifest-extensions/base/dataset.json

@@ -2,21 +2,54 @@
   "tokens": [
     {
       "key": "btn-bg",
-      "name": { "property": "background-color", "component": "button" },
+      "name": {
+        "property": "background-color",
+        "component": "button"
+      },
       "value": "#aaa",
       "uuid": "u-btn-bg"
     },
     {
       "key": "btn-fg",
-      "name": { "property": "color", "component": "button" },
+      "name": {
+        "property": "color",
+        "component": "button"
+      },
       "value": "#111",
       "uuid": "u-btn-fg"
     },
     {
       "key": "chk-bg",
-      "name": { "property": "background-color", "component": "checkbox" },
+      "name": {
+        "property": "background-color",
+        "component": "checkbox"
+      },
       "value": "#bbb",
       "uuid": "u-chk-bg"
     }
+  ],
+  "components": [
+    {
+      "$id": "https://example.com/components/button",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://example.com"
+      },
+      "implementations": [
+        {
+          "platform": "web",
+          "componentName": "Button",
+          "package": "@react-spectrum/s2"
+        },
+        {
+          "platform": "web",
+          "componentName": "Button",
+          "importPath": "@adobe/spectrum-wc/components/button",
+          "notes": "Spectrum 2 web component custom element: swc-button."
+        }
+      ]
+    }
   ]
 }

package/conformance/manifest-extensions/invalid/implementations-remove-no-match/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "errors": [
+    {
+      "message_pattern": "matched no implementation row"
+    },
+    {
+      "message_pattern": "\"web-components\""
+    }
+  ]
+}

package/conformance/manifest-extensions/invalid/implementations-remove-no-match/extensions/implementations/button.json

@@ -0,0 +1,9 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "op": "remove",
+      "componentName": "Missing"
+    }
+  ]
+}

package/conformance/manifest-extensions/invalid/implementations-remove-no-match/manifest.json

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

package/conformance/manifest-extensions/invalid/implementations-row-missing-reference/expected-errors.json

@@ -0,0 +1,7 @@
+{
+  "errors": [
+    {
+      "message_pattern": "implementation-mapping.schema.json"
+    }
+  ]
+}

package/conformance/manifest-extensions/invalid/implementations-row-missing-reference/extensions/implementations/button.json

@@ -0,0 +1,9 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Button"
+    }
+  ]
+}

package/conformance/manifest-extensions/invalid/implementations-row-missing-reference/manifest.json

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

package/conformance/manifest-extensions/invalid/implementations-unknown-component/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "errors": [
+    {
+      "message_pattern": "\"nope\""
+    },
+    {
+      "message_pattern": "does not exist in the component catalog"
+    }
+  ]
+}

package/conformance/manifest-extensions/invalid/implementations-unknown-component/extensions/implementations/nope.json

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

package/conformance/manifest-extensions/invalid/implementations-unknown-component/manifest.json

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

package/conformance/manifest-extensions/invalid/implementations-unknown-op/expected-errors.json

@@ -0,0 +1,7 @@
+{
+  "errors": [
+    {
+      "message_pattern": "implementation-mapping.schema.json"
+    }
+  ]
+}

package/conformance/manifest-extensions/invalid/implementations-unknown-op/extensions/implementations/button.json

@@ -0,0 +1,9 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "op": "replace",
+      "componentName": "Button"
+    }
+  ]
+}

package/conformance/manifest-extensions/invalid/implementations-unknown-op/manifest.json

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

package/conformance/manifest-extensions/valid/implementations-later-file-wins/expected.json

@@ -0,0 +1,19 @@
+{
+  "implementations": {
+    "button": [
+      {
+        "platform": "web",
+        "componentName": "Button",
+        "package": "@react-spectrum/s2",
+        "notes": "second",
+        "implementation": "react-spectrum"
+      },
+      {
+        "platform": "web",
+        "componentName": "Button",
+        "importPath": "@adobe/spectrum-wc/components/button",
+        "notes": "Spectrum 2 web component custom element: swc-button."
+      }
+    ]
+  }
+}

package/conformance/manifest-extensions/valid/implementations-later-file-wins/extensions/implementations/a-button.json

@@ -0,0 +1,11 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "package": "@react-spectrum/s2",
+      "notes": "first"
+    }
+  ]
+}

package/conformance/manifest-extensions/valid/implementations-later-file-wins/extensions/implementations/b-button.json

@@ -0,0 +1,11 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "package": "@react-spectrum/s2",
+      "notes": "second"
+    }
+  ]
+}

package/conformance/manifest-extensions/valid/implementations-later-file-wins/manifest.json

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

package/conformance/manifest-extensions/valid/implementations-other-owner-untouched/expected.json

@@ -0,0 +1,26 @@
+{
+  "implementations": {
+    "button": [
+      {
+        "platform": "web",
+        "componentName": "Button",
+        "package": "@react-spectrum/s2",
+        "implementation": "react-spectrum",
+        "notes": "declared by another owner"
+      },
+      {
+        "platform": "web",
+        "componentName": "Button",
+        "importPath": "@adobe/spectrum-wc/components/button",
+        "notes": "Spectrum 2 web component custom element: swc-button."
+      },
+      {
+        "platform": "web",
+        "componentName": "Button",
+        "package": "@react-spectrum/s2",
+        "implementation": "web-components",
+        "notes": "web-components row with the same package"
+      }
+    ]
+  }
+}

package/conformance/manifest-extensions/valid/implementations-other-owner-untouched/extensions/implementations/button.json

@@ -0,0 +1,18 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "package": "@react-spectrum/s2",
+      "implementation": "react-spectrum",
+      "notes": "declared by another owner"
+    },
+    {
+      "platform": "web",
+      "componentName": "Button",
+      "package": "@react-spectrum/s2",
+      "notes": "web-components row with the same package"
+    }
+  ]
+}

package/conformance/manifest-extensions/valid/implementations-other-owner-untouched/manifest.json

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

package/conformance/manifest-extensions/valid/implementations-platform-local-component/expected.json

@@ -0,0 +1,12 @@
+{
+  "implementations": {
+    "tab-bar-ios": [
+      {
+        "platform": "ios",
+        "componentName": "SpectrumTabBar",
+        "package": "SpectrumUI",
+        "implementation": "ios"
+      }
+    ]
+  }
+}

package/conformance/manifest-extensions/valid/implementations-platform-local-component/extensions/components/tab-bar-ios.json

@@ -0,0 +1,9 @@
+{
+  "$id": "https://example.com/components/tab-bar-ios",
+  "name": "tab-bar-ios",
+  "displayName": "Tab Bar (iOS)",
+  "meta": {
+    "category": "navigation",
+    "documentationUrl": "https://example.com"
+  }
+}

package/conformance/manifest-extensions/valid/implementations-platform-local-component/extensions/implementations/tab-bar-ios.json

@@ -0,0 +1,10 @@
+{
+  "component": "tab-bar-ios",
+  "implementations": [
+    {
+      "platform": "ios",
+      "componentName": "SpectrumTabBar",
+      "package": "SpectrumUI"
+    }
+  ]
+}

package/conformance/manifest-extensions/valid/implementations-platform-local-component/manifest.json

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

package/conformance/manifest-extensions/valid/implementations-remove-row/expected.json

@@ -0,0 +1,11 @@
+{
+  "implementations": {
+    "button": [
+      {
+        "platform": "web",
+        "componentName": "Button",
+        "package": "@react-spectrum/s2"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,10 @@
+{
+  "component": "button",
+  "implementations": [
+    {
+      "op": "remove",
+      "componentName": "Button",
+      "importPath": "@adobe/spectrum-wc/components/button"
+    }
+  ]
+}

package/conformance/manifest-extensions/valid/implementations-remove-row/manifest.json

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

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

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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "4.4.0",
+  "version": "4.5.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",

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