@obvi/blueprint 1.1.3 → 1.3.0

package/dist/blueprint.css

@@ -289,14 +289,19 @@
     /* Corner radius — an even 2px-step scale; each token names its pixel
        value directly (corners read as absolute, so px is the honest unit).
        -6 is the document default for sheets, panels, and chrome; -2 dresses
-       inline marks, -4 small code blocks, -8 is the soft top rung. */
+       inline marks, -4 small code blocks, -8 is decision containers, -12 is
+       the Obvious shell panel rung (dropdowns), -16 is the search command menu. */
     --bp-radius-0: 0;
     --bp-radius-2: 2px;
     --bp-radius-4: 4px;
     --bp-radius-6: 6px;
     --bp-radius-8: 8px;
+    --bp-radius-12: 12px;
+    --bp-radius-16: 16px;
     --bp-radius-pill: 9999px;
     --bp-radius-round: 50%;
+    /* Runtime shell overlays (doc switcher, contents dropdown, search palette). */
+    --bp-shell-panel-radius: var(--bp-radius-12);
 
     /* Obvious button palette — the interactive-control vocabulary. Buttons are
        the one chrome surface that carries fill: primary (committed / CTA),
@@ -511,6 +516,8 @@
   /* ---- Tier 1a: page + body ---------------------------------------- */
   :where(html) {
     font-size: 16px;
+    background: var(--bp-bg);
+    overscroll-behavior: none;
   }
   :where(body) {
     font-family: var(--bp-serif);
@@ -579,19 +586,11 @@
     margin-bottom: var(--bp-space-2);
     text-wrap: var(--bp-wrap-heading);
   }
-  /* Document masthead — the first <header> in <main>. No implicit, position-
-     based styling: author the eyebrow with <bp-eyebrow> and the lede with
-     <bp-subheader> explicitly. We only reset the title's top margin and tune
-     the gap before a following contents index. */
-  :where(main > header:first-child) {
-    margin-bottom: 0;
-  }
+  /* Document masthead — the first <header> in <main>. Its title starts flush,
+     and a following contents index keeps the masthead's own bottom gap. */
   :where(main > header:first-child > h1) {
     margin: 0 0 var(--bp-space-2);
   }
-  :where(main > header:first-child:has(+ :is(.bp-contents, bp-toc))) {
-    margin-bottom: var(--bp-space-4);
-  }
   :where(main > header:first-child + :is(.bp-contents, bp-toc)) {
     margin-top: 0;
   }
@@ -1023,6 +1022,14 @@
     margin-bottom: var(--bp-space-5);
     border-bottom: 0;
   }
+  /* The first main header is the canonical hero band; generic body/article
+     headers remain compact metadata landmarks. */
+  :where(main > header:first-child) {
+    padding-top: var(--bp-space-6);
+    padding-bottom: var(--bp-space-4);
+    margin-bottom: var(--bp-space-5);
+    border-bottom: 1px solid var(--bp-ink-line);
+  }
   /* Subordinate sources / status region */
   :where(body > footer, main > footer, article > footer) {
     margin-top: var(--bp-space-7);
@@ -1205,6 +1212,10 @@
     line-height: var(--bp-lh-lede);
     color: var(--bp-text);
   }
