@obvi/blueprint 1.1.2 → 1.2.0

package/dist/blueprint.css

@@ -184,6 +184,37 @@
       var(--bp-ink-faint) 0 var(--bp-stroke),
       oklch(0 0 0 / 0) var(--bp-stroke) var(--bp-hatch-gap)
     );
+    /* Drafting board — a faint dot-grid backdrop that marks INTERACTIVE
+       component surfaces (choice, preflight, choice-record, source, mock,
+       gallery): a second axis distinct from the diagonal --bp-hatch (which
+       means fenced / held / rejected). Dots read as an open working surface,
+       so the two textures never compete. --bp-board-gap is the grid pitch;
+       --bp-board the reusable image. The dot color rides on --bp-ink-faint;
+       light uses a stronger mix (55%) than dark (35%) — see the dark block. */
+    --bp-board-gap: 18px;
+    --bp-board-dot: color-mix(in oklch, var(--bp-ink-faint) 55%, oklch(0 0 0 / 0));
+    --bp-board: radial-gradient(
+      circle at center,
+      var(--bp-board-dot) 0 0.85px,
+      oklch(0 0 0 / 0) 0.85px
+    );
+    /* The board rides on a faintly tinted surface — one elevation step between
+       the desk (--bp-bg) and the sheet (--bp-paper) — so a dotted interactive
+       section reads as its own panel and the paper cards inside it lift off the
+       mat. Derived from the two surface tokens, so it tracks either theme (and
+       any host override of paper / bg) from this single definition. */
+    --bp-board-bg: color-mix(in oklch, var(--bp-paper) 60%, var(--bp-bg));
+    /* Footer strips on the mat (hint + reset): vertical breathing room and a
+       horizontal inset that lines up with the component content above.
+       --bp-board-footer-pad-x defaults to preflight question padding; choice
+       layouts reassign it to match .bp-choice__card inset. */
+    --bp-board-footer-pad-y: var(--bp-space-2);
+    --bp-board-footer-pad-x: var(--bp-space-4);
+    /* Single-surface interactive roots on the mat (tabs choice, preflight):
+       uniform inset + Obvious container radius so the paper card reads as a
+       decision surface on the dotted board. */
+    --bp-board-card-pad: var(--bp-space-4);
+    --bp-board-card-radius: var(--bp-radius-8);
     /* Modal scrim wash — darker than --bp-ink-soft so floated panels (search
        palette, lightbox, expanded mock) read clearly over the page. Always
        pair with --bp-hatch:
@@ -224,6 +255,7 @@
     --bp-text-body: 14px;        --bp-lh-body: 20px;      /* body copy */
     --bp-text-small: 13px;       --bp-lh-small: 18px;     /* small / captions */
     --bp-text-code: 12.5px;      --bp-lh-code: 1.6;       /* mono, harmonized to body */
+    --bp-lh-control: 1.3;        /* tighter than reading text — sans control labels */
 
     /* 3-step monospace-label scale, ONE letter-spacing each */
     --bp-label-sm: 9px;   --bp-label-sm-ls: 0.08em;
