@nonoun/native-ui 0.2.4 → 0.2.6

package/dist/native-ui.css

@@ -1267,6 +1267,54 @@
     display: none;
   }
 
+  /* WHY: Custom elements render as unstyled inline text until define() runs.
+     visibility:hidden preserves layout — no reflow when the element upgrades.
+     Only targets elements that call define(); CSS-only containers are excluded
+     (they never become :defined so would be permanently hidden). */
+  :where(
+    ui-accordion, ui-accordion-item,
+    ui-avatar,
+    ui-badge,
+    ui-breadcrumb, ui-breadcrumb-item,
+    ui-button,
+    ui-calendar,
+    ui-card,
+    ui-chat-input,
+    ui-checkbox,
+    ui-combobox,
+    ui-command, ui-command-empty, ui-command-group, ui-command-input, ui-command-item, ui-command-list,
+    ui-controller,
+    ui-dialog,
+    ui-drawer,
+    ui-field,
+    ui-icon,
+    ui-input,
+    ui-input-otp,
+    ui-kbd,
+    ui-layout-chat,
+    ui-layout-inspector,
+    ui-layout-sidebar, ui-layout-sidebar-item,
+    ui-listbox,
+    ui-nav, ui-nav-group, ui-nav-group-header, ui-nav-item,
+    ui-option, ui-option-group, ui-option-group-header,
+    ui-pagination,
+    ui-radio, ui-radio-group,
+    ui-range,
+    ui-section,
+    ui-segment, ui-segmented-control,
+    ui-select,
+    ui-slide, ui-slideshow,
+    ui-switch,
+    ui-tab, ui-tab-panel, ui-tab-panels, ui-tabs,
+    ui-table, ui-table-body, ui-table-cell, ui-table-head, ui-table-header, ui-table-row,
+    ui-textarea,
+    ui-toolbar,
+    ui-tooltip,
+    ui-tree, ui-tree-item
+  ):not(:defined) {
+    visibility: hidden;
+  }
+
   /* ── Document Defaults ── */
 
   :where(:root) {
@@ -1460,7 +1508,7 @@
     --ui-tooltip-max-width: 20rem;
 
     /* Popover (select / combobox / command) */
-    --ui-popover-max-height: 18rem;
+    --ui-popover-max-height: calc(100dvh - 2rem);
     --ui-popover-gap: 0.25rem;
 
     /* Drawer */
@@ -1493,6 +1541,18 @@
     --ui-badge-size-xl: 1.375rem;
     --ui-badge-dot: 0.5rem;
 
+    /* Kbd */
+    --ui-kbd-font-xs: 0.625rem;
+    --ui-kbd-font-sm: 0.6875rem;
+    --ui-kbd-font-md: 0.6875rem;
+    --ui-kbd-font-lg: 0.75rem;
+    --ui-kbd-font-xl: 0.8125rem;
+    --ui-kbd-size-xs: 1rem;
+    --ui-kbd-size-sm: 1.125rem;
+    --ui-kbd-size-md: 1.25rem;
+    --ui-kbd-size-lg: 1.375rem;
+    --ui-kbd-size-xl: 1.5rem;
+
     /* Group header (option-group, table category) */
     --ui-group-header-font: 0.625rem;
 
@@ -1606,6 +1666,8 @@
   /* ── Intent (maps to color token families) ── */
 
   :root {
+    --_body: var(--neutral-body);
+
     --_card: var(--neutral-card);
     --_card-hover: var(--neutral-card-hover);
 
@@ -1657,6 +1719,22 @@
     --_ink-disabled: var(--neutral-ink-disabled);
   }
 
+  /* ── Toggle control defaults ── */
+  /* WHY: Checkboxes, radios, switches, and range sliders use accent-colored
+     surface fills for their checked/active states by default.
+     [intent] selectors below override --_surface when an explicit intent is set. */
+
+  :where(ui-checkbox, ui-radio, ui-switch, ui-range) {
+    --_surface: var(--accent-surface);
+    --_surface-hover: var(--accent-surface-hover);
+    --_surface-active: var(--accent-surface-active);
+    --_surface-disabled: var(--accent-surface-disabled);
+    --_surface-ink: var(--accent-surface-ink);
+    --_surface-ink-hover: var(--accent-surface-ink-hover);
+    --_surface-ink-active: var(--accent-surface-ink-active);
+    --_surface-ink-disabled: var(--accent-surface-ink-disabled);
+  }
+
   :where([intent="neutral"]) {
     --_card: var(--neutral-card);
     --_card-hover: var(--neutral-card-hover);
@@ -2369,7 +2447,7 @@
     font-weight: var(--_font-weight);
 
     border-radius: var(--_radius);
-    border: 1px solid var(--_border-color, var(--neutral-border-muted));
+    border: 1px solid var(--_border-color, var(--_border-muted));
 
     background: var(--_background, var(--_button));
     color: var(--_color, var(--_ink));
@@ -2386,17 +2464,17 @@
 
   :where(ui-button):hover,
   :where(ui-button)[force-hover] {
-    background: var(--_background-hover, var(--neutral-button-hover));
+    background: var(--_background-hover, var(--_button-hover));
     color: var(--_color-hover, var(--_ink-hover));
-    border-color: var(--_border-color-hover, var(--neutral-border-hover));
+    border-color: var(--_border-color-hover, var(--_border-hover));
   }
 
   :where(ui-button):active,
   :where(ui-button)[pressed],
   :where(ui-button)[force-active] {
-    background: var(--_background-active, var(--neutral-button-active));
+    background: var(--_background-active, var(--_button-active));
     color: var(--_color-active, var(--_ink-active));
-    border-color: var(--_border-color-active, var(--neutral-border-active));
+    border-color: var(--_border-color-active, var(--_border-active));
   }
 
   :where(ui-button):focus-visible,
@@ -2406,9 +2484,9 @@
   }
 
   :where(ui-button)[aria-disabled="true"] {
-    background: var(--_background-disabled, var(--neutral-button-disabled));
+    background: var(--_background-disabled, var(--_button-disabled));
     color: var(--_color-disabled, var(--_ink-disabled));
-    border-color: var(--_border-color-disabled, var(--neutral-border-muted));
+    border-color: var(--_border-color-disabled, var(--_border-muted));
     cursor: not-allowed;
     pointer-events: none;
   }
@@ -2981,34 +3059,25 @@
   }
 
   /* ── Checked State ── */