+  :where(main > header:first-child > bp-subheader) {
+    text-align: justify;
+    hyphens: auto;
+  }
 
   /* ---- Section heading permalink + eyebrow --------------------------------
      Injected by blueprint.js on headings with data-sidebar: a numbered eyebrow
@@ -1353,6 +1364,12 @@
   :where(bp-eyebrow[muted]) {
     color: var(--bp-text-secondary);
   }
+  :where(main > header:first-child > bp-eyebrow) {
+    font-size: var(--bp-label-lg);
+    letter-spacing: var(--bp-label-lg-ls);
+    color: var(--bp-ink-soft);
+    margin-bottom: var(--bp-space-3);
+  }
   :where(.bp-meta) {
     font-family: var(--bp-mono);
     font-size: var(--bp-label-md);
@@ -1680,7 +1697,8 @@
     border-radius: var(--bp-radius-pill);
     transition: background var(--bp-duration-fast) var(--bp-ease-out),
       color var(--bp-duration-fast) var(--bp-ease-out),
-      box-shadow var(--bp-duration-fast) var(--bp-ease-out);
+      box-shadow var(--bp-duration-fast) var(--bp-ease-out),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
   :where(.bp-choice__seg-opt:hover) {
     color: var(--bp-button-ghost-fg-hover);
@@ -1716,7 +1734,8 @@
     color: var(--bp-button-secondary-fg);
     background: var(--bp-button-secondary-bg);
     transition: background var(--bp-duration-fast) var(--bp-ease-out),
-      color var(--bp-duration-fast) var(--bp-ease-out);
+      color var(--bp-duration-fast) var(--bp-ease-out),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
   :where(.bp-choice__adopt:hover) {
     background: var(--bp-button-secondary-bg-hover);
@@ -1913,7 +1932,8 @@
     color: var(--bp-button-ghost-fg);
     background: var(--bp-button-tertiary-bg);
     transition: background var(--bp-duration-fast) var(--bp-ease-out),
-      color var(--bp-duration-fast) var(--bp-ease-out);
+      color var(--bp-duration-fast) var(--bp-ease-out),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
   :where(.bp-choice__compare > summary:hover) {
     background: var(--bp-button-tertiary-bg-hover);
@@ -2021,7 +2041,8 @@
     background: oklch(0 0 0 / 0);
     transition: background var(--bp-duration-fast) var(--bp-ease-out),
       color var(--bp-duration-fast) var(--bp-ease-out),
-      border-color var(--bp-duration-fast) var(--bp-ease-out);
+      border-color var(--bp-duration-fast) var(--bp-ease-out),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
   :where(.bp-preflight__chip:hover) {
     border-color: var(--bp-button-secondary-bd);
@@ -2077,12 +2098,27 @@
     cursor: pointer;
     margin-top: var(--bp-space-2);
     transition: background var(--bp-duration-fast) var(--bp-ease-out),
-      border-color var(--bp-duration-fast) var(--bp-ease-out);
+      border-color var(--bp-duration-fast) var(--bp-ease-out),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
   :where(.bp-preflight__draft:hover) {
     background: var(--bp-button-primary-bg-hover);
     border-color: var(--bp-button-primary-bg-hover);
   }
+
+  /* Press feedback — the decision controls nudge 1px down on :active to match
+     the Obvious app's button press. Motion only: the squared/pill split, the
+     --bp-button-* fills, and the radius contract are all unchanged. Reduced
+     motion is handled globally, so no per-rule query here. */
+  :where(
+    .bp-choice__seg-opt,
+    .bp-choice__adopt,
+    .bp-choice__compare > summary,
+    .bp-preflight__chip,
+    .bp-preflight__draft
+  ):active {
+    transform: translateY(1px);
+  }
   :where(.bp-preflight__footer) {
     display: flex;
     align-items: center;
@@ -2635,6 +2671,9 @@
     border: 1px solid var(--bp-ink-line);
     margin-top: var(--bp-space-4);
   }
+  :where(main > header:first-child > .bp-title-block) {
+    margin-top: var(--bp-space-5);
+  }
   :where(.bp-tb-cell) {
     flex: 0 0 auto;
     padding: var(--bp-space-2) var(--bp-space-3);
@@ -2776,7 +2815,7 @@
   }
   /* The contents list hosts a single rounded ACTIVE PILL that glides between
      entries as you scroll — no rail, no left border. Obvious-style. */
