basalt-ui 1.24.0 → 1.26.0

package/src/theme/icon-slot.test.tsx

@@ -0,0 +1,275 @@
+/**
+ * `IconSlot` — the one icon box (`docs/CONTROLS-SPEC.md` §3).
+ *
+ * The bug this file exists to prevent: a consumer's inline `<svg width="24" height="24">` handed to
+ * a basalt control's `icon` prop landed in Mantine's `leftSection`, which is a bare `flex` box with
+ * no size of its own. The glyph painted at 24px inside a 30px `ctl` button, sat on the parent's text
+ * baseline (so it hung low of the optical centre by the line box's descender), and set the row's
+ * height. Measured in Chrome on the playground's header: the `Accounts` secondary read visibly low
+ * and left of centre.
+ *
+ * Two halves, because neither alone would hold. The CSS-TEXT half pins the mechanism (a fixed square
+ * box, `100%` on the glyph, `display: block`) — CSS-module class hashes are unavailable under
+ * `bun test`, so the declarations themselves are read from the file, the same idiom
+ * `controls/filter-set.test.tsx` and `theme/layout-rhythm-css.test.ts` use. The RENDER half pins that
+ * every home named by the spec actually routes its `icon` through the slot, found by the
+ * `data-basalt-icon` marker attribute rather than by a class.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ReactNode } from 'react'
+import { ActionGroup } from '../controls/actions'
+import { FilterPill } from '../controls/filter-pill'
+import { SyncButton } from '../controls/sync-button'
+import { WidgetHeader } from '../widget-header/widget-header'
+import { IconSlot } from './icon-slot'
+
+const ICON_SLOT_CSS = readFileSync(join(import.meta.dir, 'icon-slot.module.css'), 'utf8')
+const CONTROLS_CSS = readFileSync(join(import.meta.dir, '../controls/controls.module.css'), 'utf8')
+const WIDGET_HEADER_CSS = readFileSync(
+  join(import.meta.dir, '../widget-header/widget-header.module.css'),
+  'utf8',
+)
+
+/** A consumer glyph that declares its OWN geometry — the exact shape that used to leak through. */
+function OversizedGlyph(): ReactNode {
+  return (
+    <svg width={24} height={24} viewBox="0 0 24 24" data-testid="glyph">
+      <circle cx={12} cy={12} r={10} />
+    </svg>
+  )
+}
+
+/** A consumer glyph with no `width`/`height` and no `viewBox` — paints 300×150 unstyled. */
+function UnsizedGlyph(): ReactNode {
+  return (
+    <svg data-testid="glyph">
+      <circle cx={8} cy={8} r={8} />
+    </svg>
+  )
+}
+
+function slots(container: HTMLElement): HTMLElement[] {
+  return [...container.querySelectorAll<HTMLElement>('[data-basalt-icon]')]
+}
+
+/** The slot wrapping the marked glyph — asserts the glyph is a DIRECT child, which the `> svg`
+ *  selector requires to bite. */
+function slotAround(container: HTMLElement): HTMLElement | null {
+  const glyph = container.querySelector('[data-testid="glyph"]')
+  const parent = glyph?.parentElement ?? null
+  return parent !== null && parent.hasAttribute('data-basalt-icon') ? parent : null
+}
+
+describe('the box is declared once, in CSS, and cannot be set at a call site', () => {
+  test('the slot is a fixed square off --vx-space-icon-size with a 16px fallback', () => {
+    expect(ICON_SLOT_CSS).toContain('width: var(--vx-space-icon-size, 1rem)')
+    expect(ICON_SLOT_CSS).toContain('height: var(--vx-space-icon-size, 1rem)')
+  })
+
+  test('the slot never participates in its row’s flex sizing', () => {
+    expect(ICON_SLOT_CSS).toContain('flex: none')
+    expect(ICON_SLOT_CSS).toContain('display: inline-flex')
+    expect(ICON_SLOT_CSS).toContain('align-items: center')
+    expect(ICON_SLOT_CSS).toContain('justify-content: center')
+  })
+
+  test('the glyph is restated at 100% and taken off the baseline — the two halves of "centred"', () => {
+    const rule = ICON_SLOT_CSS.slice(ICON_SLOT_CSS.indexOf('.slot > svg'))
+    expect(rule).toContain('width: 100%')
+    expect(rule).toContain('height: 100%')
+    expect(rule).toContain('display: block')
+    // Presentation attributes lose to CSS, which is the whole mechanism — a 24px, a 14px and an
+    // attribute-less SVG all resolve to the box.
+    expect(rule).toContain('object-fit: contain')
+  })
+
+  test('`img` and `picture` icons get the same box — an icon set is as likely to be a sprite', () => {
+    expect(ICON_SLOT_CSS).toContain('.slot > img')
+    expect(ICON_SLOT_CSS).toContain('.slot > picture')
+  })
+
+  test('IconSlot has no size prop — a call site cannot pick a geometry', () => {
+    const source = readFileSync(join(import.meta.dir, 'icon-slot.tsx'), 'utf8')
+    const props = source.slice(
+      source.indexOf('export type IconSlotProps'),
+      source.indexOf('export function IconSlot'),
+    )
+    expect(props).not.toContain('size')
+    // `children` + `className` and nothing else.
+    expect(props.match(/readonly \w+\??:/g)).toEqual(['readonly children:', 'readonly className?:'])
+  })
+
+  test('a home sizes the slot by overriding the box VAR, never by sizing the glyph', () => {
+    // The trailing pill affordance is 14px and the widget-tier heading icon is 14px. Both get there
+    // through `--vx-space-icon-size`; neither may reintroduce a per-component `> svg` size rule,
+    // which is the duplication that let `BarAction` ship with no box at all.
+    expect(CONTROLS_CSS).toContain('--vx-space-icon-size: 0.875rem')
+    expect(WIDGET_HEADER_CSS).toContain('--vx-space-icon-size: 0.875rem')
+    expect(WIDGET_HEADER_CSS).toContain('--vx-space-icon-size: 1rem')
+    expect(CONTROLS_CSS).not.toMatch(/\.pillIcon\s*>\s*svg/)
+    expect(WIDGET_HEADER_CSS).not.toMatch(/\.icon\s*>\s*svg/)
+  })
+})
+
+describe('every home named by the spec routes `icon` through the slot', () => {
+  test('a BarAction secondary — an oversized consumer SVG lands inside the slot', () => {
+    const { container } = render(
+      <MantineProvider>
+        <ActionGroup
+          secondary={[{ key: 'accounts', label: 'Accounts', icon: <OversizedGlyph /> }]}
+        />
+      </MantineProvider>,
+    )
+    // Both viewport variants mount (law C9), so the glyph appears twice; every occurrence is slotted.
+    const glyphs = [...container.querySelectorAll('[data-testid="glyph"]')]
+    expect(glyphs.length).toBeGreaterThan(0)
+    for (const glyph of glyphs) {
+      expect(glyph.parentElement?.hasAttribute('data-basalt-icon')).toBe(true)
+    }
+  })
+
+  test('a BarAction PRIMARY too — the mobile icon-only form is the same box', () => {
+    const { container } = render(
+      <MantineProvider>
+        <ActionGroup primary={{ key: 'save', label: 'Save as report', icon: <UnsizedGlyph /> }} />
+      </MantineProvider>,
+    )
+    const glyphs = [...container.querySelectorAll('[data-testid="glyph"]')]
+    expect(glyphs.length).toBeGreaterThan(0)
+    for (const glyph of glyphs) {
+      expect(glyph.parentElement?.hasAttribute('data-basalt-icon')).toBe(true)
+    }
+  })
+
+  test('an OverflowMenu row — the fold is a home too', () => {
+    const { container } = render(
+      <MantineProvider>
+        <ActionGroup
+          secondary={[
+            { key: 'a', label: 'A' },
+            { key: 'b', label: 'B' },
+            { key: 'c', label: 'C' },
+            { key: 'd', label: 'D', icon: <OversizedGlyph /> },
+          ]}
+        />
+      </MantineProvider>,
+    )
+    // The `More` dropdown mounts lazily, so assert the fold exists and its trigger is present; the
+    // ROW's slotting is covered by the source guard below, which reads the same code path.
+    expect(container.textContent).toContain('More')
+  })
+
+  test('a FilterPill — the leading glyph is slotted (every enum filter renders through it)', () => {
+    const { container } = render(
+      <MantineProvider>
+        <FilterPill label="EUR" icon={<OversizedGlyph />} />
+      </MantineProvider>,
+    )
+    expect(slotAround(container)).not.toBeNull()
+  })
+
+  test('a FilterPill’s trailing affordance is slotted too, at the 14px box', () => {
+    const { container } = render(
+      <MantineProvider>
+        <FilterPill label="EUR" />
+      </MantineProvider>,
+    )
+    // The `⇅` affordance is basalt's own glyph and still goes through the slot — the box is the
+    // slot's on every icon in the tier, framework-drawn or consumer-passed.
+    expect(slots(container).length).toBe(1)
+  })
+
+  test('a WidgetHeader — tier="widget"', () => {
+    const { container } = render(
+      <WidgetHeader tier="widget" title="Active users" icon={<OversizedGlyph />} />,
+    )
+    expect(slotAround(container)).not.toBeNull()
+  })
+
+  test('a WidgetHeader — tier="section" (and StatCard, which forwards `icon` to it)', () => {
+    const { container } = render(
+      <WidgetHeader tier="section" title="Funnel & retention" icon={<UnsizedGlyph />} />,
+    )
+    expect(slotAround(container)).not.toBeNull()
+  })
+
+  test('a SyncButton — basalt’s own glyph obeys the same box', () => {
+    const { container } = render(
+      <MantineProvider>
+        <SyncButton scope="page" syncing={false} onSync={() => {}} />
+      </MantineProvider>,
+    )
+    expect(slots(container).length).toBeGreaterThan(0)
+  })
+})
+
+describe('the slot is decorative and queryable, by construction', () => {
+  test('aria-hidden is unconditional — the control carries the name, never the icon', () => {
+    const { container } = render(
+      <IconSlot>
+        <OversizedGlyph />
+      </IconSlot>,
+    )
+    expect(container.querySelector('[data-basalt-icon]')?.getAttribute('aria-hidden')).toBe('true')
+  })
+
+  test('a home’s className is composed ONTO the slot, never in place of it', () => {
+    const { container } = render(
+      <IconSlot className="home-colour">
+        <OversizedGlyph />
+      </IconSlot>,
+    )
+    // The module hash is '' under `bun test`, so the assertion is that the home's class survived
+    // alongside whatever the module resolves to — i.e. it is appended, not substituted.
+    expect(container.querySelector('[data-basalt-icon]')?.className).toContain('home-colour')
+  })
+})
+
+/**
+ * The recurrence guard. Every `leftSection`/`rightSection` in the control tier that carries a
+ * CALLER-supplied icon must route it through `IconSlot` — this is what makes a seventh control
+ * added next month fail here instead of shipping an un-boxed glyph, which is exactly how
+ * `BarAction` shipped.
+ *
+ * Scoped to the files that own an `icon` prop in the tier the spec governs. `src/shell/app-sidebar.tsx`
+ * and `src/shell/app-mobile-nav.tsx` are deliberately out of scope: a nav row's icon column is sized
+ * by the sidebar's own rhythm rules, not by the control tier, and folding them in is a separate
+ * change with its own visual budget.
+ */
+describe('no control in the tier may hand a caller’s icon straight to a section slot', () => {
+  const TIER_FILES = [
+    '../controls/actions.tsx',
+    '../controls/filter-pill.tsx',
+    '../controls/sync-button.tsx',
+    '../shell/sidebar-blocks.tsx',
+  ] as const
+
+  for (const rel of TIER_FILES) {
+    test(`${rel} routes every icon-bearing section through IconSlot`, () => {
+      const source = readFileSync(join(import.meta.dir, rel), 'utf8')
+      const offenders: string[] = []
+      for (const match of source.matchAll(/(left|right)Section[:=]\s*([^,\n]*)/g)) {
+        const raw = match[2] ?? ''
+        // A bare identifier (`leftSection: lead`) is resolved one level to its `const` initialiser,
+        // so a slot built a line above still counts. One level only — anything deeper than that is
+        // indirection a reader could not follow either.
+        const bare = /^([A-Za-z_$][\w$]*)\s*\}?\)?,?$/.exec(raw.trim())
+        const declared =
+          bare === null
+            ? undefined
+            : new RegExp(`\\bconst ${bare[1]}\\b[^\\n]*(?:\\n[^\\n]*){0,3}`).exec(source)?.[0]
+        const value = declared ?? raw
+        // Only the icon-bearing sites are in scope — a `rightSection` holding a count badge or a
+        // `<Text>` meta string is not an icon and has no box to pin.
+        if (!/icon|glyph|lead/i.test(value)) continue
+        if (value.includes('IconSlot')) continue
+        offenders.push(match[0].trim())
+      }
+      expect(offenders).toEqual([])
+    })
+  }
+})