@@ -257,14 +289,45 @@
     /* 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),
+       secondary (resting control), tertiary (quiet track / ghost fill), ghost
+       (text-only). Fills stay on the neutral scale (no hue) so figures keep the
+       blue monopoly. Each value consumes the live Obvious app variable
+       (--button-*) when a document is embedded in the dashboard, and otherwise
+       falls back to the OKLCH value from the app's colors.css. */
+    --bp-button-primary-bg: var(--button-primary-bg, oklch(0.1344 0 0));
+    --bp-button-primary-bg-hover: var(--button-primary-bg-hover, oklch(0.3012 0 0));
+    --bp-button-primary-bg-press: var(--button-primary-bg-press, oklch(0.36 0 0));
+    --bp-button-primary-fg: var(--button-primary-fg, oklch(1 0 0));
+    --bp-button-secondary-bg: var(--button-secondary-bg, oklch(1 0 0));
+    --bp-button-secondary-bg-hover: var(--button-secondary-bg-hover, oklch(0.9702 0 0));
+    --bp-button-secondary-bg-press: var(--button-secondary-bg-press, oklch(0.9461 0 0));
+    --bp-button-secondary-fg: var(--button-secondary-fg, oklch(0 0 0 / 0.8));
+    --bp-button-secondary-bd: var(--button-secondary-bd, oklch(0 0 0 / 0.08));
+    --bp-button-tertiary-bg: var(--button-tertiary-bg, oklch(0 0 0 / 0.04));
+    --bp-button-tertiary-bg-hover: var(--button-tertiary-bg-hover, oklch(0 0 0 / 0.08));
+    --bp-button-tertiary-fg: var(--button-tertiary-fg, oklch(0 0 0 / 0.64));
+    --bp-button-ghost-fg: var(--button-ghost-fg, oklch(0 0 0 / 0.4));
+    --bp-button-ghost-fg-hover: var(--button-ghost-fg-hover, oklch(0 0 0 / 0.64));
+    --bp-button-ghost-bg-hover: var(--button-ghost-bg-hover, oklch(0 0 0 / 0.04));
+    /* Lifted-border ring carried by a raised (selected) secondary control. */
+    --bp-button-lift: 0 0 2px 0 oklch(0 0 0 / 0.05),
+      0 0 1px 0 oklch(0 0 0 / 0.05), 0 0 0 1px oklch(0 0 0 / 0.08);
 
     /* Section-eyebrow marker — the square that leads the "01 / 02" counter.
        Size is the block edge; gap is the space between it and the number. */
@@ -354,6 +417,7 @@
     --bp-ink: var(--obvious-text-primary, oklch(1 0 0 / 0.92));
     --bp-ink-soft: oklch(1 0 0 / 0.4);
     --bp-ink-faint: oklch(1 0 0 / 0.16);
+    --bp-board-dot: color-mix(in oklch, var(--bp-ink-faint) 35%, oklch(0 0 0 / 0));
     --bp-highlight: oklch(1 0 0 / 0.14);
 
     /* Illustration accent (dark) — brighter blue holds on dark paper. */
@@ -384,6 +448,25 @@
     --bp-text-secondary: oklch(1 0 0 / 0.64);
     --bp-positive: oklch(0.74 0.15 150);
     --bp-positive-faint: oklch(0.34 0.07 150);
+
+    /* Obvious button palette (dark) — see the light block for the contract. */
+    --bp-button-primary-bg: var(--button-primary-bg, oklch(0.4091 0 0));
+    --bp-button-primary-bg-hover: var(--button-primary-bg-hover, oklch(0.4819 0 0));
+    --bp-button-primary-bg-press: var(--button-primary-bg-press, oklch(0.5795 0 0));
+    --bp-button-primary-fg: var(--button-primary-fg, oklch(1 0 0 / 0.92));
+    --bp-button-secondary-bg: var(--button-secondary-bg, oklch(0.3012 0 0));
+    --bp-button-secondary-bg-hover: var(--button-secondary-bg-hover, oklch(0.3407 0 0));
+    --bp-button-secondary-bg-press: var(--button-secondary-bg-press, oklch(0.4091 0 0));
+    --bp-button-secondary-fg: var(--button-secondary-fg, oklch(1 0 0 / 0.8));
+    --bp-button-secondary-bd: var(--button-secondary-bd, oklch(1 0 0 / 0.04));
+    --bp-button-tertiary-bg: var(--button-tertiary-bg, oklch(1 0 0 / 0.04));
+    --bp-button-tertiary-bg-hover: var(--button-tertiary-bg-hover, oklch(1 0 0 / 0.08));
+    --bp-button-tertiary-fg: var(--button-tertiary-fg, oklch(1 0 0 / 0.64));
+    --bp-button-ghost-fg: var(--button-ghost-fg, oklch(1 0 0 / 0.4));
+    --bp-button-ghost-fg-hover: var(--button-ghost-fg-hover, oklch(1 0 0 / 0.64));
+    --bp-button-ghost-bg-hover: var(--button-ghost-bg-hover, oklch(1 0 0 / 0.04));
+    --bp-button-lift: 0 0 2px 0 oklch(1 0 0 / 0.05),
+      0 0 1px 0 oklch(1 0 0 / 0.05), 0 0 0 1px oklch(1 0 0 / 0.08);
   }
 }
 
