@adia-ai/web-components 0.8.41 → 0.8.42

package/components/color-picker/color-picker.css

@@ -1,182 +1,14 @@
-@scope (color-picker-ui) {
-  :where(:scope) {
-    /* ── Tokens ── */
-    --color-picker-gap:              var(--a-space-2);
-    --color-picker-area-height:      10rem;
-    --color-picker-area-radius:      var(--a-radius-md);
-    --color-picker-track-height:     0.75rem;
-    --color-picker-track-radius:     var(--a-radius-full);
-    --color-picker-thumb-size:       1.125rem;
-    --color-picker-thumb-border:     2px solid var(--a-chrome-border);
-    --color-picker-thumb-shadow:     0 0 0 1px var(--a-chrome-ring-subtle), 0 2px 4px var(--a-chrome-shadow-soft);
-    --color-picker-font:             var(--a-font-family-code);
-    --color-picker-font-size:        var(--a-ui-sm);
-    --color-picker-fg:               var(--md-sys-color-neutral-on-surface);
-    --color-picker-label-fg:         var(--a-fg-muted);
-    --color-picker-border:           var(--md-sys-color-neutral-outline-variant);
-    --color-picker-output-bg:        var(--a-bg-muted);
-    --color-picker-output-radius:    var(--a-radius-sm);
-    --color-picker-fg-disabled:      var(--a-ui-text-disabled);
-
-    /* ── Spacing ── */
-    --color-picker-gap-sm:           var(--a-space-1);
-    --color-picker-pad-sm:           var(--a-space-2);
-
-    /* ── Interactive ── */
-    --color-picker-focus-color:      var(--md-sys-color-primary);
-    --color-picker-disabled-border:  var(--md-sys-color-neutral-outline-variant);
-
-    /* ── Transitions ── */
-    --color-picker-duration:         var(--a-duration-fast);
-    --color-picker-easing:           var(--a-easing);
-  }
-
-  :scope {
-    box-sizing: border-box;
-    display: flex;
-    flex-direction: column;
-    gap: var(--color-picker-gap);
-    width: 100%;
-  }
-
-  /* ═══════ 2D Color Area ═══════ */
-
-  [data-area] {
-    position: relative;
-    width: 100%;
-    height: var(--color-picker-area-height);
-    border-radius: var(--color-picker-area-radius);
-    border: 1px solid var(--color-picker-border);
-    overflow: hidden;
-    cursor: crosshair;
-    touch-action: none;
-  }
-
-  [data-area]:focus-visible {
-    outline: 2px solid var(--color-picker-focus-color);
-    outline-offset: 2px;
-  }
-
-  [data-area] canvas {
-    image-rendering: auto;
-  }
-
-  [data-area-thumb] {
-    position: absolute;
-    width: var(--color-picker-thumb-size);
-    height: var(--color-picker-thumb-size);
-    border-radius: 50%;
-    border: var(--color-picker-thumb-border);
-    box-shadow: var(--color-picker-thumb-shadow);
-    transform: translate(-50%, -50%);
-    pointer-events: none;
-    z-index: 1;
-  }
-
-  /* ═══════ Slider Rows (H / C / L) ═══════ */
-
-  [data-sliders] {
-    display: flex;
-    flex-direction: column;
-    gap: var(--color-picker-gap-sm);
-  }
-
-  /* ═══════ Hue Track ═══════ */
-
-  [data-hue-track] {
-    position: relative;
-    width: 100%;
-    height: var(--color-picker-track-height);
-    border-radius: var(--color-picker-track-radius);
-    cursor: pointer;
-    touch-action: none;
-  }
-
-  [data-hue-track]:focus-visible {
-    outline: 2px solid var(--color-picker-focus-color);
-    outline-offset: 2px;
-  }
-
-  [data-hue-thumb] {
-    position: absolute;
-    top: 50%;
-    width: var(--color-picker-thumb-size);
-    height: var(--color-picker-thumb-size);
-    border-radius: 50%;
-    border: var(--color-picker-thumb-border);
-    box-shadow: var(--color-picker-thumb-shadow);
-    transform: translate(-50%, -50%);
-    pointer-events: none;
-  }
-
-  /* ═══════ Output Values ═══════ */
-
-  [data-output] {
-    display: flex;
-    flex-direction: column;
-    gap: var(--color-picker-gap-sm);
-  }
-
-  [data-output-group] {
-    display: flex;
-    align-items: center;
-    gap: var(--color-picker-gap-sm);
-    padding: var(--color-picker-gap-sm) var(--color-picker-pad-sm);
-    background: var(--color-picker-output-bg);
-    border-radius: var(--color-picker-output-radius);
-  }
-
-  [data-output-value] {
-    font-family: var(--color-picker-font);
-    font-size: var(--color-picker-font-size);
-    color: var(--color-picker-fg);
-    user-select: all;
-    -webkit-user-select: all;
-    flex: 1;
-    min-width: 0;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-  }
-
-  /* Copy button */
-  [data-copy] {
-    flex-shrink: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    background: none;
-    border: none;
-    padding: 0;
-    cursor: pointer;
-    color: var(--color-picker-label-fg);
-    transition: color var(--color-picker-duration) var(--color-picker-easing);
-  }
-
-  [data-copy]:hover {
-    color: var(--color-picker-fg);
-  }
-
-  [data-copy] icon-ui {
-    --a-icon-size: var(--color-picker-font-size);
-  }
-
-  /* ═══════ Disabled ═══════ */
-
-  :scope[disabled] {
-    pointer-events: none;
-    color: var(--color-picker-fg-disabled);
-  }
-  :scope[disabled] [data-area],
-  :scope[disabled] [data-hue-track] {
-    filter: grayscale(1);
-    cursor: not-allowed;
-  }
-  :scope[disabled] slider-ui {
-    --slider-fill-bg: var(--color-picker-disabled-border);
-    --slider-thumb-bg: var(--color-picker-disabled-border);
-  }
-  :scope[disabled] [data-output-value] {
-    color: var(--color-picker-fg-disabled);
-  }
-}
+/* `<color-picker-ui>` is DEPRECATED (ADR-0063, gh#1563) — a thin
+ * `UIColorArea` subclass (see color-picker.class.js), never its own
+ * independent implementation. Its visual contract lives entirely in
+ * ../color-area/color-area.css, whose `@scope (color-area-ui,
+ * color-picker-ui)` root and `:is(color-area-ui, color-picker-ui)`
+ * selectors already cover this tag — one styling source, not two files
+ * drifting apart (`@scope` matches by literal tag name, not JS prototype
+ * chain, so the alias tag has to be named in that scope root explicitly —
+ * same shape as calendar-picker.css's own `datetime-picker-ui` alias
+ * coverage). This file intentionally carries no rules of its own;
+ * `packages/web-components/styles/components.css` still imports it so the
+ * barrel's per-component import list stays complete and mechanical (no
+ * special-cased skip for a deprecated-but-still-shipping tag).
+ */

