@adobe/design-data-spec 3.4.1 → 4.0.0

package/conformance/manifest-extensions/valid/plain-add-uuid-collision-append/extensions/relationships/slider.json

@@ -0,0 +1,5 @@
+{
+  "scope": { "component": "slider", "property": "corner-radius" },
+  "value": "2px",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/plain-add-uuid-collision-append/manifest.json

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

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/expected.json

@@ -0,0 +1 @@
+{ "relationships": { "absent": ["9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"] } }

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/extensions/relationships/button.json

@@ -0,0 +1,5 @@
+{
+  "scope": { "component": "button", "property": "corner-radius" },
+  "value": "4px",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/extensions/relationships/remove-button.json

@@ -0,0 +1,4 @@
+{
+  "op": "remove",
+  "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f1a"
+}

package/conformance/manifest-extensions/valid/remove-relationship-by-uuid/manifest.json

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

package/conformance/manifest-extensions/valid/tokens-sorted-order/expected.json

@@ -0,0 +1,8 @@
+{
+  "tokens": {
+    "orderByUuid": [
+      "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f01",
+      "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f02"
+    ]
+  }
+}

package/conformance/manifest-extensions/valid/tokens-sorted-order/extensions/tokens/a.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "elevation", "component": "card" },
+    "value": "4dp",
+    "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f01"
+  }
+]

package/conformance/manifest-extensions/valid/tokens-sorted-order/extensions/tokens/b.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "elevation", "component": "sheet" },
+    "value": "8dp",
+    "uuid": "9c858f9c-1d90-4f1a-8c1a-1f1a1f1a1f02"
+  }
+]

package/conformance/manifest-extensions/valid/tokens-sorted-order/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "3.4.1",
+  "version": "4.0.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
   "type": "module",
   "repository": {

package/rules/rules.yaml

@@ -690,3 +690,20 @@ rules:
     message: "Relationship '{relationship}' may need a legacyKey to round-trip through the legacy generator"
     spec_ref: spec/relationship-format.md#legacy-fields-interim
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-058
+    name: ctr-ref-not-deprecated
+    severity: warning
+    layer: 2
+    category: naming-consistency
+    note: >
+      Warning, not error: some deprecated targets have no `replacedBy` (or an ambiguous
+      array-form one) and can't be auto-corrected without manual triage, so this can't be
+      a hard gate yet.
+    assert: >
+      A relationship-only CTR's `$ref` (no `uuid`/`legacyKey`) SHOULD NOT resolve to a
+      token whose `lifecycle.deprecatedIn` is set. A value-owning CTR (`uuid`/`legacyKey`
+      present) is exempt — it legitimately *is* the deprecated token record.
+    message: "Relationship $ref {ref} resolves to a token deprecated in {deprecatedIn}"
+    spec_ref: spec/relationship-format.md#legacy-fields-interim
+    introduced_in: "1.0.0-draft"

package/schemas/manifest.schema.json

@@ -83,122 +83,64 @@
         "additionalProperties": false
       }
     },