@@ -433,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);
@@ -501,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;
   }
@@ -945,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);
@@ -1127,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
@@ -1275,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);
@@ -1478,7 +1573,7 @@
     padding: var(--bp-space-2) var(--bp-space-3);
     background: var(--bp-ink);
     color: var(--bp-paper);
-    border-radius: var(--bp-radius-0);
+    border-radius: var(--bp-radius-6);
     margin-bottom: var(--bp-space-3);
   }
   :where(.bp-choice:has(.bp-choice__commit:checked)) .bp-choice__verdict,
@@ -1538,10 +1633,9 @@
     border: 0;
     padding: 0;
     cursor: pointer;
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-md);
-    letter-spacing: var(--bp-label-md-ls);
-    text-transform: uppercase;
+    font-family: var(--bp-sans);
+    font-size: var(--bp-text-small);
+    line-height: var(--bp-lh-control);
     color: var(--bp-text-secondary);
     text-decoration: underline dotted;
     text-underline-offset: 3px;
@@ -1564,37 +1658,51 @@
     color: var(--bp-paper);
     background: var(--bp-ink);
     padding: 2px 8px;
+    border-radius: var(--bp-radius-pill);
   }
   :where(.bp-choice__tag--out) {
     color: var(--bp-ink);
     border: 1px solid var(--bp-ink-faint);
     padding: 1px 7px;
+    border-radius: var(--bp-radius-pill);
   }
 
   /* ---- layout: tabs (preview drafts, then adopt) ------------------- */
+  :where(.bp-choice--tabs) {
+    padding: var(--bp-board-card-pad);
+    border: 1px solid var(--bp-ink-line);
+    border-radius: var(--bp-board-card-radius);
+    overflow: hidden;
+  }
   :where(.bp-choice--tabs) :where(.bp-choice__seg) {
     display: flex;
     flex-wrap: wrap;
-    gap: 0;
-    border: 1px solid var(--bp-ink-line);
-    border-radius: var(--bp-radius-0);
-    overflow: hidden;
+    gap: 2px;
+    padding: 2px;
+    border: 0;
+    border-radius: var(--bp-radius-pill);
+    background: var(--bp-button-tertiary-bg);
+    overflow: visible;
     margin: 0 0 var(--bp-space-3);
     width: fit-content;
   }
   :where(.bp-choice__seg-opt) {
     position: relative;
     cursor: pointer;
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-md);
-    letter-spacing: var(--bp-label-md-ls);
-    text-transform: uppercase;
-    color: var(--bp-text-secondary);
+    font-family: var(--bp-sans);
+    font-size: var(--bp-text-small);
+    line-height: var(--bp-lh-control);
+    color: var(--bp-button-ghost-fg);
     padding: 6px 14px;
