@adia-ai/web-components 0.8.31 → 0.8.32

package/components/stream/stream.d.ts

@@ -27,12 +27,12 @@ export class UIStream extends UIElement {
   /** Read-only reflected state, true while stream is active */
   streaming: boolean;
 
+  addEventListener(type: 'stream-end', listener: (ev: StreamEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'stream-error', listener: (ev: StreamErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'stream-start', listener: (ev: StreamStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIStream, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'stream-end', listener: (ev: StreamEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'stream-error', listener: (ev: StreamErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'stream-start', listener: (ev: StreamStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/swatch/swatch.d.ts

@@ -73,10 +73,10 @@ pattern; blocked 3 cycles on this design call). */
   /** Size preset — sm / md / lg. Drives the swatch's intrinsic dimensions; lg is reserved for the token-scale demo (40 px tall). */
   size: 'sm' | 'md' | 'lg';
 
+  addEventListener(type: 'select', listener: (ev: SwatchSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UISwatch, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'select', listener: (ev: SwatchSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/swiper/swiper.d.ts

@@ -52,12 +52,12 @@ export class UISwiper extends UIElement {
   /** Scroll-snap alignment — start, center, end, or none. */
   snap: 'start' | 'center' | 'end' | 'none';
 
+  addEventListener(type: 'autoplay-pause', listener: (ev: SwiperAutoplayPauseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'autoplay-resume', listener: (ev: SwiperAutoplayResumeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: SwiperChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UISwiper, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'autoplay-pause', listener: (ev: SwiperAutoplayPauseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'autoplay-resume', listener: (ev: SwiperAutoplayResumeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'change', listener: (ev: SwiperChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/table/table.a2ui.json

@@ -40,7 +40,7 @@
       "default": false
     },
     "frameless": {
-      "description": "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.",
+      "description": "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.",
       "type": "boolean",
       "default": false
     },
@@ -55,7 +55,7 @@
       "default": 0
     },
     "raw": {
-      "description": "Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom \"No data\" overlay. v0.6.33+ matches the documented contract.",
+      "description": "Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Note: a `<table-ui>` placed directly inside `<card-ui><section bleed>` drops the table's visual chrome automatically (card.css, gh#796) even without `raw` — `raw` is still required to also short-circuit the data lifecycle. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom \"No data\" overlay. v0.6.33+ matches the documented contract.",
       "type": "boolean",
       "default": false
     },

package/components/table/table.d.ts

@@ -94,13 +94,13 @@ export class UITable extends UIElement {
   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. */
+  /** 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. */
   frameless: boolean;
   /** Renders N ghost skeleton rows in place of the body data (count derived from `paginate` if set, else 5). Header + columns stay intact so the table layout is preserved while data fetches. Sets aria-busy="true" on the host. Data updates are deferred until loading is set back to false. */
   loading: boolean;
   /** Rows per page. 0 = show all rows without pagination. When > 0, renders a pagination bar below the table. */
   paginate: number;
-  /** Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom "No data" overlay. v0.6.33+ matches the documented contract. */
+  /** Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Note: a `<table-ui>` placed directly inside `<card-ui><section bleed>` drops the table's visual chrome automatically (card.css, gh#796) even without `raw` — `raw` is still required to also short-circuit the data lifecycle. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom "No data" overlay. v0.6.33+ matches the documented contract. */
   raw: boolean;
   /** Global search/filter string. Filters visible rows across all columns using case-insensitive substring matching. Resets to page 1 on change. */
   search: string;
@@ -115,11 +115,6 @@ export class UITable extends UIElement {
   /** Allow body-cell content to wrap onto multiple lines. Default is single-line with ellipsis truncation (matches the row convention shared by <select-ui> + <nav-item-ui>); long unbreakable strings clip gracefully rather than rewrapping the row. With [wrap], row height auto-grows to fit wrapped content. For surgical opt-in on a single column, set [data-wrap] on the cell / col-def instead. */
   wrap: boolean;
 
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UITable, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
   addEventListener(type: 'cell-click', listener: (ev: TableCellClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'filter-change', listener: (ev: TableFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'page', listener: (ev: TablePageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
@@ -129,4 +124,9 @@ export class UITable extends UIElement {
   addEventListener(type: 'row-expand', listener: (ev: TableRowExpandEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'select', listener: (ev: TableSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'sort', listener: (ev: TableSortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITable, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
 }

package/components/table/table.yaml

@@ -74,6 +74,10 @@ props:
       surfaces that supply their own chrome (e.g. `<card-ui><section
       bleed>`), or when wrapping a consumer-authored native `<table>`
       for design-token styling without the framework's data semantics.
+      Note: a `<table-ui>` placed directly inside `<card-ui><section bleed>`
+      drops the table's visual chrome automatically (card.css, gh#796) even
+      without `raw` — `raw` is still required to also short-circuit the
+      data lifecycle.
       Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle
       still ran — wrapping a `.data`-unset native table produced a
       phantom "No data" overlay. v0.6.33+ matches the documented contract.
@@ -107,7 +111,11 @@ props:
       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.
+      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.
     type: boolean
     default: false
     reflect: true

package/components/table-toolbar/table-toolbar.d.ts

@@ -37,13 +37,13 @@ export class UITableToolbar extends UIElement {
   /** Toolbar visual variant. `default` renders bare on parent surface; `card` adds the same chrome as a card-ui header. */
   variant: 'default' | 'card';
 
+  addEventListener(type: 'columns-change', listener: (ev: TableToolbarColumnsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'filter-change', listener: (ev: TableToolbarFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'search', listener: (ev: TableToolbarSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sort-change', listener: (ev: TableToolbarSortChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITableToolbar, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'columns-change', listener: (ev: TableToolbarColumnsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'filter-change', listener: (ev: TableToolbarFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'search', listener: (ev: TableToolbarSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'sort-change', listener: (ev: TableToolbarSortChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/tabs/tabs.d.ts

@@ -27,12 +27,12 @@ export class UITabs extends UIElement {
   /** Visual variant — `default` (underline strip) or `bordered`. */
   variant: 'default' | 'bordered';
 
+  addEventListener(type: 'change', listener: (ev: TabsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITabs, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: TabsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITab extends UIElement {

package/components/tag/tag.a2ui.json

@@ -46,7 +46,7 @@
       "$ref": "common_types.json#/$defs/DynamicString"
     },
     "tone": {
-      "description": "Fill style — orthogonal to [variant]. Three values:\n  - `solid` (default for family variants) — saturated bg + on-strong\n    (near-white) text. The chip IS the state.\n  - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s\n    default look. Use on metadata chips in dense lists where the\n    saturated default would compete for attention.\n  - `outline` — transparent bg + family-colored border + family-colored\n    text. The lightest visual weight; good in dense data tables or\n    faceted filter rows where multiple chips would otherwise compete.\nThe `default` variant (no family) stays quiet chrome regardless of\ntone unless `tone=\"solid\"` is set explicitly (high-contrast neutral\ninverse), or `tone=\"outline\"` (fg-muted text + subtle border).\n",
+      "description": "Fill style — orthogonal to [variant]. Three values:\n  - `solid` (default — for EVERY variant, including the family-less\n    `default`, since gh#794) — saturated bg + on-strong (near-white)\n    text. The chip IS the state. A bare `<tag-ui text=\"…\">` renders\n    this look with no attributes at all.\n  - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s\n    default look, and is the pre-gh#794 look for the family-less\n    `default` variant. Use on metadata / citation chips in dense\n    lists or tables where the saturated default would compete for\n    attention (gh#778's oversized-pill concern).\n  - `outline` — transparent bg + family-colored border + family-colored\n    text. The lightest visual weight; good in dense data tables or\n    faceted filter rows where multiple chips would otherwise compete.\n`tone` is a declarative presentational attribute (not a reactive\nprop — see tag.class.js) so its schema `default` here is documentation\nof the rendered-by-default look, not a reflected attribute value.\n",
       "type": "string",
       "enum": [
         "solid",

package/components/tag/tag.css

@@ -6,15 +6,43 @@ tag-ui[removable]:not([disabled]):hover {
 
 @scope (tag-ui) {
   :where(:scope) {
-    /* ── Tokens ── */
-    --tag-bg:           var(--a-bg-muted);
-    --tag-fg:           var(--md-sys-color-neutral-on-surface);
+    /* ── Tokens ──
+       gh#794: the real bare-tag default lives HERE, not in the
+       `:scope[variant="default"]` rule below — `variant` is a reflect:true
+       prop (tag.class.js), and `installProps()`'s reflect() only fires on
+       a property SET, never for a value that equals its declared class
+       default at construction time. A bare `<tag-ui text="…">` therefore
+       never gets a physical `variant="default"` attribute; these
+       `:where(:scope)` zero-specificity tokens are what it actually
+       renders. Solid neutral inverse (was `--a-bg-muted` quiet chrome
+       pre-#794) — same pair the family variants and the redundant
+       `:scope[variant="default"]` rule below carry, for the rare case
+       `variant="default"` IS reflected explicitly (SSR/a2ui-producer
+       markup). Opt out via `[tone="muted"]`. */
+    --tag-bg:           var(--md-sys-color-neutral-on-surface);
+    --tag-fg:           var(--md-sys-color-neutral-background);
     --tag-border:       transparent;
     --tag-radius:       var(--a-radius-full);
     --tag-px:           var(--a-space-1-5);
-    --tag-py:           0.125rem;
+    --tag-py:           var(--a-space-0-5);
     --tag-gap:          var(--a-space-1);
     --tag-font:         var(--a-ui-sm);
+
+    /* ── Size tiers (gh#779) — md (above) is the pixel-identical default;
+       [size="sm"|"lg"] below re-point the active tokens. Component-owned
+       ladder, NOT a direct alias of the universal --a-ui-px/--a-ui-size
+       tokens (styles/api/sizing.css) — tag-ui's own md baseline predates
+       and differs from that system's md (6px/12px here vs 8px/13px
+       there), so aliasing directly would shift every default tag's
+       geometry (gh#778 is exactly this failure mode — an inflated
+       default). Instead sm/lg step off tag's OWN md baseline by the
+       same rung spacing the space/type scales already use. */
+    --tag-px-sm:  var(--a-space-1);
+    --tag-px-lg:  var(--a-space-2);
+    --tag-py-sm:  var(--a-space-px);
+    --tag-py-lg:  var(--a-space-1);
+    --tag-font-sm: var(--a-ui-xs);
+    --tag-font-lg: var(--a-ui-md);
     --tag-font-family:  var(--a-font-family-ui);
     --tag-dismiss-size: 1rem;
     --tag-bg-hover:     var(--a-bg-hover);
@@ -134,12 +162,16 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-fg: var(--md-sys-color-danger-on-danger);
   }
 
-  /* `default` (no family) stays as quiet chrome — a stark fg/bg-inverse
-     would be too loud for the no-variant case. Opt in to the inverse
-     stamp via `[tone="solid"]` when you want a high-contrast neutral pill. */
+  /* `default` (no family) is solid by default (gh#794) — the same
+     high-contrast neutral inverse the family variants already carry.
+     A bare `<tag-ui text="…">` is now a stamped pill, not quiet chrome.
+     Opt OUT to the pre-#794 quiet-chrome look via `[tone="muted"]`
+     (below) on metadata/citation chips in dense lists or tables where
+     the saturated look competes for attention (gh#778's oversized-pill
+     complaint) — same escape hatch the family variants already use. */
   :scope[variant="default"] {
-    --tag-bg: var(--a-bg-muted);
-    --tag-fg: var(--md-sys-color-neutral-on-surface);
+    --tag-bg: var(--md-sys-color-neutral-on-surface);
+    --tag-fg: var(--md-sys-color-neutral-background);
   }
 
   /* ── Tone modifier — orthogonal to [variant] ──
@@ -170,10 +202,26 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-bg: var(--md-sys-color-primary-container);
     --tag-fg: var(--md-sys-color-primary-on-surface);
   }
+  /* gh#794: the pre-#794 quiet-chrome look for the variant-less default —
+     same values the `:where(:scope)` base tokens carried before the
+     solid-default flip. This is the explicit opt-out for bare tags that
+     need the old quiet register (dense-list metadata/citation chips,
+     gh#778's oversized-pill concern) instead of the new stamped-pill
+     default. `:not([variant=…])` (not `[variant="default"]`) because
+     `variant` is a reflect:true prop whose class default ("default")
+     never gets a physical attribute reflected on a bare tag (the
+     `installProps()` reflect() path only fires on a property SET) —
+     the same reason the `[tone="solid"]` fallback below uses this same
+     `:not()` shape instead of `[variant="default"]`. */
+  :scope[tone="muted"]:not([variant="info"]):not([variant="success"]):not([variant="warning"]):not([variant="danger"]):not([variant="accent"]) {
+    --tag-bg: var(--a-bg-muted);
+    --tag-fg: var(--md-sys-color-neutral-on-surface);
+  }
 
-  /* `[tone="solid"]` on the neutral default (or no variant) inverts the
-     chrome — solid fg-color bg with bg-color text. High-contrast neutral
-     stamp. Explicit opt-in; the variant-less default stays quiet chrome.
+  /* `[tone="solid"]` explicit opt-in — redundant with the bare default
+     since gh#794 (the variant-less default is solid unconditionally
+     above) but kept so `tone="solid"` stays a valid, harmless, explicit
+     statement of intent for consumers who set it directly.
      [variant="accent"] is excluded — it already has an explicit solid
      pair above (the plain [variant="accent"] rule) that this higher-
      specificity fallback would otherwise clobber when tone="solid" is
@@ -220,7 +268,24 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-border: var(--md-sys-color-neutral-outline);
   }
 
-  /* Size handled by universal [size] attribute system. */
+  /* ── Size tiers (gh#779) — re-point the active tokens to the matching
+     tier; the token defaults at :where(:scope) above ARE the md tier, so
+     [size="md"] is declared only for explicitness (mirrors kbd.css). */
+  :scope[size="sm"] {
+    --tag-px:  var(--tag-px-sm);
+    --tag-py:  var(--tag-py-sm);
+    --tag-font: var(--tag-font-sm);
+  }
+  :scope[size="md"] {
+    --tag-px:  var(--a-space-1-5);
+    --tag-py:  var(--a-space-0-5);
+    --tag-font: var(--a-ui-sm);
+  }
+  :scope[size="lg"] {
+    --tag-px:  var(--tag-px-lg);
+    --tag-py:  var(--tag-py-lg);
+    --tag-font: var(--tag-font-lg);
+  }
 
   /* hover rule moved outside @scope — see Safari 17.x bug note at top. */
 

package/components/tag/tag.d.ts

@@ -41,26 +41,30 @@ export class UITag extends UIElement {
   /** Tag label. Renderer routes this to the `text` attribute, rendered via CSS attr(text) on ::after. */
   textContent: string;
   /** Fill style — orthogonal to [variant]. Three values:
-  - `solid` (default for family variants) — saturated bg + on-strong
-    (near-white) text. The chip IS the state.
+  - `solid` (default — for EVERY variant, including the family-less
+    `default`, since gh#794) — saturated bg + on-strong (near-white)
+    text. The chip IS the state. A bare `<tag-ui text="…">` renders
+    this look with no attributes at all.
   - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s
-    default look. Use on metadata chips in dense lists where the
-    saturated default would compete for attention.
+    default look, and is the pre-gh#794 look for the family-less
+    `default` variant. Use on metadata / citation chips in dense
+    lists or tables where the saturated default would compete for
+    attention (gh#778's oversized-pill concern).
   - `outline` — transparent bg + family-colored border + family-colored
     text. The lightest visual weight; good in dense data tables or
     faceted filter rows where multiple chips would otherwise compete.
-The `default` variant (no family) stays quiet chrome regardless of
-tone unless `tone="solid"` is set explicitly (high-contrast neutral
-inverse), or `tone="outline"` (fg-muted text + subtle border).
+`tone` is a declarative presentational attribute (not a reactive
+prop — see tag.class.js) so its schema `default` here is documentation
+of the rendered-by-default look, not a reflected attribute value.
  */
   tone: 'solid' | 'muted' | 'outline';
   /** Semantic variant — `default | accent | info | success | warning | danger`. `accent` is brand-primary emphasis for non-semantic labels — a filter chip or taxonomy tag that shouldn't imply a success/warning/danger state. Mirrors <badge-ui>'s `accent` variant token-for-token. */
   variant: 'default' | 'accent' | 'info' | 'success' | 'warning' | 'danger';
 
+  addEventListener(type: 'remove', listener: (ev: TagRemoveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITag, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'remove', listener: (ev: TagRemoveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/tag/tag.examples.md

@@ -6,14 +6,14 @@
 <tag-ui text="Default"></tag-ui>
 ```
 
-## tone
+## size
 
 ```html
-<tag-ui text="Default" tone="solid"></tag-ui>
+<tag-ui text="Small" size="sm"></tag-ui>
 ```
 
-## size
+## removable
 
 ```html
-<tag-ui text="Small" size="sm"></tag-ui>
+<tag-ui text="Removable" removable></tag-ui>
 ```

package/components/tag/tag.yaml

@@ -62,17 +62,21 @@ props:
   tone:
     description: |
       Fill style — orthogonal to [variant]. Three values:
-        - `solid` (default for family variants) — saturated bg + on-strong
-          (near-white) text. The chip IS the state.
+        - `solid` (default — for EVERY variant, including the family-less
+          `default`, since gh#794) — saturated bg + on-strong (near-white)
+          text. The chip IS the state. A bare `<tag-ui text="…">` renders
+          this look with no attributes at all.
         - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s
-          default look. Use on metadata chips in dense lists where the
-          saturated default would compete for attention.
+          default look, and is the pre-gh#794 look for the family-less
+          `default` variant. Use on metadata / citation chips in dense
+          lists or tables where the saturated default would compete for
+          attention (gh#778's oversized-pill concern).
         - `outline` — transparent bg + family-colored border + family-colored
           text. The lightest visual weight; good in dense data tables or
           faceted filter rows where multiple chips would otherwise compete.
-      The `default` variant (no family) stays quiet chrome regardless of
-      tone unless `tone="solid"` is set explicitly (high-contrast neutral
-      inverse), or `tone="outline"` (fg-muted text + subtle border).
+      `tone` is a declarative presentational attribute (not a reactive
+      prop — see tag.class.js) so its schema `default` here is documentation
+      of the rendered-by-default look, not a reflected attribute value.
     type: string
     default: solid
     enum:
@@ -127,6 +131,13 @@ a2ui:
       Group multiple tags inside a <row-ui gap="2"> — never stack them
       vertically; vertical lists of dismissable items are an
       <action-list-ui> use case, not <tag-ui>.
+    - >-
+      Bare <tag-ui text="…"> (no [tone]) renders the high-contrast
+      solid pill by default (gh#794). In dense tables, tight metadata
+      rows, or citation/footnote strips where many tags sit close
+      together, set [tone="muted"] to keep the quieter tinted look
+      instead — a wall of solid pills reads as visual noise there
+      (gh#778).
 anti_patterns: []
 examples:
   - name: basic-tag

package/components/tags-input/tags-input.d.ts

@@ -108,13 +108,13 @@ replaces the rendered chips. Reflection skipped — array values
 do not round-trip through attribute strings. */
   value: string;
 
+  addEventListener(type: 'change', listener: (ev: TagsInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'commit', listener: (ev: TagsInputCommitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: TagsInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'invalid', listener: (ev: TagsInputInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITagsInput, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: TagsInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'commit', listener: (ev: TagsInputCommitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'input', listener: (ev: TagsInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'invalid', listener: (ev: TagsInputInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/timeline/timeline.d.ts

@@ -25,12 +25,12 @@ export class UITimeline extends UIElement {
   /** Rail size preset — use `sm` for agent-reasoning/pipeline views; `md` is the default. */
   size: 'sm' | 'md';
 
+  addEventListener(type: 'timeline-toggle', listener: (ev: TimelineToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITimeline, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'timeline-toggle', listener: (ev: TimelineToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITimelineItem extends UIElement {

package/components/toc/toc.d.ts

@@ -52,10 +52,10 @@ scans the toc-ui's parent element. Set to `#article` /
  */
   target: string;
 
+  addEventListener(type: 'section-change', listener: (ev: TableOfContentsSectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITableOfContents, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'section-change', listener: (ev: TableOfContentsSectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

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

@@ -25,12 +25,12 @@ export class UIToggleGroup extends UIElement {
   /** Comma-separated selected values */
   value: string;
 
+  addEventListener(type: 'change', listener: (ev: ToggleGroupChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIToggleGroup, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: ToggleGroupChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UIToggleOption extends UIElement {

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

@@ -49,10 +49,10 @@ export class UIToggleScheme extends UIElement {
   /** Visual style forwarded to the internal <button-ui>. Defaults to "ghost" (matches app practice). */
   variant: 'default' | 'solid' | 'outline' | 'ghost' | 'primary' | 'secondary' | 'soft';
 
+  addEventListener(type: 'scheme-change', listener: (ev: ToggleSchemeSchemeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIToggleScheme, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'scheme-change', listener: (ev: ToggleSchemeSchemeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/tour/tour.d.ts

@@ -48,15 +48,15 @@ tour to that step (updating spotlight + popover position).
  */
   step: number;
 
+  addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-start', listener: (ev: TourStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-step-change', listener: (ev: TourStepChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITour, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'tour-start', listener: (ev: TourStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'tour-step-change', listener: (ev: TourStepChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITourStep extends UIElement {

package/components/tree/tree.d.ts

@@ -31,12 +31,12 @@ export type TreeSelectEvent = CustomEvent<TreeSelectEventDetail>;
 
 export class UITree extends UIElement {
 
+  addEventListener(type: 'tree-select', listener: (ev: TreeSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITree, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'tree-select', listener: (ev: TreeSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UITreeItem extends UIElement {