package/components/color-picker/color-picker.yaml

@@ -3,21 +3,38 @@
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIColorPicker
 tag: color-picker-ui
-status: stable
+status: deprecated
 component: ColorPicker
 category: input
-version: 1
+version: 2
 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.
+  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.
 # Per ADR-0027 — primitives that programmatically create other primitives
-# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import
+# the slider-ui module (same one <color-area-ui> itself needs — this alias
+# inherits its render(), not just its class).
 composes:
   - slider-ui
 props:
+  # Every prop below is inherited VERBATIM from <color-area-ui> —
+  # documented here too (not just "see the base class") because a
+  # consumer scanning THIS tag's own catalog entry, or the a2ui pipeline
+  # generating THIS tag by name, needs the full contract without a second
+  # hop. audit-static-properties-vs-yaml.mjs's component-extends-component
+  # exemption (gh#1372/gh#1563) resolves this against <color-area-ui>'s
+  # own yaml, so re-declaring the inherited names here is documentation,
+  # not a second runtime contract. Nothing overrides a default here (the
+  # alias is byte-identical behavior; only the class/tag/component names
+  # differ), unlike datetime-picker-ui's own two overridden defaults.
   name:
     description: Form field name
     type: string
@@ -100,47 +117,29 @@ states:
     description: Non-interactive; dimmed.
     attribute: disabled
 traits: []