-    border-right: 1px solid var(--bp-ink-line);
+    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),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
-  :where(.bp-choice__seg-opt:last-child) {
-    border-right: 0;
+  :where(.bp-choice__seg-opt:hover) {
+    color: var(--bp-button-ghost-fg-hover);
+    background: var(--bp-button-ghost-bg-hover);
   }
   :where(.bp-choice__seg-opt) :where(input) {
     position: absolute;
@@ -1602,8 +1710,9 @@
     pointer-events: none;
   }
   :where(.bp-choice__seg-opt:has(input:checked)) {
-    background: var(--bp-ink);
-    color: var(--bp-paper);
+    background: var(--bp-button-secondary-bg);
+    color: var(--bp-button-secondary-fg);
+    box-shadow: var(--bp-button-lift);
   }
   :where(.bp-choice--tabs) :where(.bp-choice__panel) {
     display: none;
@@ -1616,18 +1725,20 @@
     align-items: center;
     gap: 8px;
     cursor: pointer;
-    border: 1px solid var(--bp-ink);
-    border-radius: var(--bp-radius-0);
+    border: 1px solid var(--bp-button-secondary-bd);
+    border-radius: var(--bp-radius-pill);
     padding: 6px 14px;
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-md);
-    letter-spacing: var(--bp-label-md-ls);
-    text-transform: uppercase;
-    color: var(--bp-ink);
-    background: var(--bp-paper);
+    font-family: var(--bp-sans);
+    font-size: var(--bp-text-small);
+    line-height: var(--bp-lh-control);
+    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),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
   :where(.bp-choice__adopt:hover) {
-    background: var(--bp-fill-hi);
+    background: var(--bp-button-secondary-bg-hover);
   }
   :where(.bp-choice__adopt) :where(input) {
     position: absolute;
@@ -1638,13 +1749,14 @@
     border: 1px solid var(--bp-ink);
     background: var(--bp-fill-amb);
     padding: var(--bp-space-3);
-    margin-left: calc(-1 * var(--bp-space-3));
-    margin-right: calc(-1 * var(--bp-space-3));
-    border-radius: var(--bp-radius-0);
+    margin-left: calc(-1 * var(--bp-board-card-pad));
+    margin-right: calc(-1 * var(--bp-board-card-pad));
+    border-radius: var(--bp-radius-6);
   }
   :where(.bp-choice__panel:has(.bp-choice__commit:checked)) :where(.bp-choice__adopt) {
-    background: var(--bp-ink);
-    color: var(--bp-paper);
+    border-color: var(--bp-button-primary-bg);
+    background: var(--bp-button-primary-bg);
+    color: var(--bp-button-primary-fg);
   }
 
   /* ---- layout: stack (all cards visible) --------------------------- */
@@ -1656,7 +1768,7 @@
     display: block;
     position: relative;
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-0);
+    border-radius: var(--bp-radius-6);
     padding: var(--bp-space-3);
     cursor: pointer;
     background: var(--bp-paper);
@@ -1744,7 +1856,7 @@
     position: relative;
     cursor: pointer;
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-0);
+    border-radius: var(--bp-radius-6);
     overflow: hidden;
     background: var(--bp-paper);
   }
@@ -1799,18 +1911,33 @@
 
   :where(.bp-choice__compare) {
     margin-top: var(--bp-space-3);
+    /* Override the base <details> inset (0 var(--bp-space-3) padding + a 2px
+       left border) so the summary bar and disclosed body span the full card
+       width — the summary and body carry their own padding. */
+    padding: 0;
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-0);
+    border-radius: var(--bp-radius-6);
+    overflow: hidden;
+  }
+  :where(.bp-choice__compare[open]) {
+    padding-bottom: 0;
   }
   :where(.bp-choice__compare > summary) {
     cursor: pointer;
     list-style: none;
-    padding: var(--bp-space-2) var(--bp-space-3);
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-md);
-    letter-spacing: var(--bp-label-md-ls);
-    text-transform: uppercase;
-    color: var(--bp-text-secondary);
+    padding: var(--bp-space-3);
+    font-family: var(--bp-sans);
+    font-size: var(--bp-text-small);
+    line-height: var(--bp-lh-control);
+    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),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
+  }
+  :where(.bp-choice__compare > summary:hover) {
+    background: var(--bp-button-tertiary-bg-hover);
+    color: var(--bp-button-ghost-fg-hover);
   }
   :where(.bp-choice__compare > summary)::-webkit-details-marker {
     display: none;
@@ -1819,11 +1946,17 @@
     padding: var(--bp-space-3);
     border-top: 1px solid var(--bp-edge);
   }
+  /* The slot content is usually a <dl>; drop its document margins so the
+     disclosed body keeps one uniform inset (vertical matches horizontal). */
+  :where(.bp-choice__compare-body) :where(dl) {
+    margin: 0;
+    gap: var(--bp-space-2) var(--bp-space-3);
+  }
 
   /* ---- Pre-flight (decisions before drafting) ---------------------- */
   :where(.bp-preflight) {
     border: 1px solid var(--bp-ink-line);
-    border-radius: var(--bp-radius-0);
+    border-radius: var(--bp-board-card-radius);
     overflow: hidden;
     margin: var(--bp-space-4) 0;
   }