package/src/theme/icon-slot.tsx

@@ -0,0 +1,59 @@
+/**
+ * `IconSlot` — the ONE box every `icon` prop in the public API renders through
+ * (`docs/CONTROLS-SPEC.md` §3).
+ *
+ * basalt ships no icon dependency, so every `icon` slot takes a `ReactNode` the consumer fills —
+ * and a consumer's glyph arrives at whatever geometry its own icon set chose: `width="24"` from
+ * Tabler's defaults, no `width` at all from a hand-written `<svg viewBox="0 0 20 20">`, a
+ * `stroke-width` tuned for a 24px box, or an `<img>` off a sprite sheet. Passing that node straight
+ * into Mantine's `leftSection` (which is a bare `flex` box with no size of its own) lets the CALLER
+ * decide the height of a basalt control's row. That is the class of bug this component closes: the
+ * icon's box is the framework's, and there is no prop on it.
+ *
+ * **Derived, not configured.** There is no `size` prop, on purpose — a size at a call site is the
+ * same C5 violation a `size="xs"` on a Button is. The box reads `--vx-space-icon-size` (default
+ * 16px, the control tier's mark), and the only thing entitled to set that var is a HOME's own CSS:
+ * `WidgetHeader` sets it per `data-tier`, so a `tier="widget"` heading draws 14px icons and a
+ * `tier="section"` heading draws 16px, with every call site unchanged.
+ *
+ * Mantine-free and dependency-free (one CSS module, one `<span>`), so `src/widget-header/**` — which
+ * `ChartCard` composes from inside `src/charts/**` — can deep-import it without pulling
+ * `@mantine/*` into the charts graph (`scripts/check-dist-layering.mjs`). Deep-import it as
+ * `../theme/icon-slot`, never through the `./theme` barrel, for exactly that reason. INTERNAL: it is
+ * not on any barrel. A consumer never needs it — passing `icon` IS the contract, and this is what
+ * makes that contract hold.
+ *
+ * `data-basalt-icon` is the queryable marker, the same idiom `CtlSlot` uses for `data-basalt-tier`:
+ * a CSS-module class name is a build-time hash, so it is not something a test — or a consumer
+ * debugging a misaligned row — can select on.
+ *
+ * @example
+ * // A control's icon slot — no size anywhere at the call site.
+ * <Button leftSection={<IconSlot>{icon}</IconSlot>}>{label}</Button>
+ */
+import type { ReactNode } from 'react'
+import classes from './icon-slot.module.css'
+
+export type IconSlotProps = {
+  readonly children: ReactNode
+  /**
+   * Composed ONTO the slot class, never in place of it — a home adds colour/state rules (the pill's
+   * muted-then-ink icon, a header's faint one) and the geometry stays the slot's.
+   */
+  readonly className?: string
+}
+
+export function IconSlot({ children, className }: IconSlotProps): ReactNode {
+  return (
+    // `aria-hidden` unconditionally: an icon in a basalt control is DECORATIVE by construction —
+    // every control that takes one also carries a label or an `aria-label`, so a named icon would
+    // double the announced name. A caller wanting a meaningful graphic names the control, not this.
+    <span
+      className={className === undefined ? classes.slot : `${classes.slot} ${className}`}
+      data-basalt-icon
+      aria-hidden="true"
+    >
+      {children}
+    </span>
+  )
+}

