basalt-ui 1.29.2 → 1.30.1

package/src/shell/mobile-nav-model.ts

@@ -9,9 +9,23 @@
  * The law it implements is the interaction model, not a heuristic: a slot is a DESTINATION, so a
  * tap navigates with no overlay to dismiss. An overlay exists only where a slot genuinely holds
  * more than one destination, and its surface is INFERRED from how many rows it holds rather than
- * configured — six rows is the arithmetic ceiling for a menu that pops out of a 56px bar without
- * ever rendering below the fold (6 x 44px + 8px padding = 272px against 415px of headroom on the
- * smallest supported viewport), so past that the surface becomes a bottom sheet.
+ * configured — up to `menuMax` rows it is a content-sized menu popping out of the tab, past that a
+ * bottom sheet.
+ *
+ * WHAT KEEPS THE MENU ABOVE THE FOLD IS CSS, NOT THIS CONSTANT. `.menuDropdown` declares
+ * `max-height: min(72dvh, 560px)` + `overflow-y: auto` + `overscroll-behavior: contain`, so the
+ * dropdown is bounded at ANY row count and scrolls inside itself past it. Measured at 390x844 the
+ * headroom above the bar is 772px (bar top 788, less the 8px menu offset and the 8px shift
+ * padding), so the 560px cap uses 73% of it; on the smallest supported viewport (320x568) the
+ * headroom is ~496px and 72dvh is 409px — the cap is binding on every supported phone, and the row
+ * count never is. The old arithmetic here ("6 x 44px + 8px padding against 415px of headroom") was
+ * stale in almost every number: rows are 40px (`--vx-space-mobile-nav-row-height`), the dropdown's
+ * own padding is `2 * --vx-space-stack-xs` = 8px, and the headroom figures above are the measured
+ * ones.
+ *
+ * `menuMax` therefore survives for the case a menu genuinely should not hold: a 30-destination nav
+ * still deserves a sheet, where a title, a close button and 62dvh of scroll read better than a
+ * tall popover hanging off one tab.
  */
 import type {
   MobileNavConfig,
@@ -29,11 +43,16 @@ import { sidebarBlockMobile } from './sidebar-block-model'
 export const MOBILE_MAX_TABS_DEFAULT = 5
 
 /**
- * Rows a slot may hold before it becomes a sheet instead of a menu. Arithmetic, not taste — see
- * the module doc: six rows is the last count a bottom-anchored, non-flipping menu fits above the
- * bar on the smallest supported viewport.
+ * Rows a slot may hold before it becomes a sheet instead of a menu.
+ *
+ * It was 6 on the theory that the count was what kept the menu above the fold. It is not — the
+ * dropdown's own `max-height` is (module doc), at every row count. What 6 actually did was flip
+ * the playground's ~11-row More slot into a full Drawer, which is the "big door on mobile" the
+ * owner reported. 12 keeps every realistic More surface a compact popover and leaves the sheet
+ * for the nav that has genuinely outgrown one. `mobileNav.menuMax` remains the consumer opt-out
+ * in both directions.
  */
-export const MOBILE_MENU_MAX_DEFAULT = 6
+export const MOBILE_MENU_MAX_DEFAULT = 12
 
 /** The overflow slot's reserved key. A slot like any other — it just exists only when needed. */
 export const MOBILE_MORE_KEY = '__more'
@@ -285,7 +304,13 @@ function sectionCandidate(section: SidebarSection, menuMax: number): Candidate {
           // The section's own identity wins when it declares one — the consumer configured the
           // SLOT — and falls back to the single destination's icon when it does not.
           icon: mobile?.icon ?? section.icon ?? only.icon,
-          active: hasActiveDestination(only),
+          // `isActiveDestination`, not the rollup — this collapse produced a LINK, and a link slot
+          // covers exactly the one key it navigates to, exactly as `itemCandidate` does. The two
+          // predicates agree TODAY (this branch needs `rows === 1`, `countRows` counts descendants,
+          // so `only` is childless whenever it is taken) — which is the point: activeness now reads
+          // the slot's own `covered` set instead of a non-local fact about what `rows === 1`
+          // implies. Widen the collapse and the rollup would light a tab whose tap lands elsewhere.
+          active: isActiveDestination(only),
           item: only,
         }
       }
@@ -474,7 +499,10 @@ export function projectMobileNav(
       label: only.label,
       short: only.short ?? only.label,
       icon: only.icon,
-      active: hasActiveDestination(only),
+      // Same as `sectionCandidate`'s collapse, for the same reason and with the same caveat: a
+      // LINK slot reads only the destination its tap reaches, and `rows === 1` makes the two
+      // predicates agree today — state the law locally rather than inherit it.
+      active: isActiveDestination(only),
       item: only,
     })
     return { slots }

package/src/shell/page-aside.module.css

