@adia-ai/web-components 0.8.21 → 0.8.23

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

@@ -48,6 +48,14 @@ export class UINavGroup extends UIElement {
   #popover = null;
   #anchorCleanup = null;
   #headerEl = null;
+  // gh#501 — the gh#459 ruling ("the group CONTAINING the selected route
+  // fills") self-enforces: watch descendant nav-item [selected] flips and
+  // membership changes so the header glyph fills without consumer wiring.
+  // Targets ONLY the weight sync — a full render() from the observer loops:
+  // render's textContent writes are themselves subtree childList mutations.
+  // Stable ref for symmetric disconnect.
+  #onChildSelection = () => this.#syncHeaderWeight();
+  #selectionObserver = null;
 
   #onHeaderKey = (e) => {
     if (!this.collapsible) return;
@@ -80,6 +88,21 @@ export class UINavGroup extends UIElement {
     }
 
     this.#headerEl?.addEventListener('keydown', this.#onHeaderKey);
+
+    // gh#501 — fill-on-child-selection needs no consumer wiring: observe
+    // [selected] flips on descendants + child list churn. Watching the
+    // whole subtree includes this host's own [selected], which render()
+    // reads anyway; render() writes only the icon's [weight], which the
+    // attributeFilter excludes, so the observer can't feed back.
+    if (!this.#selectionObserver) {
+      this.#selectionObserver = new MutationObserver(this.#onChildSelection);
+      this.#selectionObserver.observe(this, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['selected'],
+      });
+    }
   }
 
   render() {
@@ -99,9 +122,27 @@ export class UINavGroup extends UIElement {
     // path; [open] keeps driving aria-expanded only. A state-driven weight
     // swap, not a CSS color change, since Phosphor ships filled/regular as
     // distinct SVGs.
+    this.#syncHeaderWeight();
+  }
+
+  // Own [selected] OR any selected descendant item (gh#501) — the ruling's
+  // "group CONTAINING the selected route", self-enforcing. Skips the write
+  // when the weight is already right so the observer path stays quiet.
+  #syncHeaderWeight() {
+    const containsSelection =
+      this.hasAttribute('selected') || !!this.querySelector('nav-item-ui[selected]');
+    // Reflect contains-selection for CSS (gh#522): the icon COLOR half of
+    // the selection language keys on this host attribute — weight alone
+    // read as an unselected white glyph beside nav-item's primary one.
+    // The observer's attributeFilter is ['selected'], so this write on
+    // the host cannot feed back.
+    if (containsSelection !== this.hasAttribute('data-selected-within')) {
+      this.toggleAttribute('data-selected-within', containsSelection);
+    }
     const iconEl = this.querySelector('[slot="header"] [slot="icon"] icon-ui');
-    if (iconEl)
-      iconEl.setAttribute('weight', this.hasAttribute('selected') ? 'fill' : 'regular');
+    if (!iconEl) return;
+    const weight = containsSelection ? 'fill' : 'regular';
+    if (iconEl.getAttribute('weight') !== weight) iconEl.setAttribute('weight', weight);
   }
 
   showPopover() {
@@ -165,5 +206,7 @@ export class UINavGroup extends UIElement {
     this.#anchorCleanup?.();
     this.#anchorCleanup = null;
     this.#popover?.hidePopover?.();
+    this.#selectionObserver?.disconnect();
+    this.#selectionObserver = null;
   }
 }

package/components/nav-group/nav-group.css

@@ -14,6 +14,7 @@
     --nav-group-fg-hover:      var(--a-fg-strong);
     --nav-group-fg-muted:      var(--a-fg-muted);
     --nav-group-fg-selected:   var(--a-fg-strong);
+    --nav-group-icon-fg-selected: var(--md-sys-color-primary); /* one selection color with --nav-item-accent (gh#522) */
     --nav-group-bg-hover:      var(--a-bg-muted);
     --nav-group-icon-size:     calc(var(--nav-group-row-height) - var(--a-space-2));
     --nav-group-badge-size:    var(--a-ui-sm);
@@ -52,10 +53,18 @@
   /* Selected-look header treatment keys on [selected] — the CSS half of
      gh issue 459 (PR 460 corrected the icon weight): the group CONTAINING
      the selected route reads strong; a merely-expanded group does not. */
