@adia-ai/web-components 0.8.41 → 0.8.42

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.42] — 2026-08-17
+
+### Added
+- **ADR-0063 `0.8.42` compat shims (gh#1562 wave, PR #1569).** Dual-read/alias shims easing the planned 0.9.0 renames: chart `no-*` boolean axes, `chart-legend-ui[interactive]`, `pane-ui[edge]`, the `color-area-ui` alias, and `menu-item-ui[description]`. Old names keep working this cut; the breaking removals ride 0.9.0 per the migration guide.
+- **Rename-wave W1 compat shims (gh#1560, PR #1565).** `data-sidebar-resize` / `data-layout-grid` are dual-read alongside the legacy `data-resize` / `data-grid` stamps.
+
+### Changed
+- **Rename-wave W2 (gh#1561, PR #1567).** In-repo consumers, demos, and docs migrate to the new `data-sidebar-resize` / `data-layout-grid` names; the W1 shims keep external consumers working.
+
+### Fixed
+- **`table-toolbar`** falls back to the column key when a column label is whitespace-only, and hides the title cluster when it has nothing to show (PR #1573, gh#1571 family).
+
+### Maintenance
+- ADR-0069 Class-R derived artifacts re-derived on main by the new `derived-resync` job (PR #1568).
+- Demo-attribute sweep touched `traits/view-transition`'s examples (one dead attribute dropped, gh#1576 family, PR #1584) — no trait API change.
+- **`components/` touched in this release window** (62 file(s), e.g. `chart-legend/chart-legend.a2ui.json`) — carried by the entries above.
+- **`core/` touched in this release window** (1 file(s), e.g. `core/icons.js`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (4 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (2 file(s), e.g. `admin-shell/admin-shell.examples.html`) — carried by the entries above.
+- **`styles/` touched in this release window** (1 file(s), e.g. `styles/components.css`) — carried by the entries above.
+
 ## [0.8.41] — 2026-08-17
 
 ### Added

package/MIGRATION.md

@@ -82,6 +82,12 @@ Version cuts and migration scope:
 
 - **Shipped in `0.8.41` (`image-ui` load/error states declared + converge to bare attributes, gh#1464)** — **BREAKING, no deprecation alias.** The final residue of the [data-* usage sweep](https://github.com/adiahealth/gen-ui-kit/issues/1332), deferred out of the residual round above because it needed a new `states:` declaration rather than a bare mapping change: `<image-ui>`'s `[data-loaded]`/`[data-error]` were genuine undeclared host-level state (never yaml-declared at all) — now declared as `loaded`/`error` in `image.yaml`'s `states:` list with bare `attribute:` mappings, matching qr-code-ui's own converged `error` state. Migration: any `[data-loaded]`/`[data-error]` CSS or script targeting `image-ui` moves to `[loaded]`/`[error]`; `image-ui`'s unrelated `[data-overlay]` skeleton-proximity marker (gh#1362) is untouched. A repo-wide consumer sweep (`rg -nU 'data-loaded|data-error'`) found zero external consumers of image-ui's forms specifically, so no deprecation alias was kept. The same ticket also dispositioned the `data-msg-*` validation-message config family (`data-msg-required`/`pattern`/`minlength`/`maxlength`/`min`/`max`/`bad-input`) as **exempt, non-breaking, no migration** — it stays `data-*` by design (component-side config read by `core/form.js`'s shared mixin across 7+ components, not host-reflected state; see `primitive-authoring/references/yaml-contract.md`'s new `data-msg-*` section for the full rationale). See [§ Shipped in `0.8.41` — image-ui load/error states declared + converge to bare attributes](#upcoming--image-ui-loaderror-states-declared--converge-to-bare-attributes-090-gh1464).
 
+- **Upcoming `0.9.0` (rename wave — `data-grid` / `data-resize`, docs/ops/plan/plan-090-rename-wave.md)** — **BREAKING at the 0.9.0 cut; a 0.8.x patch ships additive dual-read compat shims first (this entry), per the 2026-08-14 standing ruling that breaking renames never ship in a patch.** `admin-shell`'s consumer-authored 2/3-column content-layout helper `[data-grid]` / `[data-grid="3"]` renames to `[data-layout-grid]` / `[data-layout-grid="3"]` (sits with the `data-col`/`data-row`/`data-actions`/`data-spacer` form-layout-helper family it belongs to, outside every trait-owned root). The author-supplied drag-handle child of `<admin-sidebar>`/`<chat-sidebar>`/`<editor-sidebar>` `[data-resize]` renames to `[data-sidebar-resize]` (owner-scoped to the `*-sidebar` composite family, outside resize-observer's grandfathered `resize` root). Both attributes decorate plain light-DOM children the shells don't own (not a trait/component API), so only the name changes. **Now (0.8.x, additive):** both old and new names work — JS reads dual-query (new name first, falling back to old with a one-time `console.warn`), CSS selectors dual-select via `:is()`, and `adia-lint`'s SHELL-RESIZE rule accepts either name (advisory `DEPRECATED-LAYOUT-NAME` flags the old ones). **At the `0.9.0` cut:** the old names stop resolving — `[data-resize]` reverts to `<admin-sidebar>`'s existing "no handle found" author warning (the correct post-cut behavior, no new code needed) and `[data-grid]` simply no longer matches any CSS rule. Migration (published again, final, at the cut): `git grep -l 'data-resize' | xargs perl -pi -e 's/\bdata-resize\b(?!-)/data-sidebar-resize/g'` and `git grep -l 'data-grid' | xargs perl -pi -e 's/\bdata-grid\b(?!-)/data-layout-grid/g'` (negative lookahead protects trait-owned `data-resize-*`/`data-grid-*` names — unrelated grandfathered attributes, e.g. resize-observer's `data-resize-width`/`data-resize-observer-observed` and arrow-grid-nav's `data-grid-columns`/`mode`/`active-row`/`active-col`, which this wave never touches). Tracked: gh#1560 (this shim) → gh#1561 (in-repo consumer + docs migration) → gh#1562 (the 0.9.0 cut). Disjoint from, and coordinated with, gh#1377/gh#1563's ADR-0063 rename set (chart `hide-*`, `pane[side]`, `color-picker-ui` → `color-area-ui`, `menu-item-ui[subtitle]`) — same 0.9.0 cycle, separate PRs, no file overlap.
+
+- **Upcoming `0.9.0` (ADR-0063 attribute-grammar addendum — chart `no-*`, `chart-legend[interactive]`, `pane[edge]`, `color-area-ui`, `menu-item[description]`, gh#1377/gh#1563)** — **BREAKING at the 0.9.0 cut; a 0.8.42 patch ships additive dual-read compat shims first (this entry), per the same 2026-08-14 standing ruling gh#1560's rename wave follows: breaking renames never ship in a patch.** Five identifiers converge onto ADR-0063's ratified spellings: `chart-ui[hideAverage|hideGrid|hideValues]` → `[noAverage|noGrid|noValues]` (same polarity, straight rename — `no-*` has 8-component/12-attribute plurality over `hide-*`'s 2/4); `chart-legend-ui[static]` (opt-out) → `[interactive]` (opt-in) — **the default itself is NOT flipped in 0.8.42**, `[interactive]` defaults `true` so omitting both attributes keeps today's behavior unchanged, the real default-inversion to `false` is deferred to the 0.9.0 cut per the ADR's own consumer-scan requirement (every `<chart-legend-ui>` tag needs review first); `pane-ui[side]` → `[edge]` (pane-only — `drawer-ui[side]` keeps its own name/vocabulary unchanged); `menu-item-ui[subtitle]` → `[description]` (prop only — the `subtitle` SLOT is a separate, deliberately unrenamed surface); and the tag/component rename `color-picker-ui`/`ColorPicker`/`UIColorPicker` → `color-area-ui`/`ColorArea`/`UIColorArea` (B11 — `-picker` is reserved for the outer trigger+popover composite shape; `color-picker-ui` was the sole violator, playing `calendar-grid-ui`'s inline-substrate role — mirrors the `datetime-picker-ui` → `calendar-picker-ui` alias shape from gh#1372). **Now (0.8.42, additive):** every old name/tag keeps working — each renamed attribute dual-reads (new name wins when both are present, the old name resolves with a one-time `console.warn` when it's the only one set, no warn either way otherwise) and `<color-picker-ui>` is a thin `UIColorArea` subclass (`status: deprecated`) rather than a removed tag. `<color-input-ui>`'s own `composes:` and internal substrate references move to `<color-area-ui>` (its own tag/name is unaffected — it was already correctly *not* named `-picker` despite playing the composite role). **At the `0.9.0` cut:** the old names/tag stop resolving and `chart-legend-ui[interactive]`'s default flips to `false`. Migration (mechanical, at the cut): `git grep -l 'hide-average\|hide-grid\|hide-values' | xargs perl -pi -e 's/\bhide-average\b/no-average/g; s/\bhide-grid\b/no-grid/g; s/\bhide-values\b/no-values/g'`; `git grep -l 'pane-ui' | xargs perl -pi -e 's/(<pane-ui\b[^>]*\b)side=/\1edge=/g'`; `git grep -l 'menu-item-ui' | xargs perl -pi -e 's/(<menu-item-ui\b[^>]*\b)subtitle=/\1description=/g'`; `git grep -rl 'color-picker-ui\|UIColorPicker' | xargs perl -pi -e 's/color-picker-ui/color-area-ui/g; s/UIColorPicker/UIColorArea/g'`; every `<chart-legend-ui>` tag (with or without `[static]`/`[interactive]`) needs a manual pass adding `[interactive]` where the old default was relied on. Filed from the catalog-regularity audit's B2/B3(noodles-only, non-breaking)/B5/B11 findings (gh#1363) via [ADR-0063](../../docs/ops/adr/adr-0063-attribute-grammar-addendum.md). **Rejected/deferred, not part of this dispatch's five items:** `action-item-ui[subtitle]` (a newly-surfaced sole outlier once menu-item converges — flagged for a human decision, not fixed here); `segmented-ui[multiple]`'s comma-separated value encoding (operator-sanctioned as-is); `toggle-group-ui[value]`'s comma-string violation (tracked by gh#1363's own toggle-group/segmented consolidation candidate); `drilldown-ui[static]`→`[no-slide-transition]`, `alert-ui[dismissible]`, `card-ui[outline]`, `agent-reasoning-ui[status="done"]`→`"completed"`, and `noodles-ui[port-size]`/`[show-ports]` duplicate-entry cleanup (all ADR-0063 decisions, but each is its own separately-scoped follow-up build, not gh#1563's five-item scope). Disjoint from, and coordinated with, gh#1560/gh#1561/gh#1562's `data-grid`/`data-resize` rename wave — same 0.9.0 cycle, separate PRs, no file overlap. See [§ Upcoming — ADR-0063 attribute-grammar addendum](#upcoming--adr-0063-attribute-grammar-addendum-chart-no--chart-legendinteractive-paneedge-color-area-ui-menu-itemdescription-090-gh1377gh1563).
+
+- **Upcoming `0.9.0` (ADR-0063 convergence — `action-item-ui[description]`, gh#1571)** — **BREAKING at the 0.9.0 cut; an additive patch ships a dual-read compat shim first (this entry), per the same 2026-08-14 standing ruling gh#1560's rename wave and gh#1563's ADR-0063 addendum both follow: breaking renames never ship in a patch.** `action-item-ui[subtitle]` → `[description]` (prop only — the `subtitle` **slot** is a separate, deliberately unrenamed surface, exactly like `menu-item-ui`'s own gh#1563 shape). This closes the gap PR #1569 itself flagged as a rejected/deferred follow-up once `menu-item-ui` converged onto `description`: `action-item-ui` became the corpus's remaining sole `subtitle` outlier. **Now (additive):** both names work — `[description]` wins outright when present (no warning — this is intentional forward-compatible spelling, not a fallback); `[subtitle]` resolves with a one-time `console.warn` per class when it's the only one set; a post-mount `[subtitle]` update keeps mirroring into `[description]` until `[description]` is authored directly, at which point it wins permanently. **At the `0.9.0` cut:** `[subtitle]` stops resolving. Migration (mechanical, at the cut): `git grep -l '<action-item-ui\b' | xargs perl -pi -e 's/(<action-item-ui\b[^>]*\b)subtitle=/\1description=/g'`. See [§ Upcoming — `action-item-ui[description]` ADR-0063 convergence](#upcoming--action-item-uidescription-adr-0063-convergence-090-gh1571). **Rejected/deferred:** the 0.9.0 breaking removal itself — same "no breaking rename in a patch" standing ruling as every sibling entry above.
+
 Live demos and per-component docs at [ui-kit.exe.xyz/site/](https://ui-kit.exe.xyz/site/). The `adia-ui-migration` skill (in `.agents/skills/`) automates most of the mechanical sweeps in this guide.
 
 ---
@@ -1650,6 +1656,187 @@ npm run check
 
 ---
 
+## Upcoming — ADR-0063 attribute-grammar addendum (chart no-*, chart-legend[interactive], pane[edge], color-area-ui, menu-item[description], 0.9.0, gh#1377/gh#1563)
+
+**Shipped additively in `0.8.42`; BREAKING removal deferred to the `0.9.0`
+cut** — per the same 2026-08-14 standing ruling gh#1560's `data-grid`/
+`data-resize` rename wave follows: a breaking rename never ships in a
+patch. [ADR-0063](../../docs/ops/adr/adr-0063-attribute-grammar-addendum.md)
+ratified six decisions from the catalog-regularity audit
+([gh#1363](https://github.com/adiahealth/gen-ui-kit/issues/1363)); this
+entry covers the five identifiers gh#1563's own build scope named. (The
+sixth — `agent-reasoning-ui[status]`'s `done`→`completed` stage-terminal
+convergence — and the `alert`/`card`/`drilldown`/`noodles` decision-2
+items ship under their own separately-scoped follow-up tickets, not
+this one.)
+
+### What changed (additive, 0.8.42)
+
+| Component | Old (deprecated, still works) | New (canonical) | Shape |
+|---|---|---|---|
+| `<chart-ui>` | `[hide-average]` | `[no-average]` | straight rename, same polarity |
+| `<chart-ui>` | `[hide-grid]` | `[no-grid]` | straight rename, same polarity |
+| `<chart-ui>` | `[hide-values]` | `[no-values]` | straight rename, same polarity |
+| `<chart-legend-ui>` | `[static]` (opt-out) | `[interactive]` (opt-in) | polarity flip — **default NOT yet flipped**, see below |
+| `<pane-ui>` | `[side]` | `[edge]` | straight rename, same type/default/enum (`drawer-ui[side]` is untouched — different component, different vocabulary) |
+| `<menu-item-ui>` | `[subtitle]` prop | `[description]` prop | straight rename — the `subtitle` **slot** is a separate surface, deliberately left unrenamed |
+| `<color-picker-ui>` (tag) | `color-picker-ui` / `ColorPicker` / `UIColorPicker` | `color-area-ui` / `ColorArea` / `UIColorArea` | tag/component/class rename (B11, picker-naming convention) — old tag is now a thin `UIColorArea` subclass, `status: deprecated` |
+
+Every renamed attribute dual-reads: **new name wins** when both are
+present (no warning — this is intentional forward-compatible spelling,
+not a fallback); the **old name resolves** with a one-time
+`console.warn` per class when it's the only one set; neither present
+keeps today's default. `<color-picker-ui>` keeps rendering/behaving
+identically — it inherits every prop, event, and token from
+`<color-area-ui>` verbatim (mirrors the `<datetime-picker-ui>` →
+`<calendar-picker-ui>` alias shape from
+[gh#1372](https://github.com/adiahealth/gen-ui-kit/issues/1372)).
+`<color-input-ui>`'s own `composes:` list and internal substrate
+references move to `<color-area-ui>`; `<color-input-ui>`'s own tag/name
+is unaffected (it was already correctly *not* named `-picker` despite
+playing the outer trigger+popover composite role).
+
+**`chart-legend-ui[interactive]`'s default is deliberately NOT flipped
+in this release.** `[interactive]` defaults `true` — a `<chart-legend-ui>`
+naming neither `[static]` nor `[interactive]` renders exactly as it
+does today (interactive `<button>`-role rows). The ADR's own
+"default-inversion" consumer-scan requirement — every `<chart-legend-ui>`
+tag, with or without either attribute, reviewed for whether omission
+was relying on the old default — is the 0.9.0 cut's own prerequisite,
+not this one's.
+
+### Migration (mechanical, recommended now / required at the 0.9.0 cut)
+
+```bash
+git grep -l 'hide-average\|hide-grid\|hide-values' -- packages apps playgrounds site site-a2ui \
+  | xargs perl -pi -e 's/\bhide-average\b/no-average/g; s/\bhide-grid\b/no-grid/g; s/\bhide-values\b/no-values/g'
+
+git grep -l '<pane-ui\b' -- packages apps playgrounds site site-a2ui \
+  | xargs perl -pi -e 's/(<pane-ui\b[^>]*\b)side=/\1edge=/g'
+
+git grep -l '<menu-item-ui\b' -- packages apps playgrounds site site-a2ui \
+  | xargs perl -pi -e 's/(<menu-item-ui\b[^>]*\b)subtitle=/\1description=/g'
+
+git grep -rl 'color-picker-ui\|UIColorPicker' -- packages apps playgrounds site site-a2ui \
+  | xargs perl -pi -e 's/color-picker-ui/color-area-ui/g; s/UIColorPicker/UIColorArea/g'
+```
+
+Every `<chart-legend-ui>` tag additionally needs a manual (not
+mechanical) review pass: add `[interactive]` explicitly wherever the
+page relied on the current "interactive by default" behavior, ahead of
+the 0.9.0 default-inversion.
+
+**Find every affected consumer site:**
+
+```bash
+npm run qa:contract-migration-scan -- --roots packages,apps,playgrounds,site,site-a2ui \
+  --base <pre-upgrade-ref> --head <post-upgrade-ref>
+rg -nU 'hide-average|hide-grid|hide-values|<pane-ui\b[^>]*\bside=|<menu-item-ui\b[^>]*\bsubtitle=|color-picker-ui|UIColorPicker' \
+  -g '!**/dist/**' -g '!**/*.a2ui.json' -g '!docs/adr/**'
+```
+
+`--roots packages,apps,playgrounds,site,site-a2ui` is required (not the
+scanner's own default) — `site-a2ui/` is a separate top-level directory
+the default roots miss entirely (ADR-0063's own consumer-scan
+mechanism section explains why).
+
+### Rejected / deferred (explicitly out of gh#1563's scope)
+
+- `action-item-ui[subtitle]` — once `menu-item-ui` converges onto
+  `description`, `action-item-ui` becomes the corpus's new sole
+  `subtitle` outlier (the same shape of defect ADR-0063 just fixed for
+  menu-item). Flagged as a discovered follow-up candidate for a human
+  ticketing decision — not fixed in this dispatch.
+- `segmented-ui[multiple]`'s comma-separated value encoding — sanctioned
+  as-is (operator ruling, gh#1563, 2026-08-17).
+- `toggle-group-ui[value]`'s comma-string violation — tracked by
+  gh#1363's own `toggle-group`/`segmented` consolidation candidate, not
+  duplicated here.
+- `drilldown-ui[static]` → `[no-slide-transition]`, `alert-ui[dismissible]`
+  retirement, `card-ui[outline]` retirement,
+  `agent-reasoning-ui[status="done"]` → `"completed"`, and
+  `noodles-ui[port-size]`/`[show-ports]` duplicate-entry cleanup — all
+  real ADR-0063 decisions, each its own separately-scoped follow-up
+  build, not part of gh#1563's five-item scope.
+- `menu-item-ui`'s `subtitle` **slot** (distinct from the prop) — left
+  unrenamed by design; renaming a slot is a different, unscoped surface.
+
+### Verify
+
+```bash
+npm run qa:contract-migration-scan -- --roots packages,apps,playgrounds,site,site-a2ui \
+  --base <pre-upgrade-ref> --head <post-upgrade-ref>
+node scripts/build/components.mjs --verify
+npm run check
+```
+
+---
+
+## Upcoming — `action-item-ui[description]` ADR-0063 convergence (0.9.0, gh#1571)
+
+**Shipped additively; BREAKING removal deferred to the `0.9.0` cut** — per
+the same 2026-08-14 standing ruling gh#1560's `data-grid`/`data-resize`
+rename wave and gh#1563's ADR-0063 addendum both follow: a breaking rename
+never ships in a patch. This closes the gap [PR
+#1569](https://github.com/adiahealth/gen-ui-kit/pull/1569) itself flagged
+under its own "Rejected/deferred" section: once `<menu-item-ui>` converged
+its `subtitle` prop onto `description` ([ADR-0063](../../docs/ops/adr/adr-0063-attribute-grammar-addendum.md),
+gh#1563), `<action-item-ui>` became the corpus's remaining sole `subtitle`
+outlier — the same shape of defect ADR-0063 fixed for menu-item.
+
+### What changed (additive)
+
+| Component | Old (deprecated, still works) | New (canonical) | Shape |
+|---|---|---|---|
+| `<action-item-ui>` | `[subtitle]` prop | `[description]` prop | straight rename — the `subtitle` **slot** is a separate surface, deliberately left unrenamed |
+
+`[description]` wins outright when present (no warning — this is
+intentional forward-compatible spelling, not a fallback); `[subtitle]`
+resolves with a one-time `console.warn` per class when it's the only one
+set; neither present keeps today's default (empty string, no rendered
+subtitle row). Unlike `menu-item-ui`'s own gh#1563 shim (which only
+resolves once, at `connected()`), `action-item-ui`'s shim re-resolves on
+every render until `[description]` is authored directly, so a post-mount
+`[subtitle]` attribute update keeps propagating exactly as it did before
+this shim existed — once `[description]` is set directly (by attribute or
+property), it wins permanently and further `[subtitle]` churn is ignored.
+
+### Migration (mechanical, recommended now / required at the 0.9.0 cut)
+
+```bash
+git grep -l '<action-item-ui\b' -- packages apps playgrounds site site-a2ui \
+  | xargs perl -pi -e 's/(<action-item-ui\b[^>]*\b)subtitle=/\1description=/g'
+```
+
+**Find every affected consumer site:**
+
+```bash
+npm run qa:contract-migration-scan -- --roots packages,apps,playgrounds,site,site-a2ui \
+  --base <pre-upgrade-ref> --head <post-upgrade-ref>
+rg -nU '<action-item-ui\b[^>]*\bsubtitle=' \
+  -g '!**/dist/**' -g '!**/*.a2ui.json' -g '!docs/adr/**'
+```
+
+### Rejected / deferred
+
+- The 0.9.0 breaking removal itself — deferred under the same "no breaking
+  rename in a patch" 2026-08-14 standing ruling every sibling rename-wave
+  entry in this guide follows.
+- `action-item-ui`'s `subtitle` **slot** (distinct from the prop) — left
+  unrenamed by design, same as `menu-item-ui`'s own gh#1563 shape;
+  renaming a slot is a different, unscoped surface.
+
+### Verify
+
+```bash
+npm run qa:contract-migration-scan -- --roots packages,apps,playgrounds,site,site-a2ui \
+  --base <pre-upgrade-ref> --head <post-upgrade-ref>
+node scripts/build/components.mjs --verify
+npm run check
+```
+
+---
+
 ## Migrating to `@adia-ai/*@v0.8.23` (2026-07-30)
 
 - **Removed: the `--a-font` alias** (pre-ADR-0035 name, DEPRECATED since the 0.8.x line). Any surviving `font-family: var(--a-font)` goes invalid-at-computed-value-time → `inherit` → UA **serif** — the visible symptom is Times-faced labels on an otherwise-correct page.

package/USAGE.md

@@ -437,7 +437,7 @@ Some primitives emit named events beyond `change`/`input`:
 - `<select-ui>` — emits `action` for option-callbacks with `detail.action`
 - `<search-ui>` — emits `search` after debounce with `detail.value`
 - `<chat-composer>` — emits `composer-submit` on Enter with `detail.value`
-- `<color-picker-ui>` — emits `input` + `change` with rich detail (`{ value, l, c, h, hex, oklch }`)
+- `<color-area-ui>` — emits `input` + `change` with rich detail (`{ value, l, c, h, hex, oklch }`)
 
 Each primitive's yaml lists its complete event surface. Live demos at `https://ui-kit.exe.xyz/site/components/<name>`.
 
@@ -1208,18 +1208,18 @@ When a custom `[slot="header"]` carries action buttons (Copy / Download / Edit),
 
 §206 (v0.5.7) added the `[slot="action"]` / `[slot="actions"]` / `[data-no-toggle]` exclusion list to the toggle-cascade.
 
-### §221f — `<color-picker-ui>` inline pattern
+### §221f — `<color-area-ui>` inline pattern
 
 For a compact swatch-and-popover authoring shape:
 
 ```html
 <popover-ui trigger="click" placement="bottom-start">
   <button-ui slot="trigger" text="" icon="palette" aria-label="Pick a color"></button-ui>
-  <color-picker-ui slot="content" value="oklch(0.7 0.15 220)" alpha="off"></color-picker-ui>
+  <color-area-ui slot="content" value="oklch(0.7 0.15 220)" alpha="off"></color-area-ui>
 </popover-ui>
 ```
 
-The popover handles focus management + click-outside dismiss; the button-ui exposes the right ARIA semantics. `<color-picker-ui>` fires `change` events that bubble through the popover — listen on the popover host.
+The popover handles focus management + click-outside dismiss; the button-ui exposes the right ARIA semantics. `<color-area-ui>` fires `change` events that bubble through the popover — listen on the popover host. (`<color-area-ui>` is the ADR-0063/gh#1563 rename of `<color-picker-ui>`, which still works as a deprecated alias — this recipe is exactly what `<color-input-ui>` canonicalizes.)
 
 ### §221g — `[data-scheme]` ancestor opt-in for color scheme
 

package/components/action-list/action-item.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ActionItem.json",
   "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": [
     {
@@ -13,6 +13,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"
     },
@@ -26,7 +31,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": ""
     },
@@ -80,7 +85,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."

package/components/action-list/action-item.yaml

@@ -17,9 +17,10 @@ category: navigation
 version: 1
 description: |-
   Child of <action-list-ui>. One actionable row — icon + label + optional
-  subtitle, forwards activation to the parent action-list. Row contract
-  converges on <menu-item-ui>: icon/text/subtitle/value/variant/disabled
+  description, forwards activation to the parent action-list. Row contract
+  converges on <menu-item-ui>: icon/text/description/value/variant/disabled
   props and icon/text/subtitle/trailing slot overrides (#1363 C5).
+  (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1571.)
 
 props:
   icon:
@@ -29,7 +30,20 @@ props:
     description: Action label.
     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: ''
+  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: ''
   value:
@@ -55,8 +69,10 @@ slots:
     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.
+      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.
   trailing:
     description: >-
       Trailing element pinned to the far edge (shortcut hint, badge, caret).
@@ -82,7 +98,7 @@ a2ui:
   allowedParents:
     - ActionList
   rules:
-    - rule: 'Child of <action-list-ui> — one inline-action row with icon + label + optional subtitle + optional trailing shortcut/badge.'
+    - rule: 'Child of <action-list-ui> — one inline-action row with icon + label + optional description + optional trailing shortcut/badge.'
       reason: 'Action-list cluster contract.'
     - rule: 'Different from <menu-item-ui>: action-items live inline in content surfaces; menu-items live inside <menu-ui> popovers.'
       reason: 'Context boundary.'
@@ -90,5 +106,7 @@ a2ui:
       reason: 'Different intent — actions vs navigation.'
     - rule: 'Use [variant="danger"] exclusively for destructive/irreversible actions (Delete, Remove). Pair danger items with an explicit confirm flow when the action cannot be undone.'
       reason: 'Converged with <menu-item-ui>''s danger-variant guidance (#1363 C5).'
-    - rule: '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).'
+    - rule: '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).'
       reason: 'Row-contract convergence with <menu-item-ui> (#1363 C5).'
+    - rule: '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.'
+      reason: 'Convergence with <menu-item-ui>''s own subtitle -> description rename (gh#1563).'

package/components/action-list/action-list.class.js

@@ -94,7 +94,14 @@ export class UIActionItem extends UIElement {
   static properties = {
     icon:     { type: String,  default: '', reflect: true },
     text:     { type: String,  default: '', reflect: true },
+    // ADR-0063 (gh#1571) — `subtitle` is DEPRECATED (action-item was the
+    // corpus's remaining `subtitle` outlier once <menu-item-ui> converged
+    // under gh#1563); `description` is canonical. `subtitle` stays declared
+    // (dual-read compat, additive). The `subtitle` SLOT (a separate
+    // surface — see action-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 },
@@ -102,6 +109,51 @@ export class UIActionItem extends UIElement {
 
   static template = () => null;
 
+  // ADR-0063 (gh#1571) one-shot-per-class deprecation warn for [subtitle].
+  static #warnedSubtitle = false;
+
+  // Guards + tracks the [subtitle] -> [description] compat mirror (below).
+  // action-item-ui (unlike menu-item-ui) has pre-existing tests that set
+  // [subtitle] AFTER mount and expect the rendered row to keep tracking it
+  // (gh#1374) — a resolve-once-at-connect shim (menu-item-ui's own shape)
+  // would silently stop mirroring once `description` picks up its first
+  // reflected value. `#mirroring` suppresses the authored-flag while WE
+  // write `this.description` ourselves; `#descriptionAuthored` latches
+  // true the moment a REAL (non-mirrored) `description` attribute shows
+  // up, so [description] wins permanently from that point on, even
+  // across later [subtitle] attribute churn.
+  #mirroring = false;
+  #descriptionAuthored = false;
+
+  attributeChangedCallback(name, oldVal, val) {
+    if (name === 'description' && !this.#mirroring) this.#descriptionAuthored = true;
+    super.attributeChangedCallback(name, oldVal, val);
+  }
+
+  // ADR-0063 (gh#1571) compat shim. New-name precedence: once [description]
+  // has ever been authored directly, it wins outright and [subtitle] is
+  // ignored from then on. Until then, [subtitle] mirrors into [description]
+  // on every resolve (initial connect AND every subsequent render), so a
+  // post-mount [subtitle] update keeps propagating exactly like it did
+  // before this shim existed.
+  #resolveSubtitleCompat() {
+    if (this.#descriptionAuthored) return;
+    const mirrored = this.hasAttribute('subtitle') ? this.subtitle : '';
+    if (this.description === mirrored) return;
+    this.#mirroring = true;
+    this.description = mirrored;
+    this.#mirroring = false;
+    if (mirrored && !UIActionItem.#warnedSubtitle) {
+      UIActionItem.#warnedSubtitle = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[AdiaUI] <action-item-ui [subtitle]> is deprecated — use ' +
+        '[description] instead (ADR-0063, gh#1571). Kept working as-is; ' +
+        'no behavior change.',
+      );
+    }
+  }
+
   // Set when connected()/render() stamped this fallback child from a prop —
   // never touch a consumer-authored slot="icon"/"text"/"subtitle" child
   // (ADR-0010, slot content is source of truth). Mirrors menu-item-ui's
@@ -118,6 +170,10 @@ export class UIActionItem extends UIElement {
   }
 
   connected() {
+    // ADR-0063 (gh#1571) compat shim — resolve BEFORE #stamp() reads
+    // `this.description`, so there's no wrong-then-right flash.
+    this.#resolveSubtitleCompat();
+
     // Adopt-or-stamp (gh#753): a consumer-authored role survives connect —
     // only stamp "listitem" when the host has no author-set role at all.
     if (!this.hasAttribute('role')) this.setAttribute('role', 'listitem');
@@ -143,10 +199,10 @@ export class UIActionItem 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);
     }
   }
@@ -162,6 +218,11 @@ export class UIActionItem extends UIElement {
   }
 
   render() {
+    // ADR-0063 (gh#1571) compat shim — re-resolve on every render so a
+    // post-mount [subtitle] update keeps mirroring into [description]
+    // until an author sets [description] directly (see #resolveSubtitleCompat).
+    this.#resolveSubtitleCompat();
+
     // Sync icon — only touch elements we stamped.
     const iconEl = this.#ownChild('[slot="icon"]');
     if (this.icon) {
@@ -181,15 +242,16 @@ export class UIActionItem 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#1571)
+    // — 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 sub = this.#stampMark(document.createElement('span'));
         sub.setAttribute('slot', 'subtitle');
-        sub.textContent = this.subtitle;
+        sub.textContent = this.description;
         this.appendChild(sub);
       }
     } else if (this.#wasStamped(subEl)) {

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

@@ -34,11 +34,13 @@ export class UIActionList extends UIElement {
 }
 
 export class UIActionItem extends UIElement {
+  /** 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. */
+  description: string;
   /** Disables click + keyboard activation; aria-disabled is set. */
   disabled: boolean;
   /** Leading icon name (Phosphor). */
   icon: string;
-  /** Optional secondary description line rendered under the label. */
+  /** 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.) */
   subtitle: string;
   /** Action label. */
   text: string;

package/components/chart/chart.a2ui.json

@@ -88,17 +88,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
     },
@@ -107,6 +107,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",