feat: taxonomy registry split, schema update, and SPEC-009 validation

.changeset/taxonomy-registry-split.md

@@ -0,0 +1,14 @@
+---
+"@adobe/design-system-registry": minor
+"@adobe/design-data-spec": minor
+---
+
+Add taxonomy registries and expand token name object schema.
+
+- Split `anatomy-terms.json`: removed styling surfaces and positional terms
+- Added `token-objects.json` (background, border, edge, visual, content)
+- Added 6 new taxonomy registries:
+  structures, substructures, orientations, positions, densities, shapes
+- Exported all 7 new registries from package index
+- Added all 13 semantic fields explicitly to `nameObject` in
+  `token.schema.json`, distinguishing semantic from dimension fields

packages/design-data-spec/schemas/token.schema.json

@@ -15,30 +15,73 @@
   "$defs": {
     "nameObject": {
       "type": "object",
-      "description": "Structured token identity; additional dimension keys MUST be strings.",
+      "description": "Structured token identity. Semantic fields describe identity and structure; dimension fields drive cascade resolution. See spec/taxonomy.md and spec/token-format.md. Additional dimension keys MUST be strings.",
       "required": ["property"],
       "properties": {
         "property": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "Semantic: the stylistic attribute being defined (e.g. color, width, padding, gap)."
         },
         "component": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: component scope (e.g. button, checkbox)."
+        },
+        "structure": {
+          "type": "string",
+          "description": "Semantic: reusable visual pattern (e.g. base, container, list). Distinct from component."
+        },
+        "substructure": {
+          "type": "string",
+          "description": "Semantic: child within a parent structure (e.g. item in list-item)."
+        },
+        "anatomy": {
+          "type": "string",
+          "description": "Semantic: visible named part of a component (e.g. handle, icon, label)."
+        },
+        "object": {
+          "type": "string",
+          "description": "Semantic: styling surface (e.g. background, border, edge, visual)."
         },
         "variant": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: variant within a component (e.g. accent, negative, primary)."
         },
         "state": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: interactive or semantic state (e.g. hover, focus, disabled)."
