@obvi/blueprint 1.0.10 → 1.1.1

package/dist/blueprint.css

@@ -182,8 +182,14 @@
     --bp-hatch: repeating-linear-gradient(
       -45deg,
       var(--bp-ink-faint) 0 var(--bp-stroke),
-      transparent var(--bp-stroke) var(--bp-hatch-gap)
+      oklch(0 0 0 / 0) var(--bp-stroke) var(--bp-hatch-gap)
     );
+    /* 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:
+         background-color: var(--bp-scrim);
+         background-image: var(--bp-hatch); */
+    --bp-scrim: oklch(0 0 0 / 0.58);
     --bp-edge: var(--obvious-border-subtle, oklch(0 0 0 / 0.08));
     --bp-ink-line: var(--obvious-border-default, oklch(0 0 0 / 0.16));
     --bp-text: var(--obvious-text-primary, oklch(0 0 0 / 0.92));
@@ -322,6 +328,7 @@
     --bp-duration-normal: 200ms;
     --bp-duration-slow: 300ms;
     --bp-duration-deliberate: 450ms;
+    --bp-duration-spin: 1.4s; /* constant rotation (marquees, loading glyphs) */
 
     /* Easing — strong curves only; never ease-in for UI (its slow start delays
        feedback and feels sluggish).
@@ -358,6 +365,7 @@
     /* Neutral white-alpha panel fills over the dark paper. */
     --bp-fill-amb: oklch(1 0 0 / 0.04);
     --bp-fill-hi: oklch(1 0 0 / 0.08);
+    --bp-scrim: oklch(1 0 0 / 0.58);
     --bp-paper: var(--bp-gray-950);
     --bp-bg: oklch(0.15 0 0); /* the desk sits darker than the sheet, so the page lifts */
     --bp-edge: oklch(1 0 0 / 0.08);
@@ -430,6 +438,19 @@
     -moz-osx-font-smoothing: grayscale;
     counter-reset: bp-sec bp-fig bp-fn;
   }
+
+  /* Theme crossfade — View Transitions capture one old/new snapshot of the
+     document and the compositor crossfades them in a single pass. Per-element
+     color transitions on a token flip fight the cascade (thousands of
+     mismatched 150ms/200ms tweens, pseudo-elements snapping mid-fade, and
+     transitions cut off when an animate flag clears). blueprint.js wraps theme
+     flips in startViewTransition(); reduced motion is handled globally in
+     @layer reset. Pseudo-elements can't live in :where(); same rule here. */
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation-duration: var(--bp-duration-normal);
+    animation-timing-function: var(--bp-ease-out);
+  }
   /* Pseudo-elements can't live inside :where()/:is() — Chromium (incl. Dia)
      and Firefox drop the whole rule. Keep these as plain selectors, and
      split ::selection / ::-moz-selection so one invalid token doesn't
@@ -451,8 +472,8 @@
     padding: var(--bp-space-6);
   }
 
-  /* Section rhythm + automatic "01 / 02" eyebrow counter before each h2.
-     The counter is keyed to <section>, so reordering renumbers for free. */
+  /* Section rhythm — primary section eyebrows are injected by blueprint.js
+     on h2[data-sidebar]; nested sections without data-sidebar stay plain. */
   :where(section) {
     counter-increment: bp-sec;
   }
@@ -470,6 +491,38 @@
     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;
+  }
+  :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;
+  }
+  /* Navigation GROUP divider — every repeated <header> after the masthead.
+     It reuses the masthead structure (eyebrow + h1 + optional <bp-subheader>)
+     and reads as a calm "part" break: a hairline above and generous rhythm,
+     so the document splits into labelled groups that the runtime mirrors as
+     eyebrows in the contents rail. */
+  :where(main > header:not(:first-child)) {
+    margin: calc(var(--bp-space-7) + var(--bp-space-5)) 0 0;
+    padding-top: var(--bp-space-6);
+    border-top: 1px solid var(--bp-edge);
+  }
+  :where(main > header:not(:first-child) > h1) {
+    margin: 0 0 var(--bp-space-2);
+  }
+  :where(bp-toc) {
+    display: block;
+  }
   :where(h2) {
     font-family: var(--bp-sans);
     font-size: var(--bp-text-h2);
@@ -480,12 +533,10 @@
     scroll-margin-top: var(--bp-space-4);
     text-wrap: var(--bp-wrap-heading);
   }
