@kerfjs/ui 5.0.0-beta.106 → 5.0.0-beta.108

package/dist/styles/components/navigation/nav-stack/nav-stack.css

@@ -224,6 +224,19 @@
   background: var(--kui-chrome-material);
 }
 
+/* The material's surface context at rest (see pane.css); clear chrome keeps
+   the inherited context. */
+.kui-nav-stack[data-chrome-presentation="overlay"]:not(
+    [data-chrome-material="clear"]
+  )
+  > .kui-nav-stack__chrome,
+.kui-nav-stack[data-bottom-toolbar-presentation="overlay"]:not(
+    [data-bottom-toolbar-material="clear"]
+  )
+  > .kui-nav-stack__bottom {
+  --kui-color-surface-current-tint: var(--kui-chrome-material);
+}
+
 .kui-nav-stack[data-chrome-presentation="overlay"][data-chrome-overlay="measured"]
   > .kui-nav-stack__chrome:not(.kui-nav-stack__chrome-copy) {
   position: absolute;
@@ -291,6 +304,63 @@
   }
 }
 
+/* An overlay bar cross-fades its contents, never its material. Fading the
+   bar itself would fade its backdrop filter with it (WebKit drops the blur
+   outright), so mid push or pop the sliding views would show through the
+   chrome. Instead the live bar keeps its material at full opacity while its
+   contents fade in, and the copy cross-fading out above it carries no
+   material of its own (nor a clear bar's scroll edge), only the old
+   contents and divider. */
+.kui-nav-stack[data-chrome-presentation="overlay"] > .kui-nav-stack__chrome,
+.kui-nav-stack[data-bottom-toolbar-presentation="overlay"]
+  > .kui-nav-stack__bottom {
+  opacity: 1;
+  transition: none;
+}
+
+.kui-nav-stack[data-chrome-presentation="overlay"]
+  > .kui-nav-stack__chrome:not(.kui-nav-stack__chrome-copy)
+  > *,
+.kui-nav-stack[data-bottom-toolbar-presentation="overlay"]
+  > .kui-nav-stack__bottom:not(.kui-nav-stack__chrome-copy)
+  > * {
+  transition: opacity var(--kui-nav-stack-transition-duration, 200ms) ease;
+}
+
+.kui-nav-stack[data-chrome-presentation="overlay"]
+  > .kui-nav-stack__chrome--entering:not(.kui-nav-stack__chrome-copy)
+  > *,
+.kui-nav-stack[data-bottom-toolbar-presentation="overlay"]
+  > .kui-nav-stack__chrome--entering:not(.kui-nav-stack__chrome-copy)
+  > * {
+  transition: none;
+  opacity: 0;
+}
+
+.kui-nav-stack[data-chrome-presentation="overlay"]
+  > .kui-nav-stack__chrome.kui-nav-stack__chrome-copy,
+.kui-nav-stack[data-bottom-toolbar-presentation="overlay"]
+  > .kui-nav-stack__bottom.kui-nav-stack__chrome-copy {
+  -webkit-backdrop-filter: none;
+  backdrop-filter: none;
+  background: transparent;
+  transition: opacity var(--kui-nav-stack-transition-duration, 200ms) ease;
+}
+
+.kui-nav-stack[data-chrome-presentation="overlay"]
+  > .kui-nav-stack__chrome.kui-nav-stack__chrome-copy--exiting,
+.kui-nav-stack[data-bottom-toolbar-presentation="overlay"]
+  > .kui-nav-stack__bottom.kui-nav-stack__chrome-copy--exiting {
+  opacity: 0;
+}
+
+.kui-nav-stack[data-chrome-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__chrome.kui-nav-stack__chrome-copy::before,
+.kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__bottom.kui-nav-stack__chrome-copy::before {
+  content: none;
+}
+
 /* `clear` chrome and bottom toolbar: overlay bars (the same measuring,
    placement, and edge insets as above) that are fully transparent, for
    chrome over imagery. With `scrollEdge="material"` a pseudo-element
@@ -521,7 +591,13 @@
   .kui-nav-stack__view,
   .kui-nav-stack__chrome,
   .kui-nav-stack__bottom,
-  .kui-nav-stack__chrome-copy {
+  .kui-nav-stack__chrome-copy,
+  .kui-nav-stack[data-chrome-presentation="overlay"]
+    > .kui-nav-stack__chrome
+    > *,
+  .kui-nav-stack[data-bottom-toolbar-presentation="overlay"]
+    > .kui-nav-stack__bottom
+    > * {
     transition: none;
   }
 }

package/dist/styles/components/navigation/tab-bar/tab-bar.css

@@ -38,6 +38,12 @@
     --kui-tab-bar-strip-background,
     var(--kui-tab-bar-background)
   );
+  /* The surface context (foundation.css): the strip's fill is a tint over
+     whatever the bar sits on. */
+  --kui-color-surface-current-tint: var(
+    --kui-tab-bar-strip-background,
+    var(--kui-tab-bar-background)
+  );
   scrollbar-width: none;
   align-items: center;
   flex: var(--kui-tab-bar-strip-flex, 1 1 auto);

package/dist/styles/components/navigation/tab-navigator/tab-navigator.css

@@ -53,6 +53,7 @@
 
 .kui-tab-scaffold__scene[data-appearance="sunken"] {
   background: var(--kui-sunken-panel-background, var(--kui-sunken-surface));
+  --kui-color-surface-current-region: var(--kui-color-surface-lowered);
 }
 
 /* `background`: the navigator's color paints the root and a docked bar (the
@@ -69,6 +70,13 @@
 
 .kui-tab-scaffold__scene[data-background] {
   background: var(--_kui-tab-scaffold-scene-background);
+  --kui-color-surface-current-region: var(--_kui-tab-scaffold-scene-background);
+}
+
+/* The navigator's color paints its root and a docked bar over whatever holds
+   the navigator: a region in the surface context. */
+.kui-tab-scaffold[data-background] {
+  --kui-color-surface-current-region: var(--_kui-tab-scaffold-background);
 }
 
 @media (forced-colors: active) {
@@ -212,6 +220,15 @@
   background: var(--kui-chrome-material);
 }
 
+/* The material's surface context at rest (see pane.css); a clear bar keeps
+   the inherited context. */
+.kui-tab-scaffold[data-bar-presentation="overlay"]:not(
+    [data-bar-material="clear"]
+  )
+  > .kui-tab-scaffold__bar {
+  --kui-color-surface-current-tint: var(--kui-chrome-material);
+}
+
 .kui-tab-scaffold[data-bar-presentation="overlay"][data-bar-overlay="measured"] {
   position: relative;
 }

package/dist/styles/components/surfaces/content-item/content-item.css

@@ -126,6 +126,36 @@
   --kui-content-item-foreground: var(--kui-color-brand-on-fill);
 }
 