@@ -1852,23 +1985,9 @@
   }
   :where(.bp-preflight__q) {
     counter-increment: bp-preflight-q;
-    padding: var(--bp-space-3) var(--bp-space-3) var(--bp-space-3) calc(var(--bp-space-6) + 4px);
-    position: relative;
+    padding: var(--bp-space-4);
     border-bottom: 1px solid var(--bp-edge);
   }
-  :where(.bp-preflight__q::before) {
-    content: counter(bp-preflight-q, decimal-leading-zero);
-    position: absolute;
-    left: var(--bp-space-3);
-    top: var(--bp-space-3);
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-lg);
-    letter-spacing: 0.08em;
-    color: var(--bp-ink-soft);
-  }
-  :where(.bp-preflight__q:has(input:checked)::before) {
-    color: var(--bp-ink);
-  }
   :where(.bp-preflight__prompt) {
     font-family: var(--bp-sans);
     font-weight: var(--bp-weight-strong);
@@ -1878,6 +1997,16 @@
     align-items: baseline;
     gap: var(--bp-space-2);
   }
+  :where(.bp-preflight__prompt::before) {
+    content: counter(bp-preflight-q, decimal-leading-zero);
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-lg);
+    letter-spacing: 0.08em;
+    color: var(--bp-ink-soft);
+  }
+  :where(.bp-preflight__q:has(input:checked)) :where(.bp-preflight__prompt::before) {
+    color: var(--bp-ink);
+  }
   :where(.bp-preflight__kind) {
     font-family: var(--bp-mono);
     font-size: var(--bp-label-sm);
@@ -1887,11 +2016,11 @@
     font-weight: var(--bp-weight-body);
   }
   :where(.bp-preflight__resolved) {
-    display: none;
+    visibility: hidden;
     margin-left: auto;
   }
   :where(.bp-preflight__q:has(input:checked)) :where(.bp-preflight__resolved) {
-    display: inline-flex;
+    visibility: visible;
   }
   :where(.bp-preflight__chips) {
     display: flex;
@@ -1904,23 +2033,32 @@
     align-items: center;
     gap: 7px;
     cursor: pointer;
-    border: 1px solid var(--bp-ink-faint);
-    border-radius: var(--bp-radius-0);
+    border: 1px solid var(--bp-button-secondary-bd);
+    border-radius: var(--bp-radius-pill);
     padding: 5px 12px;
     font-size: var(--bp-text-small);
-    background: var(--bp-paper);
+    color: var(--bp-button-secondary-fg);
+    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),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
   }
   :where(.bp-preflight__chip:hover) {
-    border-color: var(--bp-ink-line);
+    border-color: var(--bp-button-secondary-bd);
+    background: var(--bp-button-tertiary-bg-hover);
   }
   :where(.bp-preflight__chip) :where(input) {
     accent-color: var(--bp-ink);
     margin: 0;
   }
   :where(.bp-preflight__chip:has(input:checked)) {
-    background: var(--bp-ink);
-    color: var(--bp-paper);
-    border-color: var(--bp-ink);
+    background: var(--bp-button-primary-bg);
+    color: var(--bp-button-primary-fg);
+    border-color: var(--bp-button-primary-bg);
+  }
+  :where(.bp-preflight__chip:has(input:checked)) :where(input) {
+    accent-color: var(--bp-button-primary-fg);
   }
   :where(.bp-preflight__gate) {
     margin: var(--bp-space-3);
@@ -1949,17 +2087,37 @@
     display: inline-flex;
     align-items: center;
     gap: 8px;
-    border: 1px solid var(--bp-ink);
-    border-radius: var(--bp-radius-0);
+    border: 1px solid var(--bp-button-primary-bg);
+    border-radius: var(--bp-radius-pill);
     padding: 8px 16px;
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-md);
-    letter-spacing: var(--bp-label-md-ls);
-    text-transform: uppercase;
-    background: var(--bp-ink);
-    color: var(--bp-paper);
+    font-family: var(--bp-sans);
+    font-size: var(--bp-text-small);
+    line-height: var(--bp-lh-control);
+    background: var(--bp-button-primary-bg);
+    color: var(--bp-button-primary-fg);
     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),