@@ -49,12 +49,13 @@
 }
 
 /* The portalled form's band matches the SHELL-OWNED page-bar band exactly, whenever one is
- * present (`--basalt-page-bar-h`, `docs/DESIGN-SPEC.md` §5) — not a fixed 48px. `PageBar`
+ * present (`--basalt-page-bar-h`, `docs/DESIGN-SPEC.md` §5) — not a fixed header height. `PageBar`
  * publishes that var on `documentElement` from a ResizeObserver on the band's own content
  * (`shell/page-bar.tsx`), so it inherits down to every descendant, this header included, with no
  * extra wiring. Two seams, one line: MEASURED on `/cbbi` 1440x900, the band's outer edge (its own
  * `border-bottom`, `app-main.module.css` `.band:not(:empty)`) used to sit at y87 while this header
- * (unconditionally `var(--app-shell-header-height)`, 48px) sat at y96 — 9px apart.
+ * (unconditionally `var(--app-shell-header-height)`, 48px at the time — the token is 44 since the
+ * desktop-shell pass) sat at y96 — 9px apart.
  *
  * The `+ 1px` is not decorative. `--basalt-page-bar-h` measures the band's CONTENT box only (the
  * portalled row-2 wrapper `page-bar.tsx` attaches its ResizeObserver to); the band's own
@@ -63,9 +64,10 @@
  * under the page's global `box-sizing: border-box` reset — so its OWN `border-bottom` is absorbed
  * INSIDE whatever height is declared instead of adding on top. Feeding the raw var straight in
  * therefore undershoots by exactly the band's border: `calc(38px + 1px)` = 39px, matching the
- * band's true painted height, while the no-band fallback nets out unchanged (`calc((48px - 1px) +
- * 1px)` = 48px) because the same `+ 1px` also wraps that branch. Without a `PageBar` there is no
- * band seam to align to, so the header keeps closing the ordinary 48px top belt
+ * band's true painted height, while the no-band fallback nets out unchanged (`calc((44px - 1px) +
+ * 1px)` = 44px, reading today's `appShellHeaderHeight`) because the same `+ 1px` also wraps that
+ * branch. Without a `PageBar` there is no band seam to align to, so the header keeps closing the
+ * ordinary 44px top belt
  * (`docs/DESIGN-SPEC.md` §5) the header and sidebar-brand bands also close.
  */
 .panel[data-basalt-page-aside='shell'] .header {
@@ -81,7 +83,7 @@
 }
 
 /* A real title (docs/DESIGN-SPEC.md §5): mirrors `widget-header.module.css` `.heading` and the
- * breadcrumb's current-page treatment — the three 48px bands each carry one 550-weight head-font
+ * breadcrumb's current-page treatment — the three 44px bands each carry one 550-weight head-font
  * name. */
 .title {
   font-family: var(--basalt-font-head);

package/src/shell/page-bar.module.css

@@ -96,10 +96,15 @@
   margin-inline-end: var(--vx-space-control-gap);
 }
 
+/* Glyph BOX, 1.125rem — a decoration-class fixed size, deliberately NOT a `--vx-space-*` token
+ * (an icon is not a gap; the shipped icon set draws on a 24px grid and the box is a fraction of
+ * the type size, not of the spacing scale). Do not re-litigate these in a token sweep.
+ * 1.125rem rather than the old 1rem because `controlHeightCtl` grew 30 -> 32: a glyph held at
+ * 16px inside a 32px control reads EMPTIER, not bigger. */
 .row1 :global(.mantine-Button-section) > svg,
 .row1 :global(.mantine-ActionIcon-root) > svg {
-  width: 1rem;
-  height: 1rem;
+  width: 1.125rem;
+  height: 1.125rem;
 }
 
 /* Actions and sync are right-aligned; the lead (or the breadcrumb, in a shell) holds the left. */