+/* The surface context follows the fill an item paints: a quiet appearance,
+   a hover, press, or selection. A transparent item keeps its parent's
+   context; a brand-loud fill shares the focus ring's hue, so a control on it
+   keeps the surface line. A surface appearance is opaque, so it resets. */
+.kui-content-item:is(
+  [data-appearance]:not(
+    [data-appearance="transparent"],
+    [data-appearance="brand-loud"]
+  ),
+  [data-interactive="true"]:hover:not([data-disabled="true"]),
+  [data-interactive="true"]:is(
+    [data-kui-pressed="true"],
+    [data-selected="true"]
+  )
+) {
+  --kui-color-surface-current-tint: var(--kui-content-item-background);
+}
+
+.kui-content-item[data-appearance="surface"]:not(
+    [data-interactive="true"]:is(
+      :hover,
+      [data-kui-pressed="true"],
+      [data-selected="true"]
+    )
+  ) {
+  --kui-color-surface-current: var(--kui-color-surface);
+  --kui-color-surface-current-region: transparent;
+  --kui-color-surface-current-tint: transparent;
+}
+
 .kui-content-item:is(:focus-visible, [data-outlined="true"]) {
   outline: var(--kui-focus-ring);
   outline-offset: 1px;

package/dist/styles/components/surfaces/disclosure/disclosure.css

@@ -24,6 +24,7 @@
 .kui-disclosure[data-appearance="sunken"] {
   --_kui-disclosure-border: var(--kui-color-neutral-border-normal);
   --_kui-disclosure-background: var(--kui-sunken-surface);
+  --kui-color-surface-current-tint: var(--kui-color-surface-lowered);
 }
 
 .kui-disclosure__summary {
@@ -90,6 +91,43 @@
     0;
 }
 
+/* Embedded: inside owner chrome, such as a ContentItem, that already draws
+   the margin, border, and padding. The root adds none of its own, so the
+   arrow sits on the owner's content inset (icons align to icons), and the
+   summary is a compact inline row. The content expects no inset of its own
+   (a flush Text, inline copy) and starts on the title's text column, one
+   item gap below the summary. A hover fill would touch the arrow and text at
+   the owner's content edge, so the embedded summary keeps only its pointer
+   cursor and draws its focus ring just outside the row. */
+.kui-disclosure[data-appearance="embedded"] {
+  margin: 0;
+  border: 0;
+  border-radius: 0;
+}
+
+.kui-disclosure[data-appearance="embedded"] > .kui-disclosure__summary {
+  min-height: 1.5rem;
+  padding: 0;
+  border-radius: var(--kui-radius-s, 0.1875rem);
+}
+
+.kui-disclosure[data-appearance="embedded"] > .kui-disclosure__summary:hover {
+  background: none;
+}
+
+.kui-disclosure[data-appearance="embedded"]
+  > .kui-disclosure__summary:focus-visible {
+  outline-offset: 0.125rem;
+}
+
+.kui-disclosure[data-appearance="embedded"] > .kui-disclosure__content {
+  padding-block: var(--kui-layout-item-gap, 0.5rem) 0;
+  padding-inline: calc(
+      var(--kui-disclosure-arrow-size, 1.125rem) + var(--kui-space-xs)
+    )
+    0;
+}
+
 @media (forced-colors: active) {
   .kui-disclosure[data-appearance="framed"],
   .kui-disclosure[data-appearance="sunken"] {

package/dist/styles/components/surfaces/sunken-panel/sunken-panel.css

@@ -13,6 +13,9 @@
   );
   color: var(--kui-sunken-panel-foreground, var(--kui-color-text));
   background: var(--kui-sunken-panel-background, var(--kui-sunken-surface));
+  /* The surface-context tint: an inset focus ring's line matches the lowered
+     color its controls sit on (foundation.css). */
+  --kui-color-surface-current-tint: var(--kui-color-surface-lowered);
   flex-direction: column;
   gap: var(--kui-sunken-panel-gap, 0.5rem);
 }

package/dist/styles/components/surfaces/surface-scaffold/surface-scaffold.css

@@ -29,6 +29,9 @@
   color: var(--kui-color-text, inherit);
   border: none;
   border-radius: var(--_kui-dialog-surface-radius);
+  --kui-color-surface-current: var(--kui-color-surface-raised);
+  --kui-color-surface-current-region: transparent;
+  --kui-color-surface-current-tint: transparent;
   background-color: var(--kui-color-surface-raised);
   box-shadow: var(--kui-shadow-l);
   /* Sizes apply at once: a theme's transition on bare dialog elements would
@@ -334,6 +337,8 @@ h2.kui-dialog-surface__title {
   -webkit-backdrop-filter: var(--kui-chrome-material-filter);
   backdrop-filter: var(--kui-chrome-material-filter);
   background: var(--kui-chrome-material-raised);
+  /* The material's surface context at rest, over the raised panel. */
+  --kui-color-surface-current-tint: var(--kui-chrome-material-raised);
   /* The divider is scroll state: the register publishes it only while
      content is scrolled beneath the header. An inset shadow, so showing it
      never moves the header or the content. */
@@ -637,6 +642,9 @@ h2.kui-dialog-surface__title {
     var(--kui-layout-pill-radius, calc(1px + 1.3125rem)) +
       var(--kui-wa-surface-inset, 0.5rem)
   );
+  --kui-color-surface-current: var(--kui-color-surface-raised);
+  --kui-color-surface-current-region: transparent;
+  --kui-color-surface-current-tint: transparent;
   background: var(--kui-color-surface-raised);
   box-shadow: var(--kui-shadow-l);
 }