+      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;
@@ -1972,17 +2130,45 @@
   :where(.bp-choice-record) {
     margin: var(--bp-space-4) 0;
   }
-  :where(.bp-choice-record__row) {
+  /* One Obvious container card per row: the host carries border and paper
+     fill; radius + overflow come from the [data-bp-rendered] mat rule above. */
+  :where(bp-choice-record-row) {
+    display: block;
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-0);
+    background-color: var(--bp-paper);
+  }
+  :where(bp-choice-record-row + bp-choice-record-row) {
+    margin-top: var(--bp-space-2);
+  }
+  :where(.bp-choice-record__row) {
+    margin: 0;
+    border: 0;
+    border-radius: 0;
+    background-color: oklch(0 0 0 / 0);
     padding: var(--bp-space-2) var(--bp-space-3);
     display: grid;
     grid-template-columns: minmax(8rem, 14rem) 1fr auto;
     gap: var(--bp-space-2) var(--bp-space-3);
     align-items: baseline;
   }
-  :where(.bp-choice-record__row + .bp-choice-record__row) {
-    margin-top: var(--bp-space-2);
+  :where(bp-choice-record-row:has(.bp-choice__compare)) :where(.bp-choice-record__row) {
+    border-bottom: 1px solid var(--bp-edge);
+  }
+  /* Compare sits flush in the card: drop the base compare top-margin and the
+     standalone compare card chrome (border / radius) used in gallery layout.
+     Wins over the base :where(.bp-choice__compare) rule by source order — no
+     !important, since the record row no longer carries a JS inline margin. */
+  :where(bp-choice-record-row) :where(.bp-choice__compare) {
+    margin: 0;
+    border: 0;
+    border-radius: 0;
+    padding: 0;
+  }
+  :where(bp-choice-record-row) :where(.bp-choice__compare > summary) {
+    background-color: var(--bp-fill-amb);
+  }
+  :where(bp-choice-record-row) :where(.bp-choice__compare > summary:hover) {
+    background-color: var(--bp-fill-hi);
   }
   :where(.bp-choice-record__row) :where(dt) {
     font-family: var(--bp-mono);
@@ -2485,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);
@@ -2626,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;
@@ -2639,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;
@@ -2657,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;
@@ -2683,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);
@@ -2730,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);
@@ -2741,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);
@@ -4058,6 +4243,119 @@
   }
 }
 
