@adia-ai/a2ui 0.8.41 → 0.8.42

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog — @adia-ai/a2ui
 
+## [0.8.42] — 2026-08-17
+
+### Maintenance
+- Catalog artifacts re-derived for the ADR-0063 compat-shim surface and rename-wave W2 names (PRs #1567/#1568/#1569, ADR-0069 Class-R resync). No protocol/runtime API change.
+
+
 > Formerly `@adia-ai/a2ui-runtime`; renamed at ADR-0048 P3. Entries below
 > 0.8.37 (the estate-split cut) were released under the old name and are kept
 > verbatim.

package/catalog/catalog-a2ui_0_9.json

@@ -416,7 +416,7 @@
     },
     "ActionItem": {
       "title": "ActionItem",
-      "description": "Child of <action-list-ui>. One actionable row — icon + label + optional\nsubtitle, forwards activation to the parent action-list. Row contract\nconverges on <menu-item-ui>: icon/text/subtitle/value/variant/disabled\nprops and icon/text/subtitle/trailing slot overrides (#1363 C5).",
+      "description": "Child of <action-list-ui>. One actionable row — icon + label + optional\ndescription, forwards activation to the parent action-list. Row contract\nconverges on <menu-item-ui>: icon/text/description/value/variant/disabled\nprops and icon/text/subtitle/trailing slot overrides (#1363 C5).\n(`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1571.)",
       "type": "object",
       "allOf": [
         {
@@ -427,6 +427,11 @@
         }
       ],
       "properties": {
+        "description": {
+          "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1571) replacing `subtitle` — converges action-item onto the same spelling <menu-item-ui> adopted under gh#1563.",
+          "type": "string",
+          "default": ""
+        },
         "component": {
           "const": "ActionItem"
         },
@@ -440,7 +445,7 @@
           "type": "string"
         },
         "subtitle": {
-          "description": "Optional secondary description line rendered under the label.",
+          "description": "DEPRECATED (ADR-0063, gh#1571) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.)",
           "type": "string",
           "default": ""
         },
@@ -494,7 +499,7 @@
             "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
           },
           "subtitle": {
-            "description": "Custom secondary-line content override; falls through to [subtitle] prop if not slotted."
+            "description": "Custom secondary-line content override; falls through to the [description] prop (or its deprecated [subtitle] alias — ADR-0063, gh#1571) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
           },
           "text": {
             "description": "Custom label content; falls through to [text] prop if not slotted."
@@ -1781,7 +1786,7 @@
     },
     "AdminShell": {
       "title": "AdminShell",
-      "description": "Behavior-only application shell. Canonical authoring shape uses\ncluster-namespaced bespoke children — <admin-topbar> at the top,\n<admin-sidebar slot=\"leading|trailing\"> rails, <admin-content> for\nthe main content region, <admin-command> for the Cmd+K palette, and\noptional <admin-statusbar> at the bottom. The shell wires sidebar\ntoggle forwarding, command-palette triggers, and the ResizeObserver\nthat drives responsive sidebar collapse; each bespoke child owns\nits own resize / collapse / open state-as-attribute semantics per\nADR-0023.\n\nLegacy data-attribute shapes (<aside data-sidebar>, <dialog\ndata-command>, [data-resize], <aside-ui slot=>, <span data-spacer>,\n<div data-actions>) were RETIRED in v0.4.0 per ADR-0024 and are no\nlonger recognized. Consumers must use the bespoke vocabulary.\n",
+      "description": "Behavior-only application shell. Canonical authoring shape uses\ncluster-namespaced bespoke children — <admin-topbar> at the top,\n<admin-sidebar slot=\"leading|trailing\"> rails, <admin-content> for\nthe main content region, <admin-command> for the Cmd+K palette, and\noptional <admin-statusbar> at the bottom. The shell wires sidebar\ntoggle forwarding, command-palette triggers, and the ResizeObserver\nthat drives responsive sidebar collapse; each bespoke child owns\nits own resize / collapse / open state-as-attribute semantics per\nADR-0023.\n\nLegacy data-attribute shapes (<aside data-sidebar>, <dialog\ndata-command>, [data-sidebar-resize], <aside-ui slot=>, <span data-spacer>,\n<div data-actions>) were RETIRED in v0.4.0 per ADR-0024 and are no\nlonger recognized. Consumers must use the bespoke vocabulary.\n",
       "type": "object",
       "allOf": [
         {
@@ -1934,7 +1939,7 @@
           "default": ""
         },
         "resizable": {
-          "description": "Opts in to drag-to-resize behavior. Author supplies a child\n[data-resize] element as the drag handle.\n",
+          "description": "Opts in to drag-to-resize behavior. Author supplies a child\n[data-sidebar-resize] element as the drag handle.\n",
           "type": "boolean",
           "default": false
         },
@@ -5862,17 +5867,17 @@
           "default": "abbr"
         },
         "hideAverage": {
-          "description": "When true, suppress the overlaid average line",
+          "description": "DEPRECATED (ADR-0063, gh#1563) — use `noAverage` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0.",
           "type": "boolean",
           "default": false
         },
         "hideGrid": {
-          "description": "Hide gridlines",
+          "description": "DEPRECATED (ADR-0063, gh#1563) — use `noGrid` instead. Same meaning, same default; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0.",
           "type": "boolean",
           "default": false
         },
         "hideValues": {
-          "description": "Hide value labels",
+          "description": "DEPRECATED (ADR-0063, gh#1563) — use `noValues` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0.",
           "type": "boolean",
           "default": false
         },
@@ -5881,6 +5886,21 @@
           "type": "boolean",
           "default": false
         },
