@adia-ai/web-components 0.5.4 → 0.5.5

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

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AccordionItem.json",
+  "title": "AccordionItem",
+  "description": "Child of <accordion-ui>. One collapsible section with header + body. Use inside <accordion-ui> only.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AccordionItem"
+    },
+    "open": {
+      "description": "Whether the section is expanded.",
+      "type": "boolean",
+      "default": false
+    },
+    "text": {
+      "description": "Header text — the clickable label that toggles the section.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIAccordionItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "accordion-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/accordion/accordion-item.yaml

@@ -0,0 +1,27 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+# Child component of <accordion-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAccordionItem
+tag: accordion-item-ui
+component: AccordionItem
+category: layout
+version: 1
+description: |-
+  Child of <accordion-ui>. One collapsible section with header + body. Use inside <accordion-ui> only.
+
+props:
+  text:
+    description: Header text — the clickable label that toggles the section.
+    type: string
+  open:
+    description: Whether the section is expanded.
+    type: boolean
+    default: false

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

@@ -0,0 +1,63 @@
+{
+  "$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, forwards activation to the parent action-list.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ActionItem"
+    },
+    "disabled": {
+      "description": "Disables click + keyboard activation; aria-disabled is set.",
+      "type": "boolean",
+      "default": false
+    },
+    "icon": {
+      "description": "Leading icon name (Phosphor).",
+      "type": "string"
+    },
+    "text": {
+      "description": "Action label.",
+      "type": "string"
+    },
+    "value": {
+      "description": "Identifier passed to the action-list change/activate handlers.",
+      "type": "string"
+    },
+    "variant": {
+      "description": "Visual variant (default | accent | danger).",
+      "type": "string",
+      "default": "default"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "navigation",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIActionItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "action-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,37 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+# Child component of <action-list-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIActionItem
+tag: action-item-ui
+component: ActionItem
+category: navigation
+version: 1
+description: |-
+  Child of <action-list-ui>. One actionable row — icon + label, forwards activation to the parent action-list.
+
+props:
+  icon:
+    description: Leading icon name (Phosphor).
+    type: string
+  text:
+    description: Action label.
+    type: string
+  value:
+    description: Identifier passed to the action-list change/activate handlers.
+    type: string
+  variant:
+    description: Visual variant (default | accent | danger).
+    type: string
+    default: 'default'
+  disabled:
+    description: Disables click + keyboard activation; aria-disabled is set.
+    type: boolean
+    default: false

package/components/avatar/avatar-group.a2ui.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AvatarGroup.json",
+  "title": "AvatarGroup",
+  "description": "Cluster of overlapping <avatar-ui> children. Stacks the first `max` avatars with a negative inline-start margin; if more children are present, renders a +N overflow indicator.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AvatarGroup"
+    },
+    "max": {
+      "description": "Maximum avatars to show before the +N overflow indicator.",
+      "type": "number",
+      "default": 5
+    },
+    "size": {
+      "description": "Forwards to each child <avatar-ui> (xs|sm|md|lg|xl). Empty uses the per-avatar size.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "feedback",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIAvatarGroup",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "avatar-group-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/avatar/avatar-group.yaml

@@ -0,0 +1,26 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAvatarGroup
+tag: avatar-group-ui
+component: AvatarGroup
+category: feedback
+version: 1
+description: |-
+  Cluster of overlapping <avatar-ui> children. Stacks the first `max` avatars with a negative inline-start margin; if more children are present, renders a +N overflow indicator.
+
+props:
+  max:
+    description: Maximum avatars to show before the +N overflow indicator.
+    type: number
+    default: 5
+  size:
+    description: Forwards to each child <avatar-ui> (xs|sm|md|lg|xl). Empty uses the per-avatar size.
+    type: string

package/components/avatar/avatar.a2ui.json

@@ -24,7 +24,10 @@
     "name": {
       "description": "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead.",
       "type": "string",
-      "default": ""
+      "default": "",
+      "deprecated": true,
+      "deprecated_reason": "Use `text` instead. Will be removed in v0.6.0.",
+      "deprecated_since": "0.4.x"
     },
     "shape": {
       "description": "Avatar shape",

package/components/avatar/avatar.yaml

@@ -19,6 +19,13 @@ props:
   name:
     description: "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead."
     type: string
+    # §179 (v0.5.5): principled deprecation metadata. The build pipeline
+    # propagates this into the sidecar + catalog; the LLM prompt builder
+    # surfaces "(deprecated, do not use)" based on this field rather than
+    # substring-matching the description.
+    deprecated: true
+    deprecated_since: "0.4.x"
+    deprecated_reason: "Use `text` instead. Will be removed in v0.6.0."
     default: ""
   icon:
     description: Phosphor icon name shown instead of initials when `src`/`text` are empty.

package/components/button/class.js

@@ -52,8 +52,47 @@ export class UIButton extends UIElement {
         this.prepend(iconEl);
       }
     }
+
+    // §184 (v0.5.5, FEEDBACK-08 §8): icon-only a11y warning + title→aria-label
+    // auto-derive. Two complementary mechanisms (consumer chooses):
+    //   (a) When [title="Undo"] is set on an icon-only button without an
+    //       explicit aria-label, mirror title → aria-label. Matches the
+    //       common icon-only-button-with-tooltip pattern (zero authoring
+    //       cost — already had to write the tooltip text).
+    //   (b) When the button is icon-only AND has no aria-label AND no
+    //       aria-labelledby AND no title, console.warn ONCE per element
+    //       so the bug class is diagnosable in dev without firing every
+    //       render tick. The warning is suppressed via a one-shot
+    //       WeakSet so subsequent re-renders stay quiet.
+    if (this.icon && !this.text) {
+      const ariaLabel = this.getAttribute('aria-label');
+      const ariaLabelledBy = this.getAttribute('aria-labelledby');
+      const titleAttr = this.getAttribute('title');
+      if (!ariaLabel && !ariaLabelledBy && titleAttr) {
+        this.setAttribute('aria-label', titleAttr);
+      } else if (!ariaLabel && !ariaLabelledBy && !titleAttr) {
+        if (!UIButton.#a11yWarned.has(this)) {
+          UIButton.#a11yWarned.add(this);
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[button-ui] Icon-only button is missing an accessible name.\n` +
+            `  Element: <button-ui icon="${this.icon}">\n` +
+            `  Add one of:\n` +
+            `    aria-label="Undo"        ← explicit accessible name\n` +
+            `    title="Undo"             ← auto-mirrored to aria-label + tooltip\n` +
+            `    aria-labelledby="..."    ← reference an existing label element\n` +
+            `  Without an accessible name screen readers announce nothing meaningful.`
+          );
+        }
+      }
+    }
   }
 
+  // §184: WeakSet of elements we've already warned about. Prevents
+  // repeat warnings across re-renders. GC-friendly — when the element
+  // is gone the entry is collected.
+  static #a11yWarned = new WeakSet();
+
   #onClick = (e) => {
     if (this.disabled) { e.stopPropagation(); return; }
     if (this.type === 'submit') {

package/components/chart/chart.a2ui.json

@@ -47,7 +47,8 @@
         "square",
         "tall"
       ],
-      "default": "std"
+      "default": "std",
+      "deprecated": true
     },
     "color": {
       "description": "Color scheme",
@@ -78,7 +79,8 @@
     "heading": {
       "description": "DEPRECATED (OD-CHART-02). Place chart titles in an enclosing card-ui's `<header><span slot=\"heading\">...</span></header>` instead. Still honored for back-compat; emits a one-shot console.warn per instance when set. Used as the chart's `aria-label` when no explicit label is provided.",
       "type": "string",
-      "default": ""
+      "default": "",
+      "deprecated": true
     },
     "hideAverage": {
       "description": "When true, suppress the overlaid average line",

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

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ListItem.json",
+  "title": "ListItem",
+  "description": "Child of <list-ui>. One list item with optional icon + text + description, plus arbitrary slotted content (cards, rows). Use inside <list-ui> only.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "description": {
+      "description": "Secondary line below the primary text. Subtle color.",
+      "type": "string"
+    },
+    "component": {
+      "const": "ListItem"
+    },
+    "icon": {
+      "description": "Optional leading icon name (Phosphor).",
+      "type": "string"
+    },
+    "text": {
+      "description": "Primary text. Renders as semibold inline body.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIListItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "list-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/list/list-item.yaml

@@ -0,0 +1,29 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+# Child component of <list-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIListItem
+tag: list-item-ui
+component: ListItem
+category: layout
+version: 1
+description: |-
+  Child of <list-ui>. One list item with optional icon + text + description, plus arbitrary slotted content (cards, rows). Use inside <list-ui> only.
+
+props:
+  icon:
+    description: Optional leading icon name (Phosphor).
+    type: string
+  text:
+    description: Primary text. Renders as semibold inline body.
+    type: string
+  description:
+    description: Secondary line below the primary text. Subtle color.
+    type: string

package/components/select/class.js

@@ -37,8 +37,14 @@ export class UISelect extends UIFormElement {
     searchable:  { type: Boolean, default: false, reflect: true },
     freeText:    { type: Boolean, default: false, reflect: true, attribute: 'free-text' },
     divider:     { type: Boolean, default: false, reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §7): optional caption beneath the
+    // trigger, wired to aria-describedby on the host.
+    hint:        { type: String,  default: '', reflect: true },
   };
 
+  // §184: per-instance hint id counter for aria-describedby wiring.
+  static #hintSeq = 0;
+
   static template = () => null;
 
   #options = [];
@@ -97,13 +103,21 @@ export class UISelect extends UIFormElement {
       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">${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
+      // schema-declared `hint` prop on switch-ui (which had the spec
+      // but not the rendering until this arc).
+      const hintId = this.hint ? `select-hint-${++UISelect.#hintSeq}` : '';
+      const hintMarkup = this.hint ? `<span slot="hint" id="${hintId}">${escapeHTML(this.hint)}</span>` : '';
       this.innerHTML = `
         <span slot="trigger">
           ${leading}
           ${displayMarkup}
           <icon-ui name="caret-up-down" slot="caret"></icon-ui>
         </span>
+        ${hintMarkup}
       `;
+      if (this.hint) this.setAttribute('aria-describedby', hintId);
 
       if (this.searchable) {
         // Detach from previous search input if any

package/components/select/select.a2ui.json

@@ -46,6 +46,11 @@
       "type": "boolean",
       "default": false
     },
+    "hint": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the select. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`.",
+      "type": "string",
+      "default": ""
+    },
     "icon": {
       "description": "Leading icon name rendered inside the trigger",
       "type": "string",

package/components/select/select.css

@@ -308,3 +308,13 @@ select-ui[divider] [role="group"] + [role="group"] {
   margin-top: var(--a-space-1);
   padding-top: var(--a-space-1);
 }
+
+/* ── Hint (§184, v0.5.5, FEEDBACK-08 §7) ──
+   Caption beneath the trigger; wired to aria-describedby on the host. */
+select-ui > [slot="hint"] {
+  display: block;
+  margin-top: var(--select-hint-mt, var(--a-space-1));
+  font-size: var(--select-hint-size, var(--a-fine-size));
+  color: var(--select-hint-fg, var(--a-fg-muted));
+  line-height: var(--select-hint-lh, 1.4);
+}

package/components/select/select.yaml

@@ -67,6 +67,11 @@ props:
     description: Label text above the trigger
     type: string
     default: ""
+  hint:
+    description: |-
+      §184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the select. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`.
+    type: string
+    default: ""
   maxlength:
     description: Maximum character length for validation
     type: number

package/components/slider/class.js

@@ -42,13 +42,31 @@ export class UISlider extends UIFormElement {
     step:   { type: Number,  default: 1,  reflect: true },
     label:  { type: String,  default: '', reflect: true },
     suffix: { type: String,  default: '', reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §4): declarative debounce for the
+    // `input` event when driving expensive computation (palette regen,
+    // shader compile, large list reflow). When > 0, value updates +
+    // visual feedback are immediate but `input` event emission is
+    // debounced — only the FINAL value in the throttle window dispatches.
+    // `change` fires unthrottled on pointerup / track click / keyboard;
+    // any pending `input` flushes BEFORE `change` so consumers always
+    // see input→input→…→input→change ordering. throttle="0" (default)
+    // preserves the pre-§184 every-pointer-move-fires-input behavior.
+    throttle: { type: Number, default: 0, reflect: true },
   };
 
   static template = () => null;
 
+  // §184: per-instance hint id counter for aria-describedby wiring.
+  static #hintSeq = 0;
+
   #trackEl = null;
   #thumbEl = null;
   #dragging = false;
+  // §184 (v0.5.5, FEEDBACK-08 §4): debounce timer for the `input`
+  // event. When `throttle > 0`, #setValue stores a pending dispatch
+  // here + restarts the timer on every value change. Flushed before
+  // any `change` event so input always precedes change.
+  #inputTimer = null;
 
   get #pct() {
     const range = this.max - this.min;
@@ -69,6 +87,9 @@ export class UISlider extends UIFormElement {
     if (this.label) this.setAttribute('aria-label', this.label);
 
     if (!this.querySelector('[slot="track"]')) {
+      // §184 (v0.5.5, FEEDBACK-08 §7): hint slot stamped underneath
+      // the track when [hint] is set. Wired to aria-describedby below.
+      const hintId = this.hint ? `slider-hint-${++UISlider.#hintSeq}` : '';
       this.innerHTML = `
         <div slot="header">
           ${this.label ? `<span slot="label">${this.label}</span>` : ''}
@@ -81,7 +102,9 @@ export class UISlider extends UIFormElement {
           <div slot="fill"></div>
           <div slot="thumb" tabindex="0"></div>
         </div>
+        ${this.hint ? `<span slot="hint" id="${hintId}">${this.hint}</span>` : ''}
       `;
+      if (this.hint) this.setAttribute('aria-describedby', hintId);
     }
 
     this.#trackEl = this.querySelector('[slot="track"]');
@@ -148,9 +171,36 @@ export class UISlider extends UIFormElement {
   #setValue(v) {
     if (v === this.value) return;
     this.value = v;
+    // §184: when throttle > 0, debounce the `input` dispatch.
+    // The value update + UI is still immediate; only event emission is
+    // accumulated. Same value can dispatch input multiple times across
+    // pointer moves, but the throttle collapses them to one trailing
+    // emission at quiet+throttle ms.
+    const t = Number(this.throttle) || 0;
+    if (t > 0) {
+      if (this.#inputTimer != null) clearTimeout(this.#inputTimer);
+      this.#inputTimer = setTimeout(() => {
+        this.#inputTimer = null;
+        this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+      }, t);
+      return;
+    }
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
   }
 
+  /**
+   * §184: flush any pending throttled `input` dispatch synchronously.
+   * Called before `change` so consumers see the trailing input event
+   * BEFORE the change commit. No-op when no timer is pending.
+   */
+  #flushInput() {
+    if (this.#inputTimer != null) {
+      clearTimeout(this.#inputTimer);
+      this.#inputTimer = null;
+      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    }
+  }
+
   #onPointerDown = (e) => {
     if (this.disabled) return;
     e.preventDefault();
@@ -170,12 +220,14 @@ export class UISlider extends UIFormElement {
     this.#thumbEl.releasePointerCapture(e.pointerId);
     this.#thumbEl.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl.removeEventListener('pointerup', this.#onPointerUp);
+    this.#flushInput(); // §184: pending throttled input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
   #onTrackClick = (e) => {
     if (this.disabled || e.target === this.#thumbEl) return;
     this.#setValue(this.#valueFromX(e.clientX));
+    this.#flushInput(); // §184: ensure trailing input precedes change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -193,6 +245,7 @@ export class UISlider extends UIFormElement {
     }
     e.preventDefault();
     this.#setValue(this.#snap(v));
+    this.#flushInput(); // §184: trailing input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -203,6 +256,11 @@ export class UISlider extends UIFormElement {
     this.#thumbEl?.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl?.removeEventListener('pointerup', this.#onPointerUp);
     this.removeEventListener('keydown', this.#onKey);
+    // §184: drop any pending throttle timer (no flush — element is gone)
+    if (this.#inputTimer != null) {
+      clearTimeout(this.#inputTimer);
+      this.#inputTimer = null;
+    }
     this.#trackEl = null;
     this.#thumbEl = null;
   }

package/components/slider/slider.a2ui.json

@@ -31,6 +31,11 @@
       "type": "string",
       "default": ""
     },
+    "hint": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the slider track. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`. Use for semantic clarifications a `<field-ui>` wrapper would be overkill for.",
+      "type": "string",
+      "default": ""
+    },
     "label": {
       "description": "Label text above the slider",
       "type": "string",
@@ -61,6 +66,11 @@
       "type": "string",
       "default": ""
     },
+    "throttle": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §4): when > 0, debounce the `input` event by this many milliseconds. Value updates + visual feedback remain immediate; only event dispatch accumulates. Pending input flushes BEFORE `change` so consumers always see input→…→input→change ordering. throttle=\"0\" (default) preserves the pre-§184 every-pointer-move-fires-input behavior. Common values: 50-100ms for palette regen / shader compile / large list reflow.",
+      "type": "number",
+      "default": 0
+    },
     "value": {
       "description": "Current slider value",
       "type": "number",