+/* =====================================================================
+   @layer components — drafting board: interactive surfaces sit on a dot
+   mat. Last in the layer so its surface overrides win by source order.
+   ===================================================================== */
+@layer components {
+  /* The interactive component family (choice, preflight, choice-record,
+     source, mock, gallery) gets a dot-grid backdrop + a padding "mat", so a
+     live/interactive block reads as a working surface distinct from settled
+     prose — a second axis beside the Obvious pill vocabulary, one that marks
+     even the non-decision interactive surfaces. The host is the mat (board
+     shows in its padding and any internal gaps); the rendered root inside is
+     the solid card. */
+  :where(bp-choice, bp-preflight, bp-choice-record, bp-source, bp-mock, bp-gallery) {
+    display: block;
+    margin: var(--bp-space-4) 0;
+    padding: var(--bp-space-5);
+    background-color: var(--bp-board-bg);
+    background-image: var(--bp-board);
+    background-size: var(--bp-board-gap) var(--bp-board-gap);
+  }
+  /* Once upgraded, every dotted-mat host rounds to the Obvious container
+     radius. data-bp-rendered is the uniform runtime hook — all interactive
+     hosts set it on connect. bp-rationale also carries the flag but is not
+     a mat host and is excluded from this selector list. */
+  :where(
+    bp-choice,
+    bp-preflight,
+    bp-choice-record,
+    bp-choice-record-row,
+    bp-source,
+    bp-mock,
+    bp-gallery
+  )[data-bp-rendered="1"] {
+    border-radius: var(--bp-radius-8);
+    overflow: hidden;
+  }
+  /* The rendered root owns no outer margin now — the host carries document
+     rhythm — so the mat reads even on all four sides. */
+  :where(.bp-choice, .bp-choice-record, .bp-source, .bp-mock, .bp-gallery),
+  :where(bp-preflight) :where(.bp-preflight) {
+    margin: 0;
+  }
+  /* Expanded mock floats fullscreen (position: fixed): collapse the host so
+     no empty dotted mat is left behind in the document flow. */
+  :where(bp-mock:has(.bp-mock.is-expanded)) {
+    margin: 0;
+    padding: 0;
+  }
+
+  /* Single-surface specimens read as ONE continuous paper card on the mat;
+     give each an opaque paper fill (source inherits a translucent
+     --bp-fill-amb from <details>, which would let the dots bleed through). */
+  :where(.bp-choice--tabs, .bp-preflight, .bp-source, .bp-gallery) {
+    background-color: var(--bp-paper);
+  }
+
+  /* Multi-card layouts (stack / gallery / resolved / record) stay transparent
+     so the host board shows in their gaps; each card carries its own paper.
+     Chosen / resolved cards swap paper for a translucent fill — restore an
+     opaque paper base so the board can't bleed through the card. */
+  :where(.bp-choice__card:has(.bp-choice__pick:checked)),
+  :where(.bp-choice__card[data-resolved]) {
+    background-color: var(--bp-paper);
+    background-image: linear-gradient(var(--bp-fill-amb), var(--bp-fill-amb));
+  }
+  /* Rejected / set-aside cards use opacity, so the whole card (incl. its
+     hatch) goes translucent and the board bleeds through. Keep the set-aside
+     read via hatch + tag, not element opacity. */
+  :where(
+    .bp-choice--stack:has(.bp-choice__pick:checked)
+      .bp-choice__card:not(:has(.bp-choice__pick:checked)),
+    .bp-choice--resolved .bp-choice__card:not([data-resolved])
+  ) {
+    opacity: 1;
+    background-color: var(--bp-paper);
+    background-image: var(--bp-hatch);
+  }
+  :where(
+    .bp-choice--gallery:has(.bp-choice__pick:checked)
+      .bp-choice__mock:not(:has(.bp-choice__pick:checked))
+  ) {
+    opacity: 1;
+  }
+  :where(
+    .bp-choice--gallery:has(.bp-choice__pick:checked)
+      .bp-choice__mock:not(:has(.bp-choice__pick:checked))
+      .bp-choice__mock-frame
+  ) {
+    background-color: var(--bp-paper);
+    background-image: var(--bp-hatch);
+  }
+
+  /* The compare disclosure sits between transparent siblings (gallery /
+     record); make it an opaque paper card so the dots stop at its edge. */
+  :where(.bp-choice__compare) {
+    background-color: var(--bp-paper);
+  }
+
+  /* Action footers (hint + reset): machine-voice mono directly on the dots is
+     hard to read. A paper strip with a top hairline keeps the gap above as
+     board; horizontal padding matches the content inset above. Tabs already
+     sit on their own paper panel, so skip them. */
+  :where(.bp-choice--stack, .bp-choice--gallery, .bp-choice--resolved) :where(.bp-choice__actions),
+  :where(.bp-preflight__footer) {
+    background-color: var(--bp-paper);
+    padding: var(--bp-board-footer-pad-y) var(--bp-board-footer-pad-x);
+    border-top: var(--bp-stroke) solid var(--bp-edge);
+  }
+  :where(.bp-choice--stack, .bp-choice--gallery, .bp-choice--resolved) :where(.bp-choice__actions) {
+    --bp-board-footer-pad-x: var(--bp-space-3);
+  }
+}
+
 /* =====================================================================
    @layer utilities — last-resort single-purpose helpers + responsive
    ===================================================================== */