+        "noAverage": {
+          "description": "When true, suppress the overlaid average line. Canonical spelling (ADR-0063, gh#1563) replacing `hideAverage`.",
+          "type": "boolean",
+          "default": false
+        },
+        "noGrid": {
+          "description": "Hide gridlines. Canonical spelling (ADR-0063, gh#1563) replacing `hideGrid`.",
+          "type": "boolean",
+          "default": false
+        },
+        "noValues": {
+          "description": "Hide value labels. Canonical spelling (ADR-0063, gh#1563) replacing `hideValues`.",
+          "type": "boolean",
+          "default": false
+        },
         "seriesEmphasis": {
           "description": "Multi-line only. Names one series key (matching a `y` key) to render at full strength — area fill + full-opacity line. Every other series drops its area fill and renders line-only at --chart-deemphasized-opacity. Empty (default) applies full treatment to every series, unchanged from pre-gh#561 behavior.",
           "type": "string",
@@ -6154,6 +6174,11 @@
           "type": "string",
           "default": ""
         },
+        "interactive": {
+          "description": "Canonical opt-in spelling (ADR-0063, gh#1563) replacing `static`'s opt-out polarity. Rows are interactive <button>-role badges by default — this default stays `true` in 0.8.42 (deliberately NOT flipped yet; the 0.9.0 cut inverts it to `false` after a full consumer scan of every `<chart-legend-ui>` tag per the ADR).",
+          "type": "boolean",
+          "default": true
+        },
         "onToggle": {
           "description": "Series-toggle mode emitted via the `toggle` event. `hide` removes the series from the render; `opacity` fades it. Wired via [for] on chart-ui.",
           "type": "string",
@@ -6186,7 +6211,7 @@
           "default": "dot"
         },
         "static": {
-          "description": "When set, rows are non-interactive <span>s (no click, no toggle).",
+          "description": "DEPRECATED (ADR-0063, gh#1563) — use `interactive` instead. When set (and `interactive` is absent), rows are non-interactive <span>s (no click, no toggle). Kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0.",
           "type": "boolean",
           "default": false
         }
@@ -6895,7 +6920,7 @@
           "default": ""
         },
         "resizable": {
-          "description": "Opts in to drag-to-resize behavior. Author supplies a child\n[data-resize] element as the drag handle.\n",
+          "description": "Opts in to drag-to-resize behavior. Author supplies a child\n[data-sidebar-resize] element as the drag handle.\n",
           "type": "boolean",
           "default": false
         },
@@ -7668,9 +7693,155 @@
         "version": 1
       }
     },
