basalt-ui 1.29.2 → 1.30.1

package/dist/tokens/palette.js

@@ -169,8 +169,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
@@ -194,7 +201,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
@@ -202,8 +209,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. */
   proseQuoteInsetY: 2,
@@ -354,8 +367,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. */
@@ -364,8 +380,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. */
@@ -391,15 +409,22 @@ const SPACE_STEP_BASE = {
   sidebarSettingsMenuWidth: 200,
   // ── 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.
@@ -411,8 +436,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
@@ -427,6 +453,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. */
   mobileNavTabGap: 3,
@@ -507,11 +563,47 @@ const SPACE_STEP_BASE = {
   virtualRowInsetY: 8,
   /** `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. */

package/dist/tokens.css

@@ -13,7 +13,7 @@
   --vx-space-control-height: 2.625rem;
   --vx-space-control-height-tag: 1.25rem;
   --vx-space-control-height-widget: 1.5rem;
-  --vx-space-control-height-ctl: 1.875rem;
+  --vx-space-control-height-ctl: 2rem;
   --vx-space-touch-control-height: 2.25rem;
   --vx-space-stack-xs: 4px;
   --vx-space-stack-sm: 8px;
@@ -22,7 +22,7 @@
   --vx-space-stack-xl: 24px;
   --vx-space-sticky-header-clearance: 12px;
   --vx-space-nav-icon-gap: 10px;
-  --vx-space-sidebar-region-gap: 10px;
+  --vx-space-sidebar-region-gap: 12px;
   --vx-space-prose-quote-inset-y: 2px;
   --vx-space-prose-quote-indent: 12px;
   --vx-space-prose-inline-code-inset-y: 1.5px;
@@ -85,17 +85,20 @@
   --vx-space-settings-row-gap: 16px;
   --vx-space-mermaid-container-inset: 16px;
   --vx-space-sidebar-brand-inset-x: 7px;
-  --vx-space-sidebar-section-gap: 12px;
+  --vx-space-sidebar-section-gap: 16px;
   --vx-space-sidebar-account-inset-top: 9px;
   --vx-space-sidebar-account-inset-x: 7px;
   --vx-space-sidebar-account-inset-bottom: 2px;
   --vx-space-sidebar-avatar-size: 28px;
-  --vx-space-sidebar-section-label-gap: 2px;
+  --vx-space-sidebar-section-label-gap: 6px;
   --vx-space-sidebar-child-list-gap-top: 2px;
   --vx-space-sidebar-child-list-gap-bottom: 3px;
   --vx-space-sidebar-child-list-indent: 15px;
   --vx-space-sidebar-child-row-inset-y: 4px;
   --vx-space-sidebar-child-row-indent: 12px;
+  --vx-space-app-shell-inset: 20px;
+  --vx-space-app-shell-inset-mobile: 8px;
+  --vx-space-app-shell-header-lead-min: 96px;
   --vx-space-mobile-nav-tab-gap: 3px;
   --vx-space-mobile-nav-icon-size: 24px;
   --vx-space-mobile-nav-tab-inset-y: 2px;
@@ -113,9 +116,12 @@
   --vx-space-badge-inset-y: 2px;
   --vx-space-badge-inset-x: 7px;
   --vx-space-stat-card-gap: 8px;
+  --vx-space-card-inset-y: 11px;
+  --vx-space-card-inset-x: 13px;
+  --vx-space-section-gap: 12px;
   --vx-space-virtual-row-inset-y: 8px;
   --vx-space-virtual-row-inset-x: 12px;
-  --vx-space-page-bar-row-height: 2.5rem;
+  --vx-space-page-bar-row-height: 2.25rem;
   --vx-space-section-header-height: 2.25rem;
   --vx-space-widget-header-height: 1.75rem;
   --vx-space-sidebar-block-row-height: 2rem;
@@ -184,6 +190,12 @@
   --vx-badRef: var(--vx-bad-ref);
   --vx-warnRef: var(--vx-warn-ref);
 }
+@media (max-width: 47.99375em) {
+  :root {
+    --vx-space-card-inset-x: 11px;
+    --vx-space-section-gap: 8px;
+  }
+}
 :root,
 html[data-mantine-color-scheme='dark'] {
   --vx-status-excellent: #43bf4d;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.29.2
+# basalt-ui v1.30.1
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.29.2
+Version: 1.30.1
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.29.2",
+  "version": "1.30.1",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/charts/index.ts

@@ -67,6 +67,7 @@ export {
   ChartFrame,
   type ChartFrameProps,
   type ChartFrameLegend,
+  type ResponsiveChartHeight,
   type PlotRect,
   resolveLegend,
 } from './primitives/ChartFrame'

package/src/charts/kinds/BandStrip.tsx

@@ -10,6 +10,7 @@ import { useBandPlot } from '../hooks/useBandPlot'
 import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot'
 import { AxisBottomDate } from '../primitives/Axes'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import {
   ChartTooltipFloat,
   TooltipBody,
@@ -94,9 +95,10 @@ export type BandStripProps<T> = BasaltProps & {
   series: readonly BandStripSeries<T>[]
   /** Which state each datum is in. */
   getBand: (d: T) => BandSpan
-  /** Fixed height in px, forwarded to `ChartFrame`. The band row gets whatever the measured
-   * margins and the measured legend band leave. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`), forwarded to `ChartFrame`.
+   * The band row gets whatever the measured margins and legend band leave. Default 240.
+   * `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   /** Fill the parent flex/grid cell's measured height instead of a fixed one. */
   fill?: boolean
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */

package/src/charts/kinds/Bars.tsx

@@ -7,6 +7,7 @@ import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { AxisConfig, CartesianTooltipConfig, PlotContext } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ZoneSpec } from '../primitives/ZoneRects'
 import type { ChartState } from '../primitives/ChartPending'
 import { curveFor, LINE_OVERLAY_STROKE_WIDTH } from '../series'
@@ -65,8 +66,9 @@ export type BarsRefLine = {
 
 export type BarsProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   getX: (d: T) => string
   /** Generic value accessor — given a data point and a bar/line key, returns the value or null. */

package/src/charts/kinds/Donut.tsx

@@ -6,6 +6,7 @@ import { assertRequiredProps } from '../../common/validate'
 import type { BasaltProps } from '../../common/props'
 import { ChartTooltipFloat, TooltipBody, TooltipRow } from '../primitives/ChartTooltip'
 import { ChartFrame } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ChartState } from '../primitives/ChartPending'
 import { VX } from '../../tokens'
 import type { SeriesStyle } from '../series'
@@ -20,8 +21,9 @@ export type DonutDatum<K extends string = SeriesKey> = { key: K; value: number }
 
 export type DonutProps<K extends string = SeriesKey> = BasaltProps & {
   data: DonutDatum<K>[]
-  /** Fixed height in pixels, forwarded to the internal `ChartFrame`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   colorForKey: (key: K) => string
   formatValue: (v: number) => string
   seriesLabel?: (key: string) => string

package/src/charts/kinds/DualPanel.tsx

@@ -15,6 +15,7 @@ import {
   TooltipRow,
 } from '../primitives/ChartTooltip'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import { Crosshair, SeriesDot } from '../primitives/Crosshair'
 import { HoverOverlay } from '../primitives/HoverOverlay'
 import { ZoneRects } from '../primitives/ZoneRects'
@@ -31,8 +32,9 @@ import { smartTicks, xLabelPxFor } from '../utils/ticks'
 
 export type DualPanelProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to the internal `ChartFrame`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   getX: (d: T) => string
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM) — same default `CartesianChart` uses,

package/src/charts/kinds/Heatmap.tsx

@@ -10,6 +10,7 @@ import {
   TooltipRow,
 } from '../primitives/ChartTooltip'
 import { ChartFrame } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import { useChartTierMetrics } from '../primitives/chart-tier'
 import type { ChartState } from '../primitives/ChartPending'
 import { maxTextWidth } from '../utils/measure-text'
@@ -24,8 +25,10 @@ type HeatmapTip = HeatmapCell & { anchor: { x: number; y: number } }
 
 export type HeatmapProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Used when neither
+   * `aspectRatio` nor `fill` is set. Default 240. `ChartFrameProps.height` owns the law —
+   * steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set. */
   aspectRatio?: number
   /** Fill the parent flex/grid cell's measured height instead of a fixed/derived one. */

package/src/charts/kinds/MirroredBars.tsx

@@ -12,6 +12,7 @@ import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot'
 import { probeAxisLabels } from '../layout/auto-margin'
 import { AxisBottomDate, AxisLeftNumeric } from '../primitives/Axes'
 import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import {
   ChartTooltipFloat,
   TooltipBody,
@@ -79,8 +80,9 @@ export type MirroredBarsProps<T> = BasaltProps & {
   /** Per-datum bar opacity — a real but qualified measurement (a short bucket, a partial interval)
    * drawn dimmer. Default 1. */
   getBarOpacity?: (d: T) => number
-  /** Fixed height in px, forwarded to `ChartFrame`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   fill?: boolean
   formatX?: (key: string) => string
   xTickValues?: (keys: readonly string[], plotWidth: number) => readonly string[]

package/src/charts/kinds/MultiLine.tsx

@@ -6,6 +6,7 @@ import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
 import { CartesianChart } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { XZoneSpec } from '../primitives/XZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
 import type { ChartState } from '../primitives/ChartPending'
@@ -15,8 +16,9 @@ import { VX } from '../../tokens'
 
 export type MultiLineProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   /** Extracts the x-axis category (date string) from a data point. */
   getX: (d: T) => string

package/src/charts/kinds/StackedArea.tsx

@@ -5,6 +5,7 @@ import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { AxisConfig, PlotContext } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ChartState } from '../primitives/ChartPending'
 import { curveFor } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
@@ -12,8 +13,9 @@ import { isDev } from '../../common/is-dev'
 
 export type StackedAreaProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   getX: (d: T) => string
   /** The stacked bands, bottom to top — the single source of truth for color, legend, and tooltip

package/src/charts/kinds/ZonedLine.tsx

@@ -7,6 +7,7 @@ import type { CursorResolution } from '../cursor/resolve'
 import { AreaGradient, areaFillUrl } from '../primitives/AreaGradient'
 import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
 import { CartesianChart } from '../primitives/CartesianChart'
+import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { XZoneSpec } from '../primitives/XZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
 import type { ChartState } from '../primitives/ChartPending'
@@ -31,8 +32,9 @@ export type ZonedLineRefLine = {
 
 export type ZonedLineProps<T> = BasaltProps & {
   data: T[]
-  /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   chartId: string
   /** Extracts the x-axis category (date string) from a data point. */
   getX: (d: T) => string

package/src/charts/primitives/CartesianChart.tsx

@@ -17,6 +17,7 @@ import { fmtAxisDate } from '../utils/format'
 import { autoXLabelRotate, smartTicks, smartTicksEvery, xLabelPxFor } from '../utils/ticks'
 import { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from './Axes'
 import { ChartFrame, resolveLegend } from './ChartFrame'
+import type { ResponsiveChartHeight } from './ChartFrame'
 import { useChartTierMetrics } from './chart-tier'
 import type { ChartState } from './ChartPending'
 import { ChartTooltipFloat, TooltipBody, TooltipHeader, TooltipRow } from './ChartTooltip'
@@ -209,7 +210,9 @@ export type CartesianChartProps<T> = BasaltProps & {
   /** X-range bands (time windows), drawn behind the marks. */
   xZones?: XZoneSpec[]
   refLines?: { value: number; color: string; dashed?: boolean; axis?: 'left' | 'right' }[]
-  height?: number
+  /** Height in px, or one per size step (`{ base, sm?, md?, lg? }`). Default 240. Forwarded
+   * unchanged; `ChartFrameProps.height` owns the law — steps resolve off the MEASURED width. */
+  height?: number | ResponsiveChartHeight
   aspectRatio?: number
   fill?: boolean
   legend?: ChartLegendConfig | false

package/src/charts/primitives/ChartCard.tsx

@@ -45,15 +45,20 @@ const bodyClipStyle: CSSProperties = {
   borderBottomLeftRadius: VX.radiusCard,
   borderBottomRightRadius: VX.radiusCard,
   overflow: 'hidden',
-  padding: '2px var(--mantine-spacing-sm, 0.8125rem) var(--mantine-spacing-xs, 0.6875rem)',
+  padding: '2px var(--vx-space-card-inset-x, 0.8125rem) var(--vx-space-card-inset-y, 0.6875rem)',
 }
-// Card inset = spacing xs (vertical) / sm (horizontal). The `--mantine-spacing-*` vars carry
-// basalt's OWNED scale (theme.spacing.xs 0.6875rem / sm 0.8125rem); the rem fallbacks keep a
-// Mantine-free `./charts`-only consumer (no MantineProvider vars) padded identically. No
-// header/body divider — the title block and the plot read as one continuous surface; a rule here
-// only doubled the card's shadow-embedded ring and made the header feel heavier.
+// Card inset = the `cardInsetY`/`cardInsetX` role tokens (vertical / horizontal), the SAME two
+// vars `StatCard` reads — a ChartCard and a StatCard in one grid row must not disagree about their
+// inset, which is why the pair is one named role rather than two files each spelling `xs`/`sm`.
+// They used to read `--mantine-spacing-xs`/`-sm`; the `--vx-*` pair carries the same numbers off
+// the same owned scale, is emitted by the same stylesheet at a retuned density, and — unlike the
+// Mantine vars — steps a rung down below `sm` (the mobile inset ladder, `spaceMobileDecls` in
+// `tokens/index.ts`). The rem fallbacks are unchanged and keep a `./charts`-only consumer with
+// neither MantineProvider nor BasaltProvider padded identically. No header/body divider — the
+// title block and the plot read as one continuous surface; a rule here only doubled the card's
+// shadow-embedded ring and made the header feel heavier.
 const headerWrapStyle: CSSProperties = {
-  padding: 'var(--mantine-spacing-xs, 0.6875rem) var(--mantine-spacing-sm, 0.8125rem) 4px',
+  padding: 'var(--vx-space-card-inset-y, 0.6875rem) var(--vx-space-card-inset-x, 0.8125rem) 4px',
 }
 
 /**