-  :where(.bp-sidebar > ul, .bp-sidebar__panel > ul, .bp-toc > ul) {
+  :where(.bp-sidebar > ul, .bp-toc-switcher > ul, .bp-toc > ul) {
     position: relative;
     counter-reset: bp-toc;
     margin: 0;
@@ -2789,7 +2828,7 @@
   }
   /* The gliding active pill, drawn behind the entries and travelling via
      --bp-toc-y / --bp-toc-h (set by blueprint.js). */
-  :where(.bp-sidebar > ul, .bp-sidebar__panel > ul, .bp-toc > ul)::before {
+  :where(.bp-sidebar > ul, .bp-toc-switcher > ul, .bp-toc > ul)::before {
     content: "";
     position: absolute;
     left: 0;
@@ -2807,7 +2846,7 @@
     transition-duration: var(--bp-duration-slow);
     transition-timing-function: var(--bp-ease-out);
   }
-  :where(.bp-sidebar > ul > li, .bp-sidebar__panel > ul > li, .bp-toc > ul > li) {
+  :where(.bp-sidebar > ul > li, .bp-toc-switcher > ul > li, .bp-toc > ul > li) {
     counter-increment: bp-toc;
     margin: 0;
     padding: 0;
@@ -2833,7 +2872,7 @@
     transition: none;
   }
   /* Auto-numbered index (01, 02…), tabular so the digits line up. */
-  :where(.bp-sidebar > ul > li > a, .bp-sidebar__panel > ul > li > a, .bp-toc > ul > li > a)::before {
+  :where(.bp-sidebar > ul > li > a, .bp-toc-switcher > ul > li > a, .bp-toc > ul > li > a)::before {
     content: counter(bp-toc, decimal-leading-zero);
     flex: 0 0 var(--bp-toc-index-w, 14px);
     min-width: var(--bp-toc-index-w, 14px);
@@ -2880,9 +2919,6 @@
   :where(.bp-sidebar a:hover, .bp-toc a:hover) {
     color: var(--bp-ink);
     background: var(--bp-fill-amb);
-    transition:
-      color var(--bp-duration-fast) var(--bp-ease),
-      background-color var(--bp-duration-fast) var(--bp-ease);
   }
   :where(.bp-sidebar a[aria-current="location"], .bp-toc a[aria-current="location"], .bp-sidebar a.active, .bp-sidebar a.is-active, .bp-toc a.active, .bp-toc a.is-active) {
     color: var(--bp-ink);
@@ -2891,7 +2927,6 @@
   }
   :where(.bp-sidebar a:hover::before, .bp-toc a:hover::before) {
     color: var(--bp-ink);
-    transition: color var(--bp-duration-fast) var(--bp-ease);
   }
   :where(.bp-sidebar a[aria-current="location"]::before, .bp-toc a[aria-current="location"]::before, .bp-sidebar a.active::before, .bp-toc a.active::before) {
     color: var(--bp-ink);
@@ -4251,10 +4286,16 @@
     margin: 0;
   }
   /* Expanded mock floats fullscreen (position: fixed): collapse the host so
-     no empty dotted mat is left behind in the document flow. */
+     no empty dotted mat is left behind in the document flow, and clear any
+     host clipping / board paint so browsers that clip fixed descendants
+     through overflow-hidden ancestors still show the overlay fullscreen. */
   :where(bp-mock:has(.bp-mock.is-expanded)) {
     margin: 0;
     padding: 0;
+    overflow: visible;
+    border-radius: 0;
+    background-color: oklch(1 0 0 / 0);
+    background-image: none;
   }
 
   /* Single-surface specimens read as ONE continuous paper card on the mat;
@@ -4425,7 +4466,7 @@
     }
     /* The gliding pill only makes sense in the fixed column; in the collapsed
        horizontal nav the active entry just shows its own static pill. */
-    :where(.bp-sidebar > ul, .bp-sidebar__panel > ul, .bp-toc > ul)::before { content: none; }
+    :where(.bp-sidebar > ul, .bp-toc-switcher > ul, .bp-toc > ul)::before { content: none; }
     :where(.bp-sidebar a[aria-current="location"], .bp-toc a[aria-current="location"]) {
       background: var(--bp-fill-hi);
     }
@@ -4694,9 +4735,10 @@ body > .site-nav .site-nav__theme:hover {
   border: 1px solid var(--bp-edge);
   border-radius: var(--bp-radius-pill);
   background: var(--bp-paper);
-  /* Hover-only color motion — idle fields snap on theme flip so the root
-     view-transition crossfade isn't fighting per-field token tweens. */
-  transition: none;
+  /* Color motion is hover-only so idle fields snap on theme flip and don't
+     fight the root view-transition crossfade; transform is exempt (not a
+     color) so the press nudge can ease in every state. */
+  transition: transform var(--bp-duration-fast) var(--bp-ease-out);
 }
 .sidebar-field:hover,
 .sidebar-field:focus-within {
@@ -4704,7 +4746,13 @@ body > .site-nav .site-nav__theme:hover {
   background: var(--bp-fill-amb);
   transition:
     border-color var(--bp-duration-fast) var(--bp-ease-out),
-    background-color var(--bp-duration-fast) var(--bp-ease-out);
+    background-color var(--bp-duration-fast) var(--bp-ease-out),
+    transform var(--bp-duration-fast) var(--bp-ease-out);
+}
+/* Press feedback — match the Obvious app: the select triggers (doc switcher,
+   contents dropdown) and the search trigger nudge 1px down on press. */
+.sidebar-field:active {
+  transform: translateY(1px);
 }
 .doc-switcher__current {
   display: flex;
@@ -4723,7 +4771,7 @@ body > .site-nav .site-nav__theme:hover {
   display: none;
 }
 .doc-switcher__current::before {
-  content: none !important;
+  content: none;
 }
 .doc-switcher__label {
   display: flex;
@@ -4760,7 +4808,7 @@ body > .site-nav .site-nav__theme:hover {
   padding: var(--bp-space-1);
   border: 1px solid var(--bp-edge);
   /* Container radius − padding = item radius, so the rows nest perfectly. */
-  border-radius: var(--bp-radius-8, 8px);
+  border-radius: var(--bp-shell-panel-radius, var(--bp-radius-12, 12px));
   background: var(--bp-paper);
   box-shadow: var(--bp-shadow-pop);
   transform-origin: top center;
@@ -4787,7 +4835,7 @@ body > .site-nav .site-nav__theme:hover {
   justify-content: space-between;
   gap: var(--bp-space-2);
   padding: var(--bp-space-2) var(--bp-space-3);
-  border-radius: var(--bp-radius-4, 4px);
+  border-radius: var(--bp-radius-8, 8px);
   text-decoration: none;
 }
 .doc-switcher__menu a:hover {
@@ -4829,6 +4877,130 @@ body > .site-nav .site-nav__theme:hover {
   opacity: 1;
 }
 
+/* =====================================================================
+   Contents dropdown (.bp-toc-switcher)
+   ---------------------------------------------------------------------
+   The runtime wraps the contents list in a <details> so the rail can
+   collapse into the same select-style control as the doc switcher once it
+   becomes a horizontal band (≤860px). On the wide column the summary is
+   hidden and blueprint.js keeps the <details> open, so the list renders as
+   the plain vertical rail; only the narrow strip shows the trigger field +
+   popover menu. ===================================================== */
+/* Reset the base <details> disclosure chrome (border/surface/padding) so the
+   wrapper is invisible on the wide column — the list must read as the plain
+   rail, not a boxed disclosure. */
+.bp-toc-switcher {
+  position: relative;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+}
+/* Trigger field — hidden on the wide column, shown as the dropdown summary on
+   the narrow strip. Mirrors the doc-switcher current row. */
+.bp-toc-switcher__current {
+  display: none;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--bp-space-3);
+  height: var(--bp-sidebar-toggle-size);
+  margin: 0;
+  padding: 0 var(--bp-space-3);
+  list-style: none;
+  font-weight: 400;
+  cursor: pointer;
+}
+.bp-toc-switcher__current::-webkit-details-marker {
+  display: none;
+}
+.bp-toc-switcher__current::before {
+  content: none;
+}
+.bp-toc-switcher__label {
+  display: flex;
+  min-width: 0;
+}
+.bp-toc-switcher__title {
+  min-width: 0;
+  overflow: hidden;
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.bp-toc-switcher__chevron {
+  display: inline-flex;
+  flex: 0 0 auto;
+  color: var(--bp-text-secondary);
+}
+.bp-toc-switcher[open] .bp-toc-switcher__chevron {
+  transform: rotate(180deg);
+}
+
+@media (max-width: 860px) {
+  /* The rail is a horizontal band here — let the dropdown's popover escape it
+     instead of being clipped by the strip's own scroll box. Size to content so
+     the rail's bottom border lands right after the footer (theme + author) — the
+     fixed-rail full-viewport height (.site-nav ~ .bp-sidebar) would otherwise
+     push it to the bottom of the screen with dead space between. */
+  .bp-sidebar:has(.bp-toc-switcher) {
+    overflow: visible;
+    max-height: none;
+    height: auto;
+  }
+  .bp-toc-switcher__current {
+    display: flex;
+  }
+  /* Popover menu: float the contents below the trigger like the doc-switcher
+     menu, replacing the inline horizontal strip. Native <details> hides it
+     while collapsed, so only the open state needs the floating chrome. */
+  .bp-toc-switcher[open] > ul {
+    position: absolute;
+    left: 0;
+    right: 0;
+    top: calc(100% + var(--bp-space-1));
+    z-index: 300;
+    display: block;
+    max-height: min(60vh, 360px);
+    overflow: hidden auto;
+    gap: 0;
+    margin: 0;
+    padding: var(--bp-space-1);
+    border: 1px solid var(--bp-edge);
+    border-radius: var(--bp-radius-8, 8px);
+    background: var(--bp-paper);
+    box-shadow: var(--bp-shadow-pop);
+    animation: bp-doc-switcher-in var(--bp-duration-normal) var(--bp-ease-out);
+  }
+  /* Nested sub-entries stack as rows too rather than the strip's inline run. */
+  .bp-toc-switcher ul ul {
+    display: block;
+    overflow: visible;
+  }
+  /* Group eyebrow heads its run as a quiet stacked label, not an inline chip. */
+  .bp-toc-switcher .bp-nav-group {
+    display: block;
+    margin: var(--bp-space-2) 0 var(--bp-space-1);
+  }
+  .bp-toc-switcher .bp-nav-group:first-child {
+    margin-top: 0;
+  }
+  /* The gliding pill is suppressed on the strip; the active row carries its
+     own fill, matching the doc-switcher's current row. */
+  .bp-toc-switcher a[aria-current="location"] {
+    background: var(--bp-fill-hi);
+  }
+  /* Menu rows snap on hover like the doc-switcher — no row color tween. */
+  .bp-toc-switcher[open] ul a,
+  .bp-toc-switcher[open] ul a:hover,
+  .bp-toc-switcher[open] ul a::before,
+  .bp-toc-switcher[open] ul a:hover::before {
+    transition: none;
+  }
+}
+
 /* Sidebar search — header row beside the corner toggle, above the header scrim. */
 .sidebar-search {
   position: relative;
@@ -4895,8 +5067,8 @@ body > .site-nav .site-nav__theme:hover {
    Search command menu (docs chrome) — Mintlify-style palette
    ---------------------------------------------------------------------
    Opened from the sidebar trigger or ⌘K / Ctrl+K (see wireSearchPalette).
-   Reuses the rounded sidebar control family: paper surface, --bp-radius-8
-   panel with --bp-shadow-pop, --bp-radius-4 rows, the --bp-fill-amb /
+   Reuses the rounded sidebar control family: paper surface, --bp-radius-16
+   panel with --bp-shadow-pop, --bp-radius-8 rows, the --bp-fill-amb /
    --bp-fill-hi hover + selected surfaces, and the shared open animation.
    Chrome stays on the neutral ink scale. Query filtering is a plain
    substring match over the page's headings; richer search is deferred.
@@ -4942,17 +5114,17 @@ body > .site-nav .site-nav__theme:hover {
   max-height: min(560px, 80vh);
   overflow: hidden;
   border: 1px solid var(--bp-edge);
-  border-radius: var(--bp-radius-8, 8px);
+  border-radius: var(--bp-radius-16, 16px);
   background: var(--bp-paper);
   box-shadow: var(--bp-shadow-pop);
 }
 
-/* Search row */
+/* Search row — icon hugging the input via a tight gap. */
 .docs-search__field {
   display: flex;
   align-items: center;
-  gap: var(--bp-space-3);
-  padding: var(--bp-space-3) var(--bp-space-4);
+  gap: var(--bp-space-2);
+  padding: var(--bp-space-3);
   border-bottom: 1px solid var(--bp-edge);
 }
 .docs-search__icon {
@@ -4999,12 +5171,15 @@ body > .site-nav .site-nav__theme:hover {
   overflow-y: auto;
   padding: var(--bp-space-2);
 }
+.docs-search__results:has(> .docs-search__empty:only-child) {
+  padding: 0;
+}
 /* Group label — machine voice (mono + uppercase) with a trailing count. */
 .docs-search__group {
   display: flex;
   align-items: center;
   gap: var(--bp-space-2);
-  padding: var(--bp-space-2) var(--bp-space-3) var(--bp-space-1);
+  padding: var(--bp-space-1) var(--bp-space-3) var(--bp-space-1);
   font-family: var(--bp-mono);
   font-size: var(--bp-label-md);
   letter-spacing: var(--bp-label-md-ls);
@@ -5020,12 +5195,11 @@ body > .site-nav .site-nav__theme:hover {
    Rows are <a> for navigation; suppress the base prose link underline except
    on the selected/hovered surface (background carries the affordance). */
 .docs-search__row {
-  display: grid;
-  grid-template-columns: 1fr auto;
-  align-items: center;
-  gap: var(--bp-space-1) var(--bp-space-3);
-  padding: var(--bp-space-2) var(--bp-space-3);
-  border-radius: var(--bp-radius-4, 4px);
+  display: flex;
+  align-items: flex-start;
+  gap: var(--bp-space-1);
+  padding: var(--bp-space-1) var(--bp-space-2);
+  border-radius: var(--bp-radius-8, 8px);
   cursor: pointer;
   text-decoration: none;
   color: inherit;
@@ -5039,13 +5213,31 @@ body > .site-nav .site-nav__theme:hover {
   background: var(--bp-fill-hi);
   text-decoration: none;
 }
+/* Leading icon cell — a fixed square holding the heading-anchor "#" in the
+   machine voice, so every row aligns on one icon column. */
+.docs-search__icon-box {
+  grid-column: 1;
+  grid-row: 1 / -1;
+  align-self: start;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  font-family: var(--bp-mono);
+  font-size: var(--bp-text-small);
+  color: var(--bp-text-secondary);
+}
 .docs-search__row-main {
-  display: flex;
-  flex-direction: column;
-  gap: var(--bp-space-1);
+  display: grid;
+  flex: 1 1 auto;
+  grid-template-columns: 20px 1fr;
+  gap: 0;
   min-width: 0;
 }
 .docs-search__crumb {
+  grid-column: 2;
+  grid-row: 1;
   display: block;
   font-family: var(--bp-mono);
   font-size: var(--bp-label-md);
@@ -5056,22 +5248,22 @@ body > .site-nav .site-nav__theme:hover {
   text-overflow: ellipsis;
 }
 .docs-search__title {
-  display: flex;
-  align-items: baseline;
-  gap: var(--bp-space-1);
+  grid-column: 2;
+  grid-row: 2;
+  display: block;
   min-width: 0;
   font-family: var(--bp-sans);
   font-size: var(--bp-text-small);
-  line-height: 1.3;
-  font-weight: var(--bp-weight-medium);
+  line-height: var(--bp-lh-small);
+  font-weight: var(--bp-weight-body);
   color: var(--bp-text);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
-/* The "#" anchor glyph borrows the machine voice so it reads as a heading
-   link, not prose. */
-.docs-search__hash {
-  flex: 0 0 auto;
-  font-family: var(--bp-mono);
-  color: var(--bp-text-secondary);
+/* When a row has no breadcrumb, the title sits on the icon's line. */
+.docs-search__row-main:not(:has(.docs-search__crumb)) .docs-search__title {
+  grid-row: 1;
 }
 .docs-search__snippet {
   overflow: hidden;
@@ -5091,8 +5283,15 @@ body > .site-nav .site-nav__theme:hover {
 .docs-search__enter {
   flex: 0 0 auto;
   align-self: center;
-  padding: 1px 5px;
-  font-size: var(--bp-label-md);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: 0;
+  background: none;
+  font-size: var(--bp-text-small);
   color: var(--bp-text-secondary);
   opacity: 0;
 }
@@ -5101,64 +5300,110 @@ body > .site-nav .site-nav__theme:hover {
   opacity: 1;
 }
 
-/* Empty state */
+/* Empty state — a quiet centered text stack, no icon. */
 .docs-search__empty {
+  border-top: 1px solid var(--bp-edge);
+  padding: var(--bp-space-2);
+  font-size: var(--bp-text-small);
+  line-height: var(--bp-lh-small);
+}
+.docs-search__empty-center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding-block: var(--bp-space-5);
+}
+.docs-search__empty-copy {
   display: flex;
   flex-direction: column;
   align-items: center;
-  gap: var(--bp-space-2);
-  padding: var(--bp-space-6) var(--bp-space-4);
   text-align: center;
 }
-.docs-search__empty-icon {
-  display: inline-flex;
-  color: var(--bp-text-secondary);
-  opacity: 0.6;
-}
 .docs-search__empty-title {
+  margin: 0;
   font-family: var(--bp-sans);
   font-size: var(--bp-text-small);
-  font-weight: var(--bp-weight-medium);
-  color: var(--bp-text);
+  line-height: var(--bp-lh-small);
+  font-weight: var(--bp-weight-body);
+  color: var(--bp-text-secondary);
+  text-align: center;
 }
 .docs-search__empty-note {
-  font-size: var(--bp-text-small);
-  color: var(--bp-text-secondary);
+  margin: var(--bp-space-1) 0 0;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-code);
+  line-height: var(--bp-lh-code);
+  color: var(--bp-ink-soft);
+  text-align: center;
 }
 
-/* Footer keyboard legend */
+/* Footer command rows. A quiet stack of secondary actions, each a full-width
+   button whose icon, label, and chip step from secondary to primary ink on
+   hover — no background wash — and trails a mono shortcut
+   chip — the layout the source palette parks its workspace commands in. */
 .docs-search__foot {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--bp-space-1) var(--bp-space-3);
-  padding: var(--bp-space-2) var(--bp-space-4);
   border-top: 1px solid var(--bp-edge);
-  font-family: var(--bp-mono);
-  font-size: var(--bp-label-md);
-  letter-spacing: var(--bp-label-md-ls);
-  color: var(--bp-text-secondary);
+  padding: var(--bp-space-2);
 }
-.docs-search__keys {
+.docs-search__actions {
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
+}
+.docs-search__action {
   display: flex;
-  flex-wrap: wrap;
   align-items: center;
-  gap: var(--bp-space-1) var(--bp-space-3);
+  gap: var(--bp-space-2);
+  width: 100%;
+  padding: var(--bp-space-1) var(--bp-space-2);
+  border: 0;
+  border-radius: var(--bp-radius-4, 4px);
+  background: none;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-small);
+  line-height: var(--bp-lh-control);
+  color: var(--bp-text-secondary);
+  text-align: left;
+  cursor: pointer;
 }
-.docs-search__key {
+.docs-search__action:hover {
+  color: var(--bp-text);
+}
+.docs-search__action:focus-visible {
+  color: var(--bp-text);
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--bp-ink-line);
+}
+.docs-search__action-icon {
+  flex: 0 0 auto;
   display: inline-flex;
-  align-items: center;
-  gap: var(--bp-space-1);
+  color: inherit;
 }
-.docs-search__foot kbd {
-  padding: 0 4px;
-  border-width: 1px;
+.docs-search__action-label {
+  flex: 1 1 auto;
+  min-width: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.docs-search__chip {
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  padding: 1px var(--bp-space-1);
+  border: 1px solid var(--bp-edge);
   border-radius: var(--bp-radius-2, 2px);
+  background: var(--bp-fill-hi);
+  font-family: var(--bp-mono);
   font-size: var(--bp-label-md);
   line-height: 1.5;
   color: var(--bp-text-secondary);
 }
+.docs-search__action:hover .docs-search__chip,
+.docs-search__action:focus-visible .docs-search__chip {
+  color: var(--bp-text);
+}
 
 /* Sidebar footer scrim token. The footer (theme switch + author/date) gets a
    soft fade above it so the scrollable TOC dissolves into the rail rather than
@@ -5433,7 +5678,27 @@ body > .site-nav .site-nav__theme:hover {
     padding-top: var(--bp-space-6);
     padding-inline: var(--bp-sidebar-content-inset);
     padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+    /* Mirror the footer clearance at the top: when the runtime scrolls the
+       active entry into view (blueprint.js revealInRail), keep it below the
+       header dissolve scrim instead of tucking under the corner toggle. */
+    scroll-padding-top: var(--bp-sidebar-header-scrim);
     scroll-padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+    display: flex;
+    flex-direction: column;
+  }
+  /* Wrapper is mobile-only chrome; on the wide column its children join the
+     panel flex in search → doc switcher → TOC order. */
+  .sidebar-mobile-head {
+    display: contents;
+  }
+  .sidebar-search {
+    order: 1;
+  }
+  .doc-switcher {
+    order: 2;
+  }
+  .bp-toc-switcher {
+    order: 3;
   }
 
   /* Drop the switcher below the header scrim (search stays above it on z 300). */
@@ -5524,12 +5789,154 @@ body > .site-nav .site-nav__theme:hover {
   }
 }
 
-/* Below the rail's fixed breakpoint it becomes a static horizontal nav,
-   where collapsing has no meaning — hide the control entirely. */
+/* Below the rail's fixed breakpoint the chrome flattens into a static
+   horizontal nav. The runtime chrome lives in this (unlayered) sheet, so its
+   resting rules beat blueprint.css's layered responsive block — the flattened
+   layout has to be reconciled here or the fixed-rail geometry leaks through. */
 @media (max-width: 860px) {
+  :root {
+    --bp-sidebar-mobile-head-h: calc(
+      var(--bp-sidebar-toggle-size) + var(--bp-space-3) * 2
+    );
+  }
+
+  /* Hash / TOC jumps land below the pinned mobile head instead of tucking the
+     heading under it. Framed layouts (701–860px) reserve the shell top band +
+     head; phones and site-nav offsets are handled in their own blocks below. */
+  html[data-bp-document] {
+    --bp-scroll-margin: calc(
+      var(--bp-sidebar-mobile-head-h) + var(--bp-space-2)
+    );
+  }
+
+  /* Collapsing has no meaning once the rail is a horizontal strip. */
   .sidebar-toggle {
     display: none;
   }
+
+  /* Fixed band: section select + search icon stay pinned while the doc
+     switcher and footer scroll with the page. Sticky failed here because the
+     whole rail scrolls away — fixed keeps the controls always reachable on long
+     documents. No own border: the rail's bottom edge carries the single
+     divider, landing below the footer where the nav content ends. Between phone
+     and rail breakpoints the head sits inside the shell frame, below the top
+     rule and one stroke inset on the sides so the pseudo borders stay visible
+     (≤700px drops the frame and returns to full bleed). */
+  .sidebar-mobile-head {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    z-index: 320;
+    display: grid;
+    grid-template-columns: 1fr auto;
+    column-gap: var(--bp-space-2);
+    background: var(--bp-bg);
+    padding: var(--bp-space-3) var(--bp-space-4);
+  }
+
+  /* Framed range (701–860px): the desk frame is drawn, so tuck the head inside
+     it and back the top rule so nothing scrolls through. */
+  @media (min-width: 701px) {
+    /* The shell top rule is a height:0 box with an 8%-alpha border-top, so when
+       content scrolls beneath it the near-transparent border lets it bleed
+       through that 1px row (the desk mask only covers the band above it).
+       Extend the opaque desk mask by one stroke so it backs the border row;
+       the frame border (z 210) then draws over solid bg, staying visible. */
+    html[data-bp-document] body::before {
+      height: calc(var(--bp-shell-inset-top) + var(--bp-stroke));
+    }
+    html[data-bp-document] {
+      --bp-scroll-margin: calc(
+        var(--bp-shell-inset-top) + var(--bp-stroke) +
+          var(--bp-sidebar-mobile-head-h) + var(--bp-space-2)
+      );
+    }
+    html[data-bp-document] .sidebar-mobile-head {
+      /* Flush below the top rule (inset-top + its hairline); one stroke inside
+         the vertical rules so they stay visible. */
+      top: calc(var(--bp-shell-inset-top) + var(--bp-stroke));
+      left: calc(var(--bp-shell-inset-left) + var(--bp-stroke));
+      right: calc(var(--bp-shell-inset-right) + var(--bp-stroke));
+      /* Frame inset + this padding matches .bp-sidebar padding-inline. */
+      padding-inline: max(
+        0px,
+        calc(
+          var(--bp-space-4) - var(--bp-shell-inset-left) - var(--bp-stroke)
+        )
+      );
+    }
+  }
+
+  /* Phone range (≤700px): the desk frame is removed, so the head is full bleed.
+     Only the site nav, when present, pushes it down. */
+  @media (max-width: 700px) {
+    html[data-bp-document]:has(body > .site-nav) {
+      --bp-scroll-margin: calc(
+        var(--bp-site-nav-height) + var(--bp-sidebar-mobile-head-h) +
+          var(--bp-space-2)
+      );
+    }
+    html:has(body > .site-nav) .sidebar-mobile-head {
+      top: var(--bp-site-nav-height);
+    }
+  }
+
+  /* Once the rail's own bottom border has scrolled up under the pinned head,
+     the head carries the divider at that same line (blueprint.js toggles the
+     attribute). At rest the head is borderless — the rail edge is the divider. */
+  .sidebar-mobile-head[data-bp-head-stuck] {
+    border-bottom: 1px solid var(--bp-edge);
+  }
+  .bp-sidebar__panel {
+    display: block;
+    /* Reserve the fixed head height so the doc switcher starts below it. */
+    padding-top: var(--bp-sidebar-mobile-head-h);
+  }
+  .bp-toc-switcher {
+    min-width: 0;
+  }
+  .sidebar-search {
+    margin: 0;
+    align-self: start;
+  }
+  /* Pill icon button — same trigger as the wide search field, opens ⌘K palette. */
+  .sidebar-search__field {
+    width: var(--bp-sidebar-toggle-size);
+    min-width: var(--bp-sidebar-toggle-size);
+    padding: 0;
+    gap: 0;
+    justify-content: center;
+  }
+  .sidebar-search__label,
+  .sidebar-search__hint {
+    display: none;
+  }
+  .doc-switcher {
+    margin: 0;
+  }
+
+  /* The fixed rail reserved a tall bottom band for its pinned footer; in the
+     static strip that band is just dead space below the meta row. Match the
+     top inset so the nav ends as tightly as it begins. Give the search,
+     switchers, and footer row breathing room from the viewport edges. */
+  .bp-sidebar {
+    display: flex;
+    flex-direction: column;
+    gap: var(--bp-space-3);
+    padding-inline: var(--bp-space-4);
+    padding-bottom: var(--bp-space-4);
+    padding-top: 0;
+  }
+
+  /* The footer is a single meta row now, not a full-height column: pull the
+     theme control and author/date into one left-aligned cluster so they read
+     together rather than stranded at opposite edges of a wide strip. */
+  .sidebar-footer {
+    justify-content: flex-start;
+    gap: var(--bp-space-5);
+    margin-top: 0;
+  }
 }
 
 @media print {