@@ -114,21 +119,24 @@
 }
 
 /*
- * Row 2's rhythm is 8px · pills · 8px, NOT a 40px reserved row.
+ * Row 2's rhythm is 8px · pills · 8px, NOT a reserved row-height box.
  *
- * `min-height: var(--vx-space-page-bar-row-height)` (40px) left a 30px pill floating inside a 40px
- * box with the 5px above and below it belonging to nothing — and because the row sat in a `Stack`
- * that already spaced it, the visible gap between the header and the pills read as ~19px while the
- * gap from the pills to the first card read as ~19px too. Symmetric padding on the row itself is
- * one declaration owning both halves, so the sticky bar's published height covers exactly the band
- * it paints — including below `sm`, where `.row2` becomes a COLUMN of `.tabs` then `.pills` and
- * `padding-block` still owns both edges of the taller band.
+ * `min-height: var(--vx-space-page-bar-row-height)` was the defect, and the arithmetic is the whole
+ * reason it is gone. Measured when that token was 40 and `ctl` was 30: a 30px pill floated inside a
+ * 40px box with the 5px above and below it belonging to nothing — and because the row sat in a
+ * `Stack` that already spaced it, the visible gap between the header and the pills read as ~19px
+ * while the gap from the pills to the first card read as ~19px too. The desktop-shell pass has
+ * since moved both numbers (row height 40 -> 36, `ctl` 30 -> 32), which narrows that unowned band
+ * to 2px a side but does not close it: a HEIGHT token still hands its spare pixels to nobody.
+ * Symmetric padding on the row itself is one declaration owning both halves, so the sticky bar's
+ * published height covers exactly the band it paints — including below `sm`, where `.row2` becomes
+ * a COLUMN of `.tabs` then `.pills` and `padding-block` still owns both edges of the taller band.
  *
  * `stackXs` and not `stackSm`: the row sits inside the shell's own bordered band
  * (`app-main.module.css`'s `.band`), so it no longer has to carry the visual separation in
- * whitespace — 4px above and below a 30px `ctl` pill still clears it (38px total) and buys back 8px
+ * whitespace — 4px above and below a 32px `ctl` pill still clears it (40px total) and buys back 8px
  * of content on every page.
- * Row 1's 40px `--vx-space-page-bar-row-height` is untouched: it is a HEIGHT token, not padding.
+ * Row 1's 36px `--vx-space-page-bar-row-height` is untouched: it is a HEIGHT token, not padding.
  */
 .row2 {
   display: flex;

package/src/shell/page-bar.tsx

@@ -41,6 +41,9 @@ import asideClasses from './page-aside.module.css'
 /** The custom property row 2's measured height is published on. */
 export const PAGE_BAR_HEIGHT_VAR = '--basalt-page-bar-h'
 
+/** Dev-only diagnostics, constant-folded out of a production bundle — see {@link useAsidePanelSlot}. */
+const DEV = process.env['NODE_ENV'] !== 'production'
+
 /**
  * What a `PageAside` publishes when it projects itself into row 2 below `sm`
  * (`docs/ASIDE-SPEC.md` §0 "Desktop and mobile are one declaration"). Metadata only — the aside's
@@ -203,13 +206,36 @@ export function usePageKebabClaimed(): boolean {
  * Internal — the seam `PageAside` projects itself through below `sm` (`docs/ASIDE-SPEC.md` §0).
  * `host` says whether there is a row 2 to hang the pill off at all; `claim` publishes the aside's
  * title and glyph; `target` is the node inside the opened sheet its children portal into.
+ *
+ * It also carries THE ONE BRANCH NOBODY PREDICTS, as a dev-only warning. `PageBar` only claims the
+ * panel host when it renders a row 2 (`tabs`, `filters` or a non-empty `filtersEnd`), so a page
+ * whose bar has actions ALONE gets `host: false` — and below `sm` that aside silently stops being
+ * reachable: no pill, no sheet, just the in-flow form at the bottom of a scrolled page. The
+ * behaviour is deliberate (there is genuinely nowhere to hang a trigger) and pinned by
+ * `page-aside.test.tsx`, so this warns rather than changes it. Nothing about the page LOOKS wrong
+ * on the desktop the author is building on, which is exactly why it needs saying out loud.
+ *
+ * `settled` is why the warning is not a one-shot mount effect: `panelHost` is published by a LAYOUT
+ * effect inside `PageBar`, so on the first pass it is false on every page, including the ones that
+ * do host. Deferring by one commit — the same deferral `PageAside` runs for the same reason — is
+ * what keeps this from firing on every aside in the library.
  */
 export function useAsidePanelSlot(): {
   host: boolean
   claim: (panel: AsidePanelClaim) => () => void
   target: HTMLElement | null
 } {
-  const { panelHost, claimPanel, panelTarget } = useContext(PageBarContext)
+  const { panelHost, claimPanel, panelTarget, inShell } = useContext(PageBarContext)
+  const [settled, setSettled] = useState(false)
+  useIsomorphicLayoutEffect(() => {
+    setSettled(true)
+  }, [])
+  useEffect(() => {
+    if (!DEV || !settled || !inShell || panelHost) return
+    console.warn(
+      "[basalt] PageAside: this page's PageBar renders no row 2 (no `tabs`, no `filters`, no `filtersEnd`), so below `sm` there is no pill to open the aside — it renders in flow at the bottom of the page instead. Give the bar a row 2, or expect the in-flow form on a phone.",
+    )
+  }, [settled, inShell, panelHost])
   return { host: panelHost, claim: claimPanel, target: panelTarget }
 }
 
@@ -419,10 +445,18 @@ export function PageBar({
           )}
           {panel !== null && (
             <FilterPill
-              // One word, no count: unlike `Filters (n)` an aside has no census to count (its
-              // children are not a `FilterSet`), and a number nobody can derive is worse than none.
-              label="Panel"
-              ariaLabel={panel.title}
+              // THE ASIDE'S OWN TITLE, not the word "Panel" — the title names the CONTENT, never
+              // the region (`docs/ASIDE-SPEC.md` §0), which is the rule the desktop header already
+              // obeys by painting `panel.title` at the top of the region. A phone user reading
+              // "Panel" for an aside called "Inspector" or "Session detail" is being told which
+              // BOX it is, which they can see, instead of what is in it, which they cannot. The
+              // separate `ariaLabel` went with it: it existed only to put the real title back for a
+              // screen reader, so once the visible label IS the title the two would say the same
+              // thing twice.
+              //
+              // Still no count: unlike `Filters (n)` an aside has no census to count (its children
+              // are not a `FilterSet`), and a number nobody can derive is worse than none.
+              label={panel.title}
               icon={panel.icon}
               className={classes.panelPill}
               hideGlyph

package/src/shell/page-title.module.css

@@ -5,10 +5,12 @@
  * and every named spot reads identically regardless of which one a given surface uses.
  */
 
+/* Title over subtitle is the tightest pair the 4px vertical rhythm has a step for — `stack-xs`,
+ * not the literal 4px it duplicated. */
 .root {
   display: flex;
   flex-direction: column;
-  gap: 4px;
+  gap: var(--vx-space-stack-xs);
 }
 
 .titleRow {

package/src/theme/use-basalt-spacing.ts

@@ -22,12 +22,14 @@
  *    as the AppShell dimensions above (see `sidebarAccountMenuWidth`'s doc in `../tokens/palette`
  *    for why a fixed dropdown width needs to track density at all).
  *
- * Deliberately INTERNAL for now — exported from this module (so `../shell` can reach it) but NOT
- * re-exported by the root `.` barrel (`src/index.ts`), so it is not part of the published package
- * surface (same convention `scaleSpace`'s doc comment in `../tokens/palette` uses for the same
- * reason). These three `../shell` components are its only consumers today; promote it to the root
- * barrel — with a surface entry in this package's `CLAUDE.md` — if/when a consumer outside the
- * framework's own components needs the ACTIVE resolved spacing.
+ * PUBLIC since the desktop-shell spacing pass — re-exported by the root `.` barrel
+ * (`src/index.ts`), on exactly the trigger this doc used to name as the condition for promoting it:
+ * a consumer outside the framework's own components needs the ACTIVE resolved spacing. Laying its
+ * own chrome out beside the shell's — a sticky sub-header under the app header, a fixed rail beside
+ * the navbar — means matching numbers that are ALL JS-consumed (an AppShell dimension, a
+ * `<Menu width={…}>`), so unlike a CSS inset there is no `--vx-*` var to read them from instead;
+ * without this hook the consumer's only option was to hardcode the level-0 constants and silently
+ * desync at any other density.
  */
 import { useMantineTheme } from '@mantine/core'
 import { DEFAULT_SPACE_VALUES } from '../tokens/palette'

package/src/tokens/index.ts

@@ -556,8 +556,9 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-stack-xl', `${space.anchors.stackXl}px`),
     // The CSS-module spacing sweep's one-offs (docs/STATUS.md) — same single-source reasoning,
     // grouped to match `SPACE_STEP_BASE`'s own grouping in tokens/palette.ts.
-    // ONE value at every viewport since 1.26.0 — the AppShell header is a single 48px row (law
-    // C14), so the `-mobile` override of the old Decision-3 responsive pair is gone.
+    // ONE value at every viewport since 1.26.0 — the AppShell header is a single
+    // `appShellHeaderHeight` row (law C14), so the `-mobile` override of the old Decision-3
+    // responsive pair is gone.
     decl('space-sticky-header-clearance', `${space.step.stickyHeaderClearance}px`),
     decl('space-nav-icon-gap', `${space.step.navIconGap}px`),
     decl('space-sidebar-region-gap', `${space.step.sidebarRegionGap}px`),
@@ -634,6 +635,24 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-sidebar-child-list-indent', `${space.step.sidebarChildListIndent}px`),
     decl('space-sidebar-child-row-inset-y', `${space.step.sidebarChildRowInsetY}px`),
     decl('space-sidebar-child-row-indent', `${space.step.sidebarChildRowIndent}px`),
+    // The page gutter — the ONE `appShell*` dimension that IS emitted, against the JS-number-only
+    // rule its five neighbours follow (see the note at the bottom of this list). It earns the
+    // exception because it is the most visible spacing number the framework ships — every page's
+    // left edge — and it was, until now, the one number the `--vx-*` layer did not expose at all, so
+    // a consumer retuning its identity through `createBasaltTheme` could not reach it and had to
+    // reach past the token layer into `AppShell.Main`'s own styles. Emitted in PLAIN PX, like every
+    // other inset/gap in this list and unlike the `pxRem` heights above it: the rem-plus-
+    // `var(--mantine-scale)` reconstruction exists so a CONTROL's box tracks the root font size and
+    // Mantine's global scale knob; a page gutter is a layout margin against a viewport, not a box
+    // sized to text, so scaling it with the font would make a large-type user's content column
+    // narrower rather than more legible.
+    decl('space-app-shell-inset', `${space.step.appShellInset}px`),
+    decl('space-app-shell-inset-mobile', `${space.step.appShellInsetMobile}px`),
+    // The header's breadcrumb floor — emitted for the same reason as the gutter pair above it and
+    // not for the JS-number reason its `appShell*` neighbours below are withheld for: this one has
+    // a real CSS consumer (`shell/app-header.module.css`'s `.lead`), which is the whole test this
+    // list applies. Plain px, like every other layout dimension here.
+    decl('space-app-shell-header-lead-min', `${space.step.appShellHeaderLeadMin}px`),
     decl('space-mobile-nav-tab-gap', `${space.step.mobileNavTabGap}px`),
     decl('space-mobile-nav-icon-size', `${space.step.mobileNavIconSize}px`),
     decl('space-mobile-nav-tab-inset-y', `${space.step.mobileNavTabInsetY}px`),
@@ -651,6 +670,11 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-badge-inset-y', `${space.step.badgeInsetY}px`),
     decl('space-badge-inset-x', `${space.step.badgeInsetX}px`),
     decl('space-stat-card-gap', `${space.step.statCardGap}px`),
+    // The card/section inset ladder — the three values `spaceMobileDecls` below re-points at `< sm`
+    // (see its doc for where the law lives and why it lives there).
+    decl('space-card-inset-y', `${space.step.cardInsetY}px`),
+    decl('space-card-inset-x', `${space.step.cardInsetX}px`),
+    decl('space-section-gap', `${space.step.sectionGap}px`),
     decl('space-virtual-row-inset-y', `${space.step.virtualRowInsetY}px`),
     decl('space-virtual-row-inset-x', `${space.step.virtualRowInsetX}px`),
     // Controls tier row/gap heights (`docs/CONTROLS-SPEC.md` §5) — the current commit's consumers
@@ -666,7 +690,8 @@ function spaceDecls(space: SpaceValues): string[] {
     // `chartDotR`/`progressBarSize`/`timelineBullet` are DELIBERATELY absent — see this function's
     // doc for why (JS-number-only consumers, zero `var()` reads). `appShellHeaderHeight`/
     // `appShellNavbarWidth`/`appShellNavbarRailWidth`/`appShellAsideWidth`/`appShellAsideRailWidth`
-    // join that list —
+    // join that list — but NOT `appShellInset`/`appShellInsetMobile`/`appShellHeaderLeadMin`, which
+    // are emitted above and carry their own reason for the exception —
     // `shell/index.tsx` reads all five as JS numbers via `useBasaltSpacing()` (Mantine's `AppShell`
     // `header`/`navbar`/`aside` props take numbers, not `var()` strings), so a `--vx-space-app-shell-*`
     // decl here would have had zero consumers, framework-wide, the same dead-weight shape this function's
@@ -912,6 +937,54 @@ const indent = (block: string): string =>
     .map((line) => (line === '' ? line : `  ${line}`))
     .join('\n')
 
+/**
+ * The `< sm` breakpoint, written the way a stylesheet has to write it — the SAME literal every
+ * basalt CSS module spells (`shell/app-header.module.css`, `dashboard/section.module.css`, …), and
+ * for the same reason `BREAKPOINTS` above exists: a `@media` condition is resolved before custom
+ * properties exist, so the number cannot be a `var()`. Held here as a constant rather than inlined
+ * so the emitter and the modules can be grepped as one set.
+ */
+const MOBILE_MEDIA = '@media (max-width: 47.99375em)'
+
+/**
+ * The MOBILE INSET LADDER, and this function is its ONE home — framework-wide, not per module.
+ *
+ * The problem it answers: the desktop-shell pass took the page gutter from 20 to 8 below `sm`
+ * (`appShellInsetMobile`), and the card ladder INSIDE that gutter never moved — card insets stayed
+ * `xs`/`sm` and a `Section`'s gaps stayed `stackMd` at every width — so a 390px phone still read
+ * "content spacing too big" after the gutter fix. Two rungs close it: the card's horizontal inset
+ * steps `sm` -> `xs`, and the Section's gap steps `stackMd` -> `stackSm`.
+ *
+ * Why it lives HERE and not in the three CSS files that consume it: two of those three sites are
+ * INLINE styles in TSX (`dashboard/stat-card.tsx`, `charts/primitives/ChartCard.tsx`), and an
+ * inline style cannot carry a media query at all. The only surface that reaches all three is a
+ * custom property whose VALUE moves at the breakpoint, and the only stylesheet guaranteed present
+ * wherever those components render is this one — `BasaltProvider` injects `buildPaletteCss()`, and
+ * a component's own CSS module is loaded only if a bundler kept that module. So the law is one
+ * `@media` block emitted beside the base declarations it overrides, and every consuming site is a
+ * plain `var()` read with no breakpoint knowledge. A media query copied into three files (or into
+ * one component stylesheet reaching for `:global(:root)`) was the alternative, and it fails the
+ * same way twice: three copies drift, and one copy in a tree-shakeable module is a law that
+ * sometimes does not ship.
+ *
+ * This does NOT make the token layer responsive in general. It stays what `BREAKPOINTS`'s doc says
+ * it is — the layer that owns the NUMBER a media query has to write — and this is the one law whose
+ * consuming sites cannot write that query themselves. A dimension whose consumer is a CSS module
+ * keeps making the choice in that module (`appShellInset`/`appShellInsetMobile` still do).
+ */
+function spaceMobileDecls(space: SpaceValues): string[] {
+  return [
+    decl('space-card-inset-x', `${space.scale.xs}px`),
+    decl('space-section-gap', `${space.anchors.stackSm}px`),
+  ]
+}
+
+/** {@link spaceMobileDecls} as the `@media` block that overrides the base `:root` declarations —
+ *  same specificity, later in source order, so it wins below `sm` and nowhere else. */
+function mobileLadderBlock(space: SpaceValues): string {
+  return `${MOBILE_MEDIA} {\n  :root {\n${indent(spaceMobileDecls(space).join('\n'))}\n  }\n}`
+}
+
 /**
  * Emit the `--vx-*` stylesheet: a `:root` block of theme-independent scalars, then the
  * dark (default) and light primitive blocks under `html[data-mantine-color-scheme='…']`.
@@ -942,8 +1015,9 @@ export function buildPaletteCss(
 ): string {
   const groups = opts.groups ?? {}
   const legacyAliases = opts.legacyAliases ?? true
+  const only = opts.only ?? 'all'
   const extraDerived = (opts.derived ?? []).map((d) => `  ${d}`).join('\n')
-  const derivedBlock = frameworkDerived(data, opts.only ?? 'all', legacyAliases)
+  const derivedBlock = frameworkDerived(data, only, legacyAliases)
   const derived = extraDerived ? `${derivedBlock}\n${extraDerived}` : derivedBlock
   const side = (s: Side): string => {
     const extra = Object.entries(groups)
@@ -952,7 +1026,14 @@ export function buildPaletteCss(
     const framework = frameworkPrimitives(s, data, legacyAliases)
     return extra ? `${framework}\n${extra}` : framework
   }
-  const rootBlock = `:root {\n${derived}\n}`
+  // The scalars, then the ONE `@media` block that re-points two of them below `sm` (see
+  // `spaceMobileDecls`). Dropped under `only: 'core'` for the same reason the declarations it
+  // overrides are: both vars are component-named one-offs, not `SPACE` anchors, so a core-only
+  // consumer never receives the base pair the block exists to override.
+  const rootBlock =
+    only === 'core'
+      ? `:root {\n${derived}\n}`
+      : `:root {\n${derived}\n}\n${mobileLadderBlock(DEFAULT_SPACE_VALUES)}`
 
   // The legacy shape — kept verbatim, and only reachable when the caller asked for nothing.
   if (opts.scheme === undefined && opts.defaultScheme === undefined && !opts.mediaFallback) {
@@ -1073,5 +1154,8 @@ export function buildRadiusCss(radius: RadiusValues | undefined): string {
  */
 export function buildDensityCss(space: SpaceValues | undefined): string {
   if (!space) return ''
-  return `:root {\n${spaceDecls(space).join('\n')}\n}`
+  // The `< sm` ladder rides along, at the retuned level — without it a phone at `density: 2` would
+  // take the level-0 mobile inset from the static stylesheet and the level-2 base from this one,
+  // which is the only way the two rungs of one ladder could ever come from different levels.
+  return `:root {\n${spaceDecls(space).join('\n')}\n}\n${mobileLadderBlock(space)}`
 }

package/src/tokens/palette.ts

@@ -312,8 +312,15 @@ const SPACE_ANCHORS_BASE = {
   controlHeightWidget: 24,
   /** The `size="ctl"` Mantine tier's resolved height (`docs/CONTROLS-SPEC.md` §5, C5) —
    * `PageBar`/`Section`/table toolbar/sidebar-block controls. Floored at 28px in
-   * {@link deriveSpacing}. */
-  controlHeightCtl: 30,
+   * {@link deriveSpacing}.
+   *
+   * 32, up from 30. At 30 this tier was the ONLY chrome number in the shell that did not agree with
+   * its neighbours: the sidebar search trigger is 32 (`sidebarSearchTriggerHeight`), a sidebar block
+   * row is 32 (`sidebarBlockRowHeight`), and a NavLink row resolves to ~32 (`2 * rowInsetY +
+   * rowLineHeight * text.md`) — so a `size="ctl"` button sitting beside any of them read 2px short
+   * and the whole band looked unresolved. 32 lands the entire chrome tier on ONE number, which is
+   * also the smallest square that still holds a 16px icon with a 8px surround. */
+  controlHeightCtl: 32,
   /** The touch hit-area size (`::before`) every home control expands to below `sm` (C15,
    * `docs/CONTROLS-SPEC.md` §5) — independent of the visible `controlHeightCtl` box, same shape as
    * `mobileNavBarHeight`/`mobileNavRowHeight`'s Apple HIG 44pt / WCAG 2.5.5 floors elsewhere in this
@@ -378,7 +385,7 @@ const SPACE_STEP_BASE = {
   // literal could drift from that header, which is exactly what happened. `SpaceValues.step` still
   // carries the key — see that type's own doc — it is just not part of this BASE table. The
   // `stickyHeaderClearanceMobile` sibling went with the two-row mobile header in 1.26.0: the header
-  // is one 48px row at every viewport now, so one clearance covers both.
+  // is one `appShellHeaderHeight` row at every viewport now, so one clearance covers both.
   /** NavLink leftSection icon-to-label gap — shared by `theme/nav-link.module.css` (every render
    * path) and `shell/app-sidebar.module.css`'s own `.link` rule (belt-and-suspenders on the same
    * DOM), and reused verbatim for `.footerBtn`/`.accountRow`'s icon gap (their own doc comments call
@@ -386,8 +393,14 @@ const SPACE_STEP_BASE = {
   navIconGap: 10,
   /** Sidebar region-to-region gap: `.brand`'s bottom padding and `.searchSlot`'s bottom padding (in
    * both the expanded and collapsed rail variants) — the searchSlot comment explicitly says its gap
-   * opens the nav region "the same way the brand row's own bottom padding does". */
-  sidebarRegionGap: 10,
+   * opens the nav region "the same way the brand row's own bottom padding does".
+   *
+   * 12, up from 10. This is the ONE gap the sidebar spends at all three of its seams (brand → search,
+   * search → nav, nav → account), so it is what separates the column's regions from each other; at 10
+   * it was indistinguishable from the gaps WITHIN a region (`sidebarSectionLabelGap`, the child-list
+   * margins), and the column read as one undifferentiated list of rows. 12 is the first step that
+   * reads as a region break without opening a hole. */
+  sidebarRegionGap: 12,
 
   // ── content/prose.module.css ──────────────────────────────────────────────────────────────────
   /** Blockquote rail's own vertical inset. */
@@ -549,8 +562,11 @@ const SPACE_STEP_BASE = {
   // ── shell/app-sidebar.module.css (beyond the shared/reused anchors above) ────────────────────
   /** Brand row's horizontal inset. */
   sidebarBrandInsetX: 7,
-  /** Gap between nav sections. */
-  sidebarSectionGap: 12,
+  /** Gap between nav sections. Paired with `sidebarSectionLabelGap` below: together they are the
+   * section's proximity law — MORE space above a section label than below it, so the label reads as
+   * belonging to the list it heads. 16/6, up from 12/2: at 12 above and 2 below the pair was
+   * INVERTED, gluing each label to the last row of the section before it. */
+  sidebarSectionGap: 16,
   /** Account row's top inset. */
   sidebarAccountInsetTop: 9,
   /** Account row's horizontal inset. */
@@ -559,8 +575,10 @@ const SPACE_STEP_BASE = {
   sidebarAccountInsetBottom: 2,
   /** Identity-initials avatar block's fixed size (width and height). */
   sidebarAvatarSize: 28,
-  /** Section-label row's bottom gap (before the first nav row). */
-  sidebarSectionLabelGap: 2,
+  /** Section-label row's bottom gap (before the first nav row) — the smaller half of the
+   * proximity pair documented on `sidebarSectionGap` above. 6, up from 2: 2 was hairline enough that
+   * the label looked welded to the first row rather than titling the list. */
+  sidebarSectionLabelGap: 6,
   /** Collapsible child-list wrapper's top margin. */
   sidebarChildListGapTop: 2,
   /** Collapsible child-list wrapper's bottom margin. */
@@ -588,15 +606,22 @@ const SPACE_STEP_BASE = {
 
   // ── shell/index.tsx (AppShell dimensions) ──────────────────────────────────────────────
   /** AppShell desktop header bar height — sized to hold one row of `size="md"` controls, so it
-   *  tracks `controlHeight`. Its level-0 coincidence with `appShellNavbarRailWidth` below is a
-   *  coincidence, not a law: this is a horizontal bar's HEIGHT (governed by control height), that
-   *  is a vertical rail's WIDTH (governed by icon footprint). They stay separate entries. */
+   *  tracks `controlHeight`. It no longer coincides with `appShellNavbarRailWidth` below, which is
+   *  the point that entry's own note was always making: this is a horizontal bar's HEIGHT (governed
+   *  by control height), that is a vertical rail's WIDTH (governed by icon footprint). Two separate
+   *  entries, and now visibly so. */
   /** AppShell header bar height — ONE value at every viewport since 1.26.0 (law C14,
    *  `docs/CONTROLS-SPEC.md` §2.1). The pre-1.26.0 `appShellHeaderMobileHeight` (97) existed only
    *  because the mobile header wrapped to a second, always-reserved page-actions row; `PageBar`
    *  folds that row's overflow into a kebab and moves its filters/tabs into the page flow, so the
-   *  bar is 48px on a phone too and there is no sum to keep in step any more. */
-  appShellHeaderHeight: 48,
+   *  bar is one row on a phone too and there is no sum to keep in step any more.
+   *
+   *  44, down from 48. The band holds ONE `ctl`-tier row (32 since this pass), so 48 left 8px of
+   *  dead air above and below it — the "too much spacing at the top bar" the header reads as. 44
+   *  keeps 6px of breathing room a side, still clears `touchControlHeight` (36) below `sm` and
+   *  `controlHeight` (42) for a `size="md"` control, and is the Apple HIG 44pt figure the rest of
+   *  this table already floors its touch targets at. */
+  appShellHeaderHeight: 44,
   /** AppShell navbar width, expanded — ONE entry for both the `base` (mobile, where the navbar is
    *  permanently collapsed and unused — see `MobileNav`) and the expanded `sm` value: the same
    *  `.root` at full width, genuinely one concept.
@@ -608,8 +633,9 @@ const SPACE_STEP_BASE = {
    *  (`sidebarAccountMenuWidth` 220 + the row inset), so the menu no longer overhangs the column it
    *  belongs to. */
   appShellNavbarWidth: 256,
-  /** AppShell navbar width, collapsed icon rail. Separate from `appShellHeaderHeight` above
-   *  despite sharing 48 at level 0 (see that entry's note). */
+  /** AppShell navbar width, collapsed icon rail. Separate from `appShellHeaderHeight` above, which
+   *  used to share 48 at level 0 and no longer does (see that entry's note) — the two were always
+   *  independent concepts and the shared literal was only ever hiding it. */
   appShellNavbarRailWidth: 48,
   /** AppShell ASIDE width, unfolded — the right-hand panel region a route claims by rendering
    *  `PageAside` (`docs/ASIDE-SPEC.md` §0). ONE entry for every viewport, same reasoning as
@@ -624,6 +650,36 @@ const SPACE_STEP_BASE = {
    *  `appShellNavbarRailWidth` (48) on purpose: the navbar rail hosts a full icon nav row and its
    *  hover targets, this one hosts exactly one `ctl`-tier icon button and nothing else. */
   appShellAsideRailWidth: 36,
+  /** The PAGE GUTTER — `AppShell.Main`'s own horizontal inset, i.e. the distance from the sidebar
+   *  seam (and from the viewport's right edge) to the first pixel of page content. Unlike its
+   *  `appShell*` neighbours above this one IS emitted as a `--vx-*` var (see `spaceDecls`'s doc in
+   *  `tokens/index.ts` for why), because it is the single most visible spacing number the framework
+   *  ships and a consumer retuning its identity has to be able to reach it.
+   *
+   *  20, up from the 13 (`SPACE_SCALE.sm`) the main column used to borrow. The sidebar's nav ICON
+   *  column already sits at x=20 — 10px of `.root` frame inset plus 10px of NavLink inset
+   *  (`rowInsetX`) — and the brand row claims to align with it while sitting at 13. 20 makes that
+   *  claim true across the seam: brand mark, nav icons and the page's first column all start on one
+   *  vertical line, and the content gets a seam-side gutter that reads deliberate instead of
+   *  incidental. */
+  appShellInset: 20,
+  /** The page gutter BELOW `sm` — the phone half of `appShellInset` above. A separate entry rather
+   *  than one responsive value for the same reason `appShellNavbarWidth` is one: there is no sidebar
+   *  seam to align to on a phone, so the number is answering a different question (how much of a
+   *  390px viewport to spend on margin) and must be free to move alone.
+   *
+   *  8, down from the same borrowed 13. 13 a side spends 26 of 390px — 6.7% of the viewport — on
+   *  margin before a single card is drawn, which is the "content spacing is too big" a phone reads
+   *  as. 8 keeps the content off the bezel without competing with the cards' own insets. */
+  appShellInsetMobile: 8,
+  /** The app header's BREADCRUMB FLOOR — `shell/app-header.module.css`'s `.lead` `min-width`, the
+   *  width below which the row's one elastic side may not shrink. A step, not the raw `96px` it
+   *  shipped as: every other dimension of that row (its height, its control tier, its gaps) tracks
+   *  density, so a frozen floor would grow relatively narrower at every level up — and it is a floor
+   *  measured in CHARACTERS of the crumb (~13 at level 0), which is exactly the quantity that moves
+   *  when the type and the row around it move. The full derivation of 96 is on the `.lead` rule
+   *  itself; this entry only owns the number. */
+  appShellHeaderLeadMin: 96,
 
   // ── shell/app-mobile-nav.module.css ───────────────────────────────────────────────────────────
   /** Tab's icon-to-label gap. */
@@ -709,11 +765,48 @@ const SPACE_STEP_BASE = {
   /** `data/virtual-list.tsx`'s skeleton row horizontal inset. */
   virtualRowInsetX: 12,
 
+  // ── The card/section inset ladder (`tokens/index.ts`'s `spaceMobileDecls` is its ONE home) ────
+  // The three numbers a page's CONTENT spends on itself, as opposed to the shell gutter around it
+  // (`appShellInset`/`appShellInsetMobile` above). They are grouped, and named, because they step
+  // TOGETHER below `sm` — the gutter went 20 -> 8 in the desktop-shell pass while the ladder inside
+  // it never moved, so a 390px phone still read "content spacing too big" after the gutter fix.
+  //
+  // Each value is deliberately the rung of an existing ladder rather than a fresh literal: the card
+  // inset IS `SPACE_SCALE.xs`/`.sm` (which is what `StatCard`/`ChartCard` spelled as
+  // `--mantine-spacing-xs`/`-sm` before they were named here) and the Section gap IS
+  // `SPACE.stackMd`. Naming them buys the ROLE, not a new number — a role the `< sm` override can
+  // then re-point without touching the scale every other consumer of `xs`/`sm` reads.
+  //
+  // There is deliberately NO `*Mobile` sibling for the two that step, unlike `appShellInsetMobile`:
+  // that one is a separate entry because a phone gutter answers a different question from a desktop
+  // one (how much of 390px to spend on margin, with no sidebar seam to align to). These two answer
+  // the SAME question one rung down, so the override reads the neighbouring rung (`scale.xs`,
+  // `anchors.stackSm`) and a second literal would only be a place for the ladder to drift apart.
+  /** Card inset, VERTICAL — `dashboard/stat-card.tsx` and `charts/primitives/ChartCard.tsx`, which
+   *  must render identically (a StatCard and a ChartCard sit in the same grid row). Does NOT step
+   *  below `sm`: the phone is short of WIDTH, and shaving the vertical inset of a card that already
+   *  hugs its content buys a few pixels at the cost of the card's own breathing room. */
+  cardInsetY: 11,
+  /** Card inset, HORIZONTAL — same two files, same must-match reason. This IS the half that steps
+   *  below `sm` (to `SPACE_SCALE.xs`), because horizontal is where a 390px viewport is short. */
+  cardInsetX: 13,
+  /** `dashboard/section.module.css`'s header→body and body-child gap — a page-level GROUPING
+   *  rhythm, which is why it reads the stack scale rather than the card-inset one. Steps to
+   *  `SPACE.stackSm` below `sm`. Distinct from `sidebarSectionGap` above, which is the gap between
+   *  two NAV sections inside the sidebar column. */
+  sectionGap: 12,
+
   // ── Controls — homes/tiers (`docs/CONTROLS-SPEC.md` §5) ──────────────────────────────────────
   /** `PageBar` row height (row 1 or row 2, each measured independently — the bar's own overall
    *  height is the sum published as `--basalt-page-bar-h`, computed by `PageBar` itself, not a
-   *  static token). */
-  pageBarRowHeight: 40,
+   *  static token).
+   *
+   *  36, down from 40. Row 1 portals into a shell-owned band directly under the app header
+   *  (`shell/page-bar.tsx`), so the two stack as visible chrome: at 40 against a 44 header the
+   *  secondary row all but matched the primary one, and the eye could not tell which band owned the
+   *  page. 36 puts it a clear step below the header while still holding a 32px `ctl` row with 2px a
+   *  side. */
+  pageBarRowHeight: 36,
   /** `WidgetHeader tier="section"` row height. */
   sectionHeaderHeight: 36,
   /** `WidgetHeader tier="widget"` row height. */