-  /* WHY: Default checked fill uses accent so checkbox is visually distinct
-     without needing intent="accent". Unchecked borders stay neutral.
+  /* WHY: Default checked fill uses --_surface (accent by default via
+     intent="accent" being the implicit default for toggle controls).
      When an explicit [intent] is set, the intent selector's --_surface wins. */
 
   :where(ui-checkbox)[aria-checked="true"]::before {
-    background: var(--accent-surface);
-    border-color: var(--accent-surface);
-  }
-
-  :where(ui-checkbox)[aria-checked="true"]::after {
-    background: var(--accent-surface-ink);
-    transform: translateY(-50%) scale(1);
-  }
-
-  :where(ui-checkbox)[intent][aria-checked="true"]::before {
     background: var(--_surface);
     border-color: var(--_surface);
   }
 
-  :where(ui-checkbox)[intent][aria-checked="true"]::after {
+  :where(ui-checkbox)[aria-checked="true"]::after {
     background: var(--_surface-ink);
+    transform: translateY(-50%) scale(1);
   }
 
   /* ── Indeterminate State ── */
 
   :where(ui-checkbox)[aria-checked="mixed"]::before {
-    background: var(--accent-surface);
-    border-color: var(--accent-surface);
+    background: var(--_surface);
+    border-color: var(--_surface);
   }
 
   :where(ui-checkbox)[aria-checked="mixed"]::after {
@@ -3016,17 +3085,8 @@
     -webkit-mask-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' fill='currentColor' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M228,128a12,12,0,0,1-12,12H40a12,12,0,0,1,0-24H216A12,12,0,0,1,228,128Z'/%3E%3C/svg%3E");
     mask-size: 75%;
     -webkit-mask-size: 75%;
-    background: var(--accent-surface-ink);
-    transform: translateY(-50%) scale(1);
-  }
-
-  :where(ui-checkbox)[intent][aria-checked="mixed"]::before {
-    background: var(--_surface);
-    border-color: var(--_surface);
-  }
-
-  :where(ui-checkbox)[intent][aria-checked="mixed"]::after {
     background: var(--_surface-ink);
+    transform: translateY(-50%) scale(1);
   }
 
   /* ── Hover ── */
@@ -3046,14 +3106,6 @@
   :where(ui-checkbox)[aria-checked="mixed"]:hover::before,
   :where(ui-checkbox)[aria-checked="true"][force-hover]::before,
   :where(ui-checkbox)[aria-checked="mixed"][force-hover]::before {
-    background: var(--accent-surface-hover);
-    border-color: var(--accent-surface-hover);
-  }
-
-  :where(ui-checkbox)[intent][aria-checked="true"]:hover::before,
-  :where(ui-checkbox)[intent][aria-checked="mixed"]:hover::before,
-  :where(ui-checkbox)[intent][aria-checked="true"][force-hover]::before,
-  :where(ui-checkbox)[intent][aria-checked="mixed"][force-hover]::before {
     background: var(--_surface-hover);
     border-color: var(--_surface-hover);
   }
@@ -3067,12 +3119,6 @@
 
   :where(ui-checkbox)[aria-checked="true"][pressed]::before,
   :where(ui-checkbox)[aria-checked="mixed"][pressed]::before {
-    background: var(--accent-surface-active);
-    border-color: var(--accent-surface-active);
-  }
-
-  :where(ui-checkbox)[intent][aria-checked="true"][pressed]::before,
-  :where(ui-checkbox)[intent][aria-checked="mixed"][pressed]::before {
     background: var(--_surface-active);
     border-color: var(--_surface-active);
   }
@@ -3726,6 +3772,45 @@
 
 }
 
