@nonoun/native-ui 0.2.4 → 0.2.6

package/dist/components.css

@@ -365,7 +365,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));
@@ -382,17 +382,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,
@@ -402,9 +402,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;
   }
@@ -977,34 +977,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 {
@@ -1012,17 +1003,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 ── */
@@ -1042,14 +1024,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);
   }
@@ -1063,12 +1037,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);
   }
@@ -1722,6 +1690,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 ── */
@@ -1862,11 +1869,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;
   }
 
@@ -1881,6 +1891,7 @@
     display: flex;
     align-items: center;
     gap: calc(var(--_space) * 2);
+    padding-inline: calc(var(--_space-k) * var(--_space));
 
     min-height: var(--_min-height);
 
@@ -1980,6 +1991,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;
@@ -2014,6 +2026,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 {
@@ -2067,12 +2091,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);
@@ -2087,7 +2115,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;
@@ -2114,6 +2142,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 {
@@ -2254,27 +2349,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 ── */
@@ -2292,12 +2375,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);
   }
@@ -2310,11 +2387,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);
   }
@@ -2413,16 +2485,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) {
@@ -2434,8 +2502,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;
 
@@ -2445,11 +2513,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),
@@ -2462,22 +2525,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);
   }
@@ -2485,19 +2537,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);
   }
@@ -3052,22 +3095,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);
   }
 
@@ -3086,12 +3120,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);
   }
@@ -3104,11 +3132,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);
   }
@@ -4568,7 +4591,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);
   }
 
 }
@@ -4630,7 +4653,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);
   }
 
 }
@@ -4657,16 +4680,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 ── */
@@ -4682,16 +4705,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;
@@ -4703,7 +4733,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;
@@ -4724,11 +4756,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. */
@@ -4741,101 +4769,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;
@@ -4851,31 +4867,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;
@@ -4883,25 +4929,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 {