-  /* Section-scoped eyebrow: "01", "02"… rendered above each section's h2.
-     A solid ink square leads the counter, set off by --bp-marker-gap. The
-     square is a left-anchored background so it stays a single pseudo-element
-     (no extra node) and centers vertically against the label line. */
-  :where(section > h2:first-child)::before,
-  :where(section > hgroup:first-child > h2)::before {
+  /* Legacy section-scoped eyebrow for pages without blueprint.js. Authored
+     h2[data-sidebar] headings get .bp-heading-eyebrow from the runtime. */
+  :where(section > h2:first-child:not([data-sidebar]):not(:has(.bp-heading-eyebrow)))::before,
+  :where(section > hgroup:first-child > h2:not([data-sidebar]):not(:has(.bp-heading-eyebrow)))::before {
     content: counter(bp-sec, decimal-leading-zero);
     display: block;
     width: max-content;
@@ -539,8 +590,8 @@
     text-wrap: var(--bp-wrap-body);
   }
   /* Lede-by-position was removed — a paragraph following a heading should
-     render as ordinary body type. Use .bp-lede explicitly when you want
-     the narrative lead-in treatment. */
+     render as ordinary body type. Use <bp-subheader> explicitly when you
+     want the narrative lead-in treatment. */
   :where(ul, ol) {
     margin: 0 0 1.2em;
     padding-left: 1.3em;
@@ -785,7 +836,7 @@
     background: var(--bp-fill-amb);
     padding: 2px 5px;
     color: var(--bp-ink);
-    border-radius: var(--bp-radius-2);
+    border-radius: var(--bp-radius-0);
   }
   :where(pre) {
     font-family: var(--bp-mono);
@@ -810,7 +861,7 @@
     background: var(--bp-paper);
     border: 1px solid var(--bp-ink-line);
     border-bottom-width: 2px;
-    border-radius: var(--bp-radius-2);
+    border-radius: var(--bp-radius-0);
     padding: 1px 5px;
     color: var(--bp-text);
   }
@@ -944,13 +995,22 @@
   :where(summary)::-webkit-details-marker {
     display: none;
   }
+  /* Disclosure caret — Iconoir nav-arrow-right, inlined as a mask so every
+     native <summary> stays JS-free and inherits ink via currentColor. */
   :where(summary)::before {
     content: "";
-    width: 0;
-    height: 0;
-    border-left: 5px solid var(--bp-ink);
-    border-top: 4px solid transparent;
-    border-bottom: 4px solid transparent;
+    flex-shrink: 0;
+    width: 16px;
+    height: 16px;
+    background-color: var(--bp-ink);
+    -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M9 6L15 12L9 18'/%3E%3C/svg%3E");
+    mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M9 6L15 12L9 18'/%3E%3C/svg%3E");
+    -webkit-mask-size: contain;
+    mask-size: contain;
+    -webkit-mask-repeat: no-repeat;
+    mask-repeat: no-repeat;
+    -webkit-mask-position: center;
+    mask-position: center;
     /* Motion: .bp-transition-transform .bp-ease (disclosure caret rotate) */
     transition-property: transform;
     transition-duration: var(--bp-duration-fast);
@@ -967,7 +1027,65 @@
   :where(a, button, summary, [tabindex]):focus-visible {
     outline: 2px solid var(--bp-ink);
     outline-offset: 3px;
-    border-radius: var(--bp-radius-2);
+    border-radius: var(--bp-radius-0);
+  }
+
+  /* Squared checkbox. Native checkboxes render with rounded corners that
+     border-radius cannot override, so reset appearance and draw the box: a
+     paper square with an Iconoir check tick (mask-inlined, same glyph as the
+     heading permalink copied state). Paper fill + ink tick stay legible
+     whether the control sits on paper or an inked chip. Radios keep their
+     native round rendering — a square radio reads as a checkbox. */
+  :where(input[type="checkbox"]) {
+    appearance: none;
+    -webkit-appearance: none;
+    flex: none;
+    display: inline-grid;
+    place-items: center;
+    inline-size: 1em;
+    block-size: 1em;
+    border: 1px solid var(--bp-ink-line);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    cursor: pointer;
+    /* Motion: .bp-transition-colors (border + fill settle on toggle) */
+    transition-property: border-color, background;
+    transition-duration: var(--bp-duration-fast);
+    transition-timing-function: var(--bp-ease-out);
+  }
+  :where(input[type="checkbox"])::before {
+    content: "";
+    inline-size: 0.7em;
+    block-size: 0.7em;
+    background-color: var(--bp-ink);
+    /* Iconoir check — same glyph as heading permalink copied state. */
+    -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 13L9 17L19 7'/%3E%3C/svg%3E");
+    mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 13L9 17L19 7'/%3E%3C/svg%3E");
+    -webkit-mask-size: contain;
+    mask-size: contain;
+    -webkit-mask-repeat: no-repeat;
+    mask-repeat: no-repeat;
+    -webkit-mask-position: center;
+    mask-position: center;
+    transform: scale(0);
+    transform-origin: center;
+    /* Motion: tick draws in as the box is checked */
+    transition: transform var(--bp-duration-fast) var(--bp-ease-out);
+  }
+  :where(input[type="checkbox"]:checked) {
+    border-color: var(--bp-ink);
+  }
+  :where(input[type="checkbox"]:checked)::before {
+    transform: scale(1);
+  }
+  :where(input[type="checkbox"]:disabled) {
+    opacity: 0.4;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+  :where(input[type="checkbox"]:focus-visible) {
+    outline: 2px solid var(--bp-ink);
+    outline-offset: 3px;
   }
 }
 
@@ -987,37 +1105,51 @@
    ===================================================================== */
 @layer components {
 
-  /* ---- Narrative lede (explicit opt-in) ---------------------------
-     A lede must be asked for — apply .bp-lede to any paragraph
-     that should read as the narrative lead-in. Lede-by-position (the
-     old automatic `section > h2 + p` rule) was removed; a paragraph
-     following a heading is now ordinary body type unless classed. */
-  :where(.bp-lede) {
+  /* ---- Narrative lede — <bp-subheader> ----------------------------
+     A lede must be asked for — wrap a lead-in paragraph in <bp-subheader>
+     so it reads as the narrative opener. Lede-by-position (the old
+     automatic `section > h2 + p` rule) was removed; a paragraph following
+     a heading is ordinary body type unless it is a <bp-subheader>. */
+  :where(bp-subheader) {
+    display: block;
+    margin: 0 0 1.2em;
     font-size: var(--bp-text-lede);
     line-height: var(--bp-lh-lede);
     color: var(--bp-text);
   }
 
-  /* ---- Section heading permalink ------------------------------------
-     Injected by blueprint.js: pixelarticons sit in the main-column gutter
-     (left of the title, no text shift). Link on heading hover, copy on icon
-     hover, check after a successful copy. */
-  :where(h2:has(.bp-heading-row)) {
+  /* ---- Section heading permalink + eyebrow --------------------------------
+     Injected by blueprint.js on headings with data-sidebar: a numbered eyebrow
+     on primary (h2) sections, plus a gutter permalink on every opted-in level.
+     Link on heading hover, copy on icon hover, check after a successful copy. */
+  :where(.bp-heading-eyebrow) {
+    display: block;
+    width: max-content;
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-lg);
+    font-weight: var(--bp-weight-medium);
+    letter-spacing: 0.18em;
+    color: var(--bp-ink);
+    padding-left: calc(var(--bp-marker-size) + var(--bp-marker-gap));
+    background: linear-gradient(var(--bp-ink), var(--bp-ink)) left center / var(--bp-marker-size) var(--bp-marker-size) no-repeat;
+    margin-bottom: var(--bp-space-2);
+  }
+  :where(:is(h2, h3, h4, h5, h6):has(.bp-heading-row)) {
     position: relative;
   }
   /* Invisible bridge from the title into the gutter so the icon stays
-     reachable while the pointer crosses the gap outside h2's border box. */
-  :where(h2:has(.bp-heading-row))::after {
+     reachable while the pointer crosses the gap outside the heading box. */
+  :where(:is(h2, h3, h4, h5, h6):has(.bp-heading-row))::after {
     content: "";
     position: absolute;
     left: calc(-1 * (16px + var(--bp-space-2)));
     bottom: 0;
     z-index: 0;
     width: calc(16px + var(--bp-space-2) + var(--bp-space-3));
-    height: var(--bp-lh-h2);
+    height: 1.2em;
     pointer-events: none;
   }
-  :where(h2:is(:hover, :focus-within, [data-heading-link="visible"]):has(.bp-heading-row))::after {
+  :where(:is(h2, h3, h4, h5, h6):is(:hover, :focus-within, [data-heading-link="visible"]):has(.bp-heading-row))::after {
     pointer-events: auto;
   }
   :where(.bp-heading-row) {
@@ -1043,7 +1175,7 @@
     margin: 0;
     padding: 0;
     border: 0;
-    background: transparent;
+    background: oklch(0 0 0 / 0);
     color: var(--bp-ink-soft);
     cursor: pointer;
     opacity: 0;
@@ -1069,21 +1201,20 @@
     inset: 0;
     display: block;
     opacity: 0;
-    image-rendering: pixelated;
     transition: opacity var(--bp-duration-fast) var(--bp-ease-out);
   }
-  :where(h2:hover .bp-heading-link),
-  :where(h2:focus-within .bp-heading-link),
-  :where(h2[data-heading-link="visible"] .bp-heading-link),
+  :where(:is(h2, h3, h4, h5, h6):hover .bp-heading-link),
+  :where(:is(h2, h3, h4, h5, h6):focus-within .bp-heading-link),
+  :where(:is(h2, h3, h4, h5, h6)[data-heading-link="visible"] .bp-heading-link),
   :where(button.bp-heading-link:focus-visible),
   :where(button.bp-heading-link[data-bp-copy-state="copied"]),
   :where(button.bp-heading-link[data-bp-copy-state="error"]) {
     opacity: 1;
     pointer-events: auto;
   }
-  :where(h2:hover .bp-heading-link__icon--link),
-  :where(h2:focus-within .bp-heading-link__icon--link),
-  :where(h2[data-heading-link="visible"] .bp-heading-link__icon--link),
+  :where(:is(h2, h3, h4, h5, h6):hover .bp-heading-link__icon--link),
+  :where(:is(h2, h3, h4, h5, h6):focus-within .bp-heading-link__icon--link),
+  :where(:is(h2, h3, h4, h5, h6)[data-heading-link="visible"] .bp-heading-link__icon--link),
   :where(button.bp-heading-link:focus-visible .bp-heading-link__icon--link) {
     opacity: 1;
   }
@@ -1110,14 +1241,19 @@
   :where(button.bp-heading-link:focus-visible) {
     outline: 2px solid var(--bp-ink);
     outline-offset: 2px;
-    border-radius: var(--bp-radius-2);
+    border-radius: var(--bp-radius-0);
   }
   :where(button.bp-heading-link[data-bp-copy-state="error"]) {
     color: var(--bp-ink-soft);
   }
 
-  /* ---- Eyebrow / label / meta — the mono-label family -------------- */
-  :where(.bp-eyebrow, .bp-label) {
+  /* ---- Mono micro-label family — <bp-eyebrow> + internal aliases -----
+     <bp-eyebrow> is a short uppercase kicker line that heads the block
+     beneath it. Default is ink; add the [muted] attribute for quiet
+     metadata or provenance. The legacy .bp-eyebrow / .bp-label classes
+     are the same ink role, and .bp-meta the muted role — all kept only
+     for runtime-injected chrome and choice internals, not authoring. */
+  :where(bp-eyebrow, .bp-eyebrow, .bp-label) {
     display: block;
     font-family: var(--bp-mono);
     font-size: var(--bp-label-md);
@@ -1126,212 +1262,28 @@
     color: var(--bp-ink);
     margin-bottom: var(--bp-space-2);
   }
-  :where(.bp-meta) {
-    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);
-  }
-  :where(.bp-note) {
+  :where(bp-eyebrow[muted]) {
     color: var(--bp-text-secondary);
   }
-
-  /* ---- 1. Decision panel ------------------------------------------
-     The single load-bearing decision, given more weight than a routine
-     callout. An inverted masthead band carries the kicker, an optional
-     status pill, and optional provenance (decider + <time>); the headline
-     statement is the typographic hero; stacked tenets explain it; and a
-     distinct hatched footer states the condition for revisiting it. Every
-     part but the statement is optional. Markup:
-       <section class="bp-decision">
-         <header class="bp-decision__bar">
-           <span class="bp-label">Decision</span>
-           <span class="bp-decision__status">Locked</span>
-           <p class="bp-decision__meta">Obvious · <time datetime="2026-06-16">16 Jun 2026</time></p>
-         </header>
-         <div class="bp-decision__body">
-           <p class="bp-decision-stmt">…the headline…</p>
-           <dl class="bp-decision__tenets"> <dt>Holds because</dt><dd>…</dd> … </dl>
-         </div>
-         <p class="bp-decision__revisit"><b>Revisit when</b> …</p>
-       </section> */
-  :where(.bp-decision) {
-    border: 1px solid var(--bp-ink);
-    border-radius: var(--bp-radius-6);
-    background: var(--bp-paper);
-    overflow: hidden;
-    margin: var(--bp-space-4) 0;
-  }
-  /* Inverted masthead band: kicker left, status pill, provenance pushed
-     right. Paper-on-ink, so it flips with the theme like the doc band. */
-  :where(.bp-decision__bar) {
-    display: flex;
-    align-items: center;
-    gap: var(--bp-space-2);
-    padding: var(--bp-space-2) var(--bp-space-3);
-    background: var(--bp-ink);
-    color: var(--bp-paper);
-  }
-  :where(.bp-decision__bar) > :where(.bp-label) {
-    margin: 0;
-    color: var(--bp-paper);
-    font-size: var(--bp-label-lg);
-    letter-spacing: var(--bp-label-lg-ls);
-    font-weight: var(--bp-weight-medium);
-  }
-  :where(.bp-decision__status) {
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-sm);
-    letter-spacing: var(--bp-label-sm-ls);
-    text-transform: uppercase;
-    border: 1px solid color-mix(in oklch, var(--bp-paper) 45%, transparent);
-    border-radius: var(--bp-radius-pill);
-    padding: 1px 8px;
-  }
-  :where(.bp-decision__meta) {
-    margin: 0 0 0 auto;
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-md);
-    letter-spacing: var(--bp-label-md-ls);
-    text-transform: uppercase;
-    color: color-mix(in oklch, var(--bp-paper) 72%, transparent);
-    text-align: right;
-  }
-  :where(.bp-decision__meta) :where(time) {
-    color: color-mix(in oklch, var(--bp-paper) 90%, transparent);
-  }
-  :where(.bp-decision__body) {
-    padding: var(--bp-space-4) var(--bp-space-4) var(--bp-space-4);
-  }
-  :where(.bp-decision-stmt) {
-    font-family: var(--bp-sans);
-    font-size: var(--bp-text-title);
-    font-weight: var(--bp-weight-strong);
-    letter-spacing: -0.48px;
-    line-height: var(--bp-lh-title);
-    color: var(--bp-text);
-    margin: 0;
-    text-wrap: balance;
-  }
-  /* Stacked tenets — mono label ABOVE its value (no stranded label column),
-     so several points stay aligned to the left margin and read cleanly. */
-  :where(.bp-decision__tenets) {
-    display: block;
-    margin: var(--bp-space-3) 0 0;
-    padding: 0;
-  }
-  :where(.bp-decision__tenets) > :where(dt) {
+  :where(.bp-meta) {
     font-family: var(--bp-mono);
     font-size: var(--bp-label-md);
-    font-weight: var(--bp-weight-body);
     letter-spacing: var(--bp-label-md-ls);
     text-transform: uppercase;
     color: var(--bp-text-secondary);
-    padding: 0;
-    margin: 0 0 var(--bp-space-1);
-  }
-  :where(.bp-decision__tenets) > :where(dt ~ dt) {
-    margin-top: var(--bp-space-3);
   }
-  :where(.bp-decision__tenets) > :where(dd) {
-    color: var(--bp-text);
-    font-size: var(--bp-text-body);
-    line-height: var(--bp-lh-body);
-    margin: 0;
+  /* Quiet subordinate paragraph — <bp-note> for authored asides/caveats.
+     .bp-note is the same role kept for runtime-injected chrome. */
+  :where(bp-note) {
+    display: block;
+    margin: 0 0 1.2em;
   }
-  /* Change condition — a distinct hatched footer (drafting "subject to
-     revision" texture). Tight, flush to the panel's bottom edge. */
-  :where(.bp-decision__revisit) {
-    display: flex;
-    align-items: baseline;
-    gap: var(--bp-space-2);
-    margin: 0;
-    padding: var(--bp-space-2) var(--bp-space-4);
-    border-top: 1px solid var(--bp-edge);
-    background-image: var(--bp-hatch);
-    font-size: var(--bp-text-small);
-    line-height: var(--bp-lh-small);
+  :where(bp-note, .bp-note) {
     color: var(--bp-text-secondary);
   }
-  :where(.bp-decision__revisit) > :where(b) {
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-md);
-    font-weight: var(--bp-weight-body);
-    letter-spacing: var(--bp-label-md-ls);
-    text-transform: uppercase;
-    color: var(--bp-ink);
-    white-space: nowrap;
-  }
-
-  /* ---- 1b. Collapsible decision -----------------------------------
-     A <details> variant for pages that carry several decisions. Collapsed,
-     the whole panel is just the inverted bar — the decision reads on the
-     left (compact, not hero scale), provenance on the right. Expanding
-     drops the tenets and the revisit footer below the same bar. No JS —
-     native disclosure. Markup:
-       <details class="bp-decision bp-decision--collapsible">
-         <summary class="bp-decision__bar">
-           <span class="bp-label">Decision</span>
-           <span class="bp-decision__title">…the decision…</span>
-           <span class="bp-decision__meta">Obvious · <time …>…</time></span>
-           <span class="bp-decision__caret" aria-hidden="true"></span>
-         </summary>
-         <dl class="bp-decision__tenets"> … </dl>
-         <p class="bp-decision__revisit"> … </p>
-       </details> */
-  :where(.bp-decision--collapsible) {
-    padding: 0;
-  }
-  /* The summary IS the bar — clicking it toggles the disclosure. */
-  :where(.bp-decision--collapsible) > :where(summary) {
-    cursor: pointer;
-    list-style: none;
-    gap: var(--bp-space-3);
-  }
-  :where(.bp-decision--collapsible) > :where(summary)::-webkit-details-marker {
-    display: none;
-  }
-  /* Suppress the global <summary> caret; this variant carries its own. */
-  :where(.bp-decision--collapsible) > :where(summary)::before {
-    content: none;
-  }
-  /* The decision itself, compact (not hero scale), sits left of the meta. */
-  :where(.bp-decision__title) {
-    min-width: 0;
-    font-family: var(--bp-sans);
-    font-size: var(--bp-text-h4);
-    font-weight: var(--bp-weight-strong);
-    letter-spacing: -0.2px;
-    line-height: var(--bp-lh-h4);
-    color: var(--bp-paper);
-  }
-  :where(.bp-decision--collapsible) :where(.bp-decision__meta) {
-    margin-right: 0;
-  }
-  /* Caret rides at the far right and rotates open. */
-  :where(.bp-decision__caret) {
-    flex: 0 0 auto;
-    width: 0;
-    height: 0;
-    border-left: 5px solid currentColor;
-    border-top: 4px solid transparent;
-    border-bottom: 4px solid transparent;
-    transition: transform var(--bp-duration-fast) var(--bp-ease);
-  }
-  /* No meta? Caret takes the auto margin so it still parks on the right. */
-  :where(.bp-decision--collapsible) :where(.bp-decision__bar):not(:has(.bp-decision__meta)) :where(.bp-decision__caret) {
-    margin-left: auto;
-  }
-  :where(.bp-decision--collapsible[open]) :where(.bp-decision__caret) {
-    transform: rotate(90deg);
-  }
-  :where(.bp-decision--collapsible) > :where(.bp-decision__tenets) {
-    padding: var(--bp-space-4) var(--bp-space-4) var(--bp-space-3);
-  }
 
   /* ---- 2. Typed callout family ------------------------------------
-     A coherent callout family with legible roles, beneath the decision.
+     A coherent callout family with legible roles.
      Drafting-style: instead of a box, four L-shaped registration ticks
      bracket the corners (drawn as layered background gradients — no extra
      DOM), with an icon + mono type label heading the body. The base is
@@ -1351,7 +1303,7 @@
     padding: var(--bp-space-3) var(--bp-space-4);
     margin: var(--bp-space-4) 0;
     color: var(--bp-text);
-    background-color: transparent;
+    background-color: oklch(0 0 0 / 0);
     background-repeat: no-repeat;
     /* 8 solid slivers = 4 corner Ls, then an optional texture fill below. */
     background-image:
@@ -1380,10 +1332,7 @@
   /* Remove trailing margin from the last child of ANY boxed component so
      padding, not stray paragraph space, controls the inner bottom gap. */
   :where(
-    .bp-decision,
     .bp-callout,
-    .bp-option-grid > *,
-    .bp-state-grid > *,
     .bp-sequence > li,
     details
   ) > :last-child {
@@ -1451,41 +1400,10 @@
     grid-template-columns: minmax(10rem, 16rem) 1fr;
   }
 
-  /* ---- 4. Option / comparison grid --------------------------------
-     True parallel comparisons (A / B / C). Equal-column cards built
-     from <article>s, with a role label and an optional verdict pill.
-     Mark the chosen option with .bp-opt--rec. */
-  :where(.bp-option-grid) {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-    gap: 0;
-    border: 1px solid var(--bp-edge);
-    margin: var(--bp-space-4) 0;
-  }
-  :where(.bp-option-grid > *) {
-    padding: var(--bp-space-3);
-    border-right: 1px solid var(--bp-edge);
-    background: var(--bp-paper);
-  }
-  :where(.bp-option-grid > :last-child) {
-    border-right: 0;
-  }
-  :where(.bp-opt--rec) {
-    background: var(--bp-fill-amb);
-    outline: 2px solid var(--bp-ink);
-    outline-offset: -2px;
-  }
-  :where(.bp-verdict) {
-    display: inline-block;
-    font-family: var(--bp-mono);
-    font-size: var(--bp-label-sm);
-    letter-spacing: var(--bp-label-sm-ls);
-    text-transform: uppercase;
-    color: var(--bp-paper);
-    background: var(--bp-ink);
-    padding: 2px 8px;
-    margin-top: var(--bp-space-2);
-  }
+  /* Parallel comparisons and state models are author-composed: a small
+     grid in the document's own <style>, colored from the core tokens (see
+     SKILL "Visual grammar"). Recommendations live in <bp-choice resolved>,
+     not a static grid modifier. */
 
   /* ---- 5. Numbered linear sequence --------------------------------
      A linear mechanism (pipeline, escalation). NOT a comparison grid.
@@ -1518,29 +1436,6 @@
     color: var(--bp-ink);
   }
 
-  /* ---- State grid -------------------------------------------------
-     Off-happy-path state model (empty / loading / ready / error …).
-     Built from <article>s; each gets a mono state name via .bp-label. */
-  :where(.bp-state-grid) {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-    gap: 0;
-    border: 1px solid var(--bp-edge);
-    margin: var(--bp-space-4) 0;
-  }
-  :where(.bp-state-grid > *) {
-    padding: var(--bp-space-3);
-    border-right: 1px solid var(--bp-edge);
-    border-bottom: 1px solid var(--bp-edge);
-    background: var(--bp-paper);
-  }
-  /* Void / fenced-off state — a dead cell (orphaned, reclaimed away).
-     The hatch layers over the paper set above; declared after so the
-     zero-specificity rules resolve by source order. */
-  :where(.bp-state--void) {
-    background-image: var(--bp-hatch);
-  }
-
   /* ---- Hatch utility ----------------------------------------------
      Drop .bp-hatch on any block element to mark a fenced / held /
      out-of-bounds region with drafting section-lining. Layers the hatch
@@ -1573,7 +1468,7 @@
     padding: var(--bp-space-2) var(--bp-space-3);
     background: var(--bp-ink);
     color: var(--bp-paper);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
     margin-bottom: var(--bp-space-3);
   }
   :where(.bp-choice:has(.bp-choice__commit:checked)) .bp-choice__verdict,
@@ -1601,7 +1496,7 @@
     font-size: var(--bp-label-md);
     letter-spacing: var(--bp-label-md-ls);
     text-transform: uppercase;
-    color: color-mix(in oklch, var(--bp-paper) 72%, transparent);
+    color: color-mix(in oklch, var(--bp-paper) 72%, oklch(0 0 0 / 0));
   }
 
   :where(.bp-choice-rationale) {
@@ -1672,7 +1567,7 @@
     flex-wrap: wrap;
     gap: 0;
     border: 1px solid var(--bp-ink-line);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
     overflow: hidden;
     margin: 0 0 var(--bp-space-3);
     width: fit-content;
@@ -1712,7 +1607,7 @@
     gap: 8px;
     cursor: pointer;
     border: 1px solid var(--bp-ink);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
     padding: 6px 14px;
     font-family: var(--bp-mono);
     font-size: var(--bp-label-md);
@@ -1735,7 +1630,7 @@
     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-4);
+    border-radius: var(--bp-radius-0);
   }
   :where(.bp-choice__panel:has(.bp-choice__commit:checked)) :where(.bp-choice__adopt) {
     background: var(--bp-ink);
@@ -1751,7 +1646,7 @@
     display: block;
     position: relative;
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
     padding: var(--bp-space-3);
     cursor: pointer;
     background: var(--bp-paper);
@@ -1796,6 +1691,38 @@
     display: inline-flex;
   }
 
+  /* ---- mode: resolved (non-interactive — the decision is already made) -
+     Same stack visuals, but driven by [data-resolved] instead of :checked:
+     the verdict banner and chosen card are shown statically, the rest read
+     as considered-and-set-aside. No inputs, no reset. */
+  :where(.bp-choice--resolved) :where(.bp-choice__verdict) {
+    display: flex;
+  }
+  :where(.bp-choice--resolved) :where(.bp-choice__verdict-pick[data-resolved]) {
+    display: block;
+  }
+  :where(.bp-choice--resolved) :where(.bp-choice__stack) {
+    display: grid;
+    gap: var(--bp-space-3);
+  }
+  :where(.bp-choice--resolved) :where(.bp-choice__card) {
+    cursor: default;
+  }
+  :where(.bp-choice__card[data-resolved]) {
+    border: 2px solid var(--bp-ink);
+    background: var(--bp-fill-amb);
+  }
+  :where(.bp-choice__card[data-resolved]) :where(.bp-choice__card-chosen) {
+    display: inline-flex;
+  }
+  :where(.bp-choice--resolved) :where(.bp-choice__card:not([data-resolved])) {
+    opacity: 0.62;
+    background-image: var(--bp-hatch);
+  }
+  :where(.bp-choice--resolved) :where(.bp-choice__card:not([data-resolved])) :where(.bp-choice__card-rejected) {
+    display: inline-flex;
+  }
+
   /* ---- layout: gallery (mockup pick) ------------------------------- */
   :where(.bp-choice--gallery) :where(.bp-choice__gallery) {
     display: grid;
@@ -1807,7 +1734,7 @@
     position: relative;
     cursor: pointer;
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
     overflow: hidden;
     background: var(--bp-paper);
   }
@@ -1863,7 +1790,7 @@
   :where(.bp-choice__compare) {
     margin-top: var(--bp-space-3);
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
   }
   :where(.bp-choice__compare > summary) {
     cursor: pointer;
@@ -1886,7 +1813,7 @@
   /* ---- Pre-flight (decisions before drafting) ---------------------- */
   :where(.bp-preflight) {
     border: 1px solid var(--bp-ink-line);
-    border-radius: var(--bp-radius-6);
+    border-radius: var(--bp-radius-0);
     overflow: hidden;
     margin: var(--bp-space-4) 0;
   }
@@ -1908,7 +1835,7 @@
     font-size: var(--bp-label-md);
     letter-spacing: var(--bp-label-md-ls);
     text-transform: uppercase;
-    color: color-mix(in oklch, var(--bp-paper) 78%, transparent);
+    color: color-mix(in oklch, var(--bp-paper) 78%, oklch(0 0 0 / 0));
   }
   :where(.bp-preflight__questions) {
     counter-reset: bp-preflight-q;
@@ -1968,7 +1895,7 @@
     gap: 7px;
     cursor: pointer;
     border: 1px solid var(--bp-ink-faint);
-    border-radius: var(--bp-radius-pill);
+    border-radius: var(--bp-radius-0);
     padding: 5px 12px;
     font-size: var(--bp-text-small);
     background: var(--bp-paper);
@@ -1988,7 +1915,7 @@
   :where(.bp-preflight__gate) {
     margin: var(--bp-space-3);
     border: 1px dashed var(--bp-ink-line);
-    border-radius: var(--bp-radius-6);
+    border-radius: var(--bp-radius-0);
     padding: var(--bp-space-4);
     text-align: center;
     background-image: var(--bp-hatch);
@@ -2013,7 +1940,7 @@
     align-items: center;
     gap: 8px;
     border: 1px solid var(--bp-ink);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
     padding: 8px 16px;
     font-family: var(--bp-mono);
     font-size: var(--bp-label-md);
@@ -2037,7 +1964,7 @@
   }
   :where(.bp-choice-record__row) {
     border: 1px solid var(--bp-edge);
-    border-radius: var(--bp-radius-4);
+    border-radius: var(--bp-radius-0);
     padding: var(--bp-space-2) var(--bp-space-3);
     display: grid;
     grid-template-columns: minmax(8rem, 14rem) 1fr auto;
@@ -2080,30 +2007,161 @@
     margin-inline: max(calc(50% - 50vw), calc((100% - var(--bp-wide)) / 2));
   }
 
-  /* ---- Source disclosure -------------------------------------------
-     A reusable source-code panel. The semantic shell is a native <details>;
-     authors provide the explicit language/copy toolbar, blueprint-code.js
-     enables the copy button, and blueprint-code.css adds Prism color. */
-  :where(bp-source) {
+  /* ---- <bp-table>: opt-in enhanced data table ----------------------
+     The bare <table> stays the calm typographic primitive in @layer base.
+     <bp-table> is the recommended wrapper when a table earns data-table
+     behavior: the runtime wraps the author's <table> in a .bp-table-x scroll
+     shell so horizontal overflow stays contained without making <bp-table> the
+     sticky header's scroll ancestor. The host washes rows on hover, end-aligns
+     numeric columns (runtime adds .bp-col-num), and opts into a sticky header /
+     key column or a compact density. The inner <table> is author content and
+     keeps its base styling untouched. All of it lives here in @layer components
+     so a plain <table> is unchanged. */
+  :where(bp-table) {
     display: block;
+    max-width: 100%;
+    margin: var(--bp-space-3) 0 var(--bp-space-4);
   }
-  :where(.bp-source) {
-    padding: 0;
+  /* Horizontal scroll lives on the inner shell, not on <bp-table> itself, so a
+     plain (non-sticky) table never makes the host an overflow ancestor. */
+  :where(bp-table > .bp-table-x) {
+    max-width: 100%;
+    overflow-x: auto;
   }
-  :where(.bp-source[open]) {
-    padding-bottom: 0;
+  /* [sticky] turns the shell into a self-contained scroll REGION: one element
+     scrolls BOTH axes within an explicit block size, so the header sticks to
+     the region's top edge and the header + body share a single horizontal
+     scroll coordinate system (no desync), identically at every width and with
+     `wide`. This is the only model that reconciles a sticky header with
+     horizontal scroll — a pure-CSS page-scroll sticky header is impossible once
+     an ancestor must scroll horizontally. Authors can retune the height with
+     --bp-table-sticky-height. */
+  :where(bp-table[sticky] > .bp-table-x) {
+    max-height: var(--bp-table-sticky-height, min(70vh, 32rem));
+    overflow: auto;
+  }
+  /* Sticky cells need border-collapse:separate — the base table rule uses
+     collapse, which prevents position:sticky from engaging on th. */
+  :where(bp-table[sticky] > .bp-table-x > table) {
+    border-collapse: separate;
+    border-spacing: 0;
+  }
+  /* The host owns the block rhythm; null the inner table's base margin so the
+     scroll shell (a BFC) does not add a top/bottom gutter. The base
+     `table { width: 100% }` makes the table shrink to exactly fill the shell,
+     so it can never overflow and overflow-x:auto never scrolls - columns just
+     crush. Size to content instead (min-width:100% still fills the band when
+     the table is narrow), so a table wider than its band overflows and the
+     shell scrolls horizontally. */
+  :where(bp-table > .bp-table-x > table) {
+    margin: 0;
+    width: max-content;
+    min-width: 100%;
   }
-  /* The summary IS the header bar: marker + intent label on the left, the
-     language tag + copy action pushed to the right. One strip, then the code
-     beneath it — no nested boxes. */
-  :where(.bp-source > summary) {
-    display: flex;
-    align-items: center;
-    gap: var(--bp-space-3);
-    padding: var(--bp-space-2) var(--bp-space-3);
+  /* Opt-in breakout: reuse the .bp-table-wrap--wide measure math. */
+  :where(bp-table[wide]) {
+    width: 100vw;
+    max-width: var(--bp-wide);
+    margin-inline: calc(50% - 50vw);
+    margin-inline: max(calc(50% - 50vw), calc((100% - var(--bp-wide)) / 2));
   }
-  :where(.bp-source-name) {
-    font-family: var(--bp-mono);
+  /* Inside the document shell, a wide table is an edge-aware scroll band. The
+     wrapper breaks out to fill <main> from its left border to the right frame
+     rule, but carries scroll padding equal to the prose offset on both ends.
+     At rest the first column lines up with the body text while the band runs
+     out to the frame rule on the right; scrolled to the end the last column
+     stops on the text's right line while the earlier columns run out to
+     <main>'s left border. The pad is the centered measure's offset from the
+     sheet edge, and collapses to 0 once the measure fills the sheet (narrow
+     widths), so the breakout simply disappears there. */
+  :where(html[data-bp-document] bp-table[wide]) {
+    --bp-wt-pad: max(
+      0px,
+      (
+          100vw - var(--bp-shell-inset-left) - var(--bp-shell-inset-right) -
+            (var(--bp-content) - 2 * var(--bp-space-6))
+        ) / 2
+    );
+    width: auto;
+    max-width: none;
+    margin-inline: calc(-1 * var(--bp-wt-pad));
+    padding-inline: var(--bp-wt-pad);
+  }
+  /* Numeric columns — the runtime end-aligns a column's data cells AND its
+     th[scope=col] by adding .bp-col-num (value-specific, so JS-driven). */
+  :where(bp-table .bp-col-num) {
+    text-align: end;
+  }
+  /* Row hover — wash the ambient fill across the row's cells. Transition on
+     the resting cell so hover-in and hover-out both ease (tokens only). */
+  :where(bp-table tbody tr :is(td, th)) {
+    transition: background-color var(--bp-duration-fast) var(--bp-ease-out);
+  }
+  :where(bp-table tbody tr:hover :is(td, th)) {
+    background: var(--bp-fill-amb);
+  }
+  /* Sticky header (opt-in [sticky]) — pins to the top of the scroll region as
+     it scrolls vertically. Backgrounds are paper so scrolled rows never show
+     through; the header out-stacks the sticky key column. */
+  :where(bp-table[sticky] thead th) {
+    position: sticky;
+    top: 0;
+    z-index: 3;
+    background: var(--bp-paper);
+  }
+  /* Sticky key column — the row header pins to the left edge as the region
+     scrolls horizontally, staying in sync with the header (one scroll box). */
+  :where(bp-table[sticky] th[scope="row"]) {
+    position: sticky;
+    left: 0;
+    z-index: 2;
+    background: var(--bp-paper);
+  }
+  /* The pinned corner (column header above the key column) out-stacks both.
+     Authors label the key column with scope="row" in tbody; the matching
+     thead cell is scope="col", so pin the first header cell left. */
+  :where(bp-table[sticky] thead th:first-child) {
+    left: 0;
+    z-index: 4;
+  }
+  /* Compact density — tighter cells; body cells drop to small, the mono
+     column headers to the small label step. */
+  :where(bp-table[density="compact"] :is(td, th)) {
+    padding-top: var(--bp-space-1);
+    padding-bottom: var(--bp-space-1);
+  }
+  :where(bp-table[density="compact"] :is(td, th[scope="row"])) {
+    font-size: var(--bp-text-small);
+  }
+  :where(bp-table[density="compact"] :is(th[scope="col"], thead th)) {
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+  }
+
+  /* ---- Source disclosure -------------------------------------------
+     A reusable source-code panel. The semantic shell is a native <details>;
+     authors provide the explicit language/copy toolbar, blueprint-code.js
+     enables the copy button, and blueprint-code.css adds Prism color. */
+  :where(bp-source) {
+    display: block;
+  }
+  :where(.bp-source) {
+    padding: 0;
+  }
+  :where(.bp-source[open]) {
+    padding-bottom: 0;
+  }
+  /* The summary IS the header bar: marker + intent label on the left, the
+     language tag + copy action pushed to the right. One strip, then the code
+     beneath it — no nested boxes. */
+  :where(.bp-source > summary) {
+    display: flex;
+    align-items: center;
+    gap: var(--bp-space-3);
+    padding: var(--bp-space-2) var(--bp-space-3);
+  }
+  :where(.bp-source-name) {
+    font-family: var(--bp-mono);
     font-size: var(--bp-label-md);
     letter-spacing: var(--bp-label-md-ls);
     text-transform: uppercase;
@@ -2125,9 +2183,9 @@
   :where(.bp-source-copy) {
     appearance: none;
     border: 1px solid var(--bp-ink-line);
-    border-radius: var(--bp-radius-2);
+    border-radius: var(--bp-radius-0);
     padding: 4px var(--bp-space-2);
-    background: transparent;
+    background: oklch(0 0 0 / 0);
     color: var(--bp-ink);
     font-family: var(--bp-mono);
     font-size: var(--bp-label-sm);
@@ -2222,7 +2280,7 @@
     width: min(460px, calc(100vw - 20px));
     padding: 0;
     border: 1px solid var(--bp-ink-line);
-    border-radius: var(--bp-radius-6);
+    border-radius: var(--bp-radius-0);
     background: var(--bp-paper);
     color: var(--bp-text);
     box-shadow: var(--bp-shadow-pop);
@@ -2261,7 +2319,7 @@
     left: var(--bp-cite-caret, 50%);
     width: 0;
     height: 0;
-    border: 7px solid transparent;
+    border: 7px solid oklch(0 0 0 / 0);
     transform: translateX(-50%);
   }
   :where(.bp-cite-pop[data-placement="top"])::before {
@@ -2312,88 +2370,63 @@
     max-height: 320px;
     margin: 0;
     border: 0;
-    border-radius: 0 0 var(--bp-radius-6) var(--bp-radius-6);
-  }
-
-  /* ---- SVG figure marks (1px hairline default via --bp-stroke) -------
-     ILLUSTRATIONS are the one place blue lives. Node/edge line work draws
-     in --bp-illustration; only the in-diagram TEXT labels stay neutral ink
-     (text everywhere reads in the monochrome scale). */
-  :where(.bp-node) {
-    fill: var(--bp-paper);
-    stroke: var(--bp-illustration);
-    stroke-width: var(--bp-stroke);
-  }
-  :where(.bp-node--amb) {
-    fill: var(--bp-illustration-fill);
-  }
-  /* Fenced node — a barrier / held step. Filled with the diagonal hatch
-     paint server (define the <pattern> once in the figure's <defs>; see
-     the .bp-hatch-fill / .bp-hatch-line tiles below). The .bp-node stroke
-     keeps the illustration border. CSS gradients can't paint an SVG shape,
-     so SVG uses a <pattern> while HTML uses the --bp-hatch gradient token. */
-  :where(.bp-node--fenced) {
-    fill: url(#bp-hatch);
-  }
-  /* Tiles for the SVG hatch <pattern> — token-driven so both themes track.
-     The fill rect carries the illustration wash; the line is the drafting
-     section-lining, both in the blue illustration family. */
-  :where(.bp-hatch-fill) {
-    fill: var(--bp-illustration-fill);
-  }
-  :where(.bp-hatch-line) {
-    stroke: var(--bp-illustration-faint);
-    stroke-width: var(--bp-stroke);
-  }
-  :where(.bp-edge) {
-    fill: none;
-    stroke: var(--bp-illustration);
-    stroke-width: var(--bp-stroke);
-  }
-  :where(.bp-edge--skip) {
-    stroke: var(--bp-illustration-soft);
-    stroke-dasharray: 4 3;
-  }
-  :where(.bp-svg-label) {
-    font-family: var(--bp-mono);
-    font-size: 11px;
-    fill: var(--bp-text);
-  }
-  :where(.bp-svg-meta) {
-    font-family: var(--bp-mono);
-    font-size: 9px;
-    fill: var(--bp-text-secondary);
-  }
-  /* Callout terminator dot — illustration line work, so it draws in blue */
-  :where(.bp-svg-dot) {
-    fill: var(--bp-illustration);
+    border-radius: 0 0 var(--bp-radius-0) var(--bp-radius-0);
   }
 
-  /* ---- Isometric solids (overview illustration) ---------------------
-     Generic isometric primitives for axis-aligned boxes: side faces read
-     as paper edges, top faces carry the illustration wash, and a faint
-     floor grid grounds the scene. Used for the overview factory line
-     (machines, conveyors, parts); blue is line work only, labels stay
-     ink. .bp-svg-dot terminates callout leaders in the illustration blue. */
-  :where(.bp-stack-face) {
-    fill: var(--bp-paper);
-    stroke: var(--bp-illustration);
-    stroke-width: var(--bp-stroke);
-  }
-  :where(.bp-stack-top) {
-    fill: var(--bp-illustration-fill);
-    stroke: var(--bp-illustration);
-    stroke-width: var(--bp-stroke);
-  }
-  :where(.bp-stack-top--fenced) {
-    fill: url(#overview-stack-hatch);
-  }
-  :where(.bp-stack-grid) {
-    fill: none;
-    stroke: var(--bp-illustration-faint);
-    stroke-width: var(--bp-stroke);
-    opacity: 0.45;
+  /* ---- SVG paint utilities (diagrams live entirely in the blue ramp) -
+     Color is the ONLY thing these set: line work AND labels are blue —
+     there is no neutral/gray ink inside a figure. Everything else
+     (stroke-width, stroke-dasharray, font-size, text-anchor, markers,
+     geometry) is plain SVG the author writes as normal attributes; SVG's
+     default stroke-width:1 already equals the hairline.
+       svg-fill-{100..900}    paints `fill`   — interiors and label text
+       svg-stroke-{100..900}  paints `stroke` — outlines, edges, grids
+     The number is ink STRENGTH, not absolute lightness: 900 is the
+     strongest mark (label text, key strokes), 100 the faintest fill. So
+     the ramp inverts under the dark theme (below) to stay legible while
+     never leaving the blue family — authors only ever touch the classes.
+     A class beats a fill=""/stroke="" presentation attribute; reach for
+     style="" only to override a single element. */
+  :where(:root) {
+    --svg-blue-100: var(--bp-blue-100);
+    --svg-blue-200: var(--bp-blue-200);
+    --svg-blue-300: var(--bp-blue-300);
+    --svg-blue-400: var(--bp-blue-400);
+    --svg-blue-500: var(--bp-blue-500);
+    --svg-blue-600: var(--bp-blue-600);
+    --svg-blue-700: var(--bp-blue-700);
+    --svg-blue-800: var(--bp-blue-800);
+    --svg-blue-900: var(--bp-blue-900);
   }
+  :where([data-obvious-theme="dark"]) {
+    --svg-blue-100: var(--bp-blue-900);
+    --svg-blue-200: var(--bp-blue-800);
+    --svg-blue-300: var(--bp-blue-700);
+    --svg-blue-400: var(--bp-blue-600);
+    --svg-blue-500: var(--bp-blue-500);
+    --svg-blue-600: var(--bp-blue-400);
+    --svg-blue-700: var(--bp-blue-300);
+    --svg-blue-800: var(--bp-blue-200);
+    --svg-blue-900: var(--bp-blue-100);
+  }
+  :where(.svg-fill-100) { fill: var(--svg-blue-100); }
+  :where(.svg-fill-200) { fill: var(--svg-blue-200); }
+  :where(.svg-fill-300) { fill: var(--svg-blue-300); }
+  :where(.svg-fill-400) { fill: var(--svg-blue-400); }
+  :where(.svg-fill-500) { fill: var(--svg-blue-500); }
+  :where(.svg-fill-600) { fill: var(--svg-blue-600); }
+  :where(.svg-fill-700) { fill: var(--svg-blue-700); }
+  :where(.svg-fill-800) { fill: var(--svg-blue-800); }
+  :where(.svg-fill-900) { fill: var(--svg-blue-900); }
+  :where(.svg-stroke-100) { stroke: var(--svg-blue-100); }
+  :where(.svg-stroke-200) { stroke: var(--svg-blue-200); }
+  :where(.svg-stroke-300) { stroke: var(--svg-blue-300); }
+  :where(.svg-stroke-400) { stroke: var(--svg-blue-400); }
+  :where(.svg-stroke-500) { stroke: var(--svg-blue-500); }
+  :where(.svg-stroke-600) { stroke: var(--svg-blue-600); }
+  :where(.svg-stroke-700) { stroke: var(--svg-blue-700); }
+  :where(.svg-stroke-800) { stroke: var(--svg-blue-800); }
+  :where(.svg-stroke-900) { stroke: var(--svg-blue-900); }
 
   /* ---- Masthead title-block: a metadata strip (author/date/status) - */
   :where(.bp-title-block) {
@@ -2549,6 +2582,10 @@
     margin: 0;
     padding: 0;
     list-style: none;
+    /* Primary label text starts after pad + index tick + gap — sub-entries
+       reuse this inset so their labels line up with the row above. */
+    --bp-toc-index-w: 14px;
+    --bp-toc-label-inset: calc(var(--bp-space-3) + var(--bp-toc-index-w) + var(--bp-space-2));
   }
   /* The gliding active pill, drawn behind the entries and travelling via
      --bp-toc-y / --bp-toc-h (set by blueprint.js). */
@@ -2591,45 +2628,72 @@
     text-decoration: none;
     padding: 6px var(--bp-space-3);
     border-radius: var(--bp-radius-6);
-    /* Motion: .bp-transition-colors .bp-ease (hover color shift) */
-    transition-property: color, background;
-    transition-duration: var(--bp-duration-fast);
-    transition-timing-function: var(--bp-ease);
+    /* Idle entries snap on theme flip so the root crossfade isn't fighting
+       per-row token tweens (labels + index numbers alike). */
+    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 {
     content: counter(bp-toc, decimal-leading-zero);
-    flex: 0 0 auto;
+    flex: 0 0 var(--bp-toc-index-w, 14px);
+    min-width: var(--bp-toc-index-w, 14px);
     font-size: var(--bp-label-lg);
     font-variant-numeric: tabular-nums;
     letter-spacing: 0.02em;
     color: var(--bp-ink-soft);
-    /* Motion: .bp-transition-colors .bp-ease (hover color shift) */
-    transition-property: color;
-    transition-duration: var(--bp-duration-fast);
-    transition-timing-function: var(--bp-ease);
+    transition: none;
   }
-  /* Nested sub-entries indent and drop the number. */
+  /* Nested sub-entries align with primary label text and read tighter. */
   :where(.bp-sidebar ul ul, .bp-toc ul ul) {
-    margin: 0;
-    padding: 0 0 0 var(--bp-space-3);
+    margin: 0 0 var(--bp-space-1);
+    padding: 0;
     list-style: none;
   }
   :where(.bp-sidebar ul ul a, .bp-toc ul ul a) {
+    display: block;
     font-size: var(--bp-text-small);
+    line-height: 1.25;
+    padding: 1px var(--bp-space-3) 1px var(--bp-toc-label-inset);
+  }
+  /* Group eyebrow row — a quiet mono kicker that heads a run of entries. It is
+     a flat sibling of the entry items (so the gliding pill + scroll-spy are
+     untouched) and is skipped by the auto-numbering counter, keeping the
+     section numbers continuous with the document's own section eyebrows. */
+  :where(.bp-sidebar .bp-nav-group, .bp-toc .bp-nav-group) {
+    counter-increment: none;
+    margin: var(--bp-space-4) 0 var(--bp-space-1);
+  }
+  :where(.bp-sidebar .bp-nav-group:first-child, .bp-toc .bp-nav-group:first-child) {
+    margin-top: var(--bp-space-1);
+  }
+  :where(.bp-nav-group__label) {
+    display: block;
+    padding: 0 var(--bp-space-3);
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+    text-transform: uppercase;
+    color: var(--bp-text-secondary);
   }
   /* Hover shows its own subtle pill; the active entry rides the gliding pill
      above (so it keeps no own background) and reads in ink + medium weight. */
   :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);
     background: none;
     font-weight: var(--bp-weight-medium);
   }
-  :where(.bp-sidebar a:hover::before, .bp-toc a:hover::before, .bp-sidebar a[aria-current="location"]::before, .bp-toc a[aria-current="location"]::before, .bp-sidebar a.active::before, .bp-toc a.active::before) {
+  :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);
   }
   /* ---- Full-width contents block -----------------------------------
@@ -2656,6 +2720,25 @@
     counter-increment: bp-contents;
     margin: 0;
   }
+  /* Group eyebrow in the inline index: a full-width band that breaks the grid
+     into labelled runs. Skipped by the numbering counter (it carries no link),
+     so entry numbers stay continuous across groups. */
+  :where(.bp-contents-group) {
+    grid-column: 1 / -1;
+    counter-increment: none;
+    margin: var(--bp-space-4) 0 var(--bp-space-1);
+  }
+  :where(.bp-contents-group:first-child) {
+    margin-top: 0;
+  }
+  :where(.bp-contents-group__label) {
+    display: block;
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+    text-transform: uppercase;
+    color: var(--bp-text-secondary);
+  }
   :where(.bp-contents a) {
     display: flex;
     align-items: baseline;
@@ -2708,13 +2791,10 @@
     transform: translateX(var(--bp-space-1));
   }
 
-  /* Column frame: the shell is pinned between fixed top/bottom insets so the
-     desk margin always shows while content scrolls inside; vertical rules at
-     the column edges run full viewport height; horizontal rules are one
-     continuous full-width line at the shell's top and bottom inset, with a
-     solid top band masking scroll bleed into the margin. Shadows off while
-     testing. */
-  :where(html:has(.bp-shell)) {
+  /* Column frame: the PAGE scrolls, while fixed top/bottom bands + fixed vertical
+     edge rules hold the desk margin on all four sides. <main> sits in normal
+     flow (paper sheet); the sidebar rail stays fixed. */
+  :where(html[data-bp-document]) {
     --bp-shell-inset-block: var(--bp-space-4);
     --bp-shell-inset-top: var(--bp-shell-inset-block);
     --bp-shell-inset-left: var(--bp-sidebar);
@@ -2727,29 +2807,43 @@
     --bp-frame-line-z: 210;
     --bp-scroll-margin: var(--bp-space-6);
   }
-  :where(body:has(.bp-shell)) {
-    overflow: hidden;
-  }
-  :where(.bp-shell) {
-    position: fixed;
-    inset: var(--bp-shell-inset-top) var(--bp-shell-inset-right)
-      var(--bp-shell-inset-block) var(--bp-shell-inset-left);
-    margin: 0;
-    overflow-x: hidden;
-    overflow-y: auto;
-    overscroll-behavior: contain;
-    -webkit-overflow-scrolling: touch;
+  /* Top/bottom desk bands are body padding so the sheet clears the fixed
+     frame rules and the page tail is not occluded by the bottom band. */
+  :where(html[data-bp-document] body) {
+    padding-top: var(--bp-shell-inset-top);
+    padding-bottom: var(--bp-shell-inset-block);
+  }
+  /* <main> is the paper sheet spanning the full column between the vertical
+     frame rules; direct children keep the prose measure from Tier 1b. Keep the
+     shell out of the overflow/scroll chain so viewport-fixed navigation nested
+     by stored Blueprints is not clipped by WebKit. The page owns scrolling. */
+  :where(html[data-bp-document] main) {
+    max-width: none;
+    overflow: visible;
+    margin: 0 var(--bp-shell-inset-right) 0 var(--bp-shell-inset-left);
+    min-height: calc(
+      100vh - var(--bp-shell-inset-top) - var(--bp-shell-inset-block)
+    );
     background: var(--bp-paper);
     border: 0;
     border-radius: var(--bp-radius-0);
     box-shadow: none;
   }
-  /* TOC / hash targets scroll inside the shell — reserve top air so headings
-     don't land flush against the inner edge. */
-  :where(.bp-shell section[id]) {
+  /* Same inner measure as max-width: var(--bp-content) on a padded main, and
+     auto margins center that measure within the sheet so the reading column
+     sits balanced between the frame rules. The sheet's own box shrinks when the
+     rail collapses (margin-inline transition above), so the centered measure
+     re-centers in step with the slide rather than hugging the left rule. */
+  :where(html[data-bp-document] main > *) {
+    max-width: min(100%, calc(var(--bp-content) - 2 * var(--bp-space-6)));
+    margin-inline: auto;
+  }
+  /* TOC / hash targets — reserve top air so a heading clears the fixed top
+     band instead of landing flush beneath it. */
+  :where(html[data-bp-document] main :is(section[id], [id][data-sidebar])) {
     scroll-margin-top: var(--bp-scroll-margin);
   }
-  :where(html:has(.bp-shell))::before {
+  :where(html[data-bp-document])::before {
     content: "";
     position: fixed;
     inset-inline: 0;
@@ -2759,7 +2853,7 @@
     pointer-events: none;
     z-index: var(--bp-frame-line-z);
   }
-  :where(html:has(.bp-shell))::after {
+  :where(html[data-bp-document])::after {
     content: "";
     position: fixed;
     inset-block: 0;
@@ -2775,10 +2869,10 @@
       var(--bp-shell-inset-left) 0,
       calc(100% - var(--bp-shell-inset-right)) 0;
   }
-  /* Top inset: solid desk band masks scroll bleed; frame lines sit above rail
-     scrims so verticals run edge-to-edge through the horizontals. Bottom: line
-     only. */
-  :where(body:has(.bp-shell))::before {
+  /* Top/bottom desk bands (fixed) mask the page scrolling beneath them; the
+     bottom band draws the lower horizontal at its top edge. Frame lines sit
+     above rail scrims so the verticals run edge-to-edge through horizontals. */
+  :where(html[data-bp-document] body)::before {
     content: "";
     position: fixed;
     inset-inline: 0;
@@ -2788,15 +2882,16 @@
     pointer-events: none;
     z-index: var(--bp-shell-mask-z);
   }
-  :where(body:has(.bp-shell))::after {
+  :where(html[data-bp-document] body)::after {
     content: "";
     position: fixed;
     inset-inline: 0;
-    height: 0;
+    bottom: 0;
+    height: var(--bp-shell-inset-block);
     border-top: var(--bp-stroke) solid var(--bp-edge);
+    background: var(--bp-bg);
     pointer-events: none;
     z-index: var(--bp-frame-line-z);
-    bottom: var(--bp-shell-inset-block);
   }
   :where(.scroll-progress) {
     position: fixed;
@@ -2815,124 +2910,475 @@
     transition-duration: var(--bp-duration-instant);
     transition-timing-function: var(--bp-ease-linear);
   }
-}
 
-/* Stored Blueprint shell contracts. New documents use bp-* components. */
-@layer components {
-  :where(.sidebar) {
-    position: fixed;
-    inset: 0 auto 0 0;
-    width: var(--sidebar);
-    height: 100vh;
-    overflow-y: auto;
-    padding: 34px 20px 34px 26px;
-    z-index: 100;
+  /* ---- <bp-mock> — drafting browser frame for UX mockups ------------
+     The frame is CHROME, so it is drawn in the neutral ink scale; the
+     sketch inside keeps the illustration-blue ramp. `viewport` draws the
+     canvas at a fixed pixel width and scales it to fit (crisp 1:1 when the
+     frame is wide enough or expanded); the expand control lifts the frame
+     into a near-fullscreen overlay over a drafting scrim. */
+  :where(.bp-mock) {
+    display: block;
+    margin: var(--bp-space-4) 0;
   }
-  :where(.sidebar-head) {
-    padding-bottom: 16px;
-    border-bottom: 1px solid var(--edge);
-    margin-bottom: 16px;
+  :where(.bp-mock__frame) {
+    display: flex;
+    flex-direction: column;
+    border: var(--bp-stroke) solid var(--bp-ink-line);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    overflow: hidden;
   }
-  :where(.sidebar-title) {
-    font: 500 11px/1.4 var(--mono);
-    letter-spacing: 0.12em;
-    text-transform: uppercase;
-    color: var(--ink);
+  :where(.bp-mock__bar) {
+    display: flex;
+    align-items: center;
+    gap: var(--bp-space-2);
+    min-height: 34px;
+    padding: var(--bp-space-2) var(--bp-space-3);
+    border-bottom: var(--bp-stroke) solid var(--bp-edge);
+    background: var(--bp-fill-amb);
   }
-  :where(.sidebar-doc) {
-    font: 400 10px/1.4 var(--mono);
-    letter-spacing: 0.08em;
-    text-transform: uppercase;
-    color: var(--text-secondary);
-    margin-top: 6px;
+  :where(.bp-mock__ticks) {
+    display: inline-flex;
+    gap: 5px;
+    flex: 0 0 auto;
   }
-  :where(.sidebar ul) {
-    list-style: none;
-    margin: 0;
-    padding: 0;
-    counter-reset: navsec;
-    display: flex;
-    flex-direction: column;
+  :where(.bp-mock__ticks i) {
+    width: 8px;
+    height: 8px;
+    border-radius: var(--bp-radius-0);
+    border: var(--bp-stroke) solid var(--bp-ink-faint);
   }
-  :where(.sidebar li) {
-    margin: 0;
+  :where(.bp-mock__label) {
+    flex: 1 1 auto;
+    min-width: 0;
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-md);
+    letter-spacing: var(--bp-label-md-ls);
+    color: var(--bp-text-secondary);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  :where(.bp-mock__btn) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+    width: 24px;
+    height: 24px;
     padding: 0;
+    border: var(--bp-stroke) solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    color: var(--bp-text-secondary);
+    cursor: pointer;
   }
-  :where(.sidebar a) {
-    position: relative;
-    display: block;
-    font: 400 12px/1.35 var(--sans);
-    color: var(--text-secondary);
-    text-decoration: none;
-    padding: 7px 10px 7px 36px;
+  :where(.bp-mock__btn svg) {
+    width: 14px;
+    height: 14px;
   }
-  :where(.sidebar a)::before {
-    counter-increment: navsec;
-    content: counter(navsec, decimal-leading-zero);
-    position: absolute;
-    left: 10px;
-    top: 8px;
-    font: 400 10px/1 var(--mono);
-    letter-spacing: 0.06em;
-    color: var(--ink-faint);
+  :where(.bp-mock__btn:hover) {
+    color: var(--bp-text);
+    border-color: var(--bp-ink-line);
   }
-  :where(.sidebar a:hover, .sidebar a[aria-current="location"]) {
-    color: var(--ink);
-    background: var(--fill-amb);
+  :where(.bp-mock__btn:focus-visible) {
+    outline: 2px solid var(--bp-ink);
+    outline-offset: 2px;
   }
-  :where(.sidebar a[aria-current="location"])::after {
-    content: "";
-    position: absolute;
-    inset: 0 auto 0 0;
-    width: 2px;
-    background: var(--ink);
+  :where(.bp-mock__stage) {
+    position: relative;
+    overflow: hidden;
+    background: var(--bp-bg);
   }
-  :where(.page-body) {
-    margin-left: var(--sidebar);
+  :where(.bp-mock__canvas) {
+    transform-origin: top left;
+    transform: scale(var(--bp-mock-scale, 1));
   }
-  :where(.sheet) {
+
+  /* Expanded → near-fullscreen overlay; the frame floats over a drafting
+     scrim (ink wash + hatch). The frame itself stays the bordered window. */
+  :where(.bp-mock.is-expanded) {
+    position: fixed;
+    inset: 0;
+    /* Above the fixed rail (100), scroll-progress (200), and frame rules
+       (210) so the overlay fully covers the document chrome. */
+    z-index: 300;
     margin: 0;
-    min-height: 100vh;
-    background: var(--paper);
-    border-left: 1px solid var(--edge);
+    display: grid;
+    place-items: center;
+    padding: clamp(var(--bp-space-4), 4vw, var(--bp-space-7));
+    background-color: var(--bp-scrim);
+    background-image: var(--bp-hatch);
   }
-  :where(.hero) {
-    padding: 48px 56px 36px;
-    border-bottom: 1px solid var(--ink-line);
-    font-family: var(--sans);
+  :where(.bp-mock.is-expanded) :where(.bp-mock__frame) {
+    width: min(100%, 1120px);
+    max-height: 100%;
+    box-shadow: var(--bp-shadow-pop);
   }
-  :where(.hero-meta) {
-    font: 400 11px/1.4 var(--mono);
-    letter-spacing: 0.14em;
-    text-transform: uppercase;
-    color: var(--ink-soft);
-    margin-bottom: 16px;
+  :where(.bp-mock.is-expanded) :where(.bp-mock__stage) {
+    overflow: auto;
   }
-  :where(.hero h1) {
-    font: 600 24px/32px var(--sans);
-    letter-spacing: -0.48px;
-    margin: 10px 0 14px;
+
+  /* ---- <bp-gallery> — image grid with a lightbox viewer -------------
+     A tidy responsive grid of images (screenshots, mockups, uploads).
+     Each thumbnail wears a BLUESCALE treatment by default — the raster
+     is desaturated and a blue veil (.bp-gallery__wash) color-blends over
+     it — and reveals its true color on hover/focus. Activating a tile
+     opens .bp-lightbox, a near-fullscreen viewer over a drafting scrim. */
+  :where(.bp-gallery) {
+    display: block;
+    margin: var(--bp-space-5) 0;
   }
-  :where(.hero-sub) {
-    font: 400 14px/20px var(--serif);
-    text-align: justify;
-    hyphens: auto;
+  :where(.bp-gallery__grid) {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(min(100%, 200px), 1fr));
+    gap: var(--bp-space-3);
   }
-  :where(.title-block) {
-    margin-top: 34px;
-    border: 1px solid var(--ink-line);
+  :where(.bp-gallery__item) {
     display: flex;
-    flex-wrap: wrap;
-  }
-  :where(.tb-cell) {
-    flex: 0 0 auto;
-    padding: 10px 20px 11px 14px;
-    border-right: 1px solid var(--ink-line);
-  }
-  :where(.tb-cell--grow) {
-    flex: 1 1 auto;
-  }
-  :where(.tb-cell:last-child) {
+    flex-direction: column;
+    gap: var(--bp-space-2);
+    min-width: 0;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    text-align: left;
+    cursor: pointer;
+    font: inherit;
+    color: inherit;
+  }
+  :where(.bp-gallery__thumb) {
+    position: relative;
+    display: block;
+    overflow: hidden;
+    aspect-ratio: 4 / 3;
+    border: var(--bp-stroke) solid var(--bp-ink-line);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-bg);
+  }
+  :where(.bp-gallery__img) {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    /* Bluescale: drop saturation; the wash supplies the blue cast. */
+    filter: grayscale(1) contrast(1.02);
+    transition:
+      filter var(--bp-duration-slow) var(--bp-ease-out),
+      transform var(--bp-duration-slow) var(--bp-ease-out);
+  }
+  :where(.bp-gallery__wash) {
+    position: absolute;
+    inset: 0;
+    background: var(--bp-illustration);
+    mix-blend-mode: color;
+    opacity: 0.85;
+    transition: opacity var(--bp-duration-slow) var(--bp-ease-out);
+    pointer-events: none;
+  }
+  :where(.bp-gallery__zoom) {
+    position: absolute;
+    inset: auto var(--bp-space-2) var(--bp-space-2) auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    color: var(--bp-text-secondary);
+    box-shadow: var(--bp-shadow-pop);
+    opacity: 0;
+    transform: translateY(4px);
+    transition:
+      opacity var(--bp-duration-fast) var(--bp-ease-out),
+      transform var(--bp-duration-fast) var(--bp-ease-out);
+    pointer-events: none;
+  }
+  :where(.bp-gallery__zoom svg) {
+    width: 16px;
+    height: 16px;
+  }
+  /* Reveal true color on hover or keyboard focus. */
+  :where(.bp-gallery__item:hover, .bp-gallery__item:focus-visible)
+    :where(.bp-gallery__img) {
+    filter: none;
+    transform: scale(1.03);
+  }
+  :where(.bp-gallery__item:hover, .bp-gallery__item:focus-visible)
+    :where(.bp-gallery__wash) {
+    opacity: 0;
+  }
+  :where(.bp-gallery__item:hover, .bp-gallery__item:focus-visible)
+    :where(.bp-gallery__zoom) {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  :where(.bp-gallery__item:focus-visible) :where(.bp-gallery__thumb) {
+    outline: 2px solid var(--bp-ink);
+    outline-offset: 2px;
+  }
+  :where(.bp-gallery__caption) {
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-md);
+    letter-spacing: var(--bp-label-md-ls);
+    color: var(--bp-text-secondary);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* The lightbox is appended to <body> by the runtime; hidden until open. */
+  :where(.bp-lightbox) {
+    /* Scrim inset and the room reserved for the caption row below the
+       image, so a portrait image taller than the viewport scales down
+       instead of pushing its caption off-screen. */
+    --bp-lightbox-pad: clamp(var(--bp-space-4), 4vw, var(--bp-space-7));
+    --bp-lightbox-meta: calc(var(--bp-space-3) + var(--bp-space-5));
+    position: fixed;
+    inset: 0;
+    z-index: 300;
+    display: none;
+    /* Side columns reserve the prev/next controls; the figure rides the
+       centered middle column and the single 1fr row fills the height so
+       the image is centered on both axes. */
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    grid-template-rows: minmax(0, 1fr);
+    align-items: center;
+    justify-items: center;
+    gap: var(--bp-space-3);
+    padding: var(--bp-lightbox-pad);
+    background-color: var(--bp-scrim);
+    background-image: var(--bp-hatch);
+  }
+  :where(.bp-lightbox.is-open) {
+    display: grid;
+  }
+  :where(.bp-lightbox__figure) {
+    grid-column: 2;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: var(--bp-space-3);
+    margin: 0;
+    min-width: 0;
+    min-height: 0;
+    max-width: 100%;
+    max-height: 100%;
+  }
+  :where(.bp-lightbox__img) {
+    display: block;
+    /* Width is bounded by the centered column; height is bounded by the
+       viewport minus the scrim inset and the reserved caption row. With
+       both maxes set and intrinsic sizing left auto, the browser scales
+       the image down while preserving its aspect ratio. */
+    width: auto;
+    height: auto;
+    max-width: 100%;
+    max-height: calc(100dvh - 2 * var(--bp-lightbox-pad) - var(--bp-lightbox-meta));
+    object-fit: contain;
+    border: var(--bp-stroke) solid var(--bp-ink-line);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    box-shadow: var(--bp-shadow-pop);
+  }
+  :where(.bp-lightbox__meta) {
+    display: flex;
+    align-items: baseline;
+    gap: var(--bp-space-3);
+    max-width: 100%;
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-md);
+    letter-spacing: var(--bp-label-md-ls);
+    color: var(--bp-paper);
+  }
+  :where(.bp-lightbox__kicker) {
+    text-transform: uppercase;
+    opacity: 0.7;
+  }
+  :where(.bp-lightbox__counter) {
+    opacity: 0.7;
+  }
+  :where(.bp-lightbox__caption) {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  :where(.bp-lightbox__close) {
+    position: absolute;
+    inset: var(--bp-space-4) var(--bp-space-4) auto auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 40px;
+    height: 40px;
+    padding: 0;
+    border: var(--bp-stroke) solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    color: var(--bp-text-secondary);
+    cursor: pointer;
+  }
+  :where(.bp-lightbox__nav) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 44px;
+    height: 44px;
+    padding: 0;
+    border: var(--bp-stroke) solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    color: var(--bp-text-secondary);
+    cursor: pointer;
+  }
+  :where(.bp-lightbox__nav--prev) {
+    grid-column: 1;
+  }
+  :where(.bp-lightbox__nav--next) {
+    grid-column: 3;
+  }
+  :where(.bp-lightbox.is-single) :where(.bp-lightbox__nav) {
+    visibility: hidden;
+  }
+  :where(.bp-lightbox__close:hover, .bp-lightbox__nav:hover) {
+    color: var(--bp-text);
+    border-color: var(--bp-ink-line);
+  }
+  :where(.bp-lightbox__close:focus-visible, .bp-lightbox__nav:focus-visible) {
+    outline: 2px solid var(--bp-paper);
+    outline-offset: 2px;
+  }
+  :where(.bp-lightbox__close svg) {
+    width: 18px;
+    height: 18px;
+  }
+  :where(.bp-lightbox__nav svg) {
+    width: 22px;
+    height: 22px;
+  }
+}
+
+/* Stored Blueprint shell contracts. New documents use bp-* components. */
+@layer components {
+  :where(.sidebar) {
+    position: fixed;
+    inset: 0 auto 0 0;
+    width: var(--sidebar);
+    height: 100vh;
+    overflow-y: auto;
+    padding: 34px 20px 34px 26px;
+    z-index: 100;
+  }
+  :where(.sidebar-head) {
+    padding-bottom: 16px;
+    border-bottom: 1px solid var(--edge);
+    margin-bottom: 16px;
+  }
+  :where(.sidebar-title) {
+    font: 500 11px/1.4 var(--mono);
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--ink);
+  }
+  :where(.sidebar-doc) {
+    font: 400 10px/1.4 var(--mono);
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--text-secondary);
+    margin-top: 6px;
+  }
+  :where(.sidebar ul) {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    counter-reset: navsec;
+    display: flex;
+    flex-direction: column;
+  }
+  :where(.sidebar li) {
+    margin: 0;
+    padding: 0;
+  }
+  :where(.sidebar a) {
+    position: relative;
+    display: block;
+    font: 400 12px/1.35 var(--sans);
+    color: var(--text-secondary);
+    text-decoration: none;
+    padding: 7px 10px 7px 36px;
+  }
+  :where(.sidebar a)::before {
+    counter-increment: navsec;
+    content: counter(navsec, decimal-leading-zero);
+    position: absolute;
+    left: 10px;
+    top: 8px;
+    font: 400 10px/1 var(--mono);
+    letter-spacing: 0.06em;
+    color: var(--ink-faint);
+  }
+  :where(.sidebar a:hover, .sidebar a[aria-current="location"]) {
+    color: var(--ink);
+    background: var(--fill-amb);
+  }
+  :where(.sidebar a[aria-current="location"])::after {
+    content: "";
+    position: absolute;
+    inset: 0 auto 0 0;
+    width: 2px;
+    background: var(--ink);
+  }
+  :where(.page-body) {
+    margin-left: var(--sidebar);
+  }
+  :where(.sheet) {
+    margin: 0;
+    min-height: 100vh;
+    background: var(--paper);
+    border-left: 1px solid var(--edge);
+  }
+  :where(.hero) {
+    padding: 48px 56px 36px;
+    border-bottom: 1px solid var(--ink-line);
+    font-family: var(--sans);
+  }
+  :where(.hero-meta) {
+    font: 400 11px/1.4 var(--mono);
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--ink-soft);
+    margin-bottom: 16px;
+  }
+  :where(.hero h1) {
+    font: 600 24px/32px var(--sans);
+    letter-spacing: -0.48px;
+    margin: 10px 0 14px;
+  }
+  :where(.hero-sub) {
+    font: 400 14px/20px var(--serif);
+    text-align: justify;
+    hyphens: auto;
+  }
+  :where(.title-block) {
+    margin-top: 34px;
+    border: 1px solid var(--ink-line);
+    display: flex;
+    flex-wrap: wrap;
+  }
+  :where(.tb-cell) {
+    flex: 0 0 auto;
+    padding: 10px 20px 11px 14px;
+    border-right: 1px solid var(--ink-line);
+  }
+  :where(.tb-cell--grow) {
+    flex: 1 1 auto;
+  }
+  :where(.tb-cell:last-child) {
     border-right: 0;
   }
   :where(.tb-label) {
@@ -3024,36 +3470,541 @@
     max-width: 100%;
     height: auto;
   }
-  :where(.fig-node) {
-    fill: var(--paper);
-    stroke: var(--bp-illustration);
-    stroke-width: 1.5;
-  }
-  :where(.fig-node-amb) {
-    fill: var(--bp-illustration-fill);
-    stroke: var(--bp-illustration);
-    stroke-width: 1.5;
-  }
-  :where(.fig-edge) {
-    fill: none;
-    stroke: var(--bp-illustration);
-    stroke-width: 1.5;
-  }
-  :where(.fig-label) {
-    font: 400 11px/1 var(--mono);
-    fill: var(--text);
-  }
-  :where(.fig-label-soft) {
-    font: 400 9px/1 var(--mono);
-    fill: var(--text-secondary);
+  :where(.fig-cap) {
+    font: 400 10px/1.4 var(--mono);
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--text-secondary);
+    text-align: center;
+    margin-top: 14px;
+  }
+}
+
+/* =====================================================================
+   @layer components — <bp-workplan>
+
+   A live "work plan": typed, dependent tasks that resolve into waves,
+   rendered four ways (list · gantt · kanban · swimlanes). Light-DOM,
+   token-only, theme-aware. Chrome is ink; the only non-ink token is
+   --bp-positive for a passing/approved PR. The element renders only
+   <div>/<span> for structure, so the base layer's semantic-element
+   styling never applies — no resets needed.
+   ===================================================================== */
+@layer components {
+  :where(.bp-workplan) {
+    font-family: var(--bp-sans);
+    color: var(--bp-text);
+    container-type: inline-size;
+  }
+
+  /* ---- plan header + summary stats ---------------------------- */
+  :where(.wp-head) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--bp-space-3);
+    align-items: flex-end;
+    justify-content: space-between;
+    padding-bottom: var(--bp-space-3);
+    margin-bottom: var(--bp-space-3);
+    border-bottom: 1px solid var(--bp-ink-line);
+  }
+  :where(.wp-head__name) {
+    font-size: var(--bp-text-h3);
+    line-height: var(--bp-lh-h3);
+    font-weight: var(--bp-weight-strong);
+    margin: 0;
+  }
+  :where(.wp-head__sub) {
+    font-size: var(--bp-text-small);
+    color: var(--bp-text-secondary);
+    margin: 2px 0 0;
+  }
+  :where(.wp-stats) {
+    display: flex;
+    gap: var(--bp-space-4);
+    margin: 0;
+  }
+  :where(.wp-stat) { text-align: right; }
+  :where(.wp-stat__k) {
+    display: block;
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+    text-transform: uppercase;
+    color: var(--bp-text-secondary);
+  }
+  :where(.wp-stat__v) {
+    display: block;
+    margin-top: 2px;
+    font-variant-numeric: tabular-nums;
+    font-size: var(--bp-text-h4);
+    font-weight: var(--bp-weight-medium);
+  }
+
+  /* ---- toolbar: built-in view selector + gantt unit toggle ---- */
+  :where(.wp-toolbar) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--bp-space-3);
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: var(--bp-space-3);
+  }
+  :where(.wp-modes) { display: flex; flex-wrap: wrap; gap: var(--bp-space-1); }
+  :where(.wp-modes--unit) { margin-left: auto; }
+  :where(.wp-modes__btn) {
+    font: inherit;
+    font-size: var(--bp-text-small);
+    line-height: 1;
+    padding: var(--bp-space-1) var(--bp-space-3);
+    border: 1px solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    color: var(--bp-text-secondary);
+    cursor: pointer;
+  }
+  :where(.wp-modes__btn):hover { background: var(--bp-fill-amb); }
+  :where(.wp-modes__btn[aria-selected="true"]) {
+    border-color: var(--bp-ink);
+    color: var(--bp-text);
+    background: var(--bp-fill-amb);
+  }
+
+  /* ---- type badge (inline mono, not a pill) ------------------- */
+  :where(.wp-type) {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    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);
+    white-space: nowrap;
+  }
+  :where(.wp-type__glyph) { color: var(--bp-ink-soft); flex: none; }
+  :where(.wp-type__label) { line-height: 1; }
+
+  /* ---- phase dot (status without color) ----------------------- */
+  :where(.wp-dot) {
+    --d: 10px;
+    width: var(--d);
+    height: var(--d);
+    border-radius: var(--bp-radius-0);
+    flex: none;
+    box-sizing: border-box;
+  }
+  :where(.wp-dot--done) { background: var(--bp-ink); }
+  :where(.wp-dot--active) {
+    background: var(--bp-ink);
+    box-shadow: 0 0 0 2px var(--bp-paper), 0 0 0 3px var(--bp-ink);
+  }
+  :where(.wp-dot--ready) {
+    background: oklch(0 0 0 / 0);
+    border: 1.5px solid var(--bp-ink-soft);
+  }
+  :where(.wp-dot--blocked) {
+    background: oklch(0 0 0 / 0);
+    border: 1.5px dashed var(--bp-ink-faint);
+  }
+
+  /* ---- PR status — inline mono text, NO pill ------------------ */
+  :where(.wp-pr) {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-md);
+    letter-spacing: 0.01em;
+    color: var(--bp-text-secondary);
+    white-space: nowrap;
+    min-width: 0;
+  }
+  :where(.wp-pr__glyph) { flex: none; width: 13px; height: 13px; }
+  :where(.wp-pr__num) { color: var(--bp-text); font-weight: var(--bp-weight-medium); }
+  :where(.wp-pr__ci) { color: var(--bp-text-secondary); }
+  :where(.wp-pr__diff) { color: var(--bp-text-secondary); }
+  :where(.wp-pr__add) { color: var(--bp-positive); }
+
+  :where(.wp-pr--passed .wp-pr__ci),
+  :where(.wp-pr--approved .wp-pr__ci) { color: var(--bp-positive); }
+  :where(.wp-pr--failed .wp-pr__glyph) { color: var(--bp-text); stroke-width: 1.8; }
+  :where(.wp-pr--running .wp-pr__glyph) {
+    color: var(--bp-ink-soft);
+    animation: wp-spin var(--bp-duration-spin) var(--bp-ease-linear) infinite;
+  }
+  @keyframes wp-spin { to { transform: rotate(360deg); } }
+  @media (prefers-reduced-motion: reduce) {
+    :where(.wp-pr--running .wp-pr__glyph) { animation: none; }
+  }
+
+  /* ---- owner mark — agent (square + spark) vs human (circle) -- */
+  :where(.wp-owner) {
+    display: inline-grid;
+    place-items: center;
+    width: 22px;
+    height: 22px;
+    flex: none;
+    font-family: var(--bp-mono);
+    font-size: 9px;
+    letter-spacing: 0.02em;
+  }
+  :where(.wp-owner--human) {
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-fill-hi);
+    border: 1px solid var(--bp-edge);
+    color: var(--bp-text-secondary);
+  }
+  :where(.wp-owner--agent) {
+    border-radius: var(--bp-radius-0);
+    border: 1px solid var(--bp-ink-line);
+    color: var(--bp-text-secondary);
+  }
+  :where(.wp-owner__glyph) { width: 12px; height: 12px; }
+
+  /* ---- waiting note — quiet inline text ----------------------- */
+  :where(.wp-wait) {
+    display: block;
+    font-size: var(--bp-text-small);
+    color: var(--bp-text-secondary);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  /* greyed-out-until-ready treatment, shared across views */
+  :where([data-locked="true"]) { opacity: 0.66; }
+
+  /* ---- LIST view ---------------------------------------------- */
+  :where(.wp-view--list) { display: grid; gap: var(--bp-space-3); }
+  :where(.wp-wave__head) {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: var(--bp-space-2);
+    margin-bottom: 6px;
+    padding: 0 2px;
+  }
+  :where(.wp-wave__no),
+  :where(.wp-wave__count) {
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-md);
+    letter-spacing: var(--bp-label-md-ls);
+    text-transform: uppercase;
+  }
+  :where(.wp-wave__no) { color: var(--bp-text); }
+  :where(.wp-wave__count) { color: var(--bp-text-secondary); }
+  :where(.wp-row) {
+    display: grid;
+    grid-template-columns: auto 84px minmax(0, 1fr) auto auto;
+    align-items: center;
+    gap: var(--bp-space-3);
+    padding: 11px var(--bp-space-3);
+    border: 1px solid var(--bp-edge);
+    border-top: none;
+    background: var(--bp-paper);
+  }
+  :where(.wp-row:first-child) {
+    border-top: 1px solid var(--bp-edge);
+    border-radius: var(--bp-radius-0) var(--bp-radius-0) 0 0;
+  }
+  :where(.wp-row:last-child) { border-radius: 0 0 var(--bp-radius-0) var(--bp-radius-0); }
+  :where(.wp-row__main) { position: relative; min-width: 0; }
+  :where(.wp-row__name) {
+    display: block;
+    font-size: var(--bp-text-body);
+    font-weight: var(--bp-weight-medium);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  /* Waiting note overlays the name and is revealed on hover, so a locked
+     row reads as its title at rest and its blockers on demand. */
+  :where(.wp-row__main .wp-wait) {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    margin: 0;
+    background: var(--bp-paper);
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity var(--bp-duration-fast) var(--bp-ease-out);
+  }
+  :where(.wp-row[data-locked="true"]:hover .wp-row__name) { opacity: 0; }
+  :where(.wp-row[data-locked="true"]:hover .wp-row__main .wp-wait) { opacity: 1; }
+  :where(.wp-row--done .wp-row__name) {
+    color: var(--bp-text-secondary);
+    text-decoration: line-through;
+    text-decoration-color: var(--bp-ink-faint);
+  }
+  :where(.wp-row__pr) { justify-self: end; }
+
+  /* ---- KANBAN view — min-width columns, horizontal scroll ----- */
+  :where(.wp-view--kanban) {
+    display: grid;
+    grid-auto-flow: column;
+    grid-auto-columns: minmax(216px, 1fr);
+    gap: var(--bp-space-3);
+    align-items: start;
+    overflow-x: auto;
+    padding-bottom: var(--bp-space-2);
+  }
+  :where(.wp-col) {
+    background: var(--bp-bg);
+    border: 1px solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    padding: var(--bp-space-2);
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+  }
+  :where(.wp-col__head) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 4px var(--bp-space-1) var(--bp-space-2);
+  }
+  :where(.wp-col__title) {
+    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);
+  }
+  :where(.wp-col__count) {
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    color: var(--bp-text-secondary);
+    font-variant-numeric: tabular-nums;
+  }
+  /* One full-width track — minmax(0,1fr) keeps cards at the column width
+     so nowrap text truncates instead of stretching the card. */
+  :where(.wp-col__body) {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--bp-space-2);
+    align-content: start;
+    min-width: 0;
+  }
+  :where(.wp-col__empty) {
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+    text-transform: uppercase;
+    color: var(--bp-ink-faint);
+    margin: var(--bp-space-1) 0 var(--bp-space-2);
+    padding-left: var(--bp-space-1);
+  }
+  :where(.wp-card) {
+    background: var(--bp-paper);
+    border: 1px solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    padding: 10px var(--bp-space-2);
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 7px;
+    min-width: 0;
+  }
+  :where(.wp-card__top) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+  :where(.wp-card__name) {
+    margin: 0;
+    font-size: var(--bp-text-small);
+    font-weight: var(--bp-weight-medium);
+    line-height: 1.35;
+  }
+  :where(.wp-card--done .wp-card__name) { color: var(--bp-text-secondary); }
+  :where(.wp-card__pr) { min-width: 0; overflow: hidden; }
+  :where(.wp-card__pr .wp-pr) { font-size: var(--bp-label-sm); max-width: 100%; }
+  :where(.wp-card__pr .wp-pr__ci) {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  :where(.wp-card__foot) {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--bp-space-2);
+    margin-top: 1px;
+  }
+  :where(.wp-card__wave) {
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+    text-transform: uppercase;
+    color: var(--bp-text-secondary);
+  }
+
+  /* ---- SWIMLANES view (type × wave grid) — single-line chips -- */
+  :where(.wp-view--swim) {
+    display: grid;
+    grid-template-columns: 120px repeat(var(--wp-waves), minmax(168px, 1fr));
+    gap: 1px;
+    background: var(--bp-edge);
+    border: 1px solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    overflow: hidden;
+  }
+  :where(.wp-swim__corner),
+  :where(.wp-swim__whead),
+  :where(.wp-swim__lanehead),
+  :where(.wp-swim__cell) { background: var(--bp-paper); padding: var(--bp-space-2); min-width: 0; }
+  :where(.wp-swim__corner),
+  :where(.wp-swim__whead) {
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+    text-transform: uppercase;
+    color: var(--bp-text-secondary);
+    background: var(--bp-bg);
+  }
+  :where(.wp-swim__lanehead) { background: var(--bp-bg); display: flex; align-items: center; }
+  :where(.wp-swim__cell) { display: grid; gap: 6px; align-content: start; }
+  :where(.wp-chip) {
+    display: grid;
+    gap: 5px;
+    padding: 7px 9px;
+    border: 1px solid var(--bp-edge);
+    border-radius: var(--bp-radius-0);
+    background: var(--bp-paper);
+    min-width: 0;
+  }
+  :where(.wp-chip__head) {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    align-items: center;
+    gap: 7px;
+  }
+  :where(.wp-chip__name) {
+    font-size: var(--bp-text-small);
+    font-weight: var(--bp-weight-medium);
+    line-height: 1.2;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  :where(.wp-chip--done .wp-chip__name) { color: var(--bp-text-secondary); }
+  :where(.wp-chip__pr) { min-width: 0; overflow: hidden; }
+  :where(.wp-chip__pr .wp-pr) { font-size: var(--bp-label-sm); max-width: 100%; }
+  :where(.wp-chip[data-locked="true"]) { border-style: dashed; }
+
+  /* ---- GANTT view (longest-path schedule) --------------------- */
+  :where(.wp-view--gantt) { display: grid; gap: 4px; }
+  :where(.wp-gantt__row) {
+    display: grid;
+    grid-template-columns: 264px 1fr;
+    gap: var(--bp-space-3);
+    align-items: center;
+  }
+  :where(.wp-gantt__label) {
+    display: grid;
+    grid-template-columns: 84px minmax(0, 1fr) auto;
+    gap: var(--bp-space-2);
+    align-items: center;
+    min-width: 0;
+  }
+  :where(.wp-gantt__name) {
+    font-size: var(--bp-text-small);
+    font-weight: var(--bp-weight-medium);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  :where(.wp-gantt__row--done .wp-gantt__name) { color: var(--bp-text-secondary); }
+  :where(.wp-gantt__track) {
+    position: relative;
+    height: 26px;
+    background: var(--bp-fill-amb);
+    border-radius: var(--bp-radius-0);
+    background-image: repeating-linear-gradient(
+      to right,
+      oklch(0 0 0 / 0) 0 calc(100% / var(--span, 10) - 1px),
+      var(--bp-edge) calc(100% / var(--span, 10) - 1px) calc(100% / var(--span, 10))
+    );
+  }
+  :where(.wp-gantt__bar) {
+    position: absolute;
+    top: 3px;
+    bottom: 3px;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 0 8px;
+    border-radius: var(--bp-radius-0);
+    border: 1px solid var(--bp-ink-line);
+    background: var(--bp-paper);
+    min-width: 28px;
+  }
+  :where(.wp-gantt__bar--done) { background: var(--bp-ink); border-color: var(--bp-ink); }
+  :where(.wp-gantt__bar--done .wp-gantt__bar-label),
+  :where(.wp-gantt__bar--done .wp-dot) { color: var(--bp-paper); }
+  :where(.wp-gantt__bar--done .wp-dot--done) { background: var(--bp-paper); }
+  :where(.wp-gantt__bar--active) { background: var(--bp-fill-hi); border-color: var(--bp-ink); }
+  :where(.wp-gantt__bar--blocked) { border-style: dashed; }
+  :where(.wp-gantt__bar-label) {
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: 0.02em;
+    color: var(--bp-text-secondary);
+  }
+  :where(.wp-gantt__track--axis) {
+    position: relative;
+    height: 18px;
+    background: none;
+    background-image: none;
+  }
+  :where(.wp-gantt__tick) {
+    position: absolute;
+    left: calc(var(--at) / var(--span) * 100%);
+    transform: translateX(-50%);
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    color: var(--bp-text-secondary);
+    font-variant-numeric: tabular-nums;
+  }
+  :where(.wp-gantt__label--axis) {
+    display: block;
+    font-family: var(--bp-mono);
+    font-size: var(--bp-label-sm);
+    letter-spacing: var(--bp-label-sm-ls);
+    text-transform: uppercase;
+    color: var(--bp-text-secondary);
+  }
+  :where(.wp-gantt__row--axis) { border-bottom: 1px solid var(--bp-edge); padding-bottom: 4px; }
+
+  /* ---- EMPTY / no-data state ---------------------------------- */
+  :where(.wp-empty) {
+    display: grid;
+    place-items: center;
+    gap: var(--bp-space-2);
+    text-align: center;
+    padding: var(--bp-space-6) var(--bp-space-4);
+    border: 1px dashed var(--bp-ink-line);
+    border-radius: var(--bp-radius-0);
+    background-color: var(--bp-fill-amb);
+    background-image: var(--bp-hatch);
+    color: var(--bp-text-secondary);
+  }
+  :where(.wp-empty__art) { color: var(--bp-ink-soft); margin-bottom: var(--bp-space-1); }
+  :where(.wp-empty__title) {
+    margin: 0;
+    font-size: var(--bp-text-h4);
+    font-weight: var(--bp-weight-strong);
+    color: var(--bp-text);
   }
-  :where(.fig-cap) {
-    font: 400 10px/1.4 var(--mono);
-    letter-spacing: 0.06em;
-    text-transform: uppercase;
-    color: var(--text-secondary);
-    text-align: center;
-    margin-top: 14px;
+  :where(.wp-empty__hint) { margin: 0; max-width: 42ch; font-size: var(--bp-text-small); }
+  :where(.wp-mono) { font-family: var(--bp-mono); font-size: 0.92em; }
+
+  /* ---- responsive: collapse the dense grids on narrow containers */
+  @container (max-width: 560px) {
+    :where(.wp-row) { grid-template-columns: auto minmax(0, 1fr) auto; }
+    :where(.wp-row .wp-type) { display: none; }
+    :where(.wp-row__pr) { grid-column: 2 / -1; justify-self: start; }
+    :where(.wp-gantt__row) { grid-template-columns: 1fr; gap: 4px; }
   }
 }
 
@@ -3107,6 +4058,29 @@
   :where(.bp-ease-overshoot) { transition-timing-function: var(--bp-ease-overshoot); }
   :where(.bp-ease-linear) { transition-timing-function: var(--bp-ease-linear); }
 
+  /* Theme flip — mute per-element transitions while the root crossfade runs.
+     TOC links, inputs, and other token-bound surfaces bake color motion into
+     @layer components; that fights the view transition the same way
+     .bp-transition-colors utilities do. blueprint.js sets
+     data-bp-theme-switching for the duration of startViewTransition().
+     Keep the data-attribute and typed selectors in separate rules — an
+     unknown :active-view-transition-type() in a comma list invalidates the
+     whole block in engines that lack typed View Transition selector support. */
+  html[data-bp-theme-switching] :where(*) {
+    transition-property: none;
+  }
+  html:active-view-transition-type(bp-theme) :where(*) {
+    transition-property: none;
+  }
+  html[data-bp-theme-switching] *::before,
+  html[data-bp-theme-switching] *::after {
+    transition-property: none;
+  }
+  html:active-view-transition-type(bp-theme) *::before,
+  html:active-view-transition-type(bp-theme) *::after {
+    transition-property: none;
+  }
+
   /* Responsive: keep section navigation reachable while collapsing the rail. */
   @media (max-width: 860px) {
     :where(.bp-sidebar, .bp-toc, .sidebar) {
@@ -3126,6 +4100,16 @@
       padding-bottom: var(--bp-space-1);
     }
     :where(.bp-sidebar li, .bp-toc li, .sidebar li) { flex: 0 0 auto; }
+    /* In the collapsed horizontal nav the group eyebrow rides inline as a
+       quiet separator ahead of its entries rather than a stacked header. */
+    :where(.bp-sidebar .bp-nav-group, .bp-toc .bp-nav-group) {
+      display: flex;
+      align-items: center;
+      margin: 0;
+    }
+    :where(.bp-nav-group__label) {
+      padding: var(--bp-space-1) var(--bp-space-2);
+    }
     /* 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; }
@@ -3133,7 +4117,7 @@
       background: var(--bp-fill-hi);
     }
     /* Rail is now on top; the sheet floats with a uniform margin. */
-    :where(html:has(.bp-shell)) {
+    :where(html[data-bp-document]) {
       --bp-shell-inset-block: var(--bp-space-3);
       --bp-shell-inset-top: var(--bp-shell-inset-block);
       --bp-shell-inset-left: var(--bp-space-3);
@@ -3145,26 +4129,29 @@
     :where(main, article) {
       padding: var(--bp-space-4) var(--bp-space-3);
     }
-    /* Edge-to-edge on phones — the float costs too much width here. */
-    :where(body:has(.bp-shell)) {
-      overflow: auto;
+    /* Edge-to-edge on phones — the desk float costs too much width here. */
+    :where(html[data-bp-document] body) {
+      padding-top: 0;
+      padding-bottom: 0;
     }
-    :where(.bp-shell) {
-      position: static;
-      inset: auto;
+    :where(html[data-bp-document] main) {
       margin: 0;
-      overflow: visible;
+      max-width: var(--bp-content);
+      min-height: 0;
       border: 0;
       border-radius: var(--bp-radius-0);
       box-shadow: none;
     }
-    :where(html:has(.bp-shell))::before,
-    :where(html:has(.bp-shell))::after,
-    :where(body:has(.bp-shell))::before,
-    :where(body:has(.bp-shell))::after {
+    :where(html[data-bp-document] main > *) {
+      max-width: none;
+    }
+    :where(html[data-bp-document])::before,
+    :where(html[data-bp-document])::after,
+    :where(html[data-bp-document] body)::before,
+    :where(html[data-bp-document] body)::after {
       content: none;
     }
-    :where(.bp-option-grid, .bp-state-grid, .bp-card-grid, .bp-layout) {
+    :where(.bp-card-grid, .bp-layout) {
       grid-template-columns: 1fr;
     }
     :where(.bp-content) {
@@ -3185,23 +4172,1061 @@
     :where(.bp-sidebar, .bp-toc, .sidebar, .scroll-progress, .bp-no-print) {
       display: none !important;
     }
-    :where(.bp-shell, .page-body, .sheet) { margin: 0; border: 0; border-radius: var(--bp-radius-0); box-shadow: none; }
-    :where(body:has(.bp-shell)) {
-      overflow: visible;
+    :where(html[data-bp-document] main, .page-body, .sheet) { margin: 0; border: 0; border-radius: var(--bp-radius-0); box-shadow: none; }
+    :where(html[data-bp-document] body) {
+      padding-top: 0;
+      padding-bottom: 0;
     }
-    :where(.bp-shell) {
-      position: static;
-      inset: auto;
+    :where(html[data-bp-document] main) {
+      min-height: 0;
       overflow: visible;
     }
-    :where(html:has(.bp-shell))::before,
-    :where(html:has(.bp-shell))::after,
-    :where(body:has(.bp-shell))::before,
-    :where(body:has(.bp-shell))::after {
+    :where(html[data-bp-document] main > *) {
+      max-width: none;
+    }
+    :where(html[data-bp-document])::before,
+    :where(html[data-bp-document])::after,
+    :where(html[data-bp-document] body)::before,
+    :where(html[data-bp-document] body)::after {
       content: none;
     }
-    :where(.bp-decision, .bp-callout, .bp-card, .bp-section, .bp-figure, figure, .bp-option-grid, details) {
+    :where(.bp-callout, .bp-card, .bp-section, .bp-figure, figure, details) {
       break-inside: avoid;
     }
   }
 }
+
+/* Shared document chrome. This stays separate in source so the docs site can
+   iterate on it independently, but the npm build appends it to the default
+   blueprint.css export because blueprint.js injects these runtime elements. */
+
+:root {
+  --bp-site-nav-height: 44px;
+}
+
+/* Only the pages that still use the top bar (e.g. the code demo) reserve
+   space for it. The main docs page drops it in favor of the sidebar
+   blueprint switcher + bottom-left theme toggle below. */
+body:has(.site-nav) {
+  padding-top: var(--bp-site-nav-height);
+}
+
+/* Frame and shell top inset align below the site nav. */
+html[data-bp-document]:has(.site-nav) {
+  --bp-shell-inset-top: calc(var(--bp-site-nav-height) + var(--bp-shell-inset-block));
+}
+
+.site-nav {
+  position: fixed;
+  inset: 0 0 auto;
+  z-index: 400;
+  display: flex;
+  align-items: stretch;
+  height: var(--bp-site-nav-height);
+  padding: 0 16px;
+  border-bottom: 1px solid var(--bp-edge);
+  background: var(--bp-paper);
+  color: var(--bp-text);
+  font-family: var(--bp-mono, var(--mono, ui-monospace, monospace));
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.site-nav__brand,
+.site-nav a {
+  display: flex;
+  align-items: center;
+  min-height: 0;
+  padding: 0 12px;
+  color: var(--bp-text-secondary);
+  text-decoration: none;
+}
+
+.site-nav__brand {
+  gap: 8px;
+  padding-left: 0;
+  color: var(--bp-ink);
+  font-weight: 650;
+  letter-spacing: 0.04em;
+  text-transform: none;
+}
+
+.site-nav__logo {
+  width: 20px;
+  height: 20px;
+  flex: 0 0 20px;
+  color: var(--bp-ink);
+}
+
+.site-nav__links {
+  display: flex;
+  align-items: stretch;
+  gap: 2px;
+  margin: 0 0 0 12px;
+  padding: 0;
+  list-style: none;
+}
+
+.site-nav__links > li {
+  display: flex;
+  margin: 0;
+  line-height: 1;
+}
+
+.site-nav a:hover,
+.site-nav a[aria-current="page"] {
+  color: var(--bp-ink);
+  background: var(--bp-fill-amb);
+}
+
+.site-nav a:focus-visible,
+.site-nav button:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: -2px;
+}
+
+body > .site-nav .site-nav__theme {
+  position: static;
+  inset: auto;
+  z-index: auto;
+  align-self: center;
+  margin: 0 0 0 auto;
+  padding: 6px 10px;
+  border: 1px solid var(--bp-ink);
+  border-radius: var(--bp-radius-0, 0);
+  background: oklch(0 0 0 / 0);
+  color: var(--bp-ink);
+  font-family: inherit;
+  font-size: inherit;
+  letter-spacing: inherit;
+  line-height: 1;
+  text-transform: uppercase;
+  cursor: pointer;
+}
+
+body > .site-nav .site-nav__theme:hover {
+  background: var(--bp-fill-amb);
+}
+
+/* The docs sidebar remains fixed, but begins below the global site nav. */
+.site-nav ~ .bp-sidebar {
+  top: var(--bp-site-nav-height);
+  height: calc(100vh - var(--bp-site-nav-height));
+}
+
+.site-nav + .scroll-progress {
+  position: fixed;
+  top: calc(var(--bp-site-nav-height)+ 4px);
+  right: 0;
+  left: 0;
+  height: 2px;
+  background: var(--bp-ink);
+  transform: scaleX(0);
+  transform-origin: left;
+  z-index: 500;
+  pointer-events: none;
+  transition: transform var(--bp-duration-instant) var(--bp-ease-linear);
+}
+
+@media (max-width: 560px) {
+  :root {
+    --bp-site-nav-height: 40px;
+  }
+
+  .site-nav {
+    padding: 0 8px;
+  }
+
+  .site-nav__brand {
+    padding: 0 8px 0 0;
+  }
+
+  .site-nav__wordmark {
+    display: none;
+  }
+
+  .site-nav__links {
+    margin-left: 0;
+  }
+
+  .site-nav a {
+    padding: 0 8px;
+  }
+
+  body > .site-nav .site-nav__theme {
+    padding: 6px 8px;
+  }
+}
+
+/* =====================================================================
+   Blueprint collection switcher (sidebar header) + bottom-left theme toggle
+   ---------------------------------------------------------------------
+   Docs chrome that replaces the old top bar: the sidebar wordmark becomes
+   a menu for jumping between blueprints, and the theme control becomes a
+   line icon pinned to the bottom-left corner.
+   ===================================================================== */
+
+/* Reset the library <details>/<summary> chrome for the switcher. */
+.doc-switcher {
+  position: relative;
+  margin: 0 0 var(--bp-space-3);
+  padding: 0;
+  border: 0;
+  background: none;
+}
+/* Shared field chrome for the switcher trigger and the search input so they
+   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);
+  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;
+}
+.sidebar-field:hover,
+.sidebar-field:focus-within {
+  border-color: var(--bp-ink-line);
+  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);
+}
+.doc-switcher__current {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--bp-space-3);
+  margin: 0;
+  /* Match the sidebar toggle box so the two controls align on one row. */
+  height: var(--bp-sidebar-toggle-size);
+  padding: 0 var(--bp-space-3);
+  list-style: none;
+  font-weight: 400;
+  cursor: pointer;
+}
+.doc-switcher__current::-webkit-details-marker {
+  display: none;
+}
+.doc-switcher__current::before {
+  content: none !important;
+}
+.doc-switcher__label {
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
+  min-width: 0;
+}
+.doc-switcher__title {
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+.doc-switcher__meta {
+  display: none;
+}
+.doc-switcher__chevron {
+  display: inline-flex;
+  flex: 0 0 auto;
+  color: var(--bp-text-secondary);
+}
+.doc-switcher[open] .doc-switcher__chevron {
+  transform: rotate(180deg);
+}
+.doc-switcher__menu {
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: calc(100% + var(--bp-space-1));
+  z-index: 300;
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
+  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);
+  background: var(--bp-paper);
+  box-shadow: var(--bp-shadow-pop);
+  transform-origin: top center;
+}
+/* Open animation: keyframes re-run every time [open] is set on the <details>,
+   unlike @starting-style which only fires on first render. Close stays instant
+   (native <details> hides content immediately). Timing uses motion tokens. */
+.doc-switcher[open] .doc-switcher__menu {
+  animation: bp-doc-switcher-in var(--bp-duration-normal) var(--bp-ease-out);
+}
+@keyframes bp-doc-switcher-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+.doc-switcher__menu a {
+  display: flex;
+  align-items: center;
+  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);
+  text-decoration: none;
+}
+.doc-switcher__menu a:hover {
+  background: var(--bp-fill-amb);
+}
+.doc-switcher__menu a.is-current {
+  background: var(--bp-fill-hi);
+}
+.doc-switcher__option {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+.doc-switcher__name {
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+.doc-switcher__desc {
+  overflow: hidden;
+  font-size: var(--bp-label-md);
+  line-height: 1.4;
+  color: var(--bp-text-secondary);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+/* Reused chevron as a quiet "go to" affordance — only on the current and
+   hovered rows so the resting menu stays clean and condensed. */
+.doc-switcher__go {
+  flex: 0 0 auto;
+  display: inline-flex;
+  color: var(--bp-text-secondary);
+  opacity: 0;
+  transform: rotate(-90deg);
+}
+.doc-switcher__menu a:hover .doc-switcher__go,
+.doc-switcher__menu a.is-current .doc-switcher__go {
+  opacity: 1;
+}
+
+/* Sidebar search — header row beside the corner toggle, above the header scrim. */
+.sidebar-search {
+  position: relative;
+  /* Sit above the header scrim (z 200) so the field stays crisp while the TOC
+     fades behind it. */
+  z-index: 300;
+  /* Left margin clears the fixed corner toggle so search sits on the same row,
+     beside it. Right edge stops at the content edge so it lines up with the
+     TOC entry pills below. */
+  margin: calc(-1 * var(--bp-space-2)) 0 var(--bp-space-3)
+    calc(var(--bp-sidebar-toggle-size) + var(--bp-space-3));
+}
+/* Trigger button: magnifier + label + ⌘K hint on one row. It is a <button>
+   (it opens the search dialog, it is not a text field); the .sidebar-field
+   chrome carries the border/radius/surface and children align inside it. */
+.sidebar-search__field {
+  display: flex;
+  align-items: center;
+  gap: var(--bp-space-2);
+  width: 100%;
+  height: var(--bp-sidebar-toggle-size);
+  padding: 0 var(--bp-space-3);
+  font: inherit;
+  text-align: left;
+  color: inherit;
+  cursor: pointer;
+  -webkit-appearance: none;
+  appearance: none;
+}
+.sidebar-search__field:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: 2px;
+}
+.sidebar-search__icon {
+  flex: 0 0 auto;
+  display: inline-flex;
+  color: var(--bp-text-secondary);
+}
+.sidebar-search__label {
+  flex: 1 1 auto;
+  min-width: 0;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: 400;
+  color: var(--bp-text-secondary);
+}
+/* ⌘K affordance — quiet keycaps, sized down from the base kbd for the rail. */
+.sidebar-search__hint {
+  flex: 0 0 auto;
+  display: inline-flex;
+  gap: 2px;
+}
+.sidebar-search__hint kbd {
+  padding: 0 4px;
+  border-width: 1px;
+  border-radius: var(--bp-radius-2, 2px);
+  font-size: var(--bp-label-md);
+  line-height: 1.5;
+  color: var(--bp-text-secondary);
+}
+
+/* =====================================================================
+   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 /
+   --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.
+   ===================================================================== */
+
+/* Modal scrim. Hidden until .is-open; centers the panel near the top of the
+   viewport, the way command palettes sit. Sits above all docs chrome. Uses
+   the same drafting scrim as .bp-lightbox (--bp-scrim + --bp-hatch). */
+.docs-search-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 600;
+  display: none;
+  justify-content: center;
+  align-items: flex-start;
+  padding: clamp(var(--bp-space-5), 12vh, var(--bp-space-7)) var(--bp-space-4)
+    var(--bp-space-4);
+  background-color: var(--bp-scrim);
+  background-image: var(--bp-hatch);
+}
+.docs-search-overlay.is-open {
+  display: flex;
+  animation: bp-search-overlay-in var(--bp-duration-fast, 120ms)
+    var(--bp-ease-out);
+}
+.docs-search-overlay.is-open .docs-search {
+  animation: bp-doc-switcher-in var(--bp-duration-normal) var(--bp-ease-out);
+}
+@keyframes bp-search-overlay-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+/* The panel. Position-agnostic: the overlay wrapper centers it over a scrim. */
+.docs-search {
+  display: flex;
+  flex-direction: column;
+  width: min(640px, 100%);
+  max-height: min(560px, 80vh);
+  overflow: hidden;
+  border: 1px solid var(--bp-edge);
+  border-radius: var(--bp-radius-8, 8px);
+  background: var(--bp-paper);
+  box-shadow: var(--bp-shadow-pop);
+}
+
+/* Search row */
+.docs-search__field {
+  display: flex;
+  align-items: center;
+  gap: var(--bp-space-3);
+  padding: var(--bp-space-3) var(--bp-space-4);
+  border-bottom: 1px solid var(--bp-edge);
+}
+.docs-search__icon {
+  flex: 0 0 auto;
+  display: inline-flex;
+  color: var(--bp-text-secondary);
+}
+.docs-search__input {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-body);
+  line-height: var(--bp-lh-body);
+  color: var(--bp-text);
+  -webkit-appearance: none;
+  appearance: none;
+}
+.docs-search__input::placeholder {
+  color: var(--bp-text-secondary);
+}
+.docs-search__input:focus {
+  outline: none;
+}
+.docs-search__input::-webkit-search-decoration,
+.docs-search__input::-webkit-search-cancel-button {
+  -webkit-appearance: none;
+}
+.docs-search__esc {
+  flex: 0 0 auto;
+  padding: 1px 6px;
+  font-size: var(--bp-label-md);
+  letter-spacing: var(--bp-label-md-ls);
+  text-transform: uppercase;
+  color: var(--bp-text-secondary);
+}
+
+/* Results region */
+.docs-search__results {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  padding: var(--bp-space-2);
+}
+/* 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);
+  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);
+}
+.docs-search__group-count {
+  color: var(--bp-text-secondary);
+  opacity: 0.7;
+}
+
+/* A result row: breadcrumb · title · snippet, with a trailing return key.
+   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);
+  cursor: pointer;
+  text-decoration: none;
+  color: inherit;
+}
+.docs-search__row:hover {
+  background: var(--bp-fill-amb);
+  text-decoration: none;
+}
+/* Keyboard-selected row — reuses the rail's "current" surface. */
+.docs-search__row[aria-selected="true"] {
+  background: var(--bp-fill-hi);
+  text-decoration: none;
+}
+.docs-search__row-main {
+  display: flex;
+  flex-direction: column;
+  gap: var(--bp-space-1);
+  min-width: 0;
+}
+.docs-search__crumb {
+  display: block;
+  font-family: var(--bp-mono);
+  font-size: var(--bp-label-md);
+  letter-spacing: var(--bp-label-md-ls);
+  color: var(--bp-text-secondary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.docs-search__title {
+  display: flex;
+  align-items: baseline;
+  gap: var(--bp-space-1);
+  min-width: 0;
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-small);
+  line-height: 1.3;
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+/* 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);
+}
+.docs-search__snippet {
+  overflow: hidden;
+  font-size: var(--bp-text-small);
+  line-height: 1.4;
+  color: var(--bp-text-secondary);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.docs-search__snippet mark {
+  padding: 0;
+  background: var(--bp-highlight);
+  color: var(--bp-text);
+}
+/* Return-key affordance — only on the selected/hovered row, like the
+   switcher's quiet "go to" chevron. */
+.docs-search__enter {
+  flex: 0 0 auto;
+  align-self: center;
+  padding: 1px 5px;
+  font-size: var(--bp-label-md);
+  color: var(--bp-text-secondary);
+  opacity: 0;
+}
+.docs-search__row:hover .docs-search__enter,
+.docs-search__row[aria-selected="true"] .docs-search__enter {
+  opacity: 1;
+}
+
+/* Empty state */
+.docs-search__empty {
+  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 {
+  font-family: var(--bp-sans);
+  font-size: var(--bp-text-small);
+  font-weight: var(--bp-weight-medium);
+  color: var(--bp-text);
+}
+.docs-search__empty-note {
+  font-size: var(--bp-text-small);
+  color: var(--bp-text-secondary);
+}
+
+/* Footer keyboard legend */
+.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);
+}
+.docs-search__keys {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--bp-space-1) var(--bp-space-3);
+}
+.docs-search__key {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--bp-space-1);
+}
+.docs-search__foot kbd {
+  padding: 0 4px;
+  border-width: 1px;
+  border-radius: var(--bp-radius-2, 2px);
+  font-size: var(--bp-label-md);
+  line-height: 1.5;
+  color: var(--bp-text-secondary);
+}
+
+/* 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
+   colliding with the footer. The bottom band stays solid to back the footer.
+   Interpolating `in oklch` is premultiplied, so a plain `oklch(0 0 0 / 0)` stop
+   fades cleanly (the zero-alpha endpoint contributes no colour, no muddy
+   mid-tone) — and our rail bg is achromatic, so no same-colour stop is needed.
+   The plain gradient syntax stays as the fallback for engines without oklch
+   gradient interpolation. */
+:root {
+  /* Shared square control size for the corner toggle, doc-switcher trigger,
+     theme switch, and scrim geometry — one token keeps every calc in sync. */
+  --bp-sidebar-toggle-size: 30px;
+  /* Content column inset — toggle, TOC pills, switcher, and footer share one
+     left/right edge so the rail reads as an even column. */
+  --bp-sidebar-content-inset: calc(var(--bp-space-4) + var(--bp-space-3));
+  /* Frame line → chrome row: same gap below the top line and above the bottom. */
+  --bp-sidebar-chrome-gap: var(--bp-space-3);
+  --bp-sidebar-chrome-inset-top: calc(
+    var(--bp-shell-inset-top, var(--bp-space-4)) + var(--bp-sidebar-chrome-gap)
+  );
+  --bp-sidebar-chrome-inset-bottom: calc(
+    var(--bp-shell-inset-block, var(--bp-space-4)) + var(--bp-sidebar-chrome-gap)
+  );
+  --bp-sidebar-footer: calc(
+    var(--bp-sidebar-chrome-inset-bottom) + var(--bp-sidebar-toggle-size)
+  );
+  /* Scroll clearance: footer band + breathing room for the last TOC pill. */
+  --bp-sidebar-scroll-padding-bottom: calc(
+    var(--bp-sidebar-footer) + var(--bp-space-4)
+  );
+  --bp-sidebar-fade: linear-gradient(
+    to top,
+    var(--bp-bg) var(--bp-sidebar-footer),
+    oklch(0 0 0 / 0)
+  );
+
+  /* Header counterpart: a circular scrim centred on the corner toggle so the
+     TOC dissolves *around* the icon as it scrolls up under it — radiating from
+     the icon rather than a flat top edge. Centre = toggle inset + half its box.
+     Solid out to --bp-space-4, then fades over --bp-space-6. */
+  --bp-sidebar-header-scrim: calc(
+    var(--bp-sidebar-icon-center) + var(--bp-space-4) + var(--bp-space-6)
+  );
+  --bp-sidebar-icon-center: calc(
+    var(--bp-sidebar-chrome-inset-top) + var(--bp-sidebar-toggle-size) / 2
+  );
+  --bp-sidebar-icon-fade: radial-gradient(
+    circle at var(--bp-sidebar-icon-center) var(--bp-sidebar-icon-center),
+    var(--bp-bg) var(--bp-space-4),
+    oklch(0 0 0 / 0) calc(var(--bp-space-4) + var(--bp-space-6))
+  );
+}
+@supports (
+  background:
+    linear-gradient(in oklch, oklch(0.5 0.1 30), oklch(0.5 0.1 240))
+) {
+  :root {
+    --bp-sidebar-fade: linear-gradient(
+      in oklch to top,
+      var(--bp-bg) var(--bp-sidebar-footer),
+      oklch(0 0 0 / 0)
+    );
+    --bp-sidebar-icon-fade: radial-gradient(
+      in oklch circle at var(--bp-sidebar-icon-center)
+        var(--bp-sidebar-icon-center),
+      var(--bp-bg) var(--bp-space-4),
+      oklch(0 0 0 / 0) calc(var(--bp-space-4) + var(--bp-space-6))
+    );
+  }
+}
+
+/* Sidebar footer: the theme switch and the author/date block read as two flex
+   items with space between them, spanning the same band as the TOC entries
+   (left edge on the pill, right edge at the rail's content edge). */
+.sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--bp-space-3);
+}
+
+/* Author / date metadata — grouped as the footer's right-hand flex item. */
+.sidebar-meta {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--bp-space-4);
+}
+.sidebar-meta__item {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+.sidebar-meta__item .bp-meta {
+  margin: 0;
+  line-height: 1.25;
+}
+.sidebar-meta__item .bp-note {
+  margin: 0;
+  line-height: 1.35;
+}
+
+/* Leave room at the bottom of the rail so the last entry clears the footer. */
+.bp-sidebar {
+  --bp-theme-toggle-height: var(--bp-sidebar-toggle-size);
+  padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+}
+
+/* Bottom-left theme switch (Iconoir half-moon / light-bulb). Scoped to the
+   sidebar so the code demo's in-nav theme button is unaffected. */
+.bp-sidebar .theme-toggle {
+  /* A flex child of .sidebar-footer; relative so the thumb anchors to it. */
+  position: relative;
+  flex: 0 0 auto;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  align-items: center;
+  width: 54px;
+  height: var(--bp-theme-toggle-height);
+  padding: 2px;
+  border: 1px solid var(--bp-edge);
+  border-radius: var(--bp-radius-6, 6px);
+  background: var(--bp-fill-amb);
+  color: var(--bp-text-secondary);
+  cursor: pointer;
+  transition: none;
+}
+.bp-sidebar .theme-toggle:hover {
+  border-color: var(--bp-ink-line);
+  background: var(--bp-paper);
+  transition:
+    border-color var(--bp-duration-fast) var(--bp-ease-out),
+    background-color var(--bp-duration-fast) var(--bp-ease-out),
+    color var(--bp-duration-fast) var(--bp-ease-out);
+}
+.bp-sidebar .theme-toggle:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: 2px;
+}
+.bp-sidebar .theme-toggle__thumb {
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  /* height − (2×border + 2×pad) keeps an even 2px gap on every side. */
+  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);
+  background: var(--bp-paper);
+  box-shadow: 0 1px 2px oklch(0 0 0 / 0.06);
+  pointer-events: none;
+}
+[data-obvious-theme="dark"] .bp-sidebar .theme-toggle__thumb {
+  transform: translateX(24px);
+}
+.bp-sidebar .theme-toggle svg {
+  display: block;
+}
+.bp-sidebar .theme-toggle__icon {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+:not([data-obvious-theme="dark"]) .bp-sidebar .theme-toggle__icon--moon,
+[data-obvious-theme="dark"] .bp-sidebar .theme-toggle__icon--bulb {
+  color: var(--bp-ink);
+}
+
+/* =====================================================================
+   Sidebar collapse toggle (Iconoir sidebar glyph, pinned top-left)
+   ---------------------------------------------------------------------
+   Docs chrome that hides/shows the fixed contents rail, like the doc
+   switcher and theme toggle above. It lives on <body> (not inside the
+   rail) so it stays reachable once the rail is gone. The collapsed-state
+   rules are unlayered author CSS, so they win over blueprint.css per the
+   specificity contract. The whole rail slides as one rigid unit — its scrims
+   + footer ride along (no opacity tricks), and the sheet trails one space-4
+   behind the rail's edge the entire way (shared duration + easing).
+   ===================================================================== */
+.sidebar-toggle {
+  position: fixed;
+  /* Same offset from the top frame line as the footer keeps from the bottom. */
+  top: var(--bp-sidebar-chrome-inset-top);
+  left: var(--bp-sidebar-content-inset);
+  z-index: 320;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--bp-sidebar-toggle-size);
+  height: var(--bp-sidebar-toggle-size);
+  padding: 0;
+  border: 1px solid var(--bp-edge);
+  border-radius: var(--bp-radius-6, 6px);
+  background: var(--bp-fill-amb);
+  color: var(--bp-text-secondary);
+  cursor: pointer;
+  transition: none;
+}
+.sidebar-toggle:hover {
+  border-color: var(--bp-ink-line);
+  background: var(--bp-paper);
+  color: var(--bp-ink);
+  transition:
+    border-color var(--bp-duration-fast) var(--bp-ease-out),
+    background-color var(--bp-duration-fast) var(--bp-ease-out),
+    color var(--bp-duration-fast) var(--bp-ease-out);
+}
+.sidebar-toggle:focus-visible {
+  outline: 2px solid var(--bp-ink);
+  outline-offset: 2px;
+}
+.sidebar-toggle__icons {
+  position: relative;
+  display: block;
+  width: 16px;
+  height: 16px;
+}
+.sidebar-toggle__icon {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+.sidebar-toggle__icon--collapse {
+  opacity: 1;
+}
+.sidebar-toggle__icon--expand {
+  opacity: 0;
+}
+[data-sidebar="collapsed"] .sidebar-toggle__icon--collapse {
+  opacity: 0;
+}
+[data-sidebar="collapsed"] .sidebar-toggle__icon--expand {
+  opacity: 1;
+}
+.sidebar-toggle svg {
+  display: block;
+}
+
+@media (min-width: 861px) {
+  /* Top padding lives on the panel (space-6 aligns the search row with the
+     fixed corner toggle); zero the shell's own top padding so it isn't added
+     on top, which would push the search below the toggle. */
+  .bp-sidebar {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    padding-top: 0;
+    padding-bottom: 0;
+    padding-inline: 0;
+  }
+
+  /* The panel scrolls; padding-bottom reserves the fixed footer band so every
+     TOC entry can scroll fully into view above it. scroll-padding-bottom keeps
+     browser-managed scroll (keyboard focus, scrollIntoView, find-in-page) from
+     landing a near-bottom entry under the fixed footer overlay. Horizontal
+     padding aligns the TOC pills with the fixed corner toggle. */
+  .bp-sidebar__panel {
+    flex: 1 1 auto;
+    min-height: 0;
+    height: auto;
+    overflow-x: hidden;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    -webkit-overflow-scrolling: touch;
+    padding-top: var(--bp-space-6);
+    padding-inline: var(--bp-sidebar-content-inset);
+    padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+    scroll-padding-bottom: var(--bp-sidebar-scroll-padding-bottom);
+  }
+
+  /* Drop the switcher below the header scrim (search stays above it on z 300). */
+  .doc-switcher {
+    margin-top: max(
+      0px,
+      calc(
+        var(--bp-sidebar-header-scrim) - var(--bp-space-6) + var(--bp-space-2) -
+          var(--bp-sidebar-toggle-size) - var(--bp-space-3) + var(--bp-space-2)
+      )
+    );
+  }
+
+  /* The rail slides as one unit. At rest transform is none, so the fixed scrims
+     (::before/::after) + footer stay viewport-anchored for the scroll dissolve;
+     during the slide a non-none transform makes the rail their containing block,
+     so they ride along with it (their %-based geometry resolves against the
+     rail's own width, which is identical math — see the footer rule below).
+     Transition only after bp-sidebar-animate is set (index.html) to skip first
+     paint; visibility flips at the end so the rail leaves the tab order. */
+  html.bp-sidebar-animate .bp-sidebar {
+    transition:
+      transform var(--bp-duration-slow) var(--bp-ease-in-out),
+      visibility var(--bp-duration-slow);
+  }
+  [data-sidebar="collapsed"] .bp-sidebar {
+    transform: translateX(-100%);
+    visibility: hidden;
+    pointer-events: none;
+  }
+
+  /* The sheet reclaims the rail's width in step with the slide. <main> is laid
+     out with margin-inline (blueprint.css shell rules), not `left`, so the
+     reclaim must transition margin — transitioning `left` on a static box was a
+     no-op, which made the sheet snap while the rail slid. Same duration/easing
+     as the rail + frame line so all three move as one. Gated on
+     bp-sidebar-animate so it never fires on first paint. */
+  html.bp-sidebar-animate[data-bp-document] main {
+    transition: margin var(--bp-duration-slow) var(--bp-ease-in-out);
+  }
+  html.bp-sidebar-animate[data-bp-document]::after {
+    transition: background-position var(--bp-duration-slow) var(--bp-ease-in-out);
+  }
+
+  /* Footer pins to the bottom of the rail, spanning the TOC band: left edge on
+     the entry pill (content edge) and right edge at the rail's content edge. */
+  .sidebar-footer {
+    position: fixed;
+    left: var(--bp-sidebar-content-inset);
+    right: calc(100% - var(--bp-sidebar) + var(--bp-sidebar-content-inset));
+    bottom: var(--bp-sidebar-chrome-inset-bottom);
+    z-index: 300;
+  }
+
+  /* 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 {
+    content: "";
+    position: fixed;
+    left: 0;
+    bottom: 0;
+    width: var(--bp-sidebar);
+    height: calc(var(--bp-sidebar-footer) + var(--bp-space-4));
+    background: var(--bp-sidebar-fade);
+    pointer-events: none;
+    z-index: 200;
+  }
+
+  /* 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 {
+    content: "";
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: var(--bp-sidebar);
+    height: var(--bp-sidebar-header-scrim);
+    background: var(--bp-sidebar-icon-fade);
+    pointer-events: none;
+    z-index: 200;
+  }
+
+  /* Collapsed: the rail (slid out via the rule above) vacates its width and the
+     sheet reclaims it, trailing one space-4 behind the rail's edge throughout. */
+  [data-sidebar="collapsed"][data-bp-document] {
+    --bp-shell-inset-left: var(--bp-space-4);
+  }
+}
+
+/* Below the rail's fixed breakpoint it becomes a static horizontal nav,
+   where collapsing has no meaning — hide the control entirely. */
+@media (max-width: 860px) {
+  .sidebar-toggle {
+    display: none;
+  }
+}
+
+@media print {
+  body {
+    padding-top: 0;
+  }
+
+  .site-nav,
+  .bp-sidebar .theme-toggle,
+  .sidebar-toggle {
+    display: none;
+  }
+}