+        },
+        "orientation": {
+          "type": "string",
+          "description": "Semantic: direction or order (e.g. vertical, horizontal)."
+        },
+        "position": {
+          "type": "string",
+          "description": "Semantic: location relative to another object (e.g. affixed, top, bottom)."
+        },
+        "size": {
+          "type": "string",
+          "description": "Semantic: relative t-shirt sizing (e.g. small, medium, large). Distinct from dimension scale."
+        },
+        "density": {
+          "type": "string",
+          "description": "Semantic: space within or around component parts (e.g. spacious, compact)."
+        },
+        "shape": {
+          "type": "string",
+          "description": "Semantic: overall component shape (e.g. uniform)."
         },
         "colorScheme": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: color scheme mode (e.g. light, dark, wireframe)."
         },
         "scale": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: platform density scale (e.g. desktop, mobile)."
         },
         "contrast": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: contrast level (e.g. regular, high)."
         }
       },
       "additionalProperties": {
@@ -98,7 +141,11 @@
         "replaced_by": {
           "oneOf": [
             { "type": "string", "format": "uuid" },
-            { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }
+            {
+              "type": "array",
+              "items": { "type": "string", "format": "uuid" },
+              "minItems": 1
+            }
           ],
           "description": "UUID(s) of the replacement token(s). Array form requires deprecated_comment."
         },
@@ -151,7 +198,11 @@
         "replaced_by": {
           "oneOf": [
             { "type": "string", "format": "uuid" },
-            { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }
+            {
+              "type": "array",
+              "items": { "type": "string", "format": "uuid" },
+              "minItems": 1
+            }
           ],
           "description": "UUID(s) of the replacement token(s). Array form requires deprecated_comment."
         },

packages/design-system-registry/index.js

@@ -62,6 +62,34 @@ export const glossary = JSON.parse(
   readFileSync(join(__dirname, "registry", "glossary.json"), "utf-8"),
 );
 
+export const tokenObjects = JSON.parse(
+  readFileSync(join(__dirname, "registry", "token-objects.json"), "utf-8"),
+);
+
+export const structures = JSON.parse(
+  readFileSync(join(__dirname, "registry", "structures.json"), "utf-8"),
+);
+
+export const substructures = JSON.parse(
+  readFileSync(join(__dirname, "registry", "substructures.json"), "utf-8"),
+);
+
+export const orientations = JSON.parse(
+  readFileSync(join(__dirname, "registry", "orientations.json"), "utf-8"),
+);
+
+export const positions = JSON.parse(
+  readFileSync(join(__dirname, "registry", "positions.json"), "utf-8"),
+);
+
+export const densities = JSON.parse(
+  readFileSync(join(__dirname, "registry", "densities.json"), "utf-8"),
+);
+
+export const shapes = JSON.parse(
+  readFileSync(join(__dirname, "registry", "shapes.json"), "utf-8"),
+);
+
 /**
  * Get all values from a registry by ID
  * @param {object} registry - The registry object

packages/design-system-registry/package.json

@@ -13,7 +13,14 @@
     "./registry/components.json": "./registry/components.json",
     "./registry/scale-values.json": "./registry/scale-values.json",
     "./registry/categories.json": "./registry/categories.json",
-    "./registry/platforms.json": "./registry/platforms.json"
+    "./registry/platforms.json": "./registry/platforms.json",
+    "./registry/token-objects.json": "./registry/token-objects.json",
+    "./registry/structures.json": "./registry/structures.json",
+    "./registry/substructures.json": "./registry/substructures.json",
+    "./registry/orientations.json": "./registry/orientations.json",
+    "./registry/positions.json": "./registry/positions.json",
+    "./registry/densities.json": "./registry/densities.json",
+    "./registry/shapes.json": "./registry/shapes.json"
   },
   "scripts": {
     "validate": "node scripts/validate-registry.js",

packages/design-system-registry/registry/anatomy-terms.json

@@ -1,20 +1,8 @@
 {
   "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
   "type": "anatomy-term",
-  "description": "Anatomical part names used in design tokens and component structures",
+  "description": "Visible, named parts of components as defined by designers. These are the parts called out in component specification diagrams. Styling surfaces (background, border, etc.) belong in token-objects.json; positional terms (top, bottom, etc.) belong in positions.json.",
   "values": [
-    {
-      "id": "edge",
-      "label": "Edge",
-      "description": "The outer boundary or border of a component",
-      "usedIn": ["tokens"]
-    },
-    {
-      "id": "visual",
-      "label": "Visual",
-      "description": "Visual elements like icons, images, or decorative elements",
-      "usedIn": ["tokens"]
-    },
     {
       "id": "text",
       "label": "Text",
@@ -27,18 +15,6 @@
       "description": "Interactive control elements like checkboxes or radio buttons",
       "usedIn": ["tokens"]
     },
-    {
-      "id": "border",
-      "label": "Border",
-      "description": "Border or outline of a component",
-      "usedIn": ["tokens"]
-    },
-    {
-      "id": "background",
-      "label": "Background",
-      "description": "Background surface or fill",
-      "usedIn": ["tokens"]
-    },
     {
       "id": "icon",
       "label": "Icon",
@@ -51,36 +27,6 @@
       "description": "Text labels",
       "usedIn": ["tokens", "component-schemas"]
     },
-    {
-      "id": "content",
-      "label": "Content",
-      "description": "Main content area",
-      "usedIn": ["tokens"]
-    },
-    {
-      "id": "top",
-      "label": "Top",
-      "description": "Top edge or boundary",
-      "usedIn": ["tokens"]
-    },
-    {
-      "id": "bottom",
-      "label": "Bottom",
-      "description": "Bottom edge or boundary",
-      "usedIn": ["tokens"]
-    },
-    {
-      "id": "start",
-      "label": "Start",
-      "description": "Start edge (left in LTR, right in RTL)",
-      "usedIn": ["tokens"]
-    },
-    {
-      "id": "end",
-      "label": "End",
-      "description": "End edge (right in LTR, left in RTL)",
-      "usedIn": ["tokens"]
-    },
     {
       "id": "body",
       "label": "Body",

packages/design-system-registry/registry/densities.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "type": "density",
+  "description": "Options that create more or less space within or around the parts of a component.",
+  "values": [
+    {
+      "id": "spacious",
+      "label": "Spacious",
+      "description": "More space within and around component parts"
+    },
+    {
+      "id": "compact",
+      "label": "Compact",
+      "description": "Less space within and around component parts"
+    }
+  ]
+}

packages/design-system-registry/registry/orientations.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "type": "orientation",
+  "description": "Direction or order of structures and elements within a component or pattern.",
+  "values": [
+    {
+      "id": "vertical",
+      "label": "Vertical",
+      "description": "Top-to-bottom direction"
+    },
+    {
+      "id": "horizontal",
+      "label": "Horizontal",
+      "description": "Left-to-right (or right-to-left) direction"
+    }
+  ]
+}

packages/design-system-registry/registry/positions.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "type": "position",
+  "description": "Location of an object relative to another, with or without respect to directional order.",
+  "values": [
+    {
+      "id": "affixed",
+      "label": "Affixed",
+      "description": "Attached to another element in a fixed position"
+    },
+    {
+      "id": "top",
+      "label": "Top",
+      "description": "Top position relative to a reference element"
+    },
+    {
+      "id": "bottom",
+      "label": "Bottom",
+      "description": "Bottom position relative to a reference element"
+    },
+    {
+      "id": "start",
+      "label": "Start",
+      "description": "Start position (left in LTR, right in RTL)"
+    },
+    {
+      "id": "end",
+      "label": "End",
+      "description": "End position (right in LTR, left in RTL)"
+    }
+  ]
+}

packages/design-system-registry/registry/shapes.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "type": "shape",
+  "description": "Terms relative to the overall shape of a component. This is a starting vocabulary — new shape terms should be added here as design system patterns are identified.",
+  "values": [
+    {
+      "id": "uniform",
+      "label": "Uniform",
+      "description": "Equal proportions (e.g., 1:1 ratio between horizontal and vertical padding)"
+    }
+  ]
+}

packages/design-system-registry/registry/structures.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "type": "structure",
+  "description": "Reusable visual patterns or object categories that occur across many varieties of components. Distinct from components, which are specific UI elements.",
+  "values": [
+    {
+      "id": "base",
+      "label": "Base",
+      "description": "Foundation structure shared across components"
+    },
+    {
+      "id": "container",
+      "label": "Container",
+      "description": "Enclosing structure that holds child elements"
+    },
+    {
+      "id": "list",
+      "label": "List",
+      "description": "Ordered or unordered collection of items"
+    },
+    {
+      "id": "accessory",
+      "label": "Accessory",
+      "description": "Supplementary element attached to a primary structure"
+    }
+  ]
+}

packages/design-system-registry/registry/substructures.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "type": "substructure",
+  "description": "Structures that only exist within the context of a parent structure (e.g., item within a list).",
+  "values": [
+    {
+      "id": "item",
+      "label": "Item",
+      "description": "Individual element within a parent structure (e.g., list item)"
+    }
+  ]
+}