@adia-ai/web-components 0.5.13 → 0.5.15

package/components/search/search.yaml

@@ -39,6 +39,12 @@ events:
     description: Fired when the clear button is clicked
   input:
     description: "Fired on each input change during typing."
+  change:
+    description: Fired alongside `input` on every keystroke + on clear. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).
+    detail:
+      value:
+        type: string
+        description: Current search-input value.
   search:
     description: Debounced CustomEvent with detail.query containing the search string
 slots:

package/components/segment/segment.css

@@ -20,10 +20,10 @@ segment-ui[selected] {
     --segment-font-weight:     var(--a-ui-weight);
 
     /* ── Colors ── */
-    --segment-fg:              var(--a-fg-subtle);
-    --segment-fg-hover:        var(--a-fg);
+    --segment-fg:              var(--a-ui-text-subtle);
+    --segment-fg-hover:        var(--a-ui-text-hover);
     --segment-fg-selected:     var(--a-chrome-dark);
-    --segment-fg-disabled:     var(--a-fg-muted);
+    --segment-fg-disabled:     var(--a-ui-text-disabled);
 
     /* ── Transition ── */
     --segment-duration:        var(--a-duration-fast);

package/components/select/select.css

@@ -24,6 +24,7 @@
     --select-placeholder-fg:    var(--a-ui-text-placeholder);
     --select-caret-fg:          var(--a-ui-text-muted);
     --select-fg:                var(--a-ui-text);
+    --select-fg-hover:          var(--a-ui-text-hover);
     --select-fg-selected:       var(--a-ui-text-selected);
     --select-fg-subtle:         var(--a-ui-text-subtle);
     --select-fg-muted:          var(--a-ui-text-muted);
@@ -38,7 +39,7 @@
     --select-option-px:         var(--a-ui-px);
     --select-option-py:         var(--a-ui-py);
     --select-option-bg-hover:   var(--a-bg-hover);
-    --select-option-fg-active:  var(--a-fg);
+    --select-option-fg-active:  var(--a-ui-text-active);
     --select-option-fg-disabled: var(--a-ui-text-disabled);
     --select-group-label-size:  var(--a-ui-size);
   }
