basalt-ui 1.29.2 → 1.30.0

package/src/shell/app-sidebar.module.css

@@ -142,12 +142,50 @@
 
 /* Re-apply the bled inset INSIDE the viewport, so rows keep their exact 10px/10px column while the
  * bar floats clear of them in the gutter. Static padding, not Mantine's `offsetScrollbars`: the
- * latter pads only while overflowing, which reflows the rows the moment a section expands. */
+ * latter pads only while overflowing, which reflows the rows the moment a section expands.
+ *
+ * `padding-block-end` is the scroll END-STOP: with only the inline inset, an overflowing column
+ * cut its last row flush against the viewport edge, which reads as a label whose list is CLIPPED
+ * rather than as something that scrolls. One `region-gap` of air below the last row is the same
+ * number the search slot opens at the column's other end.
+ *
+ * The end-stop is necessary and NOT sufficient, and the mask below is the other half. MEASURED at
+ * 1512x945 with the playground's nav: `.navScroll` is `flex: 1; min-height: 0` between the search
+ * slot and a `flex-shrink: 0` footer, so any nav taller than the leftover column overflows — and
+ * the end-stop only pads the BOTTOM OF THE CONTENT, which the reader sees exactly once, at the
+ * scroll end. Everywhere else the viewport's own edge cuts whatever row happens to cross it, and
+ * `.footer`'s progress block starts one `region-gap` under that cut. Two hard edges 12px apart:
+ * the column reads BROKEN rather than scrolled. Nothing else says otherwise, because the
+ * ScrollArea is `type="hover"` — at rest there is no bar at all.
+ *
+ * So: a scroll fade on the viewport's bottom edge, and deliberately NOT the other candidate, a
+ * `--vx-divider` seam on `.footer`. A rule there would answer a question nobody asked — the footer
+ * boundary is already carried by its own `padding-top` and the account row's inset (see `.footer`
+ * below) — and it would answer the real one WRONG: a hairline drawn across a row that is severed
+ * mid-glyph makes the severing crisper, not legible. A fade is the only one of the two that says
+ * "there is more, and it moves". It also keeps this module out of `theme/divider-law.test.ts`'s
+ * inventory, which is the correct outcome and not a dodge: that ledger exists so every hairline is
+ * a line someone chose, and this one would have been chosen to stand in for a scrollbar.
+ *
+ * The ramp is one `region-gap` tall, which is what pairs it with the end-stop instead of fighting
+ * it: at the scroll END those 12px hold the end-stop's padding — empty — so the last row lands
+ * fully opaque, and a column that does not overflow fades nothing but its own trailing air. Only
+ * mid-scroll, where a real row crosses the edge, does the fade have anything to dim.
+ *
+ * `black`/`transparent` here are alpha, not color: a mask reads only the alpha channel, so these
+ * carry no design meaning and deliberately are NOT `--vx-*` tokens. Do not route them through the
+ * palette in a token sweep. */
 .navViewport {
   padding-inline-end: var(--vx-space-row-inset-x);
+  padding-block-end: var(--vx-space-sidebar-region-gap);
+  mask-image: linear-gradient(
+    to bottom,
+    black calc(100% - var(--vx-space-sidebar-region-gap)),
+    transparent
+  );
 }
 