@@ -4162,7 +4460,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);
     }
@@ -4429,11 +4727,12 @@ body > .site-nav .site-nav__theme:hover {
    read as one control family (border, radius, surface + hover/focus states). */
 .sidebar-field {
   border: 1px solid var(--bp-edge);
-  border-radius: var(--bp-radius-6, 6px);
+  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 {
@@ -4441,7 +4740,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;
@@ -4460,7 +4765,7 @@ body > .site-nav .site-nav__theme:hover {
   display: none;
 }
 .doc-switcher__current::before {
-  content: none !important;
+  content: none;
 }
 .doc-switcher__label {
   display: flex;
@@ -4497,7 +4802,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;
@@ -4524,7 +4829,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 {
@@ -4566,6 +4871,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;
@@ -4632,8 +5061,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.
@@ -4679,17 +5108,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 {
@@ -4736,12 +5165,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);
@@ -4757,12 +5189,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;
@@ -4776,13 +5207,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);
@@ -4793,22 +5242,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;
@@ -4828,8 +5277,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;
 }
@@ -4838,64 +5294,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__actions {
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
 }
-.docs-search__keys {
+.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__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__key {
+.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
@@ -5018,7 +5520,7 @@ body > .site-nav .site-nav__theme:hover {
   height: var(--bp-theme-toggle-height);
   padding: 2px;
   border: 1px solid var(--bp-edge);
-  border-radius: var(--bp-radius-6, 6px);
+  border-radius: var(--bp-radius-pill);
   background: var(--bp-fill-amb);
   color: var(--bp-text-secondary);
   cursor: pointer;
@@ -5044,7 +5546,7 @@ body > .site-nav .site-nav__theme:hover {
   width: calc(var(--bp-theme-toggle-height) - 6px);
   height: calc(var(--bp-theme-toggle-height) - 6px);
   border: 1px solid var(--bp-ink-line);
-  border-radius: var(--bp-radius-4, 4px);
+  border-radius: var(--bp-radius-round);
   background: var(--bp-paper);
   box-shadow: 0 1px 2px oklch(0 0 0 / 0.06);
   pointer-events: none;
@@ -5092,7 +5594,7 @@ body > .site-nav .site-nav__theme:hover {
   height: var(--bp-sidebar-toggle-size);
   padding: 0;
   border: 1px solid var(--bp-edge);
-  border-radius: var(--bp-radius-6, 6px);
+  border-radius: var(--bp-radius-pill);
   background: var(--bp-fill-amb);
   color: var(--bp-text-secondary);
   cursor: pointer;
@@ -5170,7 +5672,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). */
@@ -5227,7 +5749,7 @@ body > .site-nav .site-nav__theme:hover {
 
   /* Fade scrim above the footer: the TOC scrolls out beneath it (z below the
      footer controls), with a solid bottom band backing the footer. */
-  .bp-sidebar::after {
+  #bp-contents-rail::after {
     content: "";
     position: fixed;
     left: 0;
@@ -5242,7 +5764,7 @@ body > .site-nav .site-nav__theme:hover {
   /* Radial scrim around the corner toggle: the TOC dissolves in a circle that
      radiates from the icon as entries scroll up beneath it. The box is large
      enough to hold the gradient's outer radius; transparent beyond it. */
-  .bp-sidebar::before {
+  #bp-contents-rail::before {
     content: "";
     position: fixed;
     top: 0;
@@ -5261,12 +5783,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 {
@@ -5407,7 +6071,7 @@ html[data-bp-document]:has(.bp-cite-pane.is-open) main {
   height: var(--bp-sidebar-toggle-size);
   padding: 0;
   border: var(--bp-stroke) solid var(--bp-edge);
-  border-radius: var(--bp-radius-6);
+  border-radius: var(--bp-radius-pill);
   background: var(--bp-fill-amb);
   color: var(--bp-text-secondary);
   cursor: pointer;