-    "extensions": {
+    "extensionsDir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path (relative to the manifest) to the platform's extensions directory, holding platform-local tokens/components/fields/relationships/guidelines/platform-extensions as one file per artifact (see spec/manifest.md#extensions-directory). Default: \"extensions\"."
+    },
+    "namingExceptions": {
       "type": "object",
-      "description": "Platform-local tokens, mode sets, and formatting rules.",
+      "description": "Platform-local overlay on the base naming-exceptions set: names to add and/or remove for this platform's naming validation.",
       "properties": {
-        "tokens": {
-          "$ref": "cascade-file.schema.json",
-          "description": "Platform-local token definitions, in cascade-format (same shape as a cascade token file)."
-        },
-        "components": {
+        "add": {
           "type": "array",
-          "items": { "$ref": "component.schema.json" },
-          "description": "Platform-local component specs, injected into the component catalog (add-or-replace by name)."
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Token names to add to the naming-exceptions set for this platform."
         },
-        "fields": {
+        "remove": {
           "type": "array",
-          "items": { "$ref": "field.schema.json" },
-          "description": "Platform-local field declarations, injected into the field catalog (add-or-replace by name)."
-        },
-        "relationships": {
-          "type": "array",
-          "items": {
-            "oneOf": [
-              { "$ref": "relationship.schema.json#/$defs/relationship" },
-              {
-                "type": "object",
-                "required": ["op", "uuid", "value"],
-                "properties": {
-                  "op": { "const": "override" },
-                  "uuid": { "type": "string", "format": "uuid" },
-                  "value": {
-                    "$ref": "relationship.schema.json#/$defs/relationship"
-                  }
-                },
-                "additionalProperties": false
-              },
-              {
-                "type": "object",
-                "required": ["op", "uuid"],
-                "properties": {
-                  "op": { "const": "remove" },
-                  "uuid": { "type": "string", "format": "uuid" }
-                },
-                "additionalProperties": false
-              }
-            ]
-          },
-          "description": "Platform-local Component/Token Relationship (CTR) add/override/remove. Entries without \"op\" are added positionally; \"override\"/\"remove\" require a \"uuid\" to target an existing relationship."
-        },
-        "platformExtensions": {
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Token names to remove from the base naming-exceptions set for this platform."
+        }
+      },
+      "additionalProperties": false
+    },
+    "formatting": {
+      "type": "object",
+      "description": "Rules for serializing structured name objects into platform-specific token name strings.",
+      "properties": {
+        "conceptOrder": {
           "type": "array",
           "items": {
-            "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/platform-extension.json"
+            "type": "string"
           },
-          "description": "Platform-local terminology extensions (e.g. iOS state vocabulary), annotating ids in an existing base registry."
+          "uniqueItems": true,
+          "description": "Ordered list of field names for serialization. Values must match declared field names from the design system's field catalog (field.schema.json declarations). Replaces the default serialization.position order from each field declaration."
         },
-        "guidelines": {
-          "type": "array",
-          "items": { "$ref": "guideline.schema.json" },
-          "description": "Platform-local guideline docs, injected into the guideline catalog (add-or-replace by name)."
+        "casing": {
+          "type": "string",
+          "enum": [
+            "kebab-case",
+            "camelCase",
+            "PascalCase",
+            "SCREAMING_SNAKE_CASE"
+          ],
+          "description": "Casing style for serialized token names. Default: kebab-case."
         },
-        "namingExceptions": {
-          "type": "object",
-          "description": "Platform-local overlay on the base naming-exceptions set: names to add and/or remove for this platform's naming validation.",
-          "properties": {
-            "add": {
-              "type": "array",
-              "items": { "type": "string", "minLength": 1 },
-              "description": "Token names to add to the naming-exceptions set for this platform."
-            },
-            "remove": {
-              "type": "array",
-              "items": { "type": "string", "minLength": 1 },
-              "description": "Token names to remove from the base naming-exceptions set for this platform."
-            }
-          },
-          "additionalProperties": false
+        "delimiter": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Character(s) separating concepts in the serialized string. Default: -."
         },
-        "formatting": {
+        "abbreviations": {
           "type": "object",
-          "description": "Rules for serializing structured name objects into platform-specific token name strings.",
-          "properties": {
-            "conceptOrder": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "uniqueItems": true,
-              "description": "Ordered list of field names for serialization. Values must match declared field names from the design system's field catalog (field.schema.json declarations). Replaces the default serialization.position order from each field declaration."
-            },
-            "casing": {
-              "type": "string",
-              "enum": [
-                "kebab-case",
-                "camelCase",
-                "PascalCase",
-                "SCREAMING_SNAKE_CASE"
-              ],
-              "description": "Casing style for serialized token names. Default: kebab-case."
-            },
-            "delimiter": {
-              "type": "string",
-              "minLength": 1,
-              "description": "Character(s) separating concepts in the serialized string. Default: -."
-            },
-            "abbreviations": {
-              "type": "object",
-              "additionalProperties": {
-                "type": "string"
-              },
-              "description": "Map of full term to abbreviated form, applied after ordering and before casing."
-            }
+          "additionalProperties": {
+            "type": "string"
           },
-          "additionalProperties": false
+          "description": "Map of full term to abbreviated form, applied after ordering and before casing."
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/spec/manifest-schema-override-spike.md

@@ -24,9 +24,12 @@ schemas for its own data?
 3. **No concrete need surfaced.** Nothing in the h890.22/h890.23 work (iOS
    externalization, or the guidelines/fields/relationships/naming-exceptions cascade
    additions) needed schema relaxation — every platform-local addition validates fine
-   against the existing schemas via `extensions.*`. The `extensions` object is already
-   `additionalProperties: true`, which covers "the platform wants to attach data the
-   schema doesn't know about" without touching the schema itself.
+   against the existing per-artifact schemas via the `extensions/` directory (see
+   [Manifest — `extensions/` directory](manifest.md#extensions-directory)). Each fragment
+   file there is checked against the same `component.schema.json` /
+   `field.schema.json` / `guideline.schema.json` / etc. as the foundation dataset, which
+   already covers "the platform wants to attach data the schema knows how to validate"
+   without touching the schema itself.
 
 ## Decision
 

package/spec/manifest.md

@@ -8,23 +8,23 @@ 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            |
-| Add relationships/CTRs; override/remove by `uuid`  | Yes                                                          | `extensions.relationships`      | Relationships (CTRs)  |
-| Add / remove naming exceptions                     | Yes                                                          | `extensions.namingExceptions`   | Naming validation     |
-| Annotate existing terminology (cannot add new ids) | Yes                                                          | `extensions.platformExtensions` | 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   | `extensions.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            |
+| 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)) | —                                 | —                     |
 
 ## Manifest document
 
@@ -39,13 +39,15 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
 
 ## Optional fields
 
-| Field                 | Type            | Description                                                                                                                                                                                                       |
-| --------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `include`             | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize.                                                                                                                                       |
-| `exclude`             | array of string | Queries removing tokens from the included set.                                                                                                                                                                    |
-| `overrides`           | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**.                                                                                                                                  |
-| `extensions`          | object          | Platform-local additions layered on top of foundation — `tokens`, `components`, `fields`, `guidelines`, `relationships`, `namingExceptions`, `platformExtensions`, `formatting` (see `extensions` section below). |
-| `modeSetRestrictions` | object          | Mode set restrictions for this platform; see [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions).                                                                                             |
+| Field                 | Type            | Description                                                                                                                                                     |
+| --------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `include`             | array of string | Semantic **queries** selecting subsets of foundation tokens to materialize.                                                                                     |
+| `exclude`             | array of string | Queries removing tokens from the included set.                                                                                                                  |
+| `overrides`           | array of object | Typed overrides; each entry **MUST** preserve the target token’s **value type**.                                                                                |
+| `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.                                                                        |
+| `modeSetRestrictions` | object          | Mode set restrictions for this platform; see [Mode Sets — Platform restrictions](mode-sets.md#platform-restrictions).                                           |
 
 ### `include` / `exclude`
 
@@ -71,41 +73,85 @@ apply `Foundation < Platform < Product` precedence to select a single winner. To
 counts "tokens a platform ships" from `query` output should resolve first, or it will
 double-count overridden tokens.
 
-### `extensions`
-
-**RECOMMENDED:** `extensions` follows the same structural conventions as foundation token files (tokens, mode sets) and **SHOULD** be validated with the same Layer 1 and Layer 2 rules.
-
-#### `extensions.tokens`
-
-Platform-local token definitions, in cascade-file format. Inserted at the platform layer alongside (not replacing) foundation tokens; entries **MAY** carry a `$ref` to alias an existing token instead of a literal value.
-
-#### `extensions.components`
-
-Platform-local component specs, injected into the component catalog. **NORMATIVE:** the reference SDK applies these add-or-replace by component `name` at the platform layer.
-
-#### `extensions.fields`
-
-Platform-local field declarations, injected into the field catalog. **NORMATIVE:** the reference SDK applies these add-or-replace by field `name` at the platform layer; each entry **MUST** validate against `field.schema.json`. Note: `extensions.formatting.conceptOrder` (if declared) references field names by string — a platform that renames or removes a field it also references there is self-inconsistent; that is a manifest-authoring concern, not enforced by the reference SDK.
-
-#### `extensions.guidelines`
-
-Platform-local guideline documents, injected into the guideline catalog. **NORMATIVE:** the reference SDK applies these add-or-replace by guideline `name` at the platform layer; each entry **MUST** validate against `guideline.schema.json`.
-
-#### `extensions.relationships`
-
-Platform-local Component/Token Relationship (CTR) entries. Relationships have no inherent
-stable key — only an optional `uuid` — so add and override/remove use different identity
-rules:
-
-* **Add:** an entry with no `op` field is a full relationship object (validated against
-  `relationship.schema.json`), appended at the platform layer.
-* **Override / remove:** relationships have no other stable identity, so targeting one
-  **MUST** carry a `uuid`. **NORMATIVE:** an `extensions.relationships` entry with `"op":
-  "override"` or `"op": "remove"` that omits `uuid` is a manifest error — the reference SDK
-  rejects it rather than silently skipping it. `"op": "override"` also carries a `value` (the
-  replacement relationship object); `"op": "remove"` drops the matching record.
-
-#### `extensions.namingExceptions`
+### `extensions/` directory
+
+**NORMATIVE:** Platform-local additions are declared as a sibling **directory** next to
+`manifest.json` (default name `extensions/`; override with the top-level `extensionsDir`
+field), not as an inline object in the manifest. This mirrors how the foundation dataset
+(`packages/design-data/`) splits its own catalogs into one file per artifact, and lets a
+platform's extension set grow without every addition colliding in one JSON object.
+
+```
+extensions/
+  tokens/               *.tokens.json          cascade-format token files
+  components/           <component>.json       one component per file
+  fields/                <field>.json          one field declaration per file
+  relationships/         <component>.json      one CTR set per file
+  guidelines/             <topic>.json         one guideline per file
+  platform-extensions/   <platform>-<registry>.json
+```
+
+**NORMATIVE:** Each subdirectory is discovered by a recursive glob for `*.json` files (for
+`tokens/`, `**/*.tokens.json`), with no index file — the same convention used by
+`discover_json_files` in `sdk/core/src/discovery.rs` for the foundation dataset. Matched files
+are processed in **sorted path order**; this is the sole basis for precedence below. A missing
+or empty subdirectory contributes nothing and is not an error.
+
+**NORMATIVE:** Merge semantics by subdirectory:
+
+* **`tokens/`** — every `*.tokens.json` file is cascade-format (same shape as a foundation
+  cascade token file) and **MUST** validate against `cascade-file.schema.json`. Files are
+  **deep-merged** into one tokens object, in sorted path order. Entries **MAY** carry a `$ref`
+  to alias an existing token instead of a literal value.
+* **`components/`, `fields/`, `guidelines/`, `platform-extensions/`** — one artifact per file.
+  Entries across all files in the subdirectory are concatenated, in sorted path order, and
+  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.**
+
+**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:
+
+* **`components/`** → `component.schema.json`
+* **`fields/`** → `field.schema.json` (see [`extensions/fields/`](#extensionsfields) below)
+* **`guidelines/`** → `guideline.schema.json`
+* **`relationships/`** → `relationship.schema.json` (see the Add/Override/remove rules above)
+* **`platform-extensions/`** → `platform-extension.json` (see
+  [`extensions/platform-extensions/`](#extensionsplatform-extensions) below)
+* **`tokens/`** → `cascade-file.schema.json` (see above)
+
+A fragment that fails validation against its category schema is a manifest error — the
+reference SDK rejects the load rather than silently skipping the malformed file.
+
+* **`relationships/`** — Component/Token Relationship (CTR) entries. Relationships have no
+  inherent stable key — only an optional `uuid` — so add and override/remove use different
+  identity rules:
+  * **Add:** an entry with no `op` field is a full relationship object (validated against
+    `relationship.schema.json`), appended at the platform layer, in sorted path order.
+  * **Override / remove:** targeting an existing relationship **MUST** carry a `uuid`.
+    **NORMATIVE:** an entry with `"op": "override"` or `"op": "remove"` that omits `uuid` is a
+    manifest error — the reference SDK rejects it rather than silently skipping it. `"op":
+    "override"` also carries a `value` (the replacement relationship object); `"op": "remove"`
+    drops the matching record. Override/remove ops apply, in sorted path order, against the
+    accumulated set of added relationships (across all files, foundation and platform-local).
+
+#### `extensions/fields/`
+
+Platform-local field declarations, injected into the field catalog. **NORMATIVE:** each file
+**MUST** validate against `field.schema.json`. Note: a top-level `formatting.conceptOrder` (if
+declared) references field names by string — a platform that renames or removes a field it
+also references there is self-inconsistent; that is a manifest-authoring concern, not enforced
+by the reference SDK.
+
+#### `extensions/platform-extensions/`
+
+Platform terminology annotations layered onto **existing** foundation registry entries (for
+example, platform-specific state names). **NORMATIVE:** each file **MUST** validate against
+`platform-extension.json`, and every `termId` **MUST** already exist in the referenced
+foundation registry — this mechanism annotates existing ids, it does **NOT** introduce new
+ones.
+
+### `namingExceptions`
 
 Platform-local overlay on the base naming-exceptions set used by naming validation.
 **NORMATIVE:** the reference SDK applies `remove` before `add`, so a name listed in both
@@ -117,11 +163,7 @@ ends up present (add wins) rather than silently dropped. Absent this key, the ba
 | `add`    | array of string | Names to add to the naming-exceptions set for this platform. |
 | `remove` | array of string | Names to remove from the base naming-exceptions set.         |
 
-#### `extensions.platformExtensions`
-
-Platform terminology annotations layered onto **existing** foundation registry entries (for example, platform-specific state names). **NORMATIVE:** every `termId` **MUST** already exist in the referenced foundation registry — this mechanism annotates existing ids, it does **NOT** introduce new ones.
-
-#### `extensions.formatting`
+### `formatting`
 
 A platform **MAY** declare formatting rules that control how structured name objects are serialized into flat token name strings for that platform. See [Taxonomy — Platform formatting configuration](taxonomy.md#platform-formatting-configuration) for motivation and examples.
 
@@ -132,9 +174,9 @@ A platform **MAY** declare formatting rules that control how structured name obj
 | `delimiter`     | string          | Character(s) separating concepts in the serialized string (e.g. `-`, `_`, `.`, `/`). Default: `-`.                                                                                                                                                                                                                                                                                                                                     |
 | `abbreviations` | object          | Map of full term → abbreviated form (e.g. `{ "background": "bg" }`). Abbreviations are applied after concept ordering and before casing.                                                                                                                                                                                                                                                                                               |
 
-**NORMATIVE:** When `extensions.formatting` is absent, the default serialization defined in [Taxonomy](taxonomy.md#default-serialization-legacy-format) is used.
+**NORMATIVE:** When `formatting` is absent, the default serialization defined in [Taxonomy](taxonomy.md#default-serialization-legacy-format) is used.
 
-**NORMATIVE:** A formatter applying `extensions.formatting` **MUST** produce deterministic output — the same name object and formatting configuration **MUST** always yield the same string.
+**NORMATIVE:** A formatter applying `formatting` **MUST** produce deterministic output — the same name object and formatting configuration **MUST** always yield the same string.
 
 ## Validation
 

package/spec/mode-sets.md

@@ -27,11 +27,11 @@ A **mode set declaration** is a JSON object describing one axis of variation. It
 
 These mode sets are declared in the `mode-sets/` catalog (see [Mode Set catalog](#mode-set-catalog)) and **SHOULD** be used consistently across Spectrum-compatible datasets:
 
-| `name`        | `modes`                      | `default` | Notes                                                                             |
-| ------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------- |
-| `colorScheme` | `light`, `dark`, `wireframe` | `light`   | Theme / appearance.                                                               |
-| `scale`       | `desktop`, `mobile`          | `desktop` | Density scale. Legacy names; desktop = medium, mobile = large in W3C terminology. |
-| `contrast`    | `regular`, `high`            | `regular` | Accessibility contrast level.                                                     |
+| `name`        | `modes`                      | `default` | Notes                                                                                                                                                        |
+| ------------- | ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `colorScheme` | `light`, `dark`, `wireframe` | `light`   | Theme / appearance.                                                                                                                                          |
+| `scale`       | `desktop`, `mobile`          | `desktop` | Density scale. Legacy names; desktop = medium, mobile = large in W3C terminology.                                                                            |
+| `contrast`    | `regular`, `high`            | `regular` | Accessibility contrast level. iOS platform data authors `increased` as a synonym for `high` — treat the two as the same crosswalk term, not distinct values. |
 
 ## Mode Set catalog
 

package/spec/taxonomy.md

@@ -282,7 +282,7 @@ This ordering is preserved for backward compatibility with the current `@adobe/s
 
 ## Platform formatting configuration
 
-A platform [manifest](manifest.md) **MAY** declare formatting rules in its [`extensions.formatting`](manifest.md#extensionsformatting) section to control concept ordering, casing, delimiters, and abbreviations. The normative contract for these fields is defined in [Manifest — `extensions.formatting`](manifest.md#extensionsformatting).
+A platform [manifest](manifest.md) **MAY** declare formatting rules in its top-level [`formatting`](manifest.md#formatting) field to control concept ordering, casing, delimiters, and abbreviations. The normative contract for these fields is defined in [Manifest — `formatting`](manifest.md#formatting).
 
 When no platform formatting is declared, the default serialization above is used.
 
@@ -338,5 +338,5 @@ node tools/token-corpus-migrate/src/cli.js \
 * [#806 — Token Taxonomy, Vocabulary, and Formatting](https://github.com/adobe/spectrum-design-data/discussions/806)
 * [#661 — Spectrum Design System Glossary](https://github.com/adobe/spectrum-design-data/discussions/661)
 * [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
-* [Manifest — `extensions.formatting`](manifest.md#extensionsformatting) — normative contract for platform formatting rules
+* [Manifest — `formatting`](manifest.md#formatting) — normative contract for platform formatting rules
 * Nate Baldwin, "Naming conventions & shared taxonomy" — Design Data & Platforms onsite, April 1, 2026