-/* Sections separate by SPACING only — 15px between sections, nothing above the first (the brand
+/* Sections separate by SPACING only — 16px between sections, nothing above the first (the brand
  * band's centred `min-height` already opens the region's air, and the optional search slot's own
  * `padding-block` opens more when it renders). */
 .nav > div + div {
@@ -156,9 +194,24 @@
 
 /*
  * Footer region — no border; the account row's own top padding supplies the separation.
+ *
+ * The region owns its own air on both axes, because the `Stack` wrapping it is `gap={0}`
+ * (`app-sidebar.tsx`) — the footer's rhythm is single-sourced HERE, so the whole answer is
+ * readable in one place rather than split between a prop and a stylesheet. Without it a
+ * bottom-placed block (a `kind: 'progress'` block defaults to `'bottom'`) stacked FLUSH on the
+ * settings and account rows and on the scroll region above, which is the "cramped" footer.
+ *
+ * `region-gap` (12) above the cluster, `stack-sm` (8) between its parts — deliberately tighter
+ * than the nav's `section-gap` (16): the footer is ONE pinned cluster whose rows belong together,
+ * not a list of peer sections.
  */
 .footer {
   flex-shrink: 0;
+  padding-top: var(--vx-space-sidebar-region-gap);
+}
+
+.footer > * + * {
+  margin-top: var(--vx-space-stack-sm);
 }
 
 /*

package/src/shell/index.tsx

@@ -291,10 +291,6 @@ function collapseStore(key: string): () => readonly [boolean, (next: boolean) =>
   return store
 }
 
-// The shared inset for the shell padding and the header's inline padding, so the breadcrumb's
-// left edge and the global actions' right edge land on the card column's edges.
-const SHELL_INSET = 'sm' as const
-
 /**
  * The shell's two page-level regions are providers, and both wrap the frame rather than living
  * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
@@ -334,6 +330,30 @@ function ShellFrame({
   // (controls, the search trigger/avatar, nav labels) already track density, so a fixed literal
   // container squeezes progressively worse as density rises.
   const { step } = useBasaltSpacing()
+  // THE PAGE GUTTER, responsive — the shared inset for `AppShell`'s own padding and the header's
+  // inline padding, so the breadcrumb's left edge and the global actions' right edge land on the
+  // card column's edges. It used to be the literal `'sm'` spacing key, which is 13px at EVERY
+  // width: 13 on a 360px phone and 13 on a 2560px monitor, with no token behind it. Now it is the
+  // `appShellInset` / `appShellInsetMobile` pair (see their entries in `tokens/palette.ts`).
+  //
+  // On a 390px phone that is 8 a side instead of 13 — 10px more line width, and 10px less vertical
+  // chrome, since `padding` is Main's vertical inset too. From `sm` up it is 20, which is the x the
+  // sidebar's nav icon column already sits at, so the brand mark, the nav icons and the page's
+  // first column all start on one vertical line.
+  //
+  // VERIFIED against the installed Mantine 9.3 source, because both props take the object by a
+  // DIFFERENT road and both had to be checked:
+  //   - `AppShell padding`: `AppShellMediaStyles/assign-padding-variables.mjs` puts `base` in the
+  //     `:root` rule and every other key in `get-variables.mjs`'s MIN-width block
+  //     (`(min-width: <breakpoint>)`), so the pair is mobile-first and needs no max-width twin.
+  //   - `AppShell.Header px`: a Box style prop, `Box/style-props/parse-style-props.mjs` — same
+  //     `{ base, … }` shape, same `(min-width: theme.breakpoints.sm)` query, emitted on a generated
+  //     class. Both resolve `sm` from `theme.breakpoints`, so the two gutters step at one width.
+  // A NUMBER on either road is CONVERTED by Mantine's `rem()` — 8 becomes
+  // `calc(0.5rem * var(--mantine-scale))` — rather than looked up, which is exactly why these are
+  // numbers: a spacing KEY resolves to `var(--mantine-spacing-sm)` and hands the gutter back to
+  // Mantine's own scale, which is where the 13px came from.
+  const inset = { base: step.appShellInsetMobile, sm: step.appShellInset }
   const aside = useAsideRegion()
   const [storedCollapsed, setStoredCollapsed] = collapseStore(storageKey)()
   // Controlled/uncontrolled seam (item 19): an explicit `collapsed` prop overrides the internal
@@ -410,7 +430,7 @@ function ShellFrame({
       // A plain number, NOT a `calc(... + env(safe-area-inset-bottom))` string: Mantine's own
       // `.footer` rule already adds the inset to both the height and the padding (§2.7).
       footer={{ height: { base: step.mobileNavBarHeight, sm: 0 } }}
-      padding={SHELL_INSET}
+      padding={inset}
       // `mainClasses.shell` is not decoration — see its rule for why the root has to establish a
       // block formatting context now that Main is offset with margins.
       className={cx(mainClasses.shell, className)}
@@ -419,7 +439,7 @@ function ShellFrame({
       {/* Region seams (docs/DESIGN-SPEC.md §5, §8 #12): Mantine's `[data-with-border]` painted in
        * `--vx-divider` by the theme's `AppShell.extend({ vars })`. No shell module draws a region
        * edge; never opt a section back out of its border here. */}
-      <AppShell.Header px={SHELL_INSET}>
+      <AppShell.Header px={inset}>
         <div className={headerClasses.bar}>
           {/* The header's LEADING ZONE — exactly `--app-shell-navbar-offset` wide, so its trailing
            * edge lands on the sidebar|main seam and the breadcrumb after it starts on Main's own

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)}`
 }