-  :scope[selected] > [slot="header"],
-  :scope[selected] > [slot="header"] [slot="icon"] {
+  :scope[selected] > [slot="header"] {
     color: var(--nav-group-fg-selected);
   }
+  /* Icon color = the SELECTION color, one language with nav-item's accent
+     glyph (gh#522, operator ruling 2026-07-30): filled + primary whenever
+     this group is selected OR contains the selected route.
+     [data-selected-within] is reflected by #syncHeaderWeight (gh#501) so
+     the JS-detected contains-selection state is CSS-addressable. */
+  :scope[selected] > [slot="header"] [slot="icon"],
+  :scope[data-selected-within] > [slot="header"] [slot="icon"] {
+    color: var(--nav-group-icon-fg-selected);
+  }
 
   /* Header row */
   [slot="header"] {

package/components/progress-row/progress-row.class.js

@@ -91,8 +91,16 @@ export class UIProgressRow extends UIElement {
     this.#labelEl.textContent = this.label;
     this.#labelEl.hidden = !this.label;
 
-    this.#metaEl.textContent = this.meta;
-    this.#metaEl.hidden = !this.meta;
+    // The [meta] ATTR owns the text when set. When it's absent, authored
+    // [slot="meta"] content — e.g. meta text with a trailing delta badge
+    // (gh#502) — is left intact instead of being wiped + hidden; only a
+    // genuinely empty meta element hides.
+    if (this.meta) {
+      this.#metaEl.textContent = this.meta;
+      this.#metaEl.hidden = false;
+    } else {
+      this.#metaEl.hidden = !this.#metaEl.hasChildNodes();
+    }
 
     if (this.value != null && this.value >= 0) {
       this.#progressEl.setAttribute('value', String(this.value));

package/components/richtext/richtext.css

@@ -96,6 +96,13 @@
     width: 100%;
     max-width: var(--richtext-max-width);
     padding: var(--richtext-py) var(--richtext-px);
+    /* Body spec set ONCE at the container (gh#546): p was pinned to
+       --richtext-body-size while li/ul had no font rule and inherited the
+       HOST page's larger base — chat-rendered lists read bigger than the
+       paragraph beside them. Everything now inherits this; headings/code
+       still override explicitly. */
+    font-size: var(--richtext-body-size);
+    line-height: var(--richtext-body-leading);
   }
 
   /* [flush] — paragraph-grade embedding (yaml `flush` prop): drop the

package/components/select/select.a2ui.json

@@ -106,6 +106,11 @@
       "type": "string",
       "default": ""
     },
+    "no-radio": {
+      "description": "Suppress the single-select radio indicator on option rows (gh#498). For menu-shaped switchers — workspace or user identity menus — where the trigger already shows the committed value and a per-row radio reads as redundant selection language. Rows keep their layout and aria-selected state; the trigger and selected-row weight carry the signal. No effect under [multiple]. IMPLIED by [mark] — a mark declares an identity switcher, which is always menu-shaped (gh#498 reopen: per-instance opt-outs proved forgettable).",
+      "type": "boolean",
+      "default": false
+    },
     "open": {
       "description": "Whether the listbox is open",
       "type": "boolean",

package/components/select/select.class.js

@@ -53,6 +53,10 @@ 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 },
+    // gh#498 — suppress the single-select radio indicator for menu-shaped
+    // switchers (workspace/user identity menus) where the trigger already
+    // carries the committed value; rows keep layout + aria-selected.
+    noRadio:     { type: Boolean, default: false, reflect: true, attribute: 'no-radio' },
     // §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 },
@@ -541,8 +545,12 @@ export class UISelect extends UIFormElement {
         ? new Set(this.value.split(',').map((s) => s.trim()).filter(Boolean))
         : null;
       for (const opt of this.#listbox.querySelectorAll('[role="option"]')) {
+        // Action rows have no data-value (they are commands — see the
+        // stamping note); null must never compare equal to a value, and
+        // `null === ''` is already false, but the explicit guard keeps a
+        // future `v ?? ''` normalization from resurrecting the leak.
         const v = opt.getAttribute('data-value');
-        const selected = selSet ? selSet.has(v) : v === this.value;
+        const selected = v !== null && (selSet ? selSet.has(v) : v === this.value);
         if (selected) opt.setAttribute('aria-selected', 'true');
         else opt.removeAttribute('aria-selected');
       }
@@ -766,12 +774,19 @@ export class UISelect extends UIFormElement {
       }
       const el = document.createElement('div');
       el.setAttribute('role', 'option');
-      el.setAttribute('data-value', opt.value || '');
+      // Action rows carry NO [data-value]: they are commands, not values.
+      // Stamping `opt.value || ''` gave them data-value="" — and since
+      // `this.value` ALSO defaults to '', the aria-selected sync marked
+      // every action row selected whenever nothing was committed (the
+      // default state of a user menu — reviewer finding, 2026-07-29).
+      // With the attribute absent, getAttribute() returns null and no
+      // value comparison can ever match.
+      if (!opt.action) el.setAttribute('data-value', opt.value || '');
       // §FB-46: [multiple] value is comma-separated — use Set membership.
       const selSet = this.multiple
         ? new Set(this.value.split(',').map((s) => s.trim()).filter(Boolean))
         : null;
-      const isSelected = selSet ? selSet.has(opt.value) : opt.value === this.value;
+      const isSelected = !opt.action && (selSet ? selSet.has(opt.value) : opt.value === this.value);
       // SPEC-040 — multi-select option rows render a leading checkbox
       // indicator (CSS-driven via [data-multi-option]); the `check` icon
       // shows when aria-selected="true".
@@ -806,11 +821,22 @@ export class UISelect extends UIFormElement {
         // Single-select mirrors the multi structure with a RADIO indicator
         // (operator ruling 2026-07-27) — selection is carried by the
         // indicator, not a row tint; CSS keys off [data-single-option].
+        // [no-radio] (gh#498) drops only the dot: identity-switcher menus
+        // read the committed value from the trigger, so the per-row radio
+        // is redundant there; row layout + aria-selected are unchanged.
+        // [mark] IMPLIES it (gh#498 reopen, 2026-07-30): mark declares an
+        // identity switcher, and the first fix proved per-instance
+        // attributes get forgotten — the playground got [no-radio], the
+        // site chrome switcher shipped radios anyway. The semantic
+        // attribute is the reliable signal; [no-radio] remains for
+        // markless menus.
         el.setAttribute('data-single-option', '');
-        const dot = document.createElement('span');
-        dot.setAttribute('data-radio', '');
-        dot.setAttribute('aria-hidden', 'true');
-        el.appendChild(dot);
+        if (!(this.noRadio || this.mark)) {
+          const dot = document.createElement('span');
+          dot.setAttribute('data-radio', '');
+          dot.setAttribute('aria-hidden', 'true');
+          el.appendChild(dot);
+        }
         const label = document.createElement('span');
         label.setAttribute('data-option-label', '');
         if (lead) label.innerHTML = `${lead}${escapeHTML(opt.label)}`;
@@ -1042,11 +1068,15 @@ export class UISelect extends UIFormElement {
 
   #applyFilter() {
     if (!this.#listbox) return;
-    const q = this.#query.toLowerCase();
+    // Underscores normalize to spaces on BOTH sides (gh#538): IANA-style
+    // labels ("America/Los_Angeles") must match the query a human types
+    // ("los angeles") — and vice versa.
+    const norm = (t) => t.toLowerCase().replace(/_/g, ' ');
+    const q = norm(this.#query);
     const opts = this.#listbox.querySelectorAll('[role="option"]');
     let anyVisible = false;
     for (const opt of opts) {
-      const label = (opt.textContent || '').toLowerCase();
+      const label = norm(opt.textContent || '');
       const match = !q || label.includes(q);
       if (match) {
         opt.removeAttribute('data-filtered-out');

package/components/select/select.yaml

@@ -74,6 +74,19 @@ props:
     type: boolean
     default: false
     reflect: true
+  no-radio:
+    description: >-
+      Suppress the single-select radio indicator on option rows (gh#498).
+      For menu-shaped switchers — workspace or user identity menus — where
+      the trigger already shows the committed value and a per-row radio
+      reads as redundant selection language. Rows keep their layout and
+      aria-selected state; the trigger and selected-row weight carry the
+      signal. No effect under [multiple]. IMPLIED by [mark] — a mark
+      declares an identity switcher, which is always menu-shaped
+      (gh#498 reopen: per-instance opt-outs proved forgettable).
+    type: boolean
+    default: false
+    reflect: true
   error:
     description: Validation error message
     type: string

package/components/stat/stat.js

@@ -8,6 +8,7 @@
  * Trend: up, down, neutral (colors the change badge accordingly)
  */
 
+import { defineIfFree } from '../../core/register.js';
 import { UIElement } from '../../core/element.js';
 
 class UIStat extends UIElement {
@@ -119,6 +120,8 @@ class UIStat extends UIElement {
     this.#iconEl = null;
   }
 }
-customElements.define('stat-ui', UIStat);
+// defineIfFree (gh#534): the prod bundle + module graph load in parallel;
+// second registration must no-op, not throw.
+defineIfFree('stat-ui', UIStat);
 
 export { UIStat };

package/components/stepper/stepper.css

@@ -13,20 +13,24 @@
   :where(:scope) {
     /* ── Circle ── */
     --stepper-size:            2rem;
-    --stepper-bg:              var(--md-sys-color-neutral-background);
-    --stepper-border:          var(--md-sys-color-neutral-outline);
-    --stepper-fg:              var(--a-fg-muted);
+    /* Operator stepper system (2026-07-30): next = transparent circle on a
+       low-emphasis outline; current = filled primary; completed = tonal
+       primary-container with a primary glyph. Borders on the two emphasized
+       states are transparent — the fill IS the affordance. */
+    --stepper-bg:              transparent;
+    --stepper-border:          var(--md-sys-color-neutral-outline-variant);
+    --stepper-fg:              var(--md-sys-color-neutral-on-surface-variant);
     --stepper-font:            var(--a-ui-sm);
     --stepper-weight:          var(--a-weight-medium);
     --stepper-border-size:     2px;
 
-    --stepper-bg-active:       var(--md-sys-color-neutral-background);
-    --stepper-border-active:   var(--md-sys-color-primary);
-    --stepper-fg-active:       var(--md-sys-color-primary);
+    --stepper-bg-active:       var(--md-sys-color-primary);
+    --stepper-border-active:   transparent;
+    --stepper-fg-active:       var(--md-sys-color-primary-on-primary);
 
-    --stepper-bg-done:         var(--md-sys-color-primary);
-    --stepper-border-done:     var(--md-sys-color-primary);
-    --stepper-fg-done:         var(--md-sys-color-primary-on-primary);
+    --stepper-bg-done:         var(--md-sys-color-primary-container);
+    --stepper-border-done:     transparent;
+    --stepper-fg-done:         var(--md-sys-color-primary);
 
     --stepper-line:            var(--md-sys-color-neutral-outline-variant);
     --stepper-line-done:       var(--md-sys-color-primary);
@@ -69,20 +73,20 @@
        co-located item legitimately reads parent tokens (the same
        scope pattern as menu-item-ui inside menu-ui's popover). */
     --stepper-item-size:           var(--stepper-size, 2rem);
-    --stepper-item-bg:             var(--stepper-bg, var(--md-sys-color-neutral-background));
-    --stepper-item-border:         var(--stepper-border, var(--md-sys-color-neutral-outline));
-    --stepper-item-fg:             var(--stepper-fg, var(--a-fg-muted));
+    --stepper-item-bg:             var(--stepper-bg, transparent);
+    --stepper-item-border:         var(--stepper-border, var(--md-sys-color-neutral-outline-variant));
+    --stepper-item-fg:             var(--stepper-fg, var(--md-sys-color-neutral-on-surface-variant));
     --stepper-item-font:           var(--stepper-font, var(--a-ui-sm));
     --stepper-item-weight:         var(--stepper-weight, var(--a-weight-medium));
     --stepper-item-border-size:    var(--stepper-border-size, 2px);
 
-    --stepper-item-bg-active:      var(--stepper-bg-active, var(--md-sys-color-neutral-background));
-    --stepper-item-border-active:  var(--stepper-border-active, var(--md-sys-color-primary));
-    --stepper-item-fg-active:      var(--stepper-fg-active, var(--md-sys-color-primary));
+    --stepper-item-bg-active:      var(--stepper-bg-active, var(--md-sys-color-primary));
+    --stepper-item-border-active:  var(--stepper-border-active, transparent);
+    --stepper-item-fg-active:      var(--stepper-fg-active, var(--md-sys-color-primary-on-primary));
 
-    --stepper-item-bg-done:        var(--stepper-bg-done, var(--md-sys-color-primary));
-    --stepper-item-border-done:    var(--stepper-border-done, var(--md-sys-color-primary));
-    --stepper-item-fg-done:        var(--stepper-fg-done, var(--md-sys-color-primary-on-primary));
+    --stepper-item-bg-done:        var(--stepper-bg-done, var(--md-sys-color-primary-container));
+    --stepper-item-border-done:    var(--stepper-border-done, transparent);
+    --stepper-item-fg-done:        var(--stepper-fg-done, var(--md-sys-color-primary));
 
     --stepper-item-line:           var(--stepper-line, var(--md-sys-color-neutral-outline-variant));
     --stepper-item-line-done:      var(--stepper-line-done, var(--md-sys-color-primary));
@@ -99,7 +103,8 @@
     --stepper-item-label-weight:   var(--a-weight-medium);
     --stepper-item-label-size:     var(--a-ui-size);
     --stepper-item-label-fg:       var(--md-sys-color-neutral-on-surface);
-    --stepper-item-pending-fg:     var(--a-fg-muted);
+    --stepper-item-label-fg-done:  var(--md-sys-color-neutral-on-surface-variant);
+    --stepper-item-pending-fg:     var(--md-sys-color-neutral-on-surface-variant);
     --stepper-item-desc-fg:        var(--md-sys-color-neutral-on-surface-variant);
     --stepper-item-desc-size:      var(--a-ui-sm);
 
@@ -181,7 +186,7 @@
   }
 
   :scope[status="completed"] [slot="label"] {
-    color: var(--stepper-item-label-fg);
+    color: var(--stepper-item-label-fg-done);
   }
 
   /* Pending label */

package/components/table/table.a2ui.json

@@ -14,7 +14,7 @@
   ],
   "properties": {
     "columns": {
-      "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.",
+      "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign=\"top\">).",
       "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "component": {
@@ -39,6 +39,11 @@
       "type": "boolean",
       "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.",
+      "type": "boolean",
+      "default": false
+    },
     "loading": {
       "description": "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.",
       "type": "boolean",
@@ -74,6 +79,15 @@
       "type": "boolean",
       "default": false
     },
+    "valign": {
+      "description": "Vertical alignment of body-cell content. 'center' (default) keeps today's behavior — every cell centers on the row's cross-axis, which reads well for single-line rows. 'top' aligns each cell's content to the top of its padding box instead, so tall/wrapped rows (a [wrap] title column, a stacked identity cell) share one first-line scan anchor across the row rather than each cell floating at a different vertical center (gh#505). Per-column `valign` in the columns[] array (or <col-def valign=\"…\">) overrides the host per-column — e.g. keep a checkbox column centered while data cells top-align. Header cells always stay centered regardless of this prop (single-line by contract) — the checkbox/expand structural columns also default to centered under [valign=\"top\"] since they're not part of columns[].",
+      "type": "string",
+      "enum": [
+        "top",
+        "center"
+      ],
+      "default": "center"
+    },
     "wrap": {
       "description": "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.",
       "type": "boolean",

package/components/table/table.class.js

@@ -22,6 +22,7 @@
  *   selectable — enable row selection via checkboxes
  *   striped    — alternate row background
  *   density    — 'compact' | 'standard' | 'comfortable'
+ *   valign     — 'center' (default) | 'top' — body-cell vertical alignment (gh#505)
  *   paginate   — rows per page (0 = no pagination)
  *   loading    — show loading overlay
  *   search     — global search filter string
@@ -33,7 +34,7 @@
  *
  * JS API:
  *   .columns = [{key, label, type, width, minWidth, maxWidth, flex,
- *                sortable, filterable, resizable, pinned, hidden,
+ *                sortable, filterable, resizable, pinned, hidden, valign,
  *                accessor, format, render, sortFn, sortDescFirst,
  *                filterType, filterFn, aggregate, meta}]
  *   .data    = [{...}, ...]
@@ -111,6 +112,10 @@ export class UITable extends UIElement {
     selectable: { type: Boolean, default: false, reflect: true },
     expandable: { type: Boolean, default: false, reflect: true },
     striped:    { type: Boolean, default: false, reflect: true },
+    valign:     { type: String,  default: 'center', reflect: true },
+    // gh#511 — drop the outer perimeter only (row dividers stay); the
+    // card+bleed composition's "let the container own the frame" knob.
+    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 },
@@ -412,6 +417,7 @@ export class UITable extends UIElement {
         resizable: el.hasAttribute('resizable'),
         filterable: el.hasAttribute('filterable'),
         filterType: el.getAttribute('filter-type') || null,
+        valign:    el.getAttribute('valign') || null,        // 'top' | 'center' | null (inherit host)
       };
 
       const w = el.getAttribute('width');
@@ -896,6 +902,13 @@ export class UITable extends UIElement {
         cell.dataset.align = typeDef.align;
       }
 
+      // Vertical alignment — per-column override of the host [valign] (gh#505).
+      // Only stamped when the column explicitly opts in; unset falls through
+      // to the host's --table-valign token.
+      if (col.valign) {
+        cell.dataset.valign = col.valign;
+      }
+
       // Pinned
       if (col.pinned) {
         cell.setAttribute('data-pinned', col.pinned);

package/components/table/table.css

@@ -13,10 +13,26 @@
     --table-fg-hover:         var(--a-fg-strong);
     --table-fg-secondary:     var(--a-fg-muted);
     --table-border:           var(--md-sys-color-neutral-outline-variant);
+    /* Perimeter split off the divider token (gh#511): --table-border feeds
+       BOTH the outer frame and the row dividers (TKT-0026), so consumers
+       could never drop the frame without erasing dividers. Inside card-ui
+       set --table-perimeter: transparent (or use [frameless]) — the card
+       owns the frame; standalone tables keep their chrome by default. */
+    --table-perimeter:        var(--table-border);
     --table-border-strong:    var(--md-sys-color-neutral-outline);
     --table-py:               var(--a-space-3);
     --table-px:               var(--a-space-4);
 
+    /* Body-cell vertical alignment mode (gh#505). 'center' is the default,
+       unconditional behavior every consumer already ships against — this
+       token flips to flex-start when [valign="top"] (below). Uniform
+       padding (--table-py) IS the first-line alignment story: every body
+       cell's content box starts flush at the same y-offset, so a chip in
+       one column and a wrapped title's first line in another share one
+       scan anchor, rather than each cell floating at its own vertical
+       center on a tall row. */
+    --table-valign:           center;
+
     --table-row-bg:           transparent;
     /* container-low, not the generic --a-bg-hover state-layer token
        (TKT-0020) — --a-bg-hover / --md-sys-color-neutral-hover is tuned
@@ -130,7 +146,15 @@
        inside the content box and doesn't shrink clientWidth — a real
        `border: 1px` made grid content overflow by exactly 2 px on every
        table (scrollbar appeared with nothing to scroll). */
-    box-shadow: inset 0 0 0 1px var(--table-border);
+    /* Three-sided perimeter — no TOP edge (gh#537, operator ruling
+       2026-07-30): the header row's own border-bottom is the table's top
+       structure; a line above the header reads as a stray divider under
+       a card edge or empty-state. Sides + bottom keep the standalone
+       silhouette; [frameless] still blanks all of it. */
+    box-shadow:
+      inset 1px 0 0 var(--table-perimeter),
+      inset -1px 0 0 var(--table-perimeter),
+      inset 0 -1px 0 var(--table-perimeter);
     border-radius: var(--table-radius);
     position: relative;
     /* Own stacking context — sticky headers, pinned columns, and filter
@@ -176,6 +200,9 @@
 
   /* ═══════ Column headers ═══════ */
 
+  /* align-items:center is hardcoded, NOT --table-valign (gh#505) — header
+     cells are single-line by contract regardless of [valign] on the host
+     or any column. Do not swap this to the var. */
   [role="columnheader"] {
     box-sizing: border-box;
     text-align: left;
@@ -222,7 +249,9 @@
     color: var(--table-sort-fg);
     margin-inline-start: var(--table-sort-icon-gap);
     vertical-align: middle;
-    --a-icon-size: 0.75em;
+    /* 0.95em ≈ +2px over the former 0.75em at the heading's --a-ui-xs size
+       (gh#496) — em-based so the caret keeps scaling with the register. */
+    --a-icon-size: 0.95em;
   }
 
   [aria-sort] [data-sort-icon] {
@@ -247,7 +276,7 @@
   [data-body] [role="gridcell"] {
     box-sizing: border-box;
     display: flex;
-    align-items: center;
+    align-items: var(--table-valign);
     align-self: stretch;
     padding: var(--table-py) var(--table-px);
     min-width: 0;
@@ -331,6 +360,42 @@
     justify-content: center;
   }
 
+  /* ═══════ Vertical alignment (gh#505) ═══════ */
+
+  :scope[valign="top"] {
+    --table-valign: flex-start;
+  }
+
+  /* ═══════ Frameless (gh#511) ═══════
+     Drops ONLY the perimeter faux-border; row dividers keep reading
+     --table-border. For card-composed tables, where the card owns the
+     frame and the table's square perimeter otherwise double-borders. */
+  :scope[frameless] {
+    --table-perimeter: transparent;
+  }
+
+  /* Per-column override — beats the host var regardless of [valign], in
+     either direction (top column in a center table, or vice versa).
+     Higher specificity than the base `[data-body] [role="gridcell"]`
+     rule above (:249) so it wins without relying on source order. */
+  [data-body] [role="gridcell"][data-valign="top"] {
+    align-items: flex-start;
+  }
+
+  [data-body] [role="gridcell"][data-valign="center"] {
+    align-items: center;
+  }
+
+  /* Structural columns (checkbox / expand-toggle) are never part of
+     columns[] so authors can't set [data-valign] on them — they stay
+     centered under [valign="top"] by default (gh#505's checkbox example),
+     matching the icon/control's own fixed small size regardless of row
+     height. */
+  [data-body] [role="gridcell"][data-check-col],
+  [data-body] [role="gridcell"][data-expand-col] {
+    align-items: center;
+  }
+
   /* ═══════ Row states ═══════ */
 
   [data-body] > [role="row"] {

package/components/table/table.d.ts

@@ -86,7 +86,7 @@ export interface TableSortEventDetail {
 export type TableSortEvent = CustomEvent<TableSortEventDetail>;
 
 export class UITable extends UIElement {
-  /** Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children. */
+  /** Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign="top">). */
   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;
@@ -94,6 +94,8 @@ 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. */
+  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. */
@@ -108,6 +110,8 @@ export class UITable extends UIElement {
   sortable: boolean;
   /** Alternate row background colors for visual scanning. */
   striped: boolean;
+  /** Vertical alignment of body-cell content. 'center' (default) keeps today's behavior — every cell centers on the row's cross-axis, which reads well for single-line rows. 'top' aligns each cell's content to the top of its padding box instead, so tall/wrapped rows (a [wrap] title column, a stacked identity cell) share one first-line scan anchor across the row rather than each cell floating at a different vertical center (gh#505). Per-column `valign` in the columns[] array (or <col-def valign="…">) overrides the host per-column — e.g. keep a checkbox column centered while data cells top-align. Header cells always stay centered regardless of this prop (single-line by contract) — the checkbox/expand structural columns also default to centered under [valign="top"] since they're not part of columns[]. */
+  valign: 'top' | 'center';
   /** 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;
 

package/components/table/table.yaml

@@ -20,7 +20,7 @@ composes:
   - badge-ui
 props:
   columns:
-    description: Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.
+    description: Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign="top">).
     type: array
     default: []
     dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
@@ -98,6 +98,39 @@ props:
     description: Alternate row background colors for visual scanning.
     type: boolean
     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.
+    type: boolean
+    default: false
+    reflect: true
+  valign:
+    description: >-
+      Vertical alignment of body-cell content. 'center' (default) keeps
+      today's behavior — every cell centers on the row's cross-axis, which
+      reads well for single-line rows. 'top' aligns each cell's content to
+      the top of its padding box instead, so tall/wrapped rows (a [wrap]
+      title column, a stacked identity cell) share one first-line scan
+      anchor across the row rather than each cell floating at a different
+      vertical center (gh#505). Per-column `valign` in the columns[] array
+      (or <col-def valign="…">) overrides the host per-column — e.g. keep a
+      checkbox column centered while data cells top-align. Header cells
+      always stay centered regardless of this prop (single-line by
+      contract) — the checkbox/expand structural columns also default to
+      centered under [valign="top"] since they're not part of columns[].
+    type: string
+    default: center
+    enum:
+      - top
+      - center
+    reflect: true
   wrap:
     description: >-
       Allow body-cell content to wrap onto multiple lines. Default is