package/dist/styles/components/typography/text/text.css

@@ -175,6 +175,16 @@ span.kui-text {
   white-space: nowrap;
 }
 
+/* A wrapping header keeps the whole label: it breaks onto further lines
+   instead of ellipsizing, and `anywhere` lets a single long word break too, so
+   the label's minimum width never pushes the header past its column. */
+.kui-list-header[data-wrap="true"] .kui-list-header__title > .kui-text {
+  overflow: visible;
+  overflow-wrap: anywhere;
+  text-overflow: clip;
+  white-space: normal;
+}
+
 .kui-list-header[data-size="xs"] .kui-list-header__title > .kui-text {
   font-size: var(--kui-font-2xs);
   text-transform: capitalize;

package/dist/styles/content-item.css

@@ -126,6 +126,36 @@
   --kui-content-item-foreground: var(--kui-color-brand-on-fill);
 }
 
+/* The surface context follows the fill an item paints: a quiet appearance,
+   a hover, press, or selection. A transparent item keeps its parent's
+   context; a brand-loud fill shares the focus ring's hue, so a control on it
+   keeps the surface line. A surface appearance is opaque, so it resets. */
+.kui-content-item:is(
+  [data-appearance]:not(
+    [data-appearance="transparent"],
+    [data-appearance="brand-loud"]
+  ),
+  [data-interactive="true"]:hover:not([data-disabled="true"]),
+  [data-interactive="true"]:is(
+    [data-kui-pressed="true"],
+    [data-selected="true"]
+  )
+) {
+  --kui-color-surface-current-tint: var(--kui-content-item-background);
+}
+
+.kui-content-item[data-appearance="surface"]:not(
+    [data-interactive="true"]:is(
+      :hover,
+      [data-kui-pressed="true"],
+      [data-selected="true"]
+    )
+  ) {
+  --kui-color-surface-current: var(--kui-color-surface);
+  --kui-color-surface-current-region: transparent;
+  --kui-color-surface-current-tint: transparent;
+}
+
 .kui-content-item:is(:focus-visible, [data-outlined="true"]) {
   outline: var(--kui-focus-ring);
   outline-offset: 1px;

package/dist/styles/disclosure.css

@@ -24,6 +24,7 @@
 .kui-disclosure[data-appearance="sunken"] {
   --_kui-disclosure-border: var(--kui-color-neutral-border-normal);
   --_kui-disclosure-background: var(--kui-sunken-surface);
+  --kui-color-surface-current-tint: var(--kui-color-surface-lowered);
 }
 
 .kui-disclosure__summary {
@@ -90,6 +91,43 @@
     0;
 }
 
+/* Embedded: inside owner chrome, such as a ContentItem, that already draws
+   the margin, border, and padding. The root adds none of its own, so the
+   arrow sits on the owner's content inset (icons align to icons), and the
+   summary is a compact inline row. The content expects no inset of its own
+   (a flush Text, inline copy) and starts on the title's text column, one
+   item gap below the summary. A hover fill would touch the arrow and text at
+   the owner's content edge, so the embedded summary keeps only its pointer
+   cursor and draws its focus ring just outside the row. */
+.kui-disclosure[data-appearance="embedded"] {
+  margin: 0;
+  border: 0;
+  border-radius: 0;
+}
+
+.kui-disclosure[data-appearance="embedded"] > .kui-disclosure__summary {
+  min-height: 1.5rem;
+  padding: 0;
+  border-radius: var(--kui-radius-s, 0.1875rem);
+}
+
+.kui-disclosure[data-appearance="embedded"] > .kui-disclosure__summary:hover {
+  background: none;
+}
+
+.kui-disclosure[data-appearance="embedded"]
+  > .kui-disclosure__summary:focus-visible {
+  outline-offset: 0.125rem;
+}
+
+.kui-disclosure[data-appearance="embedded"] > .kui-disclosure__content {
+  padding-block: var(--kui-layout-item-gap, 0.5rem) 0;
+  padding-inline: calc(
+      var(--kui-disclosure-arrow-size, 1.125rem) + var(--kui-space-xs)
+    )
+    0;
+}
+
 @media (forced-colors: active) {
   .kui-disclosure[data-appearance="framed"],
   .kui-disclosure[data-appearance="sunken"] {

package/dist/styles/foundation.css

@@ -178,6 +178,26 @@
   --kui-sunken-surface:
     var(--kui-sunken-texture) 0 0 / 100px 100px repeat,
     var(--kui-color-surface-lowered);
+  /* The surface context: what a region paints behind its children, for a
+     control that must match it (an inset focus ring's inner line). Left
+     undeclared here, so a reader falls back to the base surface:
+       --kui-color-surface-current: the opaque surface beneath (default
+         --kui-color-surface); an opaque surface (a raised dialog or popup, a
+         base or raised List) sets it and clears the tint.
+       --kui-color-surface-current-region: a layout region's fill over it
+         (a sunken Pane, Workbench area, or TabNavigator scene; a Pane's or
+         TabNavigator's app `background`; default transparent).
+       --kui-color-surface-current-tint: a content surface's fill over that
+         (a SunkenPanel, a sunken Disclosure, a lowered FramedList or its
+         highlighted row, a quiet ContentItem, a TabBar strip, and glass
+         chrome at rest: a Pane overlay header, NavStack overlay chrome, a
+         TabNavigator overlay bar, a dialog's floating header; default
+         transparent).
+     A reader layers the tint over the region over the color, so a content
+     surface inside a sunken region (the common nesting) composes exactly;
+     custom properties cannot fold an inherited value into a new one, so a
+     third translucent level keeps only the innermost content tint. A surface sets both on its own
+     painted element, never on a child; a scoped tint resets them below. */
   /* Translucent chrome material: a bar laid over scrolling content (a Pane's
      overlay header) lets the content show through, blurred, beneath it.
      80% of the surface keeps --kui-color-text at AA over any content
@@ -247,9 +267,11 @@
     var(--kui-color-surface)
   );
 
+  /* Each brand token below falls back to its tuned literal unless the app
+     sets the opt-in --kui-color-brand (see the brand ramp after this block). */
   --kui-color-brand-fill-loud: var(
     --wa-color-brand-fill-loud,
-    light-dark(#0075db, #64d2ff)
+    var(--_kui-brand-fill-loud, light-dark(#0075db, #64d2ff))
   );
   --kui-color-brand-fill-quiet: var(
     --wa-color-brand-fill-quiet,
@@ -295,7 +317,7 @@
      4.65:1 on the page (5.2:1 on white). */
   --kui-color-brand-on-quiet: var(
     --wa-color-brand-on-quiet,
-    light-dark(#0c62f3, #8acbff)
+    var(--_kui-brand-on-quiet, light-dark(#0c62f3, #8acbff))
   );
   --kui-color-brand-on-normal: var(
     --wa-color-brand-on-normal,
@@ -311,7 +333,10 @@
      4.26:1 over brand-fill-normal (#d6ecff), while #1a5dcf (same hue) clears
      ~4.9:1 there and ~5.5:1 over brand-fill-quiet (#ebf6ff). The dark value
      matches brand-on-quiet, which already passes over the dark fills. */
-  --kui-color-brand-on-fill: light-dark(#1a5dcf, #8acbff);
+  --kui-color-brand-on-fill: var(
+    --_kui-brand-on-fill,
+    light-dark(#1a5dcf, #8acbff)
+  );
 
   /* Pop is attractive emphasis without status meaning: use it for featured,
      novel, or celebratory content, never as a success/danger substitute. */
@@ -521,7 +546,11 @@
 
   --kui-focus-ring: var(
     --wa-focus-ring,
-    3px solid var(--wa-color-focus, light-dark(#007aff, #64d2ff))
+    3px solid
+      var(
+        --wa-color-focus,
+        var(--_kui-brand-focus, light-dark(#007aff, #64d2ff))
+      )
   );
   /* Elevation mirrors webawesome.css's scheme-aware shadows: dark raises the
      alpha so a raised surface still separates from a near-black page. */
@@ -573,6 +602,41 @@
 [data-kui-tint] {
   color: var(--kui-color-text);
   --kui-chrome-material-filter: blur(20px);
+  /* The scope re-derives its surface, so an outer surface context ends here. */
+  --kui-color-surface-current: initial;
+  --kui-color-surface-current-region: initial;
+  --kui-color-surface-current-tint: initial;
+}
+
+/* The opt-in brand, left undeclared so the tuned literals apply:
+     --kui-color-brand: any color an app sets on :root;
+   the whole brand ramp follows it, the way a scoped tint's accent re-derives
+   its ramp: the loud fill (and the quiet/normal fills and borders mixed from
+   it), brand text and links, brand text on brand fills, and the focus ring.
+   Lightness is clamped per scheme so every pair keeps WCAG AA for any hue
+   and chroma (the brand-ramp browser test sweeps them): a light fill stays
+   dark enough for white text and a dark one light enough for near-black
+   text; brand text stays dark enough for the page, the surface, and the
+   brand fills in light, and light enough in dark. Unset, each private
+   derivation references an undefined variable, is invalid, and the tokens
+   above keep their tuned literals exactly. Web Awesome's theme reads the
+   same derivations (webawesome.css). */
+@supports (color: oklch(from red l c h)) {
+  :root {
+    --_kui-brand-fill-loud: light-dark(
+      oklch(from var(--kui-color-brand) min(l, 0.46) c h),
+      oklch(from var(--kui-color-brand) clamp(0.74, l, 0.86) c h)
+    );
+    --_kui-brand-on-quiet: light-dark(
+      oklch(from var(--kui-color-brand) min(l, 0.43) c h),
+      oklch(from var(--kui-color-brand) max(l, 0.86) c h)
+    );
+    --_kui-brand-on-fill: light-dark(
+      oklch(from var(--kui-color-brand) min(l, 0.38) c h),
+      oklch(from var(--kui-color-brand) max(l, 0.9) c h)
+    );
+    --_kui-brand-focus: var(--_kui-brand-fill-loud);
+  }
 }
 
 @supports (color: oklch(from red l c h)) {
@@ -625,21 +689,22 @@
        scope: the loud fill (buttons, the current row, checked controls), its
        on-loud text, brand text and links, text on brand fills, and the focus
        ring. Lightness is clamped so each pair keeps WCAG AA for any accent:
-       a light scope's fill stays at or below 50% under white text, a dark
+       a light scope's fill stays at or below 46% under white text, a dark
        scope's between 72% and 85% under near-black text, and brand text at
-       most 45% (light) or at least 80% (dark). */
+       most 36% (light) or at least 94% (dark). Dark on-fill text also caps
+       chroma so a vivid red stays light after gamut clipping. */
     [data-kui-tint="light"][data-kui-tint-accent] {
       --wa-color-brand-fill-loud: oklch(
-        from var(--_kui-tint-accent) min(l, 0.5) c h
+        from var(--_kui-tint-accent) min(l, 0.46) c h
       );
       --wa-color-brand-on-loud: #fff;
       --wa-color-brand-on-quiet: oklch(
-        from var(--_kui-tint-accent) min(l, 0.45) c h
+        from var(--_kui-tint-accent) min(l, 0.36) c h
       );
       --kui-color-brand-on-fill: oklch(
-        from var(--_kui-tint-accent) min(l, 0.38) c h
+        from var(--_kui-tint-accent) min(l, 0.3) c h
       );
-      --wa-color-focus: oklch(from var(--_kui-tint-accent) min(l, 0.5) c h);
+      --wa-color-focus: oklch(from var(--_kui-tint-accent) min(l, 0.46) c h);
     }
 
     [data-kui-tint="dark"][data-kui-tint-accent] {
@@ -648,13 +713,13 @@
       );
       --wa-color-brand-on-loud: #111113;
       --wa-color-brand-on-quiet: oklch(
-        from var(--_kui-tint-accent) max(l, 0.8) c h
+        from var(--_kui-tint-accent) max(l, 0.94) c h
       );
       --kui-color-brand-on-fill: oklch(
-        from var(--_kui-tint-accent) max(l, 0.82) c h
+        from var(--_kui-tint-accent) max(l, 0.95) min(c, 0.12) h
       );
       --wa-color-focus: oklch(
-        from var(--_kui-tint-accent) clamp(0.72, l, 0.85) c h
+        from var(--_kui-tint-accent) clamp(0.78, l, 0.85) c h
       );
     }
   }

package/dist/styles/framed-list.css

@@ -11,10 +11,14 @@
   border: 1px solid var(--kui-framed-list-border);
   border-radius: var(--kui-layout-rounded-radius, calc(1px + 0.6875rem));
   background: var(--kui-color-surface-lowered);
+  --kui-color-surface-current-tint: var(--kui-color-surface-lowered);
   list-style: none;
 }
 
 .kui-framed-list[data-surface="base"] {
+  --kui-color-surface-current: var(--kui-color-surface);
+  --kui-color-surface-current-region: transparent;
+  --kui-color-surface-current-tint: transparent;
   background: var(--kui-color-surface);
 }
 
@@ -44,4 +48,6 @@
 
 .kui-framed-list__row[data-highlighted="true"] {
   background: var(--kui-color-brand-fill-quiet);
+  /* The row's controls sit on the tint, not the list's lowered fill. */
+  --kui-color-surface-current-tint: var(--kui-color-brand-fill-quiet);
 }

package/dist/styles/list-header.css

@@ -29,6 +29,13 @@
   padding-block: var(--kui-list-header-title-padding-block, 0.25rem);
 }
 
+/* Wrapped label lines keep the compact header's 4px block inset off the
+   header edges; a one-line label still centers in the unchanged minimum
+   height. */
+.kui-list-header[data-wrap="true"] .kui-list-header__title {
+  padding-block: var(--kui-list-header-title-padding-block, 0.25rem);
+}
+
 .kui-list-header[data-divider="before"],
 .kui-list-header[data-divider="both"] {
   border-block-start: 1px solid

package/dist/styles/list.css

@@ -273,10 +273,16 @@
 
 /* `surface`: a solid background behind the stack and its insets. */
 .kui-list[data-surface="base"] {
+  --kui-color-surface-current: var(--kui-color-surface);
+  --kui-color-surface-current-region: transparent;
+  --kui-color-surface-current-tint: transparent;
   background: var(--kui-color-surface);
 }
 
 .kui-list[data-surface="raised"] {
+  --kui-color-surface-current: var(--kui-color-surface-raised);
+  --kui-color-surface-current-region: transparent;
+  --kui-color-surface-current-tint: transparent;
   background: var(--kui-color-surface-raised);
 }