basalt-ui 1.29.2 → 1.30.0

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.0
 # 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.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

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

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',
 }
 
 /**

package/src/charts/primitives/ChartFrame.tsx

@@ -6,11 +6,13 @@ import { useChartSize } from '../hooks/useChartSize'
 import { deriveLegend } from '../series'
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series'
 import {
-  chartTierMetrics,
   legendEntryCap,
   resolveChartTier,
+  resolveFrameHeight,
+  resolveLegendMaxRows,
   resolvePlotRect,
 } from './chart-frame-layout'
+import type { ResponsiveChartHeight } from './chart-frame-layout'
 import { ChartTierProvider } from './chart-tier'
 import { ChartLegend } from './ChartLegend'
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
@@ -19,6 +21,7 @@ import type { ChartState } from './ChartPending'
 /** Re-exported for `ChartFrame.test.tsx` and any other consumer that previously reached these
  * through `ChartFrame` — the layout math itself lives in `./chart-frame-layout` (pure, DOM-free). */
 export { legendEntryCap, resolvePlotRect, resolveChartTier } from './chart-frame-layout'
+export type { ResponsiveChartHeight } from './chart-frame-layout'
 
 const DEFAULT_HEIGHT = 240
 const DEFAULT_MIN_WIDTH = 200
@@ -28,7 +31,17 @@ const DEFAULT_MIN_WIDTH = 200
 export type ChartFrameLegend = {
   /** Default 'bottom'. */
   placement?: LegendPlacement
-  /** Wrap cap → "+N more" rollup at high cardinality. */
+  /**
+   * Wrap cap → "+N more" rollup at high cardinality.
+   *
+   * An explicit value WINS OUTRIGHT — including over the phone tier's own two-row default
+   * (`chartTierMetrics`). It used to be `Math.min`'d against the tier, which made the documented
+   * per-chart opt-out ("opt back out with an explicit `legend.maxRows`") false in the one direction
+   * anybody needs it: a consumer's 380px inspector panel is "a phone" on a 1440px desktop, and a
+   * six-series legend rolled up to `+4 more` with no way to say no. Under `fill` the measured
+   * entry cap can still roll up FURTHER — that is a floor on the plot, not a tier default
+   * ({@link legendEntryCap}).
+   */
   maxRows?: number
   /** Visually separate role: series | overlay | reference. */
   groups?: boolean
@@ -47,8 +60,16 @@ export type ChartFrameLegend = {
 export type ChartFrameProps = BasaltProps & {
   /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
   series: readonly SeriesStyle[]
-  /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
-  height?: number
+  /**
+   * Height in pixels, or one per size step. Used when neither `aspectRatio` nor `fill` is set.
+   * Default 240.
+   *
+   * `{ base: 180, md: 260 }` is the declarative escape from a page of fixed-height charts: the
+   * steps are compared against the frame's own MEASURED width, not the viewport, so a chart squeezed
+   * by a `PageAside` gets the short height on a desktop too. A plain number is unchanged and stays
+   * supported ({@link resolveFrameHeight}).
+   */
+  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. */
@@ -206,7 +227,7 @@ export function ChartFrame({
     ? containerH
     : aspectRatio !== undefined
       ? Math.round(containerW / aspectRatio)
-      : (height ?? DEFAULT_HEIGHT)
+      : resolveFrameHeight(height ?? DEFAULT_HEIGHT, containerW)
 
   const sideLegendWidth = legendVisible && vertical ? legendW : 0
   const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0
@@ -225,17 +246,11 @@ export function ChartFrame({
   // A fixed-height frame grows around its legend; a `fill` one cannot, so its legend rolls up
   // instead of eating the plot (see `legendEntryCap`). Top/bottom only — a side legend costs
   // width, not height.
-  // The tier's own cap folds in as an upper bound BEFORE the fill measurement, so a phone-width
-  // `fill` frame can only ever roll up further, never less (`chartTierMetrics`).
-  const tierMaxRows = chartTierMetrics(tier).legendMaxRows
+  // The resolved cap — the caller's if they named one, else the tier's DEFAULT, never both
+  // `Math.min`'d (`resolveLegendMaxRows` owns that law and says why) — enters the fill measurement
+  // as the upper bound, so a phone-width `fill` frame can only ever roll up further, never less.
   const callerMaxRows =
-    legend === false
-      ? undefined
-      : legend.maxRows === undefined
-        ? tierMaxRows
-        : tierMaxRows === undefined
-          ? legend.maxRows
-          : Math.min(legend.maxRows, tierMaxRows)
+    legend === false ? undefined : resolveLegendMaxRows({ callerMaxRows: legend.maxRows, tier })
 
   const maxRows =
     legend === false

package/src/charts/primitives/chart-frame-layout.ts

@@ -39,6 +39,70 @@ export function resolveChartTier(containerW: number): ChartTier {
   return containerW > 0 && containerW < VX.phoneChartWidth ? 'phone' : 'desktop'
 }
 
+/**
+ * A chart height stated per size step instead of as one number — the declarative escape from "every
+ * chart on this page is 260px tall on a 375px phone too".
+ *
+ * `base` is required and is the height a box narrower than every named step gets; each further key
+ * is the height from that step UP. Keys are Mantine's breakpoint names so a consumer writes the
+ * vocabulary they already write, and nothing more than `sm`/`md`/`lg` is offered: `xs`/`xl` would
+ * be two more rungs nobody has asked a chart to have.
+ *
+ * ```tsx
+ * <ChartFrame series={series} height={{ base: 180, md: 260 }}>{…}</ChartFrame>
+ * ```
+ */
+export type ResponsiveChartHeight = {
+  /** Below the narrowest STATED step — and NOT the first-frame value; see {@link resolveFrameHeight}. */
+  base: number
+  /** From 768px of MEASURED container width up. */
+  sm?: number
+  /** From 992px up. */
+  md?: number
+  /** From 1200px up. */
+  lg?: number
+}
+
+/**
+ * The measured CONTAINER width, in px, each {@link ResponsiveChartHeight} key takes effect at.
+ *
+ * The numbers are what Mantine's `sm`/`md`/`lg` breakpoints resolve to at the 16px initial font
+ * size, so a consumer's mental model transfers — but they are compared against the element's own
+ * MEASURED box, never the viewport, for the reason {@link resolveChartTier} states: a chart in a
+ * `PageAside`-squeezed grid cell on a 1440px desktop is as narrow as one on a phone, and the
+ * viewport agrees with neither. Keeping them as plain numbers here is also what keeps this file
+ * Mantine-free — `theme.breakpoints` is on the coupled side of the boundary.
+ */
+const HEIGHT_STEP_WIDTH = { sm: 768, md: 992, lg: 1200 } as const
+
+/** Widest-first, so the first step that fits is the answer. */
+const HEIGHT_STEPS = ['lg', 'md', 'sm'] as const
+
+/**
+ * Resolve a `height` prop — a plain number, or a {@link ResponsiveChartHeight} — against the
+ * measured container width.
+ *
+ * A plain number passes through untouched: this is a WIDENING of the prop, not a replacement, and
+ * every existing `height={240}` must keep meaning exactly 240.
+ *
+ * An UNMEASURED box (`containerW <= 0` — SSR, or before the `ResizeObserver`'s first callback)
+ * resolves to the LARGEST stated step, matching {@link resolveChartTier}'s first-frame rule: the
+ * first paint must not be phone-shaped chrome that grows one frame later. Falling to `base` there
+ * would make every SSR'd chart short and then jump.
+ */
+export function resolveFrameHeight(
+  height: number | ResponsiveChartHeight,
+  containerW: number,
+): number {
+  if (typeof height === 'number') return height
+  const widest = HEIGHT_STEPS.find((step) => height[step] !== undefined)
+  if (containerW <= 0) return widest === undefined ? height.base : (height[widest] ?? height.base)
+  const step = HEIGHT_STEPS.find(
+    (name) => containerW >= HEIGHT_STEP_WIDTH[name] && height[name] !== undefined,
+  )
+  return step === undefined ? height.base : (height[step] ?? height.base)
+}
+
 /**
  * How much of `VX.margin` a phone-tier chart keeps as its FLOOR. The measured law is unchanged —
  * a side may still only grow past its floor (`autoMargin`) — this only stops a static token from
@@ -111,6 +175,28 @@ export function chartTierMetrics(tier: ChartTier): ChartTierMetrics {
   return tier === 'phone' ? PHONE_METRICS : DESKTOP_METRICS
 }
 
+/**
+ * Which legend cap applies: the caller's, or the tier's own default.
+ *
+ * **An explicit `callerMaxRows` wins OUTRIGHT.** This used to be `Math.min(caller, tier)`, which
+ * made the documented per-chart opt-out ("opt back out with an explicit `legend.maxRows`") false in
+ * the one direction anybody needs it. The tier's `PHONE_LEGEND_MAX_ROWS` is a DEFAULT for charts
+ * that said nothing — a chart that names a number has already answered the question the default
+ * exists to answer, and it matters because the tier keys on the measured box: a 380px inspector
+ * panel on a 1440px desktop is "a phone", so a six-series legend rolled up to two rows + `+4 more`
+ * with no way to say no. `margin` and `xLabelRotate` always had that escape; the legend did not.
+ *
+ * A `fill` frame's measured {@link legendEntryCap} still applies ON TOP of whatever wins here — it
+ * is a floor on the PLOT, not a tier default, so a chart that would otherwise render no plot at all
+ * still rolls up.
+ */
+export function resolveLegendMaxRows(input: {
+  callerMaxRows?: number | undefined
+  tier: ChartTier
+}): number | undefined {
+  return input.callerMaxRows ?? chartTierMetrics(input.tier).legendMaxRows
+}
+
 /**
  * Resolve the plot rect from the measured box and the measured legend band. Pure and exported so
  * the two floors below are testable without a `ResizeObserver`.

package/src/cli/check-theme.ts

@@ -19,6 +19,7 @@ import {
   conflictingProfileFlags,
   declaredProfile,
   DEFAULT_ROOTS,
+  hasBasaltKey,
   readBasaltConfig,
   resolveExemptRules,
   resolveProjectDir,
@@ -96,6 +97,18 @@ export function checkTheme(
     // A configured-but-wrong root is never intentional, and silently scanning 0 files under the
     // built-in defaults (argo's pre-migration layout) is the same failure mode for every other
     // consumer — both cases fail loud instead of warn-plus-green.
+    // The WRONG-DIRECTORY case leads, and since 1.29.0's single resolver it is the common one:
+    // lefthook and GitHub Actions both run at the REPO ROOT while the config lives in a package
+    // below it. Only the roots messages used to print, sending a consumer to edit `basalt.roots` in
+    // a package.json that has no `basalt` block at all.
+    if (!hasBasaltKey(cwd)) {
+      console.error(
+        `✖ basalt-ui check-theme: ${cwd}/package.json has no "basalt" key — very likely not the ` +
+          'package you meant to scan (BASALT_CWD, else the invocation cwd; nothing is inferred). ' +
+          'At a repo root? Give the command `root: <pkg>/` (lefthook) or `working-directory: ' +
+          '<pkg>` (Actions), or set BASALT_CWD=<pkg>. If this directory IS it, run `basalt-ui init`.',
+      )
+    }
     if (cfg.roots === undefined) {
       console.error(
         `✖ basalt-ui check-theme: 0 files scanned — no "basalt.roots" configured in package.json, and ` +