@@ -195,7 +196,7 @@ select-ui [slot="listbox"] {
   overflow-y: auto;
   font-family: inherit;
   font-size: var(--a-ui-size);
-  color: var(--a-fg);
+  color: var(--select-fg);
 
   /* Positioned by JS (#positionListbox) — fixed to viewport */
   width: max-content;
@@ -223,7 +224,7 @@ select-ui [role="option"] {
   padding: var(--a-space-1) var(--a-ui-px);
   border-radius: var(--a-radius-sm);
   white-space: nowrap;
-  color: var(--a-fg-subtle);
+  color: var(--select-fg-subtle);
   cursor: pointer;
   transition:
     background var(--a-duration-fast) var(--a-easing),
@@ -231,8 +232,8 @@ select-ui [role="option"] {
 }
 select-ui [role="option"]:hover,
 select-ui [role="option"][data-focused] {
-  background: var(--a-bg-hover);
-  color: var(--a-fg-hover);
+  background: var(--select-option-bg-hover);
+  color: var(--select-fg-hover);
 }
 select-ui [role="option"][aria-selected="true"] {
   color: var(--select-fg-selected);
@@ -240,7 +241,7 @@ select-ui [role="option"][aria-selected="true"] {
   font-weight: var(--a-ui-weight);
 }
 select-ui [role="option"][aria-disabled="true"] {
-  color: var(--a-fg-muted);
+  color: var(--select-option-fg-disabled);
   cursor: not-allowed;
 }
 select-ui [role="option"][aria-disabled="true"]:hover {
@@ -250,7 +251,7 @@ select-ui [role="option"][aria-disabled="true"]:hover {
 /* Option with icon */
 select-ui [role="option"] icon-ui {
   --a-icon-size: var(--a-ui-size);
-  color: var(--a-fg-muted);
+  color: var(--select-fg-muted);
   margin-inline-end: var(--a-space-1);
   vertical-align: -0.125em;
 }
@@ -282,21 +283,21 @@ select-ui [data-menu-header] img {
 select-ui [data-menu-header] strong {
   display: block;
   font-weight: var(--a-weight-medium);
-  color: var(--a-fg);
+  color: var(--select-fg);
   font-size: var(--a-ui-size);
 }
 
 select-ui [data-menu-header] span {
   display: block;
   font-size: var(--a-ui-sm);
-  color: var(--a-fg-muted);
+  color: var(--select-fg-muted);
 }
 
 select-ui [role="group"] [slot="group-label"] {
   padding: var(--a-space-1) var(--a-ui-px);
   font-size: var(--a-ui-tiny);
   font-weight: var(--a-ui-weight);
-  color: var(--a-fg-muted);
+  color: var(--select-fg-muted);
   text-transform: uppercase;
   letter-spacing: 0.05em;
   white-space: nowrap;
@@ -315,6 +316,6 @@ select-ui > [slot="hint"] {
   display: block;
   margin-top: var(--select-hint-mt, var(--a-space-1));
   font-size: var(--select-hint-size, var(--a-ui-xs));
-  color: var(--select-hint-fg, var(--a-fg-muted));
+  color: var(--select-hint-fg, var(--select-fg-muted));
   line-height: var(--select-hint-lh, 1.4);
 }

package/components/stepper/stepper.css

@@ -20,13 +20,13 @@
     --stepper-weight:          var(--a-weight-medium);
     --stepper-border-size:     2px;
 
-    --stepper-active-bg:       var(--a-bg);
-    --stepper-active-border:   var(--a-accent);
-    --stepper-active-fg:       var(--a-accent);
+    --stepper-bg-active:       var(--a-bg);
+    --stepper-border-active:   var(--a-accent);
+    --stepper-fg-active:       var(--a-accent);
 
-    --stepper-done-bg:         var(--a-accent);
-    --stepper-done-border:     var(--a-accent);
-    --stepper-done-fg:         var(--a-accent-fg);
+    --stepper-bg-done:         var(--a-accent);
+    --stepper-border-done:     var(--a-accent);
+    --stepper-fg-done:         var(--a-accent-fg);
 
     --stepper-line:            var(--a-border-subtle);
     --stepper-line-done:       var(--a-accent);
@@ -76,13 +76,13 @@
     --stepper-item-weight:         var(--stepper-weight, var(--a-weight-medium));
     --stepper-item-border-size:    var(--stepper-border-size, 2px);
 
-    --stepper-item-active-bg:      var(--stepper-active-bg, var(--a-bg));
-    --stepper-item-active-border:  var(--stepper-active-border, var(--a-accent));
-    --stepper-item-active-fg:      var(--stepper-active-fg, var(--a-accent));
+    --stepper-item-bg-active:      var(--stepper-bg-active, var(--a-bg));
+    --stepper-item-border-active:  var(--stepper-border-active, var(--a-accent));
+    --stepper-item-fg-active:      var(--stepper-fg-active, var(--a-accent));
 
-    --stepper-item-done-bg:        var(--stepper-done-bg, var(--a-accent));
-    --stepper-item-done-border:    var(--stepper-done-border, var(--a-accent));
-    --stepper-item-done-fg:        var(--stepper-done-fg, var(--a-accent-fg));
+    --stepper-item-bg-done:        var(--stepper-bg-done, var(--a-accent));
+    --stepper-item-border-done:    var(--stepper-border-done, var(--a-accent));
+    --stepper-item-fg-done:        var(--stepper-fg-done, var(--a-accent-fg));
 
     --stepper-item-line:           var(--stepper-line, var(--a-border-subtle));
     --stepper-item-line-done:      var(--stepper-line-done, var(--a-accent));
@@ -158,9 +158,9 @@
 
   /* Active state */
   :scope[status="active"]::after {
-    border-color: var(--stepper-item-active-border);
-    color: var(--stepper-item-active-fg);
-    background: var(--stepper-item-active-bg);
+    border-color: var(--stepper-item-border-active);
+    color: var(--stepper-item-fg-active);
+    background: var(--stepper-item-bg-active);
   }
 
   :scope[status="active"] [slot="label"] {
@@ -171,9 +171,9 @@
   /* Completed state — checkmark replaces number */
   :scope[status="completed"]::after {
     content: '\2713';
-    background: var(--stepper-item-done-bg);
-    border-color: var(--stepper-item-done-border);
-    color: var(--stepper-item-done-fg);
+    background: var(--stepper-item-bg-done);
+    border-color: var(--stepper-item-border-done);
+    color: var(--stepper-item-fg-done);
   }
 
   :scope[status="completed"]::before {
@@ -214,15 +214,15 @@
   }
 
   :scope[status="active"] [slot="icon"] {
-    border-color: var(--stepper-item-active-border);
-    color: var(--stepper-item-active-fg);
-    background: var(--stepper-item-active-bg);
+    border-color: var(--stepper-item-border-active);
+    color: var(--stepper-item-fg-active);
+    background: var(--stepper-item-bg-active);
   }
 
   :scope[status="completed"] [slot="icon"] {
-    background: var(--stepper-item-done-bg);
-    border-color: var(--stepper-item-done-border);
-    color: var(--stepper-item-done-fg);
+    background: var(--stepper-item-bg-done);
+    border-color: var(--stepper-item-border-done);
+    color: var(--stepper-item-fg-done);
   }
 
   /* ── Content slots ── */

package/components/swatch/class.js

@@ -226,6 +226,17 @@ export class UISwatch extends UIElement {
     // Capture pre-existing default-slot content so consumer-authored
     // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
     // `[slot="chrome"]` children are already removed above, so won't appear here.
+    //
+    // §325 (v0.5.16, FB-36): filter pure-whitespace text nodes from the
+    // capture. Pre-§325, indented multi-line HTML (`<swatch-ui
+    // label="500">\n  <span>tip</span>\n</swatch-ui>`) captured the
+    // leading whitespace text node, which then made #labelEl.firstChild
+    // a nodeType=3 text node. #syncCore()'s "stale-text-node" branch
+    // matched the whitespace + did textContent = this.label, wiping
+    // BOTH the whitespace AND the consumer's <span>. Filter here so
+    // #labelEl.firstChild is the actual element/non-whitespace text,
+    // and #syncCore's stale-text branch only fires for genuinely
+    // attr-driven cases.
     const slotted = Array.from(this.childNodes).filter(n =>
       !(n.nodeType === 1 && n.dataset && (
         n.dataset.tile !== undefined ||
@@ -233,7 +244,7 @@ export class UISwatch extends UIElement {
         n.dataset.detail !== undefined ||
         n.dataset.badge !== undefined ||
         n.dataset.copy !== undefined
-      ))
+      )) && !(n.nodeType === 3 && !n.textContent.trim())
     );
     this.innerHTML = '';
 
@@ -282,9 +293,53 @@ export class UISwatch extends UIElement {
 
   // ── Sync ──────────────────────────────────────────────────────────
 
+  /**
+   * §326 (v0.5.16, FB-37): Late-arriving `[slot="chrome"]` children may
+   * land on the host AFTER `#stamp()` runs — happens in any template
+   * engine (lit-html, AdiaUI `html\`\``, etc.) that batches child appends
+   * separately from element creation. `#stamp()` is gated by
+   * `this.#stamped` and won't re-run; this method picks up the late
+   * arrivals on every `render()` pass + moves them to the canonical
+   * sibling-of-tile position (between `#tileEl` and `#badgeEl`).
+   *
+   * Idempotent: chrome children already in the right slot are left
+   * alone (the `insertBefore` only moves them if they're not the
+   * #badgeEl's immediate previousSibling chain).
+   */
+  #absorbChromeSlot() {
+    if (!this.#tileEl || !this.#badgeEl) return;
+    const chromeChildren = [];
+    for (const child of this.children) {
+      if (child === this.#tileEl) continue;
+      if (child === this.#badgeEl) break; // hit the badge — done scanning the head region
+      if (child.getAttribute?.('slot') === 'chrome') chromeChildren.push(child);
+    }
+    // Walk the rest of the children looking for chrome children that landed
+    // AFTER the internal structure (the common template-late-append case).
+    for (const child of Array.from(this.children)) {
+      if (
+        child !== this.#tileEl &&
+        child !== this.#badgeEl &&
+        child !== this.#labelEl &&
+        child !== this.#detailEl &&
+        child !== this.#copyEl &&
+        child.getAttribute?.('slot') === 'chrome'
+      ) {
+        // Move to the canonical position: immediately after #tileEl.
+        // insertBefore is idempotent — moving an already-positioned child
+        // to the same spot is a no-op.
+        this.insertBefore(child, this.#badgeEl);
+      }
+    }
+  }
+
   #syncCore() {
     if (!this.#tileEl || !this.#labelEl) return;
 
+    // §326 (v0.5.16, FB-37): pick up `[slot="chrome"]` children that
+    // landed after #stamp() ran (template-render path).
+    this.#absorbChromeSlot();
+
     // Normalize enum values; fall back silently when a consumer sets a typo.
     const shape = SHAPES.has(this.shape) ? this.shape : 'square';
     const size  = SIZES.has(this.size)   ? this.size  : 'md';

package/components/swatch/swatch.css

@@ -291,7 +291,7 @@
     line-height: 1;
     cursor: pointer;
     border-radius: var(--a-radius-xs);
-    transition: color 100ms ease-out, background 100ms ease-out;
+    transition: color var(--a-duration-fast) var(--a-easing-out), background var(--a-duration-fast) var(--a-easing-out);
   }
   :scope > [data-copy]:hover { color: var(--a-fg); background: var(--a-bg-muted); }
   :scope > [data-copy]:focus-visible {
@@ -308,7 +308,7 @@
   :scope[selectable] {
     cursor: pointer;
     border-radius: var(--a-radius-sm);
-    transition: box-shadow 120ms ease-out;
+    transition: box-shadow var(--a-duration-fast) var(--a-easing-out);
   }
   :scope[selectable]:focus { outline: none; }
   :scope[selectable]:focus-visible {

package/components/swatch/swatch.test.js

@@ -0,0 +1,163 @@
+/**
+ * <swatch-ui> behavioral tests.
+ *
+ * Currently scoped to FB-36 / §325 regression coverage. Future tests for
+ * #stamp() lifecycle, chrome-slot composition, auto-contrast probe,
+ * etc. land here.
+ *
+ * Test setup note: happy-dom connects custom elements synchronously
+ * during innerHTML parsing — BEFORE sibling children inside the same
+ * element are appended. Real browsers connect after the full innerHTML
+ * is parsed. To exercise the FB-36 path (children present at connect
+ * time), tests use `document.createElement` + `appendChild` to build
+ * the full subtree FIRST, then attach to the document — guaranteeing
+ * the children are in `this.childNodes` when `connectedCallback()` fires.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./swatch.js');
+});
+
+function buildSwatch({ label, defaultSlot, shape = 'block', labelPosition = 'overlay', color = '#3b82f6' }) {
+  const swatch = document.createElement('swatch-ui');
+  swatch.setAttribute('shape', shape);
+  swatch.setAttribute('label-position', labelPosition);
+  swatch.setAttribute('color', color);
+  if (label !== undefined) swatch.setAttribute('label', label);
+  if (defaultSlot) {
+    // Mimic indented HTML's whitespace text nodes — the FB-36 trigger.
+    swatch.appendChild(document.createTextNode('\n      '));
+    const child = document.createElement('span');
+    child.id = defaultSlot.id;
+    child.textContent = defaultSlot.text;
+    swatch.appendChild(child);
+    swatch.appendChild(document.createTextNode('\n    '));
+  }
+  return swatch;
+}
+
+describe('<swatch-ui> default-slot + label-attr precedence (FB-36 / §325)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  it('preserves default-slot element when label="X" is also present (FB-36 §325 fix)', async () => {
+    const swatch = buildSwatch({
+      label: '500',
+      defaultSlot: { id: 'probe-default', text: 'richlabel' },
+    });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const label = swatch.querySelector('[data-label]');
+    const span = swatch.querySelector('#probe-default');
+
+    // Pre-§325 the span was wiped + label="500" took precedence.
+    // Post-§325 the default-slot wins (yaml spec: "richer content").
+    expect(span).not.toBeNull();
+    expect(label.textContent.trim()).toBe('richlabel');
+  });
+
+  it('renders label-attr text when no default-slot is present', async () => {
+    const swatch = buildSwatch({ label: '500' });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+    const label = swatch.querySelector('[data-label]');
+    expect(label.textContent.trim()).toBe('500');
+  });
+
+  it('renders default-slot text when no label-attr is present', async () => {
+    const swatch = buildSwatch({
+      defaultSlot: { id: 'probe-only', text: 'defaultonly' },
+    });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+    const label = swatch.querySelector('[data-label]');
+    const span = swatch.querySelector('#probe-only');
+    expect(span).not.toBeNull();
+    expect(label.textContent.trim()).toBe('defaultonly');
+  });
+
+  it('syncs label-attr changes when there is no default-slot (no whitespace regression)', async () => {
+    const swatch = buildSwatch({ label: '500' });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+    swatch.label = '600';
+    await new Promise((r) => setTimeout(r, 80));
+    const label = swatch.querySelector('[data-label]');
+    expect(label.textContent.trim()).toBe('600');
+  });
+});
+
+describe('<swatch-ui> late-arriving [slot="chrome"] children (FB-37 / §326)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  it('absorbs chrome child appended AFTER connectedCallback (template-render path)', async () => {
+    // Mimic the template-engine timing: create the swatch + connect it FIRST
+    // (children empty), then append the chrome child + trigger a render.
+    const swatch = document.createElement('swatch-ui');
+    swatch.setAttribute('shape', 'block');
+    swatch.setAttribute('label-position', 'overlay');
+    swatch.setAttribute('color', '#3b82f6');
+    swatch.setAttribute('label', '500');
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+
+    // At this point #stamp() has run + chromeSlot was empty.
+    // Append a chrome child LATER — this is what template engines do.
+    const chrome = document.createElement('span');
+    chrome.setAttribute('slot', 'chrome');
+    chrome.id = 'late-chrome';
+    chrome.textContent = '★';
+    swatch.appendChild(chrome);
+
+    // Trigger a re-render via property mutation (template engines typically
+    // set props after appending — this nudge fires render → #syncCore →
+    // #absorbChromeSlot picks up the late chrome child). Must use a value
+    // DIFFERENT from current to actually fire the signal write.
+    swatch.label = '999';
+    await new Promise((r) => setTimeout(r, 80));
+
+    const found = swatch.querySelector('#late-chrome');
+    expect(found).not.toBeNull();
+    // Chrome child should be a direct host sibling positioned between tile + badge.
+    const tile = swatch.querySelector('[data-tile]');
+    const badge = swatch.querySelector('[data-badge]');
+    expect(found.previousElementSibling).toBe(tile);
+    expect(found.nextElementSibling).toBe(badge);
+  });
+
+  it('still handles chrome child appended BEFORE connect (static-HTML path)', async () => {
+    // Build swatch with chrome child present at connect time — the canonical
+    // FB-34 / §314 path should still work post-§326.
+    const swatch = document.createElement('swatch-ui');
+    swatch.setAttribute('shape', 'block');
+    swatch.setAttribute('label-position', 'overlay');
+    swatch.setAttribute('color', '#3b82f6');
+    swatch.setAttribute('label', '500');
+    const chrome = document.createElement('span');
+    chrome.setAttribute('slot', 'chrome');
+    chrome.id = 'early-chrome';
+    chrome.textContent = '⚑';
+    swatch.appendChild(chrome);
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const found = swatch.querySelector('#early-chrome');
+    expect(found).not.toBeNull();
+    const tile = swatch.querySelector('[data-tile]');
+    const badge = swatch.querySelector('[data-badge]');
+    expect(found.previousElementSibling).toBe(tile);
+    expect(found.nextElementSibling).toBe(badge);
+  });
+});

package/components/switch/switch.css

@@ -59,7 +59,7 @@ switch-ui[checked] [slot="thumb"] {
     --switch-thumb-travel:         calc(var(--switch-track-width) - var(--switch-thumb-size) - 2 * var(--switch-thumb-inset) - 2px);
 
     /* ── State: disabled ── */
-    --switch-fg-disabled:          var(--a-fg-muted);
+    --switch-fg-disabled:          var(--a-ui-text-disabled);
   }
 
   :scope {

package/components/tabs/tabs.css

@@ -13,7 +13,7 @@
     --tabs-fg:              var(--a-fg-subtle);
     --tabs-fg-hover:        var(--a-fg);
     --tabs-fg-active:       var(--a-fg-selected);
-    --tabs-fg-disabled:     var(--a-fg-muted);
+    --tabs-fg-disabled:     var(--a-ui-text-disabled);
 
     /* ── Spacing ── */
     --tabs-vertical-gap:    var(--a-space-4);

package/components/text/text.a2ui.json

@@ -36,7 +36,7 @@
       "default": false
     },
     "variant": {
-      "description": "Typography variant — sets role tokens (size/weight/tracking/color).",
+      "description": "Typography variant — sets design-role tokens (size / weight /\ntracking / color / leading) per the L0 typography token family.\n**PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant=\"heading\">`\ndoes NOT set `role=\"heading\"` + `aria-level` on the host. Document-\noutline assistive technology will treat the element as `role=\"generic\"`.\nFor semantic headings, wrap with native `<h1>`-`<h6>` OR add\n`role=\"heading\" aria-level=\"N\"` on the host directly. For visual-only\nlabels (eyebrows, kickers, captions, deck), the presentational default\nis correct. The §221k chooser guide in USAGE.md documents picker heuristics.",
       "type": "string",
       "enum": [
         "body",
@@ -52,7 +52,21 @@
         "metric",
         "code"
       ],
-      "default": "body"
+      "default": "body",
+      "enum_descriptions": {
+        "title": "Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog.",
+        "body": "Default body copy. 14px / regular. Paragraphs, multi-line content, running prose.",
+        "caption": "Annotation under a primary line — smaller + muted. Use for image captions, footnotes.",
+        "code": "Inline monospace code reference. Use for inline code within prose.",
+        "deck": "Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.",
+        "display": "Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners.",
+        "heading": "Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.",
+        "kicker": "Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).",
+        "label": "Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.",
+        "metric": "Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.",
+        "section": "Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.",
+        "subsection": "Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section."
+      }
     }
   },
   "required": [

package/components/text/text.d.ts

@@ -1,41 +1,28 @@
 /**
- * `<text-ui>` — Typography wrapper that applies role tokens. Supports
- * truncation and line clamping.
+ * `<text-ui>` — Typography wrapper that applies role tokens. Supports truncation and line clamping.
  *
  * @see https://ui-kit.exe.xyz/site/components/text
  *
- * HAND-AUTHORED (not codegen'd) per §247 (v0.5.10) — the yaml `enum:` schema
- * carries variant names but not per-value descriptions; codegen emits a
- * single property-level JSDoc and loses the per-variant disambiguation that
- * the §221k chooser guide documents. Hand-authored .d.ts carries per-variant
- * JSDoc inline so IDE hover surfaces the disambiguation at authoring time.
- * Also carries the FB-23 §2 ARIA-role disclaimer on the property doc.
- * `dts-codegen.mjs` keeps this file in its `HAND_AUTHORED_DTS` skip list.
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
-/**
- * Typography variants — visual rank from `display` (largest, hero) to
- * `code` (inline monospace). Pick by intent, not by visual size — every
- * variant has a distinct typographic role per §221k chooser guide.
- *
- * See `packages/web-components/USAGE.md` "v0.5.9 — Consumer-feedback
- * discoverability sweep" §221k for the picker heuristics.
- */
 export type UITextVariant =
   /** Default body copy. 14px / regular. Paragraphs, multi-line content, running prose. */
   | 'body'
-  /** Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners. */
-  | 'display'
-  /** Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog. */
-  | 'title'
   /** Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers. */
   | 'heading'
+  /** Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog. */
+  | 'title'
   /** Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section. */
   | 'subsection'
-  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
-  | 'section'
+  /** Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners. */
+  | 'display'
   /** Annotation under a primary line — smaller + muted. Use for image captions, footnotes. */
   | 'caption'
   /** Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls. */
@@ -44,34 +31,30 @@ export type UITextVariant =
   | 'kicker'
   /** Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title. */
   | 'deck'
+  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
+  | 'section'
   /** Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers. */
   | 'metric'
-  /** Inline monospace code reference. Use for `\`code\`` inline within prose. */
+  /** Inline monospace code reference. Use for inline code within prose. */
   | 'code';
 
 export class UIText extends UIElement {
-  /**
-   * Typography variant — sets design-role tokens (size / weight / tracking /
-   * color / leading) per the L0 typography token family.
-   *
-   * **PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant="heading">`
-   * does NOT set `role="heading"` + `aria-level` on the host. Document-outline
-   * assistive technology will treat the element as `role="generic"`. For
-   * **semantic** headings (screen-reader heading-navigation, document
-   * outline), wrap with native `<h1>`-`<h6>` OR add
-   * `role="heading" aria-level="N"` on the host element directly.
-   *
-   * For visual-only labels (eyebrows, kickers, captions, deck), the
-   * presentational default is correct. The §221k chooser guide in USAGE.md
-   * documents the picker heuristics.
-   */
-  variant: UITextVariant;
-  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via `:scope[strong]` in text.css. Use instead of `variant="heading"` when you want a single emphasized word inline in body copy. */
-  strong: boolean;
-  /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
-  truncate: boolean;
-  /** Multi-line clamp count (0 = no clamp). Sets `--_text-lines` for `-webkit-line-clamp`. */
+  /** Multi-line clamp count (0 = no clamp) */
   lines: number;
+  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
+  strong: boolean;
   /** Display text content. The main payload field for Text components extracted from HTML. */
   textContent: string;
+  /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
+  truncate: boolean;
+  /** Typography variant — sets design-role tokens (size / weight /
+tracking / color / leading) per the L0 typography token family.
+**PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant="heading">`
+does NOT set `role="heading"` + `aria-level` on the host. Document-
+outline assistive technology will treat the element as `role="generic"`.
+For semantic headings, wrap with native `<h1>`-`<h6>` OR add
+`role="heading" aria-level="N"` on the host directly. For visual-only
+labels (eyebrows, kickers, captions, deck), the presentational default
+is correct. The §221k chooser guide in USAGE.md documents picker heuristics. */
+  variant: UITextVariant;
 }