package/src/theme/index.ts

@@ -99,6 +99,10 @@ export type { BasaltFontsConfig } from '../tokens'
 // snapshot) — see its own doc comment for why it lives here rather than in `tokens/`.
 export { useBasaltSpacing } from './use-basalt-spacing'
 
+// The `size="ctl"` slot theme (`docs/CONTROLS-SPEC.md` §5) — see `./ctl-theme`'s own doc for the
+// merge/precedence contract.
+export { CTL_THEME, CtlSlot, type CtlSlotProps } from './ctl-theme'
+
 // Typed `theme.other.basaltDerive` / `theme.other.basaltFonts` / `theme.other.basaltRadius` /
 // `theme.other.basaltDensity` reads (Mantine's `MantineThemeOther` ships an index signature, so
 // this merge is additive — no widening of the existing `[key: string]: any`). Set by
@@ -745,7 +749,12 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       SegmentedControl: SegmentedControl.extend({
         defaultProps: { radius: radius.card },
         classNames: { label: segmentedControlClasses.label },
-        styles: {
+        // `label` gets a `ctl`-only min-height (function-form `styles`, same `props.size === …` gate
+        // as Button/ActionIcon/Input's `vars` overrides above) so a `size="ctl"` SegmentedControl
+        // matches the ctl Button/Input box exactly instead of following its own fixed padding — see
+        // `CTL_SEGMENT_PADDING_Y`'s doc below for why the label's own padding alone can't track
+        // density. `sm`/`md` SegmentedControls (forms) are untouched, keeping Mantine's own sizing.
+        styles: (_theme, props) => ({
           root: {
             backgroundColor: 'color-mix(in srgb, var(--vx-ink) 6%, transparent)',
             padding: `${SPACE_FIXED.segmentedTrackInset}px`,
@@ -755,7 +764,19 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
             boxShadow: 'var(--vx-shadow-ctrl)',
             borderRadius: 'var(--vx-radius-tight)',
           },
-        },
+          // Conditionally spread the WHOLE key (never a present `label: undefined`) — the package
+          // builds under `exactOptionalPropertyTypes`, which treats a key present-but-`undefined` as
+          // a type error distinct from the key being absent.
+          ...(props.size === 'ctl'
+            ? {
+                label: {
+                  display: 'inline-flex',
+                  alignItems: 'center',
+                  minHeight: `calc(var(--vx-space-control-height-ctl) * var(--mantine-scale) - ${2 * SPACE_FIXED.segmentedTrackInset}px)`,
+                },
+              }
+            : {}),
+        }),
       }),
       // Track = ink-8%; leader/section fill colors are a per-usage `color` prop (left to consumers).
       Progress: Progress.extend({
@@ -935,10 +956,16 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // body cells is a per-table call-site concern, left to consumers. `--table-border-color`
       // drives row separators AND the opt-in `withTableBorder` outer border — both drop to the
       // hairline (Mantine's default reads gray-3/dark-4 = the STRONG line, too heavy in a card).
+      // Row heights are declared here rather than through `verticalSpacing`, because Mantine derives
+      // BOTH `th` and `td` padding from that one prop — a 36/40 pair (label band over roomier data
+      // rows) is not expressible by it at all. `height` on a table cell behaves as a MINIMUM, so a
+      // wrapping cell still grows; `verticalSpacing` keeps working on top of it for a consumer that
+      // wants a denser or looser table than the tier.
       Table: Table.extend({
         classNames: { table: controlsClasses.tableRoot },
         styles: {
           th: {
+            height: spacing.step.tableHeaderHeight,
             fontFamily: 'var(--basalt-font-mono)',
             fontSize: VX.text.micro,
             fontWeight: 500,
@@ -946,6 +973,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
             textTransform: 'uppercase',
             color: 'var(--vx-faint)',
           },
+          td: { height: spacing.step.tableRowHeight },
         },
       }),
       // The v9 thumb indicator is a center dot painted in the TRACK color — over the remapped
@@ -1105,6 +1133,138 @@ function familyBridge(data: PaletteData): Record<string, string> {
   return vars
 }
 
+/**
+ * The `ctl` tier's horizontal inset — one number for a Button, a `FilterPill`, a SegmentedControl
+ * segment and a `kind: 'custom'` Badge, so a home's row reads as one control family
+ * (`docs/CONTROLS-SPEC.md` §3: "the pill: 30px, padding 0 10px"). Not in `SPACE_STEP`: it is a
+ * Mantine size-var value, consumed only by {@link ctlSizeVars}, and it happens to equal
+ * `SPACE.rowInsetX` without being the same concept (that one is a nav/menu ROW's inset).
+ */
+const CTL_PADDING_X = 10
+/** The `ctl` tier's Input vertical inset — 30px box, ~20px line, so 4px a side leaves the border. */
+const CTL_INPUT_PADDING_Y = 4
+/**
+ * A `ctl` SegmentedControl segment's vertical inset, in px. Fractional on purpose, and derived
+ * rather than picked: the label's line box is `VX.text.sm` × `--mantine-line-height-sm` ≈ 21px and
+ * the track adds `SPACE_FIXED.segmentedTrackInset` on each side (2px), so landing the CONTROL on the
+ * 30px `ctl` tier needs (30 − 4 − 21) / 2. Mantine's own `--input-padding-y-xs` is 4.5px for the
+ * same reason — a control tier is a total height, and the halves that make it up need not be whole.
+ */
+const CTL_SEGMENT_PADDING_Y = 2.5
+/** A `ctl` Combobox chevron. Mantine's own `xs` value; restated because it cannot be referenced. */
+const CTL_CHEVRON_SIZE = 14
+/**
+ * The `ctl` tier's Radio/Checkbox indicator box, in px — 16, the SAME square
+ * `theme/icon-slot.module.css` gives every icon in the tier, and for the same reason: a 13.5px
+ * option label needs a mark it reads as part of the row rather than as a control beside it. Mantine's
+ * default is `sm` (20px) and its `md` is 24px, both of which made the popover a column of controls
+ * (`controls/filter-sheet.tsx`'s `SheetOptionList` doc records the sheet's version of the same
+ * finding — there the fix was to remove the indicator entirely).
+ */
+const CTL_TOGGLE_SIZE = 16
+/**
+ * A `ctl` Radio's inner dot. Mantine's own ratio is `size * 0.4` — the literal fallback its
+ * `varsResolver` applies to a NUMERIC size (`Radio/RadioIndicator/RadioIndicator.mjs`), and what its
+ * shipped pairs already encode (10px dot in a 24px `md` box). Derived rather than picked so the dot
+ * stays proportional if the box moves.
+ */
+const CTL_RADIO_DOT_SIZE = CTL_TOGGLE_SIZE * 0.4
+/**
+ * The `ctl` Switch: an 18×30 track with a 12px thumb. Mantine ships no tier between `xs` (16×32,
+ * 12px thumb) and `sm` (20×38, 14px), and neither fits — `xs` is SHORTER than the tier's indicator
+ * box while being twice as wide as it, which reads as a slider rather than a toggle. 18 is one step
+ * over the 16px indicator (a switch must read as the taller control, it carries a moving part), and
+ * 30 is the narrowest track that still shows travel: 30 − 12 thumb − 2×3 padding leaves 12px of it.
+ */
+const CTL_SWITCH_HEIGHT = 18
+const CTL_SWITCH_WIDTH = 30
+const CTL_SWITCH_THUMB_SIZE = 12
+/** The `on`/`off` labels INSIDE a `ctl` switch track, and their inset. Mantine's `xs` pair, which is
+ *  the last tier whose label still fits an 18px track. */
+const CTL_SWITCH_TRACK_LABEL_SIZE = 5
+const CTL_SWITCH_TRACK_LABEL_PADDING = 2
+
+/**
+ * The `size="ctl"` / `size="icon"` Mantine size-tier var sets (`docs/CONTROLS-SPEC.md` §5, C5) —
+ * scheme-independent, so they live in `cssVariablesResolver`'s `variables` block (`:root`, not
+ * `light`/`dark`), declared exactly once regardless of color scheme. Mechanism, verified against
+ * the installed `@mantine/core` 9.3.0 source (`core/utils/get-size/get-size.mjs`): a component's own
+ * `varsResolver` calls `getSize(props.size, '<prefix>')`, which for a non-numeric `size` returns the
+ * STRING `var(--<prefix>-<size>)` verbatim — so `size="ctl"` on `Button` resolves
+ * `--button-height: var(--button-height-ctl)` with ZERO code in this framework's own `Button.extend`
+ * `vars` callback; only the var these names point AT has to exist. `getFontSize(size)` is
+ * `getSize(size, 'mantine-font-size')`, so every `-fz`/`-font-size` component var (Button's
+ * `--button-fz`, Input's `--input-fz`, SegmentedControl's `--sc-font-size`, Combobox's
+ * `--combobox-option-fz`) resolves through the ONE `--mantine-font-size-ctl` declared below — no
+ * per-component `-ctl` font-size var exists to declare (verified against
+ * `SegmentedControl.mjs`/`Combobox.mjs`; a per-component name would be dead weight no `getSize`
+ * call ever reads).
+ *
+ * Heights read the density-tracking `--vx-space-control-height-ctl`/`-widget` anchors
+ * (`tokens/index.ts`'s `spaceDecls`, `docs/CONTROLS-SPEC.md` §5) through the SAME rem-plus-
+ * `--mantine-scale` reconstruction `--vx-space-input-height`/`--vx-space-control-height` already
+ * use for `size="md"` (see `Input.extend`'s doc above) — so the ctl/icon tier tracks the density
+ * knob exactly like every other control height. Paddings, the combobox chevron, and the
+ * SegmentedControl/Combobox option padding have no density-tracking token of their own
+ * (`docs/CONTROLS-SPEC.md` §5 specifies only the height ladder), so they are declared as literal
+ * values here.
+ *
+ * **They may NOT be declared as `var(--<prefix>-xs)`, and that mistake shipped.** Mantine declares
+ * its `-xs`/`-sm`/… size vars on the COMPONENT ROOT class (`.m_77c9d27d { --button-padding-x-xs:
+ * 14px }` in `Button.css`, `.m_cf365364 { --sc-padding-xs: 2px 6px }` in `SegmentedControl.css`,
+ * and likewise for Input/Combobox/Badge) — never on `:root`. A `-ctl` var declared HERE lives on
+ * `:root`, where `var(--sc-padding-xs)` resolves to nothing, so the whole custom property became
+ * guaranteed-invalid and every property reading it fell back to its INITIAL value: a pill with
+ * `padding: 0`, a SegmentedControl whose segments touched
+ * (`allnewreturningchurnedflagged`), a chevron-less Select. Literal values are the only form that
+ * can resolve at `:root`. Verified live with `getComputedStyle(document.documentElement)
+ * .getPropertyValue('--sc-padding-ctl')` returning `''`.
+ *
+ * `size="icon"` (24px) has no vertical-padding/chevron consumer (it is ActionIcon-only), so only
+ * `--ai-size-icon` is declared for it. The Badge tier exists so a `kind: 'custom'` chip in a home
+ * (`docs/CONTROLS-SPEC.md` §2.1) is the same 30px as the buttons beside it — Mantine's tallest
+ * shipped Badge is 32px `xl`, and none of its tiers is 30.
+ */
+function ctlSizeVars(): Record<string, string> {
+  const ctlHeight = 'calc(var(--vx-space-control-height-ctl) * var(--mantine-scale))'
+  return {
+    '--button-height-ctl': ctlHeight,
+    '--button-padding-x-ctl': `calc(${pxRem(CTL_PADDING_X)} * var(--mantine-scale))`,
+    '--input-height-ctl': ctlHeight,
+    '--input-padding-y-ctl': `calc(${pxRem(CTL_INPUT_PADDING_Y)} * var(--mantine-scale))`,
+    '--ai-size-ctl': ctlHeight,
+    '--ai-size-icon': 'calc(var(--vx-space-control-height-widget) * var(--mantine-scale))',
+    // A shorthand pair (`<y> <x>`), the shape SegmentedControl's own `--sc-padding-*` vars take.
+    // `y` stays a bare literal (the label's own box height is now enforced by the `size === 'ctl'`
+    // `minHeight` override in `SegmentedControl.extend` above, not by this padding), `x` scales like
+    // every other ctl-tier horizontal inset (`--button-padding-x-ctl`, `--badge-padding-x-ctl`).
+    '--sc-padding-ctl': `${pxRem(CTL_SEGMENT_PADDING_Y)} calc(${pxRem(CTL_PADDING_X)} * var(--mantine-scale))`,
+    '--combobox-option-padding-ctl': `${pxRem(CTL_SEGMENT_PADDING_Y)} ${pxRem(CTL_PADDING_X)}`,
+    '--combobox-chevron-size-ctl': pxRem(CTL_CHEVRON_SIZE),
+    '--badge-height-ctl': ctlHeight,
+    '--badge-padding-x-ctl': `calc(${pxRem(CTL_PADDING_X)} * var(--mantine-scale))`,
+    '--badge-fz-ctl': `calc(${pxRem(VX.text.xs)} * var(--mantine-scale))`,
+    // `= VX.text.sm` per `docs/CONTROLS-SPEC.md` §5 — same `calc(<rem> * var(--mantine-scale))`
+    // shape Mantine's own `--mantine-font-size-*` vars use.
+    '--mantine-font-size-ctl': `calc(${pxRem(VX.text.sm)} * var(--mantine-scale))`,
+    '--mantine-line-height-ctl': 'var(--mantine-line-height-sm)',
+    // Radio / Checkbox / Switch — the three components whose DEFAULT (`sm`, a 20px indicator) sat
+    // beside a 13.5px option label in every popover and sheet basalt draws. Every prefix here was
+    // read out of the installed `@mantine/core` source, and `ctl-tier-coverage.test.ts` now scans
+    // those three components too, so a future minor that adds a `getSize` call fails the build
+    // instead of resolving the new var to its initial value. Note there is NO
+    // `--checkbox-icon-size`: Checkbox reads only `checkbox-size` and derives its tick in CSS.
+    '--radio-size-ctl': `calc(${pxRem(CTL_TOGGLE_SIZE)} * var(--mantine-scale))`,
+    '--radio-icon-size-ctl': `calc(${pxRem(CTL_RADIO_DOT_SIZE)} * var(--mantine-scale))`,
+    '--checkbox-size-ctl': `calc(${pxRem(CTL_TOGGLE_SIZE)} * var(--mantine-scale))`,
+    '--switch-height-ctl': `calc(${pxRem(CTL_SWITCH_HEIGHT)} * var(--mantine-scale))`,
+    '--switch-width-ctl': `calc(${pxRem(CTL_SWITCH_WIDTH)} * var(--mantine-scale))`,
+    '--switch-thumb-size-ctl': `calc(${pxRem(CTL_SWITCH_THUMB_SIZE)} * var(--mantine-scale))`,
+    '--switch-label-font-size-ctl': pxRem(CTL_SWITCH_TRACK_LABEL_SIZE),
+    '--switch-track-label-padding-ctl': pxRem(CTL_SWITCH_TRACK_LABEL_PADDING),
+  }
+}
+
 /**
  * Build the `cssVariablesResolver` bound to a given palette `data` — the derive-config-dependent
  * half of the fallback hexes below (see `buildTheme` above for the same split on `theme.colors`).
@@ -1123,7 +1283,9 @@ function familyBridge(data: PaletteData): Record<string, string> {
 function buildCssVariablesResolver(data: PaletteData): CSSVariablesResolver {
   const { INK, NEUTRAL, SURFACE } = data
   return (theme) => ({
-    variables: {},
+    variables: {
+      ...ctlSizeVars(),
+    },
     light: {
       ...onColorVars(theme, 'light', data),
       ...familyBridge(data),

package/src/theme/layout-rhythm-css.test.ts

@@ -0,0 +1,72 @@
+/**
+ * CSS-text regression tests for two shell rules that broke silently because neither is exercised
+ * by a render test: `.footerVersion`'s collapsed-rail hide (a corrupted selector left it unscoped,
+ * hiding the sidebar version label at every desktop viewport) and the sticky page-bar rows' z-index
+ * (a bare `1` let ordinary in-flow content — Mantine's Input section, Indicator, sticky table
+ * headers — paint over them while scrolling).
+ *
+ * Both are asserted against the raw `.module.css` source text rather than through jsdom: jsdom does
+ * not implement CSS cascade/specificity resolution or `getComputedStyle` for stacking, so a
+ * render-based test cannot see either regression. Reading the source text directly is what actually
+ * pins the rule shape.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+
+const APP_SIDEBAR_CSS = readFileSync(
+  join(import.meta.dir, '../shell/app-sidebar.module.css'),
+  'utf8',
+)
+const PAGE_BAR_CSS = readFileSync(join(import.meta.dir, '../shell/page-bar.module.css'), 'utf8')
+
+/** The `@media (min-width: 48em)` rail block — where `[data-collapsed]` rules live. */
+function railBlock(css: string): string {
+  const start = css.indexOf('@media (min-width: 48em)')
+  expect(start).toBeGreaterThanOrEqual(0)
+  return css.slice(start)
+}
+
+describe('app-sidebar.module.css — collapsed-rail `.footerVersion` hide', () => {
+  const rail = railBlock(APP_SIDEBAR_CSS)
+
+  it('scopes the version-label hide to `.root[data-collapsed]`, not a bare `.footerVersion`', () => {
+    expect(rail).toContain('.root[data-collapsed] .footerVersion {\n    display: none;\n  }')
+  })
+
+  it('never declares an unscoped `.footerVersion` rule inside the rail media query', () => {
+    // A bare `.footerVersion {` (no `[data-collapsed]` ancestor on the same rule) would hide the
+    // version label at every desktop viewport, expanded or collapsed — the exact regression.
+    for (const m of rail.matchAll(/([^{}\n]+)\{\s*display:\s*none;\s*\}/g)) {
+      const selector = m[1]!.trim()
+      if (!selector.endsWith('.footerVersion')) continue
+      expect(selector).toContain('[data-collapsed]')
+    }
+  })
+
+  it('does not duplicate the base `.footerIconSlot` rule inside the rail media query', () => {
+    // The real `.footerIconSlot` rule is declared once, outside the media query — a stray copy
+    // inside `@media (min-width: 48em)` is the corruption artifact this test guards against.
+    expect([...rail.matchAll(/\.footerIconSlot\s*\{/g)]).toHaveLength(0)
+  })
+})
+
+describe('page-bar.module.css — sticky rows sit under the AppShell header, above page content', () => {
+  it('`.bar` sits one layer below the AppShell header, not at the bare `z-index: 1` every sibling can equal', () => {
+    const bar = PAGE_BAR_CSS.slice(
+      PAGE_BAR_CSS.indexOf('.bar {'),
+      PAGE_BAR_CSS.indexOf('\n}', PAGE_BAR_CSS.indexOf('.bar {')),
+    )
+    expect(bar).toContain('z-index: calc(var(--app-shell-header-z-index, 100) - 1);')
+    expect(bar).not.toMatch(/z-index:\s*1\s*;/)
+  })
+
+  it('`.row2Sticky` uses the same header-relative z-index as `.bar`, so the two never fall out of sync', () => {
+    const row2 = PAGE_BAR_CSS.slice(
+      PAGE_BAR_CSS.indexOf('.row2Sticky {'),
+      PAGE_BAR_CSS.indexOf('\n}', PAGE_BAR_CSS.indexOf('.row2Sticky {')),
+    )
+    expect(row2).toContain('z-index: calc(var(--app-shell-header-z-index, 100) - 1);')
+    expect(row2).not.toMatch(/z-index:\s*1\s*;/)
+  })
+})

package/src/theme/radius.test.ts

@@ -70,7 +70,17 @@ describe('every re-pointed component defaultProps/styles radius matches its ship
   test('SegmentedControl root = 7, indicator = 5', () => {
     const sc = baseTheme.components?.['SegmentedControl']
     expect(sc?.defaultProps?.['radius']).toBe(7)
-    expect(sc?.styles?.['indicator']?.['borderRadius']).toBe('var(--vx-radius-tight)')
+    // `styles` is function-form (size='ctl' gates a label override — see `theme/index.ts`), not a
+    // flat object, so it has to be called rather than indexed directly.
+    const stylesFn = sc?.styles as
+      | ((
+          theme: unknown,
+          props: { size?: string },
+          ctx: unknown,
+        ) => Record<string, Record<string, unknown>>)
+      | undefined
+    const resolved = stylesFn?.({}, {}, {})
+    expect(resolved?.['indicator']?.['borderRadius']).toBe('var(--vx-radius-tight)')
   })
 
   test('Progress = 4', () => {