-tokens: {}
+tokens: {}  # No component-owned tokens — styling flows entirely through
+            # <color-area-ui>'s own --color-area-* custom properties.
 requiredIcons:
   - copy
   - check
   - warning
 a2ui:
   rules:
-    - rule: 'OKLCH-native color picker with 2D color area + H/C/L sliders. Form-associated; emits OKLCH color strings.'
-      reason: 'Canonical color-authoring surface.'
+    - rule: 'DEPRECATED — prefer `{"component": "ColorArea"}` over `{"component": "ColorPicker"}`. Both render and behave identically; ColorPicker is a thin compatibility alias.'
+      reason: 'ADR-0063/gh#1377 B11 fold — steer new generation at the canonical primitive.'
     - rule: 'For simple color swatches (read-only display) use <swatch-ui>; for hex/rgb text input use <color-input-ui>.'
       reason: 'Surface boundary.'
-    - rule: 'Output format defaults to oklch(); set format= to override (hex, rgb, hsl).'
-      reason: 'Format knob.'
-anti_patterns: []
+anti_patterns:
+  - wrong: |
+      {"component": "ColorPicker", "name": "brand"}
+    why: |
+      ColorPicker is deprecated (ADR-0063, gh#1563) — new generation should
+      reach for ColorArea instead.
+    fix: |
+      {"component": "ColorArea", "name": "brand"}
 examples:
-  - name: color-picker-demo
-    description: Color picker card with a color picker component for selecting colors with swatches.
-    a2ui: >-
-      [
-        {
-          "id": "root",
-          "component": "Card",
-          "children": [
-            "sec"
-          ]
-        },
-        {
-          "id": "sec",
-          "component": "Section",
-          "children": [
-            "cp"
-          ]
-        },
-        {
-          "id": "cp",
-          "component": "ColorPicker",
-          "value": "#6366f1"
-        }
-      ]
-  - name: color-picker-panel
-    description: Color picker with swatch selection in a card.
+  - name: color-picker-legacy
+    description: Deprecated tag — prefer ColorArea's own "color-area-demo" example for NEW markup.
     a2ui: >-
       [
         {
@@ -169,7 +168,8 @@ keywords:
   - color
   - picker
 synonyms:
-  color-picker: [color-canvas, color-surface, swatch-picker]
+  color-picker: [color-canvas, color-surface, swatch-picker, color-area]
 related:
+  - color-area
   - grid
   - button

package/components/description-list/description-list.a2ui.json

@@ -18,7 +18,7 @@
       "$ref": "common_types.json#/$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",

package/components/description-list/description-list.css

@@ -88,7 +88,7 @@
 
   /* §-TBD (v0.5.19, FB-51 #3): align="stretch" lets dd fill the
      remaining inline-grid track width. Useful when dd hosts a block-
-     level form control (slider-ui / select-ui / color-picker-ui) that
+     level form control (slider-ui / select-ui / color-area-ui) that
      would otherwise shrink-wrap to content. width:100% on direct
      children reaches block controls that have their own inline-flex
      :scope rule (e.g. <slider-ui>) so they stretch to track width. */

package/components/description-list/description-list.d.ts

@@ -15,7 +15,7 @@ import { UIElement } from '../../core/element.js';
 export class UIDescriptionList extends UIElement {
   /** Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children */
   items: string;
-  /** 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.
+  /** 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.
  */
   align: 'start' | 'between' | 'stretch';
   /** stacked: term above description. inline: term and description on one row. */

package/components/description-list/description-list.yaml

@@ -16,7 +16,7 @@ props:
       `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>`
+      `<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.

package/components/field/field.a2ui.json

@@ -99,7 +99,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)."

package/components/field/field.class.js

@@ -280,7 +280,10 @@ export class UIField extends UIElement {
     'check-ui', 'radio-ui', 'switch-ui', 'slider-ui', 'range-ui',
     'otp-input-ui', 'tags-input-ui', 'chat-input-ui', 'autocomplete-input-ui',
     'datetime-picker-ui', 'date-range-picker-ui', 'calendar-picker-ui',
-    'color-picker-ui', 'upload-ui', 'rating-ui', 'segmented-ui',
+    // ADR-0063 (gh#1563) — color-picker-ui's real implementation moved to
+    // color-area-ui; color-picker-ui is now a thin deprecated alias. Both
+    // tags need to resolve here since either may be the one actually used.
+    'color-area-ui', 'color-picker-ui', 'upload-ui', 'rating-ui', 'segmented-ui',
     'input', 'textarea', 'select',
   ]);
 

package/components/field/field.yaml

@@ -68,7 +68,7 @@ slots:
     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
+      color-area-ui, upload-ui, otp-input-ui. Auto-id'd for the
       label's [for] binding.
 
       DO NOT wrap small self-labeling widgets here. check-ui,

package/components/index.js

@@ -50,6 +50,7 @@ export { UITooltip } from './tooltip/tooltip.js';
 export { UIBadge } from './badge/badge.js';
 export { UIBreadcrumb } from './breadcrumb/breadcrumb.js';
 export { UICommand } from './command/command.js';
+export { UIColorArea } from './color-area/color-area.js';
 export { UIColorPicker } from './color-picker/color-picker.js';
 export { UIColorInput } from './color-input/color-input.js';
 export { UINoodles } from './noodles/noodles.js';

package/components/integration-card/integration-card.examples.md

@@ -16,7 +16,8 @@
 
 ```html
 <integration-card-ui provider="github" name="GitHub" description="Sync issues and pull requests." status="connected">
-  <menu-ui slot="actions" label="More" trigger-icon="dots-three" trigger-variant="ghost">
+  <menu-ui slot="actions">
+    <button-ui slot="trigger" icon="dots-three" variant="ghost" aria-label="More"></button-ui>
     <menu-item-ui action="reauth">Re-authenticate</menu-item-ui>
     <menu-item-ui action="disconnect" variant="danger">Disconnect</menu-item-ui>
   </menu-ui>

package/components/menu/menu-item.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/MenuItem.json",
   "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": [
     {
@@ -13,6 +13,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"
     },
@@ -27,7 +32,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": ""
     },
@@ -81,7 +86,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."

package/components/menu/menu-item.yaml

@@ -13,7 +13,7 @@ component: MenuItem
 category: navigation
 version: 1
 description: |-
-  Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + subtitle + value.
+  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.)
 
 props:
   icon:
@@ -25,7 +25,20 @@ props:
     type: string
     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: ""
+  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: ""
   value:
@@ -49,7 +62,11 @@ slots:
   text:
     description: Custom label content; falls through to `[text]` 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.
   trailing:
     description: Trailing element pinned to the far edge (shortcut hint, check mark).
 
@@ -84,6 +101,10 @@ a2ui:
       (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).
 
 keywords:
   - menu-item

package/components/menu/menu.class.js

@@ -258,7 +258,14 @@ export class UIMenuItem extends UIElement {
   static properties = {
     icon:     { type: String,  default: '', reflect: true },
     text:     { type: String,  default: '', reflect: true },
+    // ADR-0063 (gh#1563) — `subtitle` is DEPRECATED (menu-item was the sole
+    // ~20-component-corpus outlier using `subtitle` where every sibling
+    // uses `description`); `description` is canonical. `subtitle` stays
+    // declared (dual-read compat, 0.8.42). The `subtitle` SLOT (a separate
+    // surface — see menu-item.yaml) is deliberately unchanged; only the
+    // PROP renames.
     subtitle: { type: String,  default: '', reflect: true },
+    description: { type: String, default: '', reflect: true },
     value:    { type: String,  default: '', reflect: true },
     variant:  { type: String,  default: 'default', reflect: true },
     disabled: { type: Boolean, default: false, reflect: true },
@@ -266,12 +273,32 @@ export class UIMenuItem extends UIElement {
 
   static template = () => null;
 
+  // ADR-0063 (gh#1563) one-shot-per-class deprecation warn for [subtitle].
+  static #warnedSubtitle = false;
+
   // Set when connected() stamped role="menuitem" itself; a consumer-provided
   // role (e.g. admin-roster's role="menuitemradio", gh#616) is never touched
   // — that consumer also owns tabindex and any checked-state aria.
   #roleStamped = false;
 
   connected() {
+    // ADR-0063 (gh#1563) compat shim — resolve BEFORE #stamp() reads
+    // `this.description`, so there's no wrong-then-right flash. New-name
+    // precedence: [description] wins outright when present; only fall
+    // back to (and mirror) [subtitle] when [description] is absent.
+    if (!this.hasAttribute('description') && this.hasAttribute('subtitle')) {
+      this.description = this.subtitle;
+      if (!UIMenuItem.#warnedSubtitle) {
+        UIMenuItem.#warnedSubtitle = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[AdiaUI] <menu-item-ui [subtitle]> is deprecated — use ' +
+          '[description] instead (ADR-0063, gh#1563). Kept working as-is; ' +
+          'no behavior change.',
+        );
+      }
+    }
+
     // role="menuitem" ONLY when actually inside a menu container. A menu-ui
     // closes by moving its items back into its own light DOM (see #hide()),
     // where there is no role="menu"/menubar ancestor — a bare role="menuitem"
@@ -324,10 +351,10 @@ export class UIMenuItem extends UIElement {
       this.appendChild(span);
     }
 
-    if (this.subtitle && !this.#ownChild('[slot="subtitle"]')) {
+    if (this.description && !this.#ownChild('[slot="subtitle"]')) {
       const sub = this.#stampMark(document.createElement('span'));
       sub.setAttribute('slot', 'subtitle');
-      sub.textContent = this.subtitle;
+      sub.textContent = this.description;
       this.appendChild(sub);
     }
   }
@@ -357,15 +384,16 @@ export class UIMenuItem extends UIElement {
     const textEl = this.#ownChild('[slot="text"]');
     if (this.#wasStamped(textEl)) textEl.textContent = this.text;
 
-    // Sync subtitle — only touch elements we stamped.
+    // Sync subtitle (backed by the `description` prop — ADR-0063, gh#1563)
+    // — only touch elements we stamped.
     const subEl = this.#ownChild('[slot="subtitle"]');
-    if (this.subtitle) {
+    if (this.description) {
       if (subEl) {
-        if (this.#wasStamped(subEl)) subEl.textContent = this.subtitle;
+        if (this.#wasStamped(subEl)) subEl.textContent = this.description;
       } else {
         const el = this.#stampMark(document.createElement('span'));
         el.setAttribute('slot', 'subtitle');
-        el.textContent = this.subtitle;
+        el.textContent = this.description;
         this.appendChild(el);
       }
     } else if (this.#wasStamped(subEl)) {

package/components/menu/menu.d.ts

@@ -41,11 +41,13 @@ export class UIMenuDivider extends UIElement {
 }
 
 export class UIMenuItem extends UIElement {
+  /** 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`. */
+  description: string;
   /** Disabled state — blocks pointer + keyboard activation. */
   disabled: boolean;
   /** Optional leading Phosphor icon name. */
   icon: string;
-  /** Optional secondary description line rendered under the label. */
+  /** 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.) */
   subtitle: string;
   /** Item label text. */
   text: string;

package/components/pane/pane.a2ui.json

@@ -21,6 +21,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",
@@ -37,7 +47,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": [
         "",