+@layer ui {
+
+  /* ╭──────────────────────────────────────────────────────────╮
+     │  ui-kbd                                                   │
+     │  Keyboard shortcut indicator. Own font/size scale         │
+     │  (like ui-badge) — zero-attribute = md.                   │
+     ╰──────────────────────────────────────────────────────────╯ */
+
+  :where(ui-kbd) {
+    --_icon-size: 1.125em;
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-family: ui-monospace, monospace;
+    font-size: var(--ui-kbd-font-md);
+    line-height: 1;
+    min-height: var(--ui-kbd-size-md);
+    padding-inline: 0.4em;
+    border-radius: 0.5em;
+    background: var(--_ground, var(--_body));
+    border: 1px solid var(--_border-muted);
+    color: var(--_ink-muted);
+    white-space: nowrap;
+    user-select: none;
+    flex-shrink: 0;
+    vertical-align: baseline;
+  }
+
+  /* ── Sizes ── */
+
+  :where(ui-kbd[size="xs"]) { font-size: var(--ui-kbd-font-xs); min-height: var(--ui-kbd-size-xs); }
+  :where(ui-kbd[size="sm"]) { font-size: var(--ui-kbd-font-sm); min-height: var(--ui-kbd-size-sm); }
+  :where(ui-kbd[size="md"]) { font-size: var(--ui-kbd-font-md); min-height: var(--ui-kbd-size-md); }
+  :where(ui-kbd[size="lg"]) { font-size: var(--ui-kbd-font-lg); min-height: var(--ui-kbd-size-lg); }
+  :where(ui-kbd[size="xl"]) { font-size: var(--ui-kbd-font-xl); min-height: var(--ui-kbd-size-xl); }
+
+}
+
 @layer ui {
 
   /* ── Listbox Base ── */
@@ -3866,11 +3951,14 @@
      │  Uses ui-nav-item / ui-nav-group for children.           │
      ╰──────────────────────────────────────────────────────────╯ */
 
+  /* WHY: ui-nav is a transparent flex wrapper — no inline padding.
+     Inline padding is owned by leaf items (nav-item, summary).
+     Block padding is owned by nav-group margins. */
   :where(ui-nav) {
     display: flex;
     flex-direction: column;
     gap: 0;
-    padding: var(--_space);
+    padding: 0;
     outline: none;
   }
 
@@ -3885,6 +3973,7 @@
     display: flex;
     align-items: center;
     gap: calc(var(--_space) * 2);
+    padding-inline: calc(var(--_space-k) * var(--_space));
 
     min-height: var(--_min-height);
 
@@ -3984,6 +4073,7 @@
     display: flex;
     align-items: center;
     gap: calc(var(--_space) * 2);
+    padding-inline: calc(var(--_space-k) * var(--_space));
     cursor: pointer;
     user-select: none;
     list-style: none;
@@ -4018,6 +4108,18 @@
     user-select: none;
   }
 
