@adia-ai/web-components 0.8.38 → 0.8.40

package/components/select/select.class.js

@@ -439,8 +439,14 @@ export class UISelect extends UIFormElement {
           : this.icon
             ? `<icon-ui slot="leading" data-select-leading name="${escapeHTML(this.icon)}"></icon-ui>`
             : '';
+      // No native <input> wrap (per ADR-0055 / ADR-0025): the searchable
+      // trigger is a `contenteditable="plaintext-only"` surface carrying
+      // `role="combobox"`, mirroring combobox-ui's editable-surface pattern.
+      // Placeholder text renders via the [data-empty]::before pseudo (see
+      // select.css), same mechanism as input-ui / combobox-ui.
+      const initialDisplayText = this.#displayText() === this.placeholder ? '' : this.#displayText();
       const displayMarkup = this.searchable
-        ? `<input slot="display" type="text" role="combobox" aria-autocomplete="list" autocomplete="off" placeholder="${escapeHTML(this.placeholder || '')}" value="${escapeHTML(this.#displayText() === this.placeholder ? '' : this.#displayText())}" />`
+        ? `<span slot="display" contenteditable="plaintext-only" role="combobox" aria-autocomplete="list" tabindex="0" data-placeholder="${escapeHTML(this.placeholder || '')}"${initialDisplayText ? '' : ' data-empty'}>${escapeHTML(initialDisplayText)}</span>`
         : `<span slot="display">${escapeHTML(this.#displayText())}</span>`;
       // §184 (v0.5.5, FEEDBACK-08 §7): optional hint slot beneath the
       // trigger. Mirrors slider-ui's hint pattern + matches the
@@ -478,7 +484,7 @@ export class UISelect extends UIFormElement {
           this.#searchInput.removeEventListener('focus', this.#onSearchFocus);
           this.#searchInput.removeEventListener('click', this.#onSearchClick);
         }
-        this.#searchInput = this.querySelector('input[slot="display"]');
+        this.#searchInput = this.querySelector('[slot="display"][contenteditable]');
         if (this.#searchInput) {
           this.#searchInput.addEventListener('input', this.#onSearchInput);
           this.#searchInput.addEventListener('focus', this.#onSearchFocus);
@@ -492,9 +498,13 @@ export class UISelect extends UIFormElement {
       const display = this.querySelector('[slot="display"]');
       if (display && !this.multiple) {
         // Single-select: keep the canonical text-rendering path.
-        if (display.tagName === 'INPUT') {
-          // Only update value when not actively editing (no active query)
-          if (!this.#query) display.value = this.#displayText() === this.placeholder ? '' : this.#displayText();
+        if (display.hasAttribute('contenteditable')) {
+          // Only update text when not actively editing (no active query)
+          if (!this.#query) {
+            const text = this.#displayText() === this.placeholder ? '' : this.#displayText();
+            display.textContent = text;
+            display.toggleAttribute('data-empty', !text);
+          }
         } else {
           display.textContent = this.#displayText();
         }
@@ -502,10 +512,13 @@ export class UISelect extends UIFormElement {
         // Multi-select: display element holds the placeholder ONLY when
         // no chips are present (otherwise the chip row IS the display).
         const hasChips = this.#values().length > 0;
-        if (display.tagName === 'INPUT') {
+        if (display.hasAttribute('contenteditable')) {
           // search input — keep placeholder; never inject the value text.
-          display.placeholder = hasChips ? '' : (this.placeholder || '');
-          if (!this.#query) display.value = '';
+          display.setAttribute('data-placeholder', hasChips ? '' : (this.placeholder || ''));
+          if (!this.#query) {
+            display.textContent = '';
+            display.toggleAttribute('data-empty', true);
+          }
         } else {
           display.textContent = hasChips ? '' : (this.placeholder || '');
         }
@@ -991,7 +1004,7 @@ export class UISelect extends UIFormElement {
     // before it would start removing query characters.
     if (e.key === 'Backspace' && this.multiple && !this.disabled && !this.readonly) {
       const target = e.target;
-      const fromInput = target && target.tagName === 'INPUT' && target.getAttribute('slot') === 'display';
+      const fromInput = target && target.hasAttribute?.('contenteditable') && target.getAttribute('slot') === 'display';
       const queryEmpty = !this.#query || this.#query.length === 0;
       if (!fromInput || queryEmpty) {
         if (this.#values().length > 0) {
@@ -1005,8 +1018,11 @@ export class UISelect extends UIFormElement {
       if (this.searchable && this.#query) {
         // First Escape: clear query
         this.#query = '';
-        const input = this.querySelector('input[slot="display"]');
-        if (input) input.value = '';
+        const input = this.querySelector('[slot="display"][contenteditable]');
+        if (input) {
+          input.textContent = '';
+          input.toggleAttribute('data-empty', true);
+        }
         this.#applyFilter();
         return;
       }
@@ -1061,7 +1077,9 @@ export class UISelect extends UIFormElement {
   };
 
   #onSearchInput = (e) => {
-    this.#query = e.target.value || '';
+    const text = e.target.textContent || '';
+    this.#query = text;
+    e.target.toggleAttribute('data-empty', !text);
     if (!this.open) this.open = true;
     this.#applyFilter();
   };

package/components/select/select.css

@@ -91,7 +91,7 @@
     border: 1px solid var(--select-border);
     border-radius: var(--select-radius);
     background: var(--select-bg);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     cursor: pointer;
     /* Match every property the hover / focus / invalid states change. */
     transition:
@@ -130,7 +130,7 @@
     display: inline-flex;
     align-items: center;
     flex-shrink: 0;
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     --a-icon-size: var(--select-font-size);
     color: var(--select-fg-muted);
   }
@@ -149,7 +149,7 @@
     white-space: nowrap;
     color: var(--select-fg);
   }
-  input[slot="display"] {
+  [slot="display"][contenteditable] {
     border: none;
     outline: none;
     background: transparent;
@@ -159,9 +159,18 @@
     color: var(--select-fg);
     min-width: 0;
     width: 100%;
+    /* Positioning context for the [data-empty]::before placeholder pseudo
+       below — out-of-flow, same rationale as input-ui/combobox-ui: an
+       in-flow pseudo would render the caret after the placeholder text
+       instead of at content-start. */
+    position: relative;
   }
-  input[slot="display"]::placeholder {
+  [slot="display"][contenteditable][data-empty]::before {
+    content: attr(data-placeholder);
     color: var(--select-placeholder-fg);
+    pointer-events: none;
+    position: absolute;
+    inset: 0;
   }
   :scope:not([value]) [slot="display"],
   :scope[value=""] [slot="display"] {
@@ -405,7 +414,7 @@ select-ui [role="group"] [slot="group-label"] {
   font-weight: var(--a-ui-weight);
   color: var(--select-fg-muted);
   text-transform: uppercase;
-  letter-spacing: 0.05em;
+  letter-spacing: var(--a-font-tracking-wide);
   white-space: nowrap;
 }
 

package/components/spinner/spinner.css

@@ -178,7 +178,7 @@
       align-items: center;
       justify-content: center;
       font: inherit;
-      line-height: 1;
+      line-height: var(--a-font-leading-none);
       text-align: center;
       color: currentColor;
     }

package/components/stat/stat.css

@@ -171,7 +171,7 @@
     grid-area: label;
     font-size: var(--stat-label-size);
     color: var(--stat-label-fg);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
@@ -185,7 +185,7 @@
     align-items: center;
     gap: 0.25em;
     font-size: var(--stat-change-size);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     justify-self: start;
   }
 
@@ -195,7 +195,7 @@
     font-size: var(--stat-value-size);
     font-weight: var(--stat-value-weight);
     color: var(--stat-value-fg);
-    line-height: 1.2;
+    line-height: var(--a-font-leading-snug);
     min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;

package/components/step-progress/step-progress.css

@@ -46,7 +46,7 @@
   [slot="caption"] {
     color: var(--step-progress-caption-fg);
     font-size: var(--step-progress-caption-size);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
   }
 
   [slot="caption"][hidden] {

package/components/stepper/stepper.css

@@ -236,7 +236,7 @@
     display: block;
     font-weight: var(--stepper-item-label-weight);
     font-size: var(--stepper-item-label-size);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     color: var(--stepper-item-label-fg);
     min-width: 0;
     overflow-wrap: break-word;
@@ -247,7 +247,7 @@
     margin-top: var(--stepper-item-offset-xs);
     color: var(--stepper-item-desc-fg);
     font-size: var(--stepper-item-desc-size);
-    line-height: 1.5;
+    line-height: var(--a-font-leading-relaxed);
   }
 
   :scope [slot]:empty {

package/components/swatch/swatch.css

@@ -63,7 +63,7 @@
     min-width: 0;
     color: var(--swatch-label-fg);
     font-size: var(--swatch-label-size);
-    line-height: 1.2;
+    line-height: var(--a-font-leading-snug);
     vertical-align: baseline;
   }
 
@@ -238,7 +238,7 @@
     background: var(--swatch-badge-bg);
     color: var(--swatch-badge-fg);
     font-size: var(--swatch-badge-size);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     border-radius: var(--swatch-badge-radius);
     box-shadow: 0 0 0 1px color-mix(in oklab, var(--md-sys-color-neutral-outline-variant) 60%, transparent);
   }
@@ -274,20 +274,22 @@
     z-index: 1;
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] {
-    color: var(--a-chrome-light, #fafafa);
+    color: var(--a-chrome-light);
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-light] {
-    color: var(--a-chrome-dark, #111);
+    color: var(--a-chrome-dark);
   }
   /* Detail line follows the same auto-contrast choice. */
   :scope[shape="block"][auto-contrast] > [data-detail] {
     z-index: 1;
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] ~ [data-detail] {
-    color: color-mix(in oklab, var(--a-chrome-light, #fafafa) 80%, transparent);
+    color: var(--a-chrome-light);
+    opacity: 0.8;
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-light] ~ [data-detail] {
-    color: color-mix(in oklab, var(--a-chrome-dark, #111) 70%, transparent);
+    color: var(--a-chrome-dark);
+    opacity: 0.7;
   }
 
   /* ═══════ Copy button — a stamped <button-ui variant="ghost" size="sm">

package/components/table/table.a2ui.json

@@ -24,16 +24,6 @@
       "description": "JS property (set programmatically — `el.data = [...]`) — row records, an array of plain objects keyed to columns[].key. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect (gh#288) — the same pattern chart-ui's `data` attribute uses. Custom accessor on the element class, not a reflected attribute.",
       "$ref": "common_types.json#/$defs/DynamicObjectList"
     },
-    "density": {
-      "description": "Controls cell padding and row height. 'compact' for dense data, 'standard' for default spacing, 'comfortable' for spacious rows.",
-      "type": "string",
-      "enum": [
-        "compact",
-        "standard",
-        "comfortable"
-      ],
-      "default": "standard"
-    },
     "expandable": {
       "description": "Enable row expansion",
       "type": "boolean",

package/components/table/table.class.js

@@ -21,8 +21,11 @@
  *   sortable   — enable column sorting on header click
  *   selectable — enable row selection via checkboxes
  *   striped    — alternate row background
- *   density    — 'compact' | 'standard' | 'comfortable'
  *   valign     — 'center' (default) | 'top' — body-cell vertical alignment (gh#505)
+ *
+ * table-ui has no local `density` prop (ADR-0054) — it converges onto the
+ * ambient global [density="compact"|"spacious"] attribute; --table-py/-px
+ * already derive from --a-space-* steps, which --a-density scales.
  *   paginate   — rows per page (0 = no pagination)
  *   loading    — show loading overlay
  *   search     — global search filter string
@@ -118,7 +121,6 @@ export class UITable extends UIElement {
     frameless:  { type: Boolean, default: false, reflect: true },
     wrap:       { type: Boolean, default: false, reflect: true },
     raw:        { type: Boolean, default: false, reflect: true },
-    density:    { type: String,  default: 'standard', reflect: true },
     paginate:   { type: Number,  default: 0,     reflect: true },
     loading:    { type: Boolean, default: false, reflect: true },
     search:     { type: String,  default: '',    reflect: true },
@@ -294,7 +296,6 @@ export class UITable extends UIElement {
       columnWidths: Object.fromEntries(this.#columnWidths),
       hiddenColumns: this.#columns.filter(c => c.hidden).map(c => c.key),
       page: this.#page,
-      density: this.density,
     };
   }
 
@@ -319,7 +320,6 @@ export class UITable extends UIElement {
       }
     }
     if (state.page != null) this.#page = state.page;
-    if (state.density) this.density = state.density;
     this.#requestRender();
   }
 

package/components/table/table.css

@@ -463,14 +463,11 @@
 
   /* ═══════ Density ═══════ */
 
-  :scope[density="compact"] {
-    --table-py: var(--a-space-1);
-    --table-px: var(--a-space-2);
-  }
-
-  :scope[density="comfortable"] {
-    --table-py: var(--a-space-4);
-  }
+  /* No local override (ADR-0054 convergence) — --table-py/-px above already
+     derive from --a-space-* steps, which the ambient global
+     [density="compact"|"spacious"] attribute already scales via
+     --a-density. Do not reintroduce a component-local :scope[density=…]
+     block; that would re-shadow the global grammar (ADR-0053). */
 
   /* ═══════ Pinned cells ═══════ */
 
@@ -744,7 +741,7 @@
     grid-template-columns: subgrid;
     grid-column: 1 / -1;
     border-top: 2px solid var(--table-agg-border);
-    font-weight: 600;
+    font-weight: var(--a-weight-semibold);
     font-size: var(--table-agg-size);
     color: var(--table-fg-secondary);
   }

package/components/table/table.d.ts

@@ -90,8 +90,6 @@ export class UITable extends UIElement {
   columns: string;
   /** JS property (set programmatically — `el.data = [...]`) — row records, an array of plain objects keyed to columns[].key. May also be supplied declaratively as a JSON-array `data="[…]"` attribute, hydrated once at connect (gh#288) — the same pattern chart-ui's `data` attribute uses. Custom accessor on the element class, not a reflected attribute. */
   data: string;
-  /** Controls cell padding and row height. 'compact' for dense data, 'standard' for default spacing, 'comfortable' for spacious rows. */
-  density: 'compact' | 'standard' | 'comfortable';
   /** Enable row expansion */
   expandable: boolean;
   /** Drop the table's outer 1px perimeter and nothing else (gh#511) — row dividers are untouched (the perimeter is split onto its own --table-perimeter token, defaulting to --table-border). For card-composed tables: the card owns the frame, so the table's square perimeter otherwise renders a doubled edge (flush bleed) or a stray inner box (with content above). Standalone tables keep their chrome by default. Theming path without the attribute: set --table-perimeter to transparent per instance. Note: `<card-ui><section bleed>` already drops a direct-child table-ui's chrome automatically (card.css, gh#796) — `frameless`/`raw` on the instance still applies and is honored, but is no longer required just to avoid the doubled-edge look in that composition. */

package/components/table/table.yaml

@@ -36,15 +36,6 @@ props:
       type: object
     default: []
     dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
-  density:
-    description: Controls cell padding and row height. 'compact' for dense data, 'standard' for default
-      spacing, 'comfortable' for spacious rows.
-    type: string
-    default: standard
-    enum:
-      - compact
-      - standard
-      - comfortable
   expandable:
     description: Enable row expansion
     type: boolean

package/components/table-toolbar/table-toolbar.css

@@ -82,7 +82,7 @@
     font-size: var(--table-toolbar-title-size);
     font-weight: var(--table-toolbar-title-weight);
     color: var(--table-toolbar-title-fg);
-    line-height: 1.2;
+    line-height: var(--a-font-leading-snug);
   }
 
   [data-count-badge][hidden] { display: none; }

package/components/tabs/tabs.css

@@ -138,7 +138,7 @@
     /* font-family floor — see segment.css rationale. */
     font-family: var(--tabs-font-family);
     font-size: var(--tabs-font-size);
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     cursor: pointer;
     user-select: none;
     white-space: nowrap;

package/components/tag/tag.css

@@ -154,8 +154,8 @@ tag-ui[removable]:not([disabled]):hover {
     /* font-family floor — see segment.css rationale. */
     font-family: var(--tag-font-family);
     font-size: var(--tag-font);
-    font-weight: 500;
-    line-height: 1;
+    font-weight: var(--a-weight-medium);
+    line-height: var(--a-font-leading-none);
     color: var(--tag-fg);
     background: var(--tag-bg);
     white-space: nowrap;

package/components/tags-input/tags-input.css

@@ -109,7 +109,7 @@
     color: var(--tags-input-fg);
     font: inherit;
     font-size: var(--tags-input-font-size);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     white-space: pre-wrap;
     overflow-wrap: anywhere;
     cursor: text;

package/components/textarea/textarea.css

@@ -75,7 +75,7 @@ textarea-ui:not([disabled]) [slot="text"]:hover {
     /* font-family floor — see segment.css rationale. */
     font-family: var(--textarea-font-family);
     font-size: var(--textarea-font-size);
-    line-height: 1.5;
+    line-height: var(--a-font-leading-relaxed);
     white-space: pre-wrap;
     word-break: break-word;
     overflow-y: auto;

package/components/time-picker/time-picker.css

@@ -42,7 +42,7 @@
     font-family: var(--time-picker-font-family, var(--a-font-family-ui));
     font-size: var(--time-picker-font-size);
     font-variant-numeric: tabular-nums;
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     cursor: text;
     transition:
       border-color var(--time-picker-duration) var(--time-picker-easing),

package/components/timeline/timeline.css

@@ -309,7 +309,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     font-weight: var(--timeline-item-label-weight);
     font-size: var(--timeline-item-label-size);
     color: var(--timeline-item-label-fg);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     overflow-wrap: break-word;
     min-width: 0;
   }
@@ -323,7 +323,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     grid-row: 2;
     color: var(--timeline-item-desc-fg);
     font-size: var(--timeline-item-desc-size);
-    line-height: 1.5;
+    line-height: var(--a-font-leading-relaxed);
     margin-top: var(--a-space-0-5);
   }
 
@@ -333,7 +333,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     color: var(--timeline-item-time-fg);
     font-size: var(--timeline-item-time-size);
     font-variant-numeric: tabular-nums;
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     white-space: nowrap;
     justify-self: end;
   }
@@ -356,7 +356,7 @@ agent-reasoning-ui timeline-ui:not([orientation="horizontal"]),
     gap: var(--a-space-0-5);
     color: var(--timeline-item-outcome-fg);
     font-size: var(--timeline-item-desc-size);
-    line-height: 1.4;
+    line-height: var(--a-font-leading-relaxed);
     animation: tl-fade var(--timeline-item-duration) var(--timeline-item-easing);
   }
 

package/components/toc/toc.css

@@ -59,7 +59,7 @@
     padding-inline: var(--toc-padding-inline);
     text-decoration: none;
     color: inherit;
-    line-height: 1.4;
+    line-height: var(--a-font-leading-normal);
     border-inline-start: 2px solid var(--toc-rule-inactive);
     transition:
       color  var(--a-duration-fast) var(--a-easing),

package/components/toggle-group/toggle-group.class.js

@@ -30,10 +30,12 @@ import { UIElement } from '../../core/element.js';
 // ── Toggle Option ──
 //
 // Parent-managed. Selection state flows through `toggle-group-ui`'s `value`
-// (and `single` mode flag). Items don't expose `checked` — parent applies
-// `data-selected` on the DOM element when the item's `value` is part of the
-// group's comma-separated `value` list. Consistent with native `<option>`
-// inside `<select>`.
+// (and `single` mode flag) — the group's `value` stays the single source of
+// truth. ADR-0056 (gh#1303): the child's current-state surface is the
+// declared, reflected `selected` prop below, converging onto <segment-ui>'s
+// mechanism (yaml → catalog → generative grammar) instead of a private
+// stamp. Don't set `selected` directly on an option; drive the group's
+// `value` instead.
 
 export class UIToggleOption extends UIElement {
   static properties = {
@@ -41,6 +43,7 @@ export class UIToggleOption extends UIElement {
     text:     { type: String,  default: '', reflect: true },
     icon:     { type: String,  default: '', reflect: true },
     disabled: { type: Boolean, default: false, reflect: true },
+    selected: { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;
@@ -59,6 +62,7 @@ export class UIToggleOption extends UIElement {
     }
     if (this.disabled) this.setAttribute('aria-disabled', 'true');
     else this.removeAttribute('aria-disabled');
+    this.setAttribute('aria-pressed', this.selected ? 'true' : 'false');
   }
 
   #stamp() {
@@ -100,13 +104,11 @@ export class UIToggleGroup extends UIElement {
     const selected = this.#valueSet;
     for (const opt of this.querySelectorAll('toggle-option-ui')) {
       const optVal = opt.value || opt.getAttribute('value') || '';
-      if (selected.has(optVal)) {
-        opt.setAttribute('data-selected', '');
-        opt.setAttribute('aria-pressed', 'true');
-      } else {
-        opt.removeAttribute('data-selected');
-        opt.setAttribute('aria-pressed', 'false');
-      }
+      const isSelected = selected.has(optVal);
+      // ADR-0056 (gh#1303): `selected` is the declared, reflected mechanism —
+      // converges onto <segment-ui>'s convention (opt's own render() stamps
+      // aria-pressed from it).
+      opt.selected = isSelected;
     }
   }
 

package/components/toggle-group/toggle-group.css

@@ -1,12 +1,21 @@
-/* Safari 17.x bug: `:scope:not(...):hover` inside `@scope` doesn't match
-   the scope root. Plain selector outside works. The @scope is
-   `(toggle-option-ui)` — NOT `(toggle-group-ui)` — so the moved-out
-   selector targets `toggle-option-ui:hover`. See docs/BROWSER-COMPAT.md §3a. */
+/* Safari 17.x bug: `:scope:not(...):hover` (Flavor A) and `:scope[selected]`
+   (Flavor B — attribute-removal restyle) both fail inside `@scope`.
+   Selectors moved out. The @scope is `(toggle-option-ui)` — NOT
+   `(toggle-group-ui)` — so the moved-out selectors target
+   `toggle-option-ui:hover` / `toggle-option-ui[selected]`. See
+   docs/BROWSER-COMPAT.md §3a; mirrors segment.css. */
 toggle-option-ui:not([disabled]):hover {
   --toggle-option-bg: var(--toggle-option-bg-hover);
   --toggle-option-fg: var(--toggle-option-fg-hover);
 }
 
+/* ADR-0056 (gh#1303): converged onto <segment-ui>'s declared, reflected
+   [selected] prop, set by <toggle-group-ui> (toggle-group.class.js). */
+toggle-option-ui[selected] {
+  --toggle-option-bg: var(--toggle-option-selected-bg);
+  --toggle-option-fg: var(--toggle-option-selected-fg);
+}
+
 @scope (toggle-group-ui) {
   :where(:scope) {
     /* ── Tokens ── */
@@ -94,10 +103,7 @@ toggle-option-ui:not([disabled]):hover {
     z-index: 1;
   }
 
-  :scope[data-selected] {
-    --toggle-option-bg: var(--toggle-option-selected-bg);
-    --toggle-option-fg: var(--toggle-option-selected-fg);
-  }
+  /* [selected] state rule moved outside @scope — see Safari 17.x bug note at top. */
 
   :scope[disabled] {
     --toggle-option-fg: var(--toggle-option-fg-disabled);

package/components/toggle-group/toggle-group.d.ts

@@ -38,6 +38,11 @@ export class UIToggleOption extends UIElement {
   disabled: boolean;
   /** Optional Phosphor icon name; renders as a leading icon. */
   icon: string;
+  /** Whether this option is currently selected. Managed by the parent
+<toggle-group-ui> container (ADR-0056) — don't set directly; the group's
+`value` is the single source of truth. Converges onto <segment-ui>'s
+declared reflected-prop mechanism. */
+  selected: boolean;
   /** Visible label text. */
   text: string;
   /** Stable identifier matched against the parent group's `value`. */

package/components/toggle-group/toggle-group.yaml

@@ -1,5 +1,10 @@
 # Generated by scripts/migrate-yamls-to-v1.mjs — migrated to v1 contract.
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# ADR-0056 (gh#1303): <toggle-option-ui>'s current-state surface converges
+# onto <segment-ui>'s declared, reflected `[selected]` prop (see
+# toggle-option.yaml). This container sets that prop, keeping `value` as the
+# single source of truth.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIToggleGroup
 tag: toggle-group-ui
@@ -80,6 +85,8 @@ a2ui:
       reason: 'Selection model distinction.'
     - rule: 'Use for filter chips, multi-flag toggles, day-of-week pickers; for binary on/off use <switch-ui>.'
       reason: 'Capacity guidance.'
+    - rule: 'Sets the child <toggle-option-ui>''s declared [selected] prop to reflect the group value (ADR-0056) — do not author [selected] directly in generated markup; author the group''s value instead.'
+      reason: 'Parent-managed declared state — group value stays the single source of truth.'
 anti_patterns: []
 examples:
   - name: basic-toggle-group

package/components/toggle-group/toggle-option.a2ui.json

@@ -26,6 +26,11 @@
       "type": "string",
       "default": ""
     },
+    "selected": {
+      "description": "Whether this option is currently selected. Managed by the parent\n<toggle-group-ui> container (ADR-0056) — don't set directly; the group's\n`value` is the single source of truth. Converges onto <segment-ui>'s\ndeclared reflected-prop mechanism.",
+      "type": "boolean",
+      "default": false
+    },
     "text": {
       "description": "Visible label text.",
       "type": "string",