+    "ColorArea": {
+      "title": "ColorArea",
+      "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead. Renamed from `<color-picker-ui>` (ADR-0063, gh#1563 — `-picker` is reserved for the outer trigger + popover composite shape; this is the inline substrate, mirroring <calendar-grid-ui>'s naming precedent). `<color-picker-ui>` is now a thin deprecated alias subclassing this component.",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "baseHue": {
+          "description": "Reference hue (degrees) for the [hue-drift-max] constraint. Default\nNaN — falls back to the picker's hue at first commit so the consumer\ncan pre-seed the picker and constrain drift from that initial value.\n",
+          "type": "number",
+          "default": "NaN"
+        },
+        "component": {
+          "const": "ColorArea"
+        },
+        "disabled": {
+          "description": "Disables all interaction",
+          "type": "boolean",
+          "default": false
+        },
+        "format": {
+          "description": "Output format for the value property",
+          "type": "string",
+          "enum": [
+            "hex",
+            "oklch"
+          ],
+          "default": "hex"
+        },
+        "hueDriftMax": {
+          "description": "Generation constraint — maximum allowed signed-shortest-path hue\ndeviation (degrees) from [base-hue] (or the first-committed hue\nif [base-hue] is unset). Default NaN (no constraint). Wrap-aware\nso a drift of 350 degrees resolves as -10.\n",
+          "type": "number",
+          "default": "NaN"
+        },
+        "maxChroma": {
+          "description": "Generation constraint (v0.4.9 §99h, FEEDBACK-02 #7) — clamp the\nOKLCH chroma channel to at most this value before commit. Out-of-\nbound mutations round-trip to the nearest in-bound equivalent +\nfire `constraint-clamp`. Default Infinity (no constraint).\n",
+          "type": "number",
+          "default": "Infinity"
+        },
+        "maxL": {
+          "description": "Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint).",
+          "type": "number",
+          "default": 1
+        },
+        "minL": {
+          "description": "Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint).",
+          "type": "number",
+          "default": 0
+        },
+        "name": {
+          "description": "Form field name",
+          "type": "string",
+          "default": ""
+        },
+        "value": {
+          "description": "Current color as hex string",
+          "type": "string",
+          "default": "#3b82f6"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [],
+        "category": "input",
+        "composes": [
+          "slider-ui"
+        ],
+        "events": {
+          "change": {
+            "description": "Fired on every color change"
+          },
+          "constraint-clamp": {
+            "description": "Fired immediately before `change` / `input` when one or more\nconsumer-declared constraints (max-chroma / max-l / min-l /\nhue-drift-max) clamped a channel away from the user-requested\nvalue. detail.clamps is an array of axis-specific clamp records.\n",
+            "detail": {
+              "clamps": {
+                "description": "Array of `{ axis, requested, clamped, reason }` objects. axis is\none of \"l\" / \"c\" / \"h\". reason names the triggering constraint\nprop. Empty arrays are never emitted.\n",
+                "type": "array"
+              }
+            }
+          },
+          "input": {
+            "description": "Fired during continuous interaction (drag)"
+          }
+        },
+        "examples": [
+          {
+            "description": "Color picker card with a color picker component for selecting colors with swatches.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"cp\"\n    ]\n  },\n  {\n    \"id\": \"cp\",\n    \"component\": \"ColorArea\",\n    \"value\": \"#6366f1\"\n  }\n]",
+            "name": "color-area-demo"
+          },
+          {
+            "description": "Color picker with swatch selection in a card.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"cp\"\n    ]\n  },\n  {\n    \"id\": \"cp\",\n    \"component\": \"ColorArea\",\n    \"value\": \"#3b82f6\"\n  }\n]",
+            "name": "color-area-panel"
+          }
+        ],
+        "keywords": [
+          "colorarea",
+          "color-area",
+          "colorpicker",
+          "color-picker",
+          "color",
+          "picker"
+        ],
+        "name": "UIColorArea",
+        "parts": {},
+        "related": [
+          "grid",
+          "button"
+        ],
+        "slots": {},
+        "states": [
+          {
+            "description": "Default, ready for interaction.",
+            "name": "idle"
+          },
+          {
+            "description": "Non-interactive; dimmed.",
+            "attribute": "disabled",
+            "name": "disabled"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "color-area": [
+            "color-canvas",
+            "color-surface",
+            "swatch-picker",
+            "color-picker"
+          ]
+        },
+        "tag": "color-area-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
     "ColorInput": {
       "title": "ColorInput",
-      "description": "Compact form-bearing color input — opens a popover-anchored\n`<color-picker-ui>` from an inline swatch button. §302 (v0.5.12,\nFEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f\nOption B recipe (popover + button + color-picker) into a single\nform-associated tag for inline form contexts (settings drawer \"source\ncolor\" field, swatch-row inline-edit, etc.).",
+      "description": "Compact form-bearing color input — opens a popover-anchored\n`<color-area-ui>` from an inline swatch button. §302 (v0.5.12,\nFEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f\nOption B recipe (popover + button + color-area) into a single\nform-associated tag for inline form contexts (settings drawer \"source\ncolor\" field, swatch-row inline-edit, etc.). Composes `<color-area-ui>`\n(ADR-0063, gh#1563 — renamed from `<color-picker-ui>`, which is now a\ndeprecated alias); `color-input-ui`'s own tag/name is unaffected.",
       "type": "object",
       "allOf": [
         {
@@ -7709,7 +7880,7 @@
           "default": "NaN"
         },
         "maxChroma": {
-          "description": "Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13\n§-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.\nDefault Infinity (no constraint).\n",
+          "description": "Generation constraint forwarded to the inner `<color-area-ui>` (v0.5.13\n§-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.\nDefault Infinity (no constraint).\n",
           "type": "number",
           "default": "Infinity"
         },
@@ -7734,7 +7905,7 @@
           "default": false
         },
         "placement": {
-          "description": "Popover placement relative to the trigger. Default `bottom` centers the color-picker panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger).",
+          "description": "Popover placement relative to the trigger. Default `bottom` centers the color-area panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger).",
           "type": "string",
           "enum": [
             "top",
@@ -7764,7 +7935,7 @@
         "composes": [
           "button-ui",
           "popover-ui",
-          "color-picker-ui"
+          "color-area-ui"
         ],
         "events": {
           "change": {
@@ -7845,7 +8016,7 @@
         "name": "UIColorInput",
         "parts": {},
         "related": [
-          "color-picker",
+          "color-area",
           "popover",
           "button",
           "swatch"
@@ -7888,7 +8059,7 @@
     },
     "ColorPicker": {
       "title": "ColorPicker",
-      "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead.",
+      "description": "DEPRECATED (ADR-0063, gh#1563, gh#1377 B11) — `-picker` is reserved for the outer, trigger + popover, form-associated composite shape (`calendar-picker-ui` / `date-range-picker-ui` / `datetime-picker-ui` / `time-picker-ui`); `color-picker-ui` was the sole violator, playing `calendar-grid-ui`'s inline-substrate role under a `-picker` name. `<color-picker-ui>` is now a thin `UIColorArea` subclass (see color-picker.class.js) rather than an independent implementation — every prop/event/token is inherited unchanged from `<color-area-ui>`. Existing markup keeps working, but new markup should reach for `<color-area-ui>` directly. See `<color-area-ui>` for the full contract.",
       "type": "object",
       "allOf": [
         {
@@ -7957,7 +8128,13 @@
       ],
       "unevaluatedProperties": false,
       "x-adiaui": {
-        "anti_patterns": [],
+        "anti_patterns": [
+          {
+            "fix": "{\"component\": \"ColorArea\", \"name\": \"brand\"}\n",
+            "why": "ColorPicker is deprecated (ADR-0063, gh#1563) — new generation should\nreach for ColorArea instead.\n",
+            "wrong": "{\"component\": \"ColorPicker\", \"name\": \"brand\"}\n"
+          }
+        ],
         "category": "input",
         "composes": [
           "slider-ui"
@@ -7981,14 +8158,9 @@
         },
         "examples": [
           {
-            "description": "Color picker card with a color picker component for selecting colors with swatches.",
-            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"cp\"\n    ]\n  },\n  {\n    \"id\": \"cp\",\n    \"component\": \"ColorPicker\",\n    \"value\": \"#6366f1\"\n  }\n]",
-            "name": "color-picker-demo"
-          },
-          {
-            "description": "Color picker with swatch selection in a card.",
+            "description": "Deprecated tag — prefer ColorArea's own \"color-area-demo\" example for NEW markup.",
             "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"cp\"\n    ]\n  },\n  {\n    \"id\": \"cp\",\n    \"component\": \"ColorPicker\",\n    \"value\": \"#3b82f6\"\n  }\n]",
-            "name": "color-picker-panel"
+            "name": "color-picker-legacy"
           }
         ],
         "keywords": [
@@ -8000,6 +8172,7 @@
         "name": "UIColorPicker",
         "parts": {},
         "related": [
+          "color-area",
           "grid",
           "button"
         ],
@@ -8015,18 +8188,19 @@
             "name": "disabled"
           }
         ],
-        "status": "stable",
+        "status": "deprecated",
         "synonyms": {
           "color-picker": [
             "color-canvas",
             "color-surface",
-            "swatch-picker"
+            "swatch-picker",
+            "color-area"
           ]
         },
         "tag": "color-picker-ui",
         "tokens": {},
         "traits": [],
-        "version": 1
+        "version": 2
       }
     },
     "Combobox": {
@@ -10235,7 +10409,7 @@
           "$ref": "#/$defs/DynamicStringList"
         },
         "align": {
-          "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.\n",
+          "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-area-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.\n",
           "type": "string",
           "enum": [
             "start",
@@ -12321,7 +12495,7 @@
         ],
         "slots": {
           "default": {
-            "description": "The form control — a WIDE control like input-ui, select-ui, textarea-ui, slider-ui, range-ui, calendar-picker-ui, color-picker-ui, upload-ui, otp-input-ui. Auto-id'd for the label's [for] binding.\nDO NOT wrap small self-labeling widgets here. check-ui, switch-ui, radio-ui, toggle-ui all carry their own [label] attribute that renders inline next to the control — wrapping them in field-ui produces broken layouts (settings-row `justify-self: end` rule pushes the control to the trailing edge, away from the label that field-ui stamps; the widget's own label then renders again on the right, creating a doubled / right-justified affordance). See anti_patterns below for the canonical alternatives."
+            "description": "The form control — a WIDE control like input-ui, select-ui, textarea-ui, slider-ui, range-ui, calendar-picker-ui, color-area-ui, upload-ui, otp-input-ui. Auto-id'd for the label's [for] binding.\nDO NOT wrap small self-labeling widgets here. check-ui, switch-ui, radio-ui, toggle-ui all carry their own [label] attribute that renders inline next to the control — wrapping them in field-ui produces broken layouts (settings-row `justify-self: end` rule pushes the control to the trailing edge, away from the label that field-ui stamps; the widget's own label then renders again on the right, creating a doubled / right-justified affordance). See anti_patterns below for the canonical alternatives."
           },
           "action": {
             "description": "Button adjacent to the control for inline actions (clear, reset, help popover)."
@@ -16873,7 +17047,7 @@
     },
     "MenuItem": {
       "title": "MenuItem",
-      "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + subtitle + value.",
+      "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1563.)",
       "type": "object",
       "allOf": [
         {
@@ -16884,6 +17058,11 @@
         }
       ],
       "properties": {
+        "description": {
+          "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`.",
+          "type": "string",
+          "default": ""
+        },
         "component": {
           "const": "MenuItem"
         },
@@ -16898,7 +17077,7 @@
           "default": ""
         },
         "subtitle": {
-          "description": "Optional secondary description line rendered under the label.",
+          "description": "DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.)",
           "type": "string",
           "default": ""
         },
@@ -16952,7 +17131,7 @@
             "description": "Custom leading element override; falls through to `[icon]` prop if not slotted."
           },
           "subtitle": {
-            "description": "Custom secondary-line content override; falls through to `[subtitle]` prop if not slotted."
+            "description": "Custom secondary-line content override; falls through to the `[description]` prop (or its deprecated `[subtitle]` alias — ADR-0063, gh#1563) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
           },
           "text": {
             "description": "Custom label content; falls through to `[text]` prop if not slotted."
@@ -19148,6 +19327,16 @@
         "component": {
           "const": "Pane"
         },
+        "edge": {
+          "description": "Opts a pane into horizontal-sibling chrome: suppresses the default\nfour-sided border and moves the resize grabber to the inner edge\n(right edge for `leading`, left edge for `trailing`). Also flips the\nresize-drag direction so `trailing` panes grow when dragged leftward.\nUnset keeps the pane-intrinsic chrome (full border, right-edge\ngrabber when resizable). Canonical spelling (ADR-0063, gh#1563)\nreplacing `side`.\n",
+          "type": "string",
+          "enum": [
+            "",
+            "leading",
+            "trailing"
+          ],
+          "default": ""
+        },
         "maxWidth": {
           "description": "Component property: maxWidth.",
           "type": "number",
@@ -19164,7 +19353,7 @@
           "default": false
         },
         "side": {
-          "description": "Opts a pane into horizontal-sibling chrome: suppresses the default\nfour-sided border and moves the resize grabber to the inner edge\n(right edge for `leading`, left edge for `trailing`). Also flips the\nresize-drag direction so `trailing` panes grow when dragged leftward.\nUnset keeps the pane-intrinsic chrome (full border, right-edge\ngrabber when resizable).\n",
+          "description": "DEPRECATED (ADR-0063, gh#1563) — use `edge` instead. Same type/default/enum; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0.",
           "type": "string",
           "enum": [
             "",

package/catalog/catalog-a2ui_0_9_rules.txt

@@ -17,11 +17,12 @@
 - Set variant="contained" for a bounded per-item surface (background, border, radius, and an open-state divider) — the composition to reach for when nesting inside <card-ui>. Default variant="flat" (no chrome) suits settings pages and FAQ blocks sitting on the page canvas.
 
 ## ActionItem
-- Child of <action-list-ui> — one inline-action row with icon + label + optional subtitle + optional trailing shortcut/badge.
+- Child of <action-list-ui> — one inline-action row with icon + label + optional description + optional trailing shortcut/badge.
 - Different from <menu-item-ui>: action-items live inline in content surfaces; menu-items live inside <menu-ui> popovers.
 - For navigation entries (route-changing) use <nav-item-ui> instead.
 - Use [variant="danger"] exclusively for destructive/irreversible actions (Delete, Remove). Pair danger items with an explicit confirm flow when the action cannot be undone.
-- Prefer [icon]/[text]/[subtitle] props over slotted markup; use slot="icon"/"text"/"subtitle"/"trailing" only for custom markup (e.g. a slotted <kbd> shortcut hint).
+- Prefer [icon]/[text]/[description] props over slotted markup; use slot="icon"/"text"/"subtitle"/"trailing" only for custom markup (e.g. a slotted <kbd> shortcut hint).
+- NOTE (ADR-0063, gh#1571): [subtitle] is now a deprecated alias for [description] — kept as a dual-read compat shim (new-name precedence, one-time console.warn), removed at the 0.9.0 cut.
 
 ## ActionList
 - Hosts <action-item-ui> children as a vertical command list inline in content surfaces.
@@ -201,17 +202,22 @@
 - Pair with <row-ui> for horizontal layouts; both share the same gap-token contract.
 - Set align/justify attributes for cross-axis / main-axis alignment; default is start/start.
 
+## ColorArea
+- OKLCH-native color picker with 2D color area + H/C/L sliders. Form-associated; emits OKLCH color strings.
+- For simple color swatches (read-only display) use <swatch-ui>; for hex/rgb text input use <color-input-ui>.
+- Renamed from <color-picker-ui> (ADR-0063, gh#1563); the old tag is a deprecated alias that still works — new generation should reach for ColorArea directly.
+- Output format defaults to oklch(); set format= to override (hex, rgb, hsl).
+
 ## ColorInput
-- Use <color-input-ui> for any form-row color field — it canonicalizes the popover + button + color-picker recipe and is the only form-bearing color primitive. Do not hand-roll the composition; reach for color-input-ui directly.
+- Use <color-input-ui> for any form-row color field — it canonicalizes the popover + button + color-area recipe and is the only form-bearing color primitive. Do not hand-roll the composition; reach for color-input-ui directly.
 - Set [format="oklch"] when the persisted value feeds CSS tokens or perceptual math; [format="hex"] for legacy / design-tool interop. Event detail (`change` / `input`) carries BOTH `hex` and `oklch` views regardless of [format], plus parsed `{l, c, h}` channel scalars.
-- For brand-palette constraints, set [maxChroma] / [minL] / [maxL] / [hueDriftMax] (with [baseHue]) on the host — they forward to the inner <color-picker-ui> and clamp generation. Useful for Tokens-Studio-style guarded color generation.
-- Use <color-picker-ui> DIRECTLY (no color-input-ui wrapper) only for full-surface editors where the picker IS the page (e.g. Tokens Studio main canvas). For inline form-row use, always reach for <color-input-ui>.
-- Per ADR-0027 (cross-primitive composition imports), consumer pages MUST explicitly import <button-ui>, <popover-ui>, and <color-picker-ui> before <color-input-ui>. The primitive composes them but does NOT auto-register them.
+- For brand-palette constraints, set [maxChroma] / [minL] / [maxL] / [hueDriftMax] (with [baseHue]) on the host — they forward to the inner <color-area-ui> and clamp generation. Useful for Tokens-Studio-style guarded color generation.
+- Use <color-area-ui> DIRECTLY (no color-input-ui wrapper) only for full-surface editors where the picker IS the page (e.g. Tokens Studio main canvas). For inline form-row use, always reach for <color-input-ui>.
+- Per ADR-0027 (cross-primitive composition imports), consumer pages MUST explicitly import <button-ui>, <popover-ui>, and <color-area-ui> before <color-input-ui>. The primitive composes them but does NOT auto-register them.
 
 ## ColorPicker
-- OKLCH-native color picker with 2D color area + H/C/L sliders. Form-associated; emits OKLCH color strings.
+- DEPRECATED — prefer `{"component": "ColorArea"}` over `{"component": "ColorPicker"}`. Both render and behave identically; ColorPicker is a thin compatibility alias.
 - For simple color swatches (read-only display) use <swatch-ui>; for hex/rgb text input use <color-input-ui>.
-- Output format defaults to oklch(); set format= to override (hex, rgb, hsl).
 
 ## Combobox
 - Use <combobox-ui> for typeahead-filterable single-select with a constrained-choice value model. `value` MUST be one of `options[].value` unless `[free-text]` is set. For ≤ 4 options, use <segmented-ui> or <radio-ui> instead.
@@ -447,7 +453,7 @@
 - Use [variant="danger"] exclusively for destructive / irreversible actions (Delete, Remove). "Sign out" is NOT danger. Pair danger items with an explicit confirm flow (<modal-ui> destructive-confirm pattern) when the action cannot be undone.
 - Set [disabled] (not [hidden]) when an action is contextually unavailable — disabled items remain visible for affordance discoverability but skip roving focus + don't fire `action`.
 - Prefer [icon] + [text] props over slotted markup for consistency. Use slot="icon" / slot="text" only when you need custom markup (e.g. <avatar-ui slot="icon">, <kbd slot="trailing"> shortcut hint).
-- <action-item-ui> (child of <action-list-ui>) shares this row contract (icon/text/subtitle/value/variant/disabled props, icon/text/subtitle/ trailing slot overrides) for inline, non-popover command rows — use it instead when the surface isn't a <menu-ui> popover (#1363 C5).
+- <action-item-ui> (child of <action-list-ui>) shares this row contract (icon/text/subtitle/value/variant/disabled props, icon/text/subtitle/ trailing slot overrides) for inline, non-popover command rows — use it instead when the surface isn't a <menu-ui> popover (#1363 C5). NOTE (ADR-0063, gh#1563): <menu-item-ui>'s own `subtitle` PROP is now a deprecated alias for `description` — <action-item-ui> still uses `subtitle` as its own primary spelling and was NOT renamed in this pass (flagged as a discovered follow-up candidate, not fixed here).
 
 ## MenuLabel
 - <menu-label-ui> MUST be a direct child of <menu-ui>; like menu-item-ui and menu-divider-ui it is hoisted into the top-layer popover via <menu-ui>'s direct-descendant query — a label nested elsewhere renders outside the popover.
@@ -693,7 +699,7 @@
 - For static (post-stream) display use <text-ui> or <richtext-ui>; stream-ui assumes live token feed.
 
 ## Swatch
-- Use to display a single color sample with optional label. For interactive color picking use <color-picker-ui>.
+- Use to display a single color sample with optional label. For interactive color picking use <color-area-ui>.
 - Inside design-token displays or palette grids; not for general decoration.
 - Color value accepts hex, rgb, hsl, or oklch; oklch preferred for AdiaUI token alignment.
 
@@ -1186,7 +1192,7 @@ inside <grid-ui>; reach for the page composite only when search
 - admin-shell takes bespoke admin-* children only. The canonical composition is <admin-topbar> + <admin-sidebar slot="leading"> + <admin-content> + <admin-sidebar slot="trailing"> + <admin-command> + optional <admin-statusbar>. The shell's CSS grid reads child tag selectors to place them.
 - Don't nest col-ui / row-ui or generic layout primitives directly inside admin-shell — app-shell.css handles grid layout based on bespoke child tags. Generic layout goes inside <admin-content> or inside <admin-page-body>.
 - Click forwarding patterns — [data-sidebar-toggle="<name>"] on a button forwards to <admin-sidebar[slot="<name>"]>.toggle(); [data-command-trigger] on a button forwards to <admin-command>.show(). The shell doesn't need to know about the buttons; the bespoke children own the behavior.
-- Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024. Do not author <aside data-sidebar>, <dialog data-command>, [data-resize], <aside-ui slot=>, <span data-spacer>, or <div data-actions> inside admin-shell.
+- Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024. Do not author <aside data-sidebar>, <dialog data-command>, [data-sidebar-resize], <aside-ui slot=>, <span data-spacer>, or <div data-actions> inside admin-shell.
 
 ## AdminSidebar
 - admin-sidebar is the bespoke replacement for legacy <aside data-sidebar>. Use slot="leading" or slot="trailing" to position. Add resizable + collapsible attributes to opt in to interactive behaviors.

package/catalog/tier-index.json

@@ -1,14 +1,14 @@
 {
-  "catalogId": "adia.tiers@0.8.41",
+  "catalogId": "adia.tiers@0.8.42",
   "description": "Tier index of the AdiaUI catalog contract (ADR-0050). L0-L4 ladder; every tier-N entry is a declared composition of tier-(N-1) entries. L1 `composes` edges speak A2UI component TYPE names — the R-C7 catalogs’ `components` keys (genui-system SPEC R-C13). Derived — regenerate with `npm run build:catalog-tiers`, never hand-edit.",
   "extends": {
     "catalogId": "adia.base",
-    "version": "0.8.41"
+    "version": "0.8.42"
   },
   "tiers": {
     "L0": {
       "composesTier": null,
-      "count": 193,
+      "count": 194,
       "entries": {
         "A2UIRoot": {
           "category": "container",
@@ -352,6 +352,12 @@
           "origin": "primitive",
           "tag": "col-ui"
         },
+        "ColorArea": {
+          "category": "input",
+          "composes": [],
+          "origin": "primitive",
+          "tag": "color-area-ui"
+        },
         "ColorInput": {
           "category": "input",
           "composes": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui",
-  "version": "0.8.41",
+  "version": "0.8.42",
   "description": "The A2UI protocol — runtime (renderer, registry, streams, surface manifest, wiring primitives, dockable base classes) plus protocol-side validation. Framework-agnostic and dependency-free; pairs with any A2UI-conformant component set. Folded from @adia-ai/a2ui-runtime + the protocol half of @adia-ai/a2ui-validator (ADR-0048).",
   "type": "module",
   "exports": {

package/registry.js

@@ -65,6 +65,7 @@ export const registry = new Map([
   ['RadioGroup',       'radio-group-ui'],
   ['DateTimeInput',    'calendar-picker-ui'],
   ['CalendarPicker',   'calendar-picker-ui'],
+  ['ColorArea',        'color-area-ui'],
   ['ColorPicker',      'color-picker-ui'],
   // Search deprecated — use Input type="search" prefix="magnifying-glass"
   ['Upload',           'upload-ui'],
@@ -187,6 +188,7 @@ export const registry = new Map([
   ['segment-ui',       'segment-ui'],
   ['command-ui',       'command-ui'],
   ['calendar-picker-ui', 'calendar-picker-ui'],
+  ['color-area-ui',    'color-area-ui'],
   ['color-picker-ui',  'color-picker-ui'],
   ['kbd-ui',           'kbd-ui'],
   ['toolbar-ui',       'toolbar-ui'],