+  /* WHY: Fixed-size icon well — matches ui-layout-sidebar-item [slot="icon"].
+     All sidebar icons align on the same 1.5rem column regardless of icon size.
+     JS wraps the first <ui-icon> child in a .icon-well span during setup(). */
+  :where(ui-nav-group-header) > :where(.icon-well) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    flex-shrink: 0;
+  }
+
   /* ── Chevron icon (right side of summary) ── */
 
   :where(ui-nav-group) > :where(details) > :where(summary)::after {
@@ -4071,12 +4173,16 @@
   /* WHY: Connector draws from below the header to the bottom of the group.
      Only shown when header contains an icon. Scoped via :has(). */
 
-  :where(ui-nav-group):has(:where(ui-nav-group-header) :where(ui-icon)) {
-    --_group-line-inset: calc(var(--_icon-size) / 2);
-    --_group-child-inset: calc(var(--_icon-size) + var(--_space) * 2);
+  /* WHY: Insets account for the summary's padding-inline so the connector
+     line passes through the icon center and child text aligns with header text. */
+  :where(ui-nav-group):has(:where(ui-nav-group-header) :where(.icon-well)) {
+    --_group-pad: calc(var(--_space-k) * var(--_space));
+    --_group-icon-well: 1.5rem;
+    --_group-line-inset: calc(var(--_group-pad) + var(--_group-icon-well) / 2);
+    --_group-child-inset: calc(var(--_group-icon-well) + var(--_space) * 2);
   }
 
-  :where(ui-nav-group):has(:where(ui-nav-group-header) :where(ui-icon)):has(:where(details[open]))::after {
+  :where(ui-nav-group):has(:where(ui-nav-group-header) :where(.icon-well)):has(:where(details[open]))::after {
     content: '';
     position: absolute;
     inset-inline-start: var(--_group-line-inset);
@@ -4091,7 +4197,7 @@
   /* WHY: A ::before pseudo on the group slides along the connector line.
      JS sets --_indicator-index; :state(has-selection) gates visibility. */
 
-  :where(ui-nav-group):has(:where(ui-nav-group-header) :where(ui-icon)):has(:where(details[open])):state(has-selection)::before {
+  :where(ui-nav-group):has(:where(ui-nav-group-header) :where(.icon-well)):has(:where(details[open])):state(has-selection)::before {
     content: '';
     position: absolute;
     z-index: 1;
@@ -4118,6 +4224,73 @@
     margin-inline-start: var(--_group-child-inset, 0);
   }
 
+  /* ── Nav Group Flyout (collapsed sidebar) ── */
+  /* WHY: In collapsed mode, summary click opens a ui-listbox popover to the right
+     instead of expanding the <details>. Same pattern as sidebar-trigger menus. */
+
+  :where(ui-nav-group) > :where(ui-listbox.nav-group-flyout[popover]) {
+    position: fixed;
+    position-area: inline-end span-block-end;
+    position-try-fallbacks: --nav-flyout-flip-up;
+    margin: 0 0 0 var(--ui-popover-gap);
+    min-width: 200px;
+    max-height: var(--ui-popover-max-height);
+    overflow-y: auto;
+  }
+
+  @position-try --nav-flyout-flip-up {
+    position-area: inline-end span-block-start;
+  }
+
+  /* ── Container Query: Collapsed Sidebar ── */
+  /* WHY: Nav components own their own collapsed behavior via @container.
+     The sidebar aside declares container-name: sidebar. When it shrinks
+     to 48px (icon rail), nav responds to the width — not to [collapsed].
+     Threshold 80px: collapsed = 48px, min expanded = 160px. */
+
+  @container sidebar (max-width: 80px) {
+
+    /* Nav items hide entirely — only group headers (with icons) remain. */
+    :where(ui-nav-item) {
+      display: none;
+    }
+
+    /* Summary shrinks to icon-only. Reduced inline padding wraps tightly
+       around the icon; parent align-items: center handles horizontal centering. */
+    :where(ui-nav-group) > :where(details) > :where(summary) {
+      padding-inline: var(--_space);
+      border-radius: var(--_radius);
+    }
+
+    /* Hide chevron — no expand/collapse in icon rail (flyout instead). */
+    :where(ui-nav-group) > :where(details) > :where(summary)::after {
+      display: none;
+    }
+
+    /* Hide vertical connector line and sliding indicator. */
+    :where(ui-nav-group)::after,
+    :where(ui-nav-group)::before {
+      display: none;
+    }
+
+    /* Header collapses to icon-only. font-size: 0 hides text nodes
+       (can't be targeted by CSS). Icon overrides back to normal below. */
+    :where(ui-nav-group-header) {
+      flex: 0 0 auto;
+      font-size: 0;
+      gap: 0;
+    }
+
+    :where(ui-nav-group-header) :where(.icon-well) :where(ui-icon) {
+      font-size: var(--_font-size, 1rem);
+    }
+
+    /* Collapse inter-group spacing in icon rail. */
+    :where(ui-nav-group) + :where(ui-nav-group) {
+      margin-block-start: 0;
+    }
+  }
+
 }
 
 @layer ui {
@@ -4258,27 +4431,15 @@
   }
 
   /* ── Selected ── */
-  /* WHY: Default selected fill uses accent so radio is visually distinct
-     without needing intent="accent". Unchecked borders stay neutral.
-     When an explicit [intent] is set, the intent selector's --_surface wins. */
 
   :where(ui-radio)[aria-checked="true"]::before {
-    background: var(--accent-surface);
-    border-color: var(--accent-surface);
-  }
-
-  :where(ui-radio)[aria-checked="true"]::after {
-    background: var(--accent-surface-ink);
-    transform: translateY(-50%) scale(1);
-  }
-
-  :where(ui-radio-group)[intent] :where(ui-radio)[aria-checked="true"]::before {
     background: var(--_surface);
     border-color: var(--_surface);
   }
 
-  :where(ui-radio-group)[intent] :where(ui-radio)[aria-checked="true"]::after {
+  :where(ui-radio)[aria-checked="true"]::after {
     background: var(--_surface-ink);
+    transform: translateY(-50%) scale(1);
   }
 
   /* ── Hover ── */
@@ -4296,12 +4457,6 @@
 
   :where(ui-radio)[aria-checked="true"]:hover::before,
   :where(ui-radio)[aria-checked="true"][force-hover]::before {
-    background: var(--accent-surface-hover);
-    border-color: var(--accent-surface-hover);
-  }
-
-  :where(ui-radio-group)[intent] :where(ui-radio)[aria-checked="true"]:hover::before,
-  :where(ui-radio-group)[intent] :where(ui-radio)[aria-checked="true"][force-hover]::before {
     background: var(--_surface-hover);
     border-color: var(--_surface-hover);
   }
@@ -4314,11 +4469,6 @@
   }
 
   :where(ui-radio)[aria-checked="true"][pressed]::before {
-    background: var(--accent-surface-active);
-    border-color: var(--accent-surface-active);
-  }
-
-  :where(ui-radio-group)[intent] :where(ui-radio)[aria-checked="true"][pressed]::before {
     background: var(--_surface-active);
     border-color: var(--_surface-active);
   }
@@ -4417,16 +4567,12 @@
     /* 0% = track-height (circle), 100% = full width */
     width: calc(var(--_track-height) + (100% - var(--_track-height)) * var(--_progress));
     border-radius: calc(var(--_track-height) / 2);
-    background: var(--accent-surface);
+    background: var(--_surface);
 
     transition:
       background var(--_duration) var(--_easing);
   }
 
-  :where(ui-range)[intent]::after {
-    background: var(--_surface);
-  }
-
   /* ── Thumb ── */
 
   :where(ui-range) > :where(.ui-range-thumb) {
@@ -4438,8 +4584,8 @@
     width: var(--_thumb-size);
     height: var(--_thumb-size);
     border-radius: 50%;
-    background: var(--accent-surface-ink);
-    border: 2px solid var(--accent-surface);
+    background: var(--_surface-ink);
+    border: 2px solid var(--_surface);
     box-shadow: var(--ui-shadow-sm);
     pointer-events: none;
 
@@ -4449,11 +4595,6 @@
       border-color var(--_duration) var(--_easing);
   }
 
-  :where(ui-range)[intent] > :where(.ui-range-thumb) {
-    background: var(--_surface-ink);
-    border-color: var(--_surface);
-  }
-
   /* ── Focus ── */
 
   :where(ui-range):focus-visible > :where(.ui-range-thumb),
@@ -4466,22 +4607,11 @@
 
   :where(ui-range):hover::after,
   :where(ui-range)[force-hover]::after {
-    background: var(--accent-surface-hover);
-  }
-
-  :where(ui-range)[intent]:hover::after,
-  :where(ui-range)[intent][force-hover]::after {
     background: var(--_surface-hover);
   }
 
   :where(ui-range):hover > :where(.ui-range-thumb),
   :where(ui-range)[force-hover] > :where(.ui-range-thumb) {
-    border-color: var(--accent-surface-hover);
-    box-shadow: var(--ui-shadow-sm), 0 0 0 4px var(--accent-surface);
-  }
-
-  :where(ui-range)[intent]:hover > :where(.ui-range-thumb),
-  :where(ui-range)[intent][force-hover] > :where(.ui-range-thumb) {
     border-color: var(--_surface-hover);
     box-shadow: var(--ui-shadow-sm), 0 0 0 4px var(--_surface);
   }
@@ -4489,19 +4619,10 @@
   /* ── Active (dragging) ── */
 
   :where(ui-range)[pressed]::after {
-    background: var(--accent-surface-active);
-  }
-
-  :where(ui-range)[intent][pressed]::after {
     background: var(--_surface-active);
   }
 
   :where(ui-range)[pressed] > :where(.ui-range-thumb) {
-    border-color: var(--accent-surface-active);
-    box-shadow: var(--ui-shadow-sm), 0 0 0 6px var(--accent-surface);
-  }
-
-  :where(ui-range)[intent][pressed] > :where(.ui-range-thumb) {
     border-color: var(--_surface-active);
     box-shadow: var(--ui-shadow-sm), 0 0 0 6px var(--_surface);
   }
@@ -5056,22 +5177,13 @@
      When an explicit [intent] is set, the intent selector's --_surface wins. */
 
   :where(ui-switch)[aria-checked="true"]::before {
-    background: var(--accent-surface);
-    border-color: var(--accent-surface);
+    background: var(--_surface);
+    border-color: var(--_surface);
   }
 
   :where(ui-switch)[aria-checked="true"]::after {
     /* Slide thumb to the right via translateX — GPU composited */
     transform: translateY(-50%) translateX(calc(var(--_track-width) - var(--_thumb-size) - var(--_thumb-offset) * 2));
-    background: var(--accent-surface-ink);
-  }
-
-  :where(ui-switch)[intent][aria-checked="true"]::before {
-    background: var(--_surface);
-    border-color: var(--_surface);
-  }
-
-  :where(ui-switch)[intent][aria-checked="true"]::after {
     background: var(--_surface-ink);
   }
 
@@ -5090,12 +5202,6 @@
 
   :where(ui-switch)[aria-checked="true"]:hover::before,
   :where(ui-switch)[aria-checked="true"][force-hover]::before {
-    background: var(--accent-surface-hover);
-    border-color: var(--accent-surface-hover);
-  }
-
-  :where(ui-switch)[intent][aria-checked="true"]:hover::before,
-  :where(ui-switch)[intent][aria-checked="true"][force-hover]::before {
     background: var(--_surface-hover);
     border-color: var(--_surface-hover);
   }
@@ -5108,11 +5214,6 @@
   }
 
   :where(ui-switch)[aria-checked="true"][pressed]::before {
-    background: var(--accent-surface-active);
-    border-color: var(--accent-surface-active);
-  }
-
-  :where(ui-switch)[intent][aria-checked="true"][pressed]::before {
     background: var(--_surface-active);
     border-color: var(--_surface-active);
   }
@@ -6572,7 +6673,7 @@
 
   :where(ui-layout-chat) :where(.layout-resize-handle):hover,
   :where(ui-layout-chat[resizing]) :where(.layout-resize-handle) {
-    background: var(--neutral-border-muted);
+    background: var(--_border-muted);
   }
 
 }
@@ -6634,7 +6735,7 @@
 
   :where(ui-layout-inspector) :where(.layout-resize-handle):hover,
   :where(ui-layout-inspector[resizing]) :where(.layout-resize-handle) {
-    background: var(--neutral-border-muted);
+    background: var(--_border-muted);
   }
 
 }
@@ -6661,16 +6762,16 @@
     content: '';
     width: var(--ui-layout-sidebar-width);
     flex-shrink: 0;
-    background: var(--neutral-body);
-    border-right: 1px solid var(--neutral-border-muted);
+    background: var(--_body);
+    border-right: 1px solid var(--_border-muted);
   }
 
   :where(ui-layout-sidebar):not([data-ready])[collapsed]::before {
     content: '';
     width: 48px;
     flex-shrink: 0;
-    background: var(--neutral-body);
-    border-right: 1px solid var(--neutral-border-muted);
+    background: var(--_body);
+    border-right: 1px solid var(--_border-muted);
   }
 
   /* ── Content Column ── */
@@ -6686,16 +6787,23 @@
   }
 
   /* ── Sidebar Aside ── */
+  /* WHY: position: relative creates the containing block for absolute
+     header/footer overlays. Content fills the full height and scrolls
+     underneath the pinned header/footer. */
 
   :where(ui-layout-sidebar) > :where([slot="sidebar"]) {
+    --_sidebar-header-height: 0px;
+    --_sidebar-footer-height: 0px;
+
+    container-name: sidebar;
+    container-type: inline-size;
+    position: sticky;
+    top: 0;
     width: var(--ui-layout-sidebar-width);
     min-width: 160px;
     max-width: 400px;
     height: 100dvh;
-    position: sticky;
-    top: 0;
-    display: flex;
-    flex-direction: column;
+    display: block;
     transition: width var(--_duration) var(--_easing), min-width var(--_duration) var(--_easing);
     overflow: hidden;
     z-index: 10;
@@ -6707,7 +6815,9 @@
   }
 
   /* ── Collapsed Icon Rail ── */
-  /* WHY: Collapsed = icon rail, not fully hidden. 48px fits icons (1rem) + padding. */
+  /* WHY: Collapsed = icon rail, not fully hidden. 48px fits icons (1rem) + padding.
+     [collapsed] drives the aside to 48px which triggers @container sidebar queries
+     in this file and in child component CSS (ui-nav.css, etc.). */
 
   :where(ui-layout-sidebar)[collapsed] > :where([slot="sidebar"]) {
     width: 48px;
@@ -6728,11 +6838,7 @@
 
   :where(ui-layout-sidebar) :where(.layout-resize-handle):hover,
   :where(ui-layout-sidebar) > :where([slot="sidebar"][resizing]) :where(.layout-resize-handle) {
-    background: var(--neutral-border-muted);
-  }
-
-  :where(ui-layout-sidebar)[collapsed] > :where([slot="sidebar"]) :where(.layout-resize-handle) {
-    display: none;
+    background: var(--_border-muted);
   }
 
   /* WHY: When collapsed to icon rail, the sidebar edge meets content — drop left padding. */
@@ -6745,101 +6851,89 @@
     padding-left: 0;
   }
 
-  /* ── Collapsed Icon-Rail Content ── */
-  /* WHY: When collapsed, sidebar slot becomes a narrow icon rail.
-     Text and trailing slots are hidden; only icons remain visible.
-     Nav items hide entirely — only group headers (with icons) stay. */
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-layout-sidebar-content) {
-    align-items: center;
-    padding: 0.5rem;
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-layout-sidebar-header),
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-layout-sidebar-footer) {
-    justify-content: center;
-    padding-inline: 0.5rem;
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-layout-sidebar-trigger) :where([slot="label"]),
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-layout-sidebar-trigger) :where([slot="trailing"]) {
-    display: none;
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-item) {
-    display: none;
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-group) > :where(details) > :where(summary) {
-    justify-content: center;
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-group) > :where(details) > :where(summary)::after {
-    display: none;
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-group)::after,
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-group)::before {
-    display: none;
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-group-header) {
-    justify-content: center;
-    font-size: 0;
-    gap: 0;
-  }
-
-  /* WHY: Icon keeps its size even though parent font-size is 0. */
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-group-header) :where(ui-icon) {
-    font-size: var(--_font-size, 1rem);
-  }
-
-  :where(ui-layout-sidebar)[collapsed] :where([slot="sidebar"]) :where(ui-nav-group) + :where(ui-nav-group) {
-    margin-block-start: 0;
-  }
-
   /* ── Sidebar Header ── */
+  /* WHY: Absolute-positioned overlay pinned to top of aside. Content scrolls
+     underneath it. z-index: 2 sits above content (z-index: 0). */
 
   :where(ui-layout-sidebar-header) {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    z-index: 2;
     display: flex;
-    align-items: center;
-    min-height: var(--ui-layout-bar-height);
-    gap: calc(var(--_space) * 2);
-    padding-block: var(--_space);
-    padding-inline: calc(var(--_space-k) * var(--_space));
-    flex-shrink: 0;
+    flex-direction: column;
   }
 
   /* ── Sidebar Content ── */
+  /* WHY: Full height of the aside, scrollable. Padding-block offsets keep
+     content from starting behind header / ending behind footer.
+     Fade-out alpha mask dissolves content edges under the overlays. */
 
   :where(ui-layout-sidebar-content) {
     display: flex;
     flex-direction: column;
-    gap: calc(var(--_space) * 2);
-    padding-block: var(--_space);
-    padding-inline: calc(var(--_space-k) * var(--_space));
-    flex: 1;
-    min-height: 0;
+    padding-block-start: var(--_sidebar-header-height);
+    padding-block-end: var(--_sidebar-footer-height);
     width: 100%;
+    height: 100%;
+    overflow-y: auto;
+    scrollbar-width: none;
+  }
+
+  /* WHY: When header is present, fade top edge. Content dissolves as it
+     scrolls under the header — transparent at top, fully visible by 1.25×
+     the header height. No opaque header background needed. */
+  :where(ui-layout-sidebar-content)[data-has-header] {
+    mask-image: linear-gradient(
+      to bottom,
+      transparent 0,
+      black calc(var(--_sidebar-header-height) * 1.25),
+      black 100%
+    );
+  }
+
+  /* WHY: When footer is present, fade bottom edge. */
+  :where(ui-layout-sidebar-content)[data-has-footer] {
+    mask-image: linear-gradient(
+      to bottom,
+      black 0,
+      black calc(100% - var(--_sidebar-footer-height) * 1.25),
+      transparent 100%
+    );
+  }
+
+  /* WHY: When both header AND footer are present, fade both edges. */
+  :where(ui-layout-sidebar-content)[data-has-header][data-has-footer] {
+    mask-image: linear-gradient(
+      to bottom,
+      transparent 0,
+      black calc(var(--_sidebar-header-height) * 1.25),
+      black calc(100% - var(--_sidebar-footer-height) * 1.25),
+      transparent 100%
+    );
   }
 
   /* ── Sidebar Footer ── */
+  /* WHY: Absolute-positioned overlay pinned to bottom of aside. */
 
   :where(ui-layout-sidebar-footer) {
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    z-index: 2;
     display: flex;
-    align-items: center;
-    min-height: var(--ui-layout-bar-height);
-    gap: calc(var(--_space) * 2);
-    padding-block: var(--_space);
-    padding-inline: calc(var(--_space-k) * var(--_space));
-    flex-shrink: 0;
+    flex-direction: column;
   }
 
-  /* ── Sidebar Trigger ── */
-  /* WHY: Menu trigger for sidebar header/footer. Styled like ui-nav-group-header:
-     bold text, icon support, hover color. Opens a popover on click. */
+  /* ── Sidebar Item ── */
+  /* WHY: Universal sidebar row element. Provides inline padding for any content
+     (buttons, links, icons). When a child ui-listbox[popover] is present, JS
+     wires PopoverController for click-to-toggle menu behavior.
+     Absorbs the old ui-layout-sidebar-trigger role — one element for all rows. */
 
-  :where(ui-layout-sidebar-trigger) {
+  :where(ui-layout-sidebar-item) {
     display: flex;
     align-items: center;
     flex: 1;
@@ -6855,31 +6949,61 @@
     user-select: none;
     border: none;
     background: none;
-    padding: var(--_space);
+    padding-block: var(--_space);
+    padding-inline: calc(var(--_space-k) * var(--_space));
     border-radius: var(--_radius);
     transition: color var(--_duration) var(--_easing);
   }
 
-  :where(ui-layout-sidebar-trigger):hover,
-  :where(ui-layout-sidebar-trigger)[force-hover] {
+  /* WHY: Items in header/footer match the breadcrumb bar height so the
+     first sidebar row aligns horizontally with the breadcrumb. */
+  :where(ui-layout-sidebar-header) > :where(ui-layout-sidebar-item),
+  :where(ui-layout-sidebar-footer) > :where(ui-layout-sidebar-item) {
+    min-height: var(--ui-layout-bar-height);
+  }
+
+  :where(ui-layout-sidebar-item):hover,
+  :where(ui-layout-sidebar-item)[force-hover] {
     color: var(--_ink-strong);
   }
 
-  :where(ui-layout-sidebar-trigger):focus-visible,
-  :where(ui-layout-sidebar-trigger)[force-focus-visible] {
+  :where(ui-layout-sidebar-item):focus-visible,
+  :where(ui-layout-sidebar-item)[force-focus-visible] {
     outline: 2px solid var(--ui-focus-ring);
     outline-offset: -2px;
   }
 
+  /* WHY: Fixed-size icon well so all sidebar icons (header logo, nav group icons,
+     standalone icons) center-align on the same column width regardless of intrinsic
+     icon size. 1.5rem matches the sidebar's visual rhythm at default density.
+     Consumer wraps the icon: <span slot="icon"><ui-icon name="..."></ui-icon></span>
+     The wrapper is the well; the icon keeps its own --ui-icon-size dimensions. */
+  :where(ui-layout-sidebar-item) > :where([slot="icon"]) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    flex-shrink: 0;
+  }
+
   /* WHY: Trailing caret pushes to end — same pattern as button justify="spread". */
-  :where(ui-layout-sidebar-trigger) > :where([slot="trailing"]) {
+  :where(ui-layout-sidebar-item) > :where([slot="trailing"]) {
     margin-inline-start: auto;
     flex-shrink: 0;
     color: var(--_ink-muted);
   }
 
+  /* WHY: When the item wraps a sub-component (e.g. ui-button) that provides
+     its own icon, hide [slot="icon"] in expanded mode — it only serves as the
+     bare collapsed-rail representation. Items without sub-components (just
+     icon + label + trailing) keep [slot="icon"] visible in both modes. */
+  :where(ui-layout-sidebar-item:has(> ui-button)) > :where([slot="icon"]) {
+    display: none;
+  }
+
   /* WHY: Title text truncates when sidebar narrows during resize. */
-  :where(ui-layout-sidebar-trigger) > :where([slot="label"]) {
+  :where(ui-layout-sidebar-item) > :where([slot="label"]) {
     flex: 1;
     min-width: 0;
     white-space: nowrap;
@@ -6887,25 +7011,67 @@
     text-overflow: ellipsis;
   }
 
-  /* ── Trigger Popover ── */
-  /* WHY: Popover opens to the right of the sidebar trigger.
+  /* ── Item Popover ── */
+  /* WHY: Popover opens to the right of the sidebar item.
      Default: top-aligned, grows downward (span-block-end).
      Flip: bottom-aligned, grows upward (span-block-start). */
 
-  :where(ui-layout-sidebar-trigger) > :where(ui-listbox[popover]) {
+  :where(ui-layout-sidebar-item) > :where(ui-listbox[popover]) {
     position: fixed;
     position-area: inline-end span-block-end;
-    position-try-fallbacks: --flip-up;
+    position-try-fallbacks: --sidebar-item-flip-up;
     margin: 0 0 0 var(--ui-popover-gap);
     min-width: 200px;
     max-height: var(--ui-popover-max-height);
     overflow-y: auto;
   }
 
-  @position-try --flip-up {
+  @position-try --sidebar-item-flip-up {
     position-area: inline-end span-block-start;
   }
 
+  /* ── Container Query: Collapsed Sidebar ── */
+  /* WHY: Each component owns its own collapsed behavior via @container.
+     The aside is the container (container-name: sidebar). When it shrinks
+     to 48px (icon rail), components respond to the width, not to [collapsed].
+     Threshold 80px: collapsed = 48px, min expanded = 160px. */
+
+  @container sidebar (max-width: 80px) {
+
+    /* Resize handle — no dragging in icon rail */
+    :where(.layout-resize-handle) {
+      display: none;
+    }
+
+    /* Header/footer — center content horizontally */
+    :where(ui-layout-sidebar-header),
+    :where(ui-layout-sidebar-footer) {
+      align-items: center;
+    }
+
+    /* Content — center items in the 48px rail */
+    :where(ui-layout-sidebar-content) {
+      align-items: center;
+    }
+
+    /* Item — shrink to icon-only. Show [slot="icon"], hide everything else.
+       WHY: Sidebar items can contain complex children (buttons with slots,
+       links, etc.). Rather than overriding sub-component styles, the item
+       provides its own bare icon via [slot="icon"] for the collapsed rail. */
+    :where(ui-layout-sidebar-item) {
+      flex: 0 0 auto;
+      padding-inline: var(--_space);
+    }
+
+    :where(ui-layout-sidebar-item) > :where([slot="icon"]) {
+      display: inline-flex;
+    }
+
+    :where(ui-layout-sidebar-item) > :where(:not([slot="icon"]):not(ui-listbox[popover]):not(.nav-group-flyout)) {
+      display: none;
+    }
+  }
+
 }
 
 @layer ui {