basalt-ui 1.25.0 → 1.26.0

package/src/theme/segmented-control.module.css

@@ -12,3 +12,23 @@
   color: var(--vx-ink);
   font-weight: 600;
 }
+
+/*
+ * Numeric segment labels read mono `VX.text.xs` (`docs/CONTROLS-SPEC.md` §3 last paragraph, C7) —
+ * a consumer opts in with a bare `data-numeric` attribute on the `SegmentedControl` itself (an
+ * unrecognized native prop, forwarded onto the root `Box` via Mantine's own `...others` spread,
+ * `SegmentedControl.mjs`), retiring the per-consumer `theme-allow` + inline `styles={{ label: {
+ * fontFamily: 'var(--basalt-font-mono)', fontSize: 11.5 } }}` hack (`DashboardDateFilter.tsx`).
+ * The MONO FACE itself is now a package-wide law in `styles.css` (`[data-numeric]` in `@layer
+ * basalt`, so a plain `<Text data-numeric>` works too — the module-scoped copy is why it used to
+ * look broken outside a SegmentedControl); what stays here is the component's own `font-size`, plus
+ * the face restated so this module is still correct read on its own.
+ * `[data-numeric]` is a bare attribute selector, not a CSS-module class, so it is intentionally left
+ * unscoped — same ancestor-attribute pattern as `controls.module.css`'s
+ * `html[data-mantine-color-scheme] .inputWrapper[data-variant='default']`. `.label` here is the
+ * SAME scoped class `data-active` above targets, so both rules can co-apply (active + numeric).
+ */
+[data-numeric] .label {
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+}

package/src/theme/shadow-surfaces.test.ts

@@ -353,19 +353,32 @@ export const SHADOW_SURFACES: readonly ShadowSurfaceEntry[] = [
       "on the root part; Mantine's own Notification.css declares `border-radius: var(--" +
       'notification-radius)` on that same root element the styles.root boxShadow targets).',
   },
+  // ── widget-header ────────────────────────────────────────────────────────────────────────────
+  {
+    file: 'widget-header/widget-header.module.css',
+    site: '.infoBubble',
+    roundedBy:
+      'border-radius: var(--vx-radius-card) (co-declared in the same .infoBubble rule as the ' +
+      'box-shadow, so the ring follows this box’s own shape). This is the info-tooltip bubble that ' +
+      'used to live in charts/primitives/ChartCard.tsx as `bubbleStyle`; it moved down into ' +
+      'WidgetHeader when ChartCard started composing it, so every tier gets the same ' +
+      'hover/focus/click affordance. Nothing clips it: its host `.info` span is `position: ' +
+      'relative` with no overflow, and ChartCard deliberately keeps its header outside the chart ' +
+      'body’s clip box for exactly this reason.',
+  },
   // ── charts/primitives ────────────────────────────────────────────────────────────────────────
   {
     file: 'charts/primitives/ChartCard.tsx',
     site: 'default',
     roundedBy:
-      'Two shadowed boxes in this file, each co-declaring borderRadius: VX.radiusCard with its own ' +
-      'boxShadow (both fall back to the file-level default label). (1) cardStyle — the outer card box ' +
-      'co-declares borderRadius + boxShadow + backgroundColor, so the ring is bound to THIS radius and ' +
+      'One shadowed box in this file: cardStyle — the outer card box co-declares borderRadius: ' +
+      'VX.radiusCard + boxShadow + backgroundColor, so the ring is bound to THIS radius and ' +
       'matches. It carries NO overflow: the chart body clips itself on a separate inner box ' +
-      '(bodyClipStyle, identical bottom-corner radius, no shadow) so the header — and its info-tooltip ' +
-      'bubble — can escape the clip; the ring is safe on the outer box either way (an element’s own ' +
-      'overflow never clips its own shadow). (2) bubbleStyle — the info-tooltip bubble, a floating panel ' +
-      'surface whose ring likewise follows its co-declared card radius.',
+      '(bodyClipStyle, identical bottom-corner radius, no shadow) so the header — and the info ' +
+      'bubble WidgetHeader opens under it — can escape the clip; the ring is safe on the outer box ' +
+      'either way (an element’s own overflow never clips its own shadow). The second shadowed box ' +
+      'this entry used to cover, `bubbleStyle`, now lives in widget-header.module.css’s ' +
+      '.infoBubble (registered above).',
   },
   {
     file: 'charts/primitives/ChartTooltip.tsx',

package/src/theme/spacing.test.ts

@@ -20,21 +20,19 @@
  *   `rowInsetY`, the 4px stack rhythm, and the sidebar SIZES (`sidebarAvatarSize`,
  *   `sidebarSearchTriggerHeight`, the two Menu widths) were held back on purpose — see that commit.
  * - `SPACE_STEP.stickyHeaderClearance` moved from 84 (the original literal) through an
- * intermediate single derived value of 108, to its FINAL shape — a responsive PAIR (Decision 3):
- * `stickyHeaderClearance` (desktop, `>= sm`) now 60, plus a new `stickyHeaderClearanceMobile`
- * (mobile, `< sm`) at 108. Both are DERIVED from their own AppShell header (`appShellHeaderHeight`/
- * `appShellHeaderMobileHeight`) instead of one independent literal, which fixed two bugs at once:
- * the original 84 under-cleared the mobile header (96px at the time, 97 since the retune above) at
- * level 0 (before density entered the
- * picture at all), and a single derived value tuned against the mobile header over-cleared the 48px
- * desktop header by 60px on the common (desktop) path. See `deriveSpacing`'s doc in
- * `tokens/palette.ts` for the full rationale. Every value NOT named above is still byte-identical to
- * the pre-tokenization number it replaced.
+ * intermediate single derived value of 108, then a responsive PAIR (Decision 3), to its FINAL shape:
+ * ONE value, 60, DERIVED as `appShellHeaderHeight + anchors.stackMd`. Deriving it fixed the original
+ * 84's drift from the header it was supposed to clear; the `stickyHeaderClearanceMobile` half of the
+ * pair was deleted in 1.26.0 along with the two-row mobile header it existed for — the AppShell
+ * header is one 48px row at every viewport now (law C14, `docs/CONTROLS-SPEC.md` §2.1), so
+ * `appShellHeaderMobileHeight` and `appHeaderMobileActionsHeight` went with it. See `deriveSpacing`'s
+ * doc in `tokens/palette.ts` for the full rationale. Every value NOT named above is still
+ * byte-identical to the pre-tokenization number it replaced.
  */
 import { DEFAULT_THEME, mergeMantineTheme } from '@mantine/core'
 import type { MantineTheme } from '@mantine/core'
 import { describe, expect, test } from 'bun:test'
-import { buildPaletteCss } from '../tokens'
+import { buildPaletteCss, pxRem } from '../tokens'
 import { SPACE, SPACE_FIXED, SPACE_SCALE, SPACE_STEP } from '../tokens/palette'
 import { baseTheme } from './index'
 
@@ -58,6 +56,13 @@ describe('SPACE anchors match the shipped identity', () => {
     expect(SPACE.inputHeight).toBe(42)
     expect(SPACE.controlHeight).toBe(42)
   })
+
+  test('the controls tier anchors are 20/24/30/36 (docs/CONTROLS-SPEC.md §5)', () => {
+    expect(SPACE.controlHeightTag).toBe(20)
+    expect(SPACE.controlHeightWidget).toBe(24)
+    expect(SPACE.controlHeightCtl).toBe(30)
+    expect(SPACE.touchControlHeight).toBe(36)
+  })
 })
 
 describe('SPACE_SCALE matches the shipped identity — independent of SPACE even where it coincides', () => {
@@ -118,7 +123,17 @@ describe('every re-pointed component styles/defaultProps spacing value matches i
   })
 
   test('SegmentedControl root padding = 2 (a density-exempt SPACE_FIXED literal, not a var)', () => {
-    expect(baseTheme.components?.['SegmentedControl']?.styles?.['root']?.['padding']).toBe('2px')
+    // `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 = baseTheme.components?.['SegmentedControl']?.styles as
+      | ((
+          theme: unknown,
+          props: { size?: string },
+          ctx: unknown,
+        ) => Record<string, Record<string, unknown>>)
+      | undefined
+    const resolved = stylesFn?.({}, {}, {})
+    expect(resolved?.['root']?.['padding']).toBe('2px')
   })
 
   test('Timeline defaultProps stays bulletSize: 22, lineWidth: 1', () => {
@@ -240,6 +255,19 @@ describe('--vx-space-* is emitted from the SAME constants', () => {
     expect(css).toContain('--vx-space-control-height: 2.625rem;')
     expect(css).not.toContain('--vx-space-control-height: 42px;')
   })
+
+  test('emits the controls-tier heights in REM, and the control gap in px (docs/CONTROLS-SPEC.md §5)', () => {
+    expect(css).toContain('--vx-space-control-height-tag: 1.25rem;')
+    expect(css).toContain('--vx-space-control-height-widget: 1.5rem;')
+    expect(css).toContain('--vx-space-control-height-ctl: 1.875rem;')
+    expect(css).toContain('--vx-space-touch-control-height: 2.25rem;')
+    expect(css).toContain('--vx-space-page-bar-row-height: 2.5rem;')
+    expect(css).toContain('--vx-space-section-header-height: 2.25rem;')
+    expect(css).toContain('--vx-space-widget-header-height: 1.75rem;')
+    expect(css).toContain('--vx-space-sidebar-block-row-height: 2rem;')
+    expect(css).toContain('--vx-space-control-gap: 6px;')
+    expect(css).toContain('--vx-space-sheet-row-height: 2.75rem;')
+  })
 })
 
 /**
@@ -253,16 +281,22 @@ describe('--vx-space-* is emitted from the SAME constants', () => {
  * in `tokens/index.ts`).
  */
 const SPACE_STEP_SWEEP: ReadonlyArray<
-  readonly [key: keyof typeof SPACE_STEP, value: number, cssVar: string | null]
+  readonly [
+    key: keyof typeof SPACE_STEP,
+    value: number,
+    cssVar: string | null,
+    /** Defaults to `'px'`. The controls-tier row/sheet heights emit REM (`pxRem`), same
+     *  reconstruction as `space-input-height`/`space-control-height` — see `spaceDecls`'s doc in
+     *  `tokens/index.ts`. */
+    unit?: 'px' | 'rem',
+  ]
 > = [
   // DERIVED, not an independent literal — see `deriveSpacing`'s doc (`tokens/palette.ts`, third
-  // bullet, Decision 3) for why 60/108 (not 84) are the level-0 values: the ONE responsive PAIR
-  // deliberately exempt from the "every SPACE_STEP number is locked at level 0" invariant
-  // this file otherwise enforces (locked here, not skipped, precisely so a future regression back to
-  // 84, or back to a single shared value, shows up as a failing assertion rather than a silent
-  // revert).
+  // bullet) for why 60 (not 84) is the level-0 value: the ONE key deliberately exempt from the
+  // "every SPACE_STEP number is locked at level 0" invariant this file otherwise enforces (locked
+  // here, not skipped, precisely so a future regression back to 84 shows up as a failing assertion
+  // rather than a silent revert).
   ['stickyHeaderClearance', 60, 'space-sticky-header-clearance'],
-  ['stickyHeaderClearanceMobile', 109, 'space-sticky-header-clearance-mobile'],
   ['navIconGap', 10, 'space-nav-icon-gap'],
   ['sidebarRegionGap', 10, 'space-sidebar-region-gap'],
   ['proseQuoteInsetY', 2, 'space-prose-quote-inset-y'],
@@ -343,13 +377,11 @@ const SPACE_STEP_SWEEP: ReadonlyArray<
   // Mantine's `<Menu width={…}>` also takes a number, not a `var()` string).
   ['sidebarAccountMenuWidth', 220, null],
   ['sidebarSettingsMenuWidth', 200, null],
-  ['appHeaderMobileActionsHeight', 52, 'space-app-header-mobile-actions-height'],
-  // JS-number-only (`shell/index.tsx` reads all four via `useBasaltSpacing()` — Mantine's AppShell
+  // JS-number-only (`shell/index.tsx` reads all three via `useBasaltSpacing()` — Mantine's AppShell
   // `header`/`navbar` props take numbers, not `var()` strings) — see `spaceDecls`'s doc in
   // `tokens/index.ts` for why a `--vx-space-app-shell-*` declaration would have zero consumers.
   ['appShellHeaderHeight', 48, null],
-  ['appShellHeaderMobileHeight', 97, null],
-  ['appShellNavbarWidth', 216, null],
+  ['appShellNavbarWidth', 256, null],
   ['appShellNavbarRailWidth', 48, null],
   ['mobileNavTabGap', 3, 'space-mobile-nav-tab-gap'],
   // JS-number-only, and for the same two reasons the six above are: `shell/index.tsx` hands
@@ -384,6 +416,19 @@ const SPACE_STEP_SWEEP: ReadonlyArray<
   ['chartDotR', 5, null],
   ['progressBarSize', 6, null],
   ['timelineBullet', 22, null],
+  // Controls tier row/gap heights (`docs/CONTROLS-SPEC.md` §5) — emitted in REM for the heights
+  // (`pageBarRowHeight`/`sectionHeaderHeight`/`widgetHeaderHeight`/`sidebarBlockRowHeight`/
+  // `sheetRowHeight`, same `pxRem` reconstruction as `space-input-height`), px for the gap.
+  ['pageBarRowHeight', 40, 'space-page-bar-row-height', 'rem'],
+  ['sectionHeaderHeight', 36, 'space-section-header-height', 'rem'],
+  ['widgetHeaderHeight', 28, 'space-widget-header-height', 'rem'],
+  ['sidebarBlockRowHeight', 32, 'space-sidebar-block-row-height', 'rem'],
+  ['controlGap', 6, 'space-control-gap'],
+  ['sheetRowHeight', 44, 'space-sheet-row-height', 'rem'],
+  // Applied as JS numbers in `Table.extend`'s `styles.th`/`styles.td` `height`, so — like
+  // `progressBarSize` — neither has a `--vx-space-*` declaration to assert.
+  ['tableHeaderHeight', 36, null],
+  ['tableRowHeight', 40, null],
 ]
 
 describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identity', () => {
@@ -395,9 +440,10 @@ describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identit
 
   test('every constant with a cssVar is emitted as its own --vx-space-* declaration, unchanged', () => {
     const css = buildPaletteCss()
-    for (const [, value, cssVar] of SPACE_STEP_SWEEP) {
+    for (const [, value, cssVar, unit = 'px'] of SPACE_STEP_SWEEP) {
       if (cssVar === null) continue
-      expect(css).toContain(`--vx-${cssVar}: ${value}px;`)
+      const expected = unit === 'rem' ? pxRem(value) : `${value}px`
+      expect(css).toContain(`--vx-${cssVar}: ${expected};`)
     }
   })
 
@@ -410,7 +456,6 @@ describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identit
       'sidebarAccountMenuWidth',
       'sidebarSettingsMenuWidth',
       'appShellHeaderHeight',
-      'appShellHeaderMobileHeight',
       'appShellNavbarWidth',
       'appShellNavbarRailWidth',
       'mobileNavBarHeight',
@@ -424,11 +469,12 @@ describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identit
       'chartDotR',
       'progressBarSize',
       'timelineBullet',
+      'tableHeaderHeight',
+      'tableRowHeight',
     ])
     expect(css).not.toContain('--vx-space-sidebar-account-menu-width')
     expect(css).not.toContain('--vx-space-sidebar-settings-menu-width')
     expect(css).not.toContain('--vx-space-app-shell-header-height')
-    expect(css).not.toContain('--vx-space-app-shell-header-mobile-height')
     expect(css).not.toContain('--vx-space-app-shell-navbar-width')
     expect(css).not.toContain('--vx-space-app-shell-navbar-rail-width')
     expect(css).not.toContain('--vx-space-mobile-nav-bar-height')
@@ -436,6 +482,8 @@ describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identit
     expect(css).not.toContain('--vx-space-chart-legend-gap')
     expect(css).not.toContain('--vx-space-progress-bar-size')
     expect(css).not.toContain('--vx-space-timeline-bullet')
+    expect(css).not.toContain('--vx-space-table-header-height')
+    expect(css).not.toContain('--vx-space-table-row-height')
   })
 
   test('the sweep table covers every SPACE_STEP key', () => {

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

@@ -13,8 +13,8 @@
  *
  * Three `../shell` components consume it today, two distinct classes of use:
  *  - `BasaltShell` (`../shell/index.tsx`) — its AppShell header/navbar dimensions need the ACTIVE
- *    density level's numbers (`step.appShellHeaderHeight`/`.appShellHeaderMobileHeight`/
- *    `.appShellNavbarWidth`/`.appShellNavbarRailWidth`), not the frozen shipped-identity constants,
+ *    density level's numbers (`step.appShellHeaderHeight`/`.appShellNavbarWidth`/
+ *    `.appShellNavbarRailWidth`), not the frozen shipped-identity constants,
  *    because those boxes must grow/shrink with the density-tracked controls rendered inside them.
  *  - `AppSidebar` (`../shell/app-sidebar.tsx`) and `SidebarAccount` (`../shell/app-sidebar-
  *    account.tsx`) each read `step.sidebarSettingsMenuWidth`/`.sidebarAccountMenuWidth` for their

package/src/tokens/density.test.ts

@@ -125,8 +125,8 @@ describe('rowLineHeight follows its own additive law, not the multiplier', () =>
   })
 })
 
-describe('stickyHeaderClearance/stickyHeaderClearanceMobile derive from their OWN AppShell header, not a shared base (Decision 3 — responsive split)', () => {
-  test('level -3/0/+3: desktop 43 / 60 / 77 — appShellHeaderHeight + anchors.stackMd at each level', () => {
+describe('stickyHeaderClearance derives from the AppShell header, not an independent base', () => {
+  test('level -3/0/+3: 43 / 60 / 77 — appShellHeaderHeight + anchors.stackMd at each level', () => {
     const low = deriveSpacing(-3)
     const zero = deriveSpacing(0)
     const high = deriveSpacing(3)
@@ -139,28 +139,10 @@ describe('stickyHeaderClearance/stickyHeaderClearanceMobile derive from their OW
     )
   })
 
-  test('level -3/0/+3: mobile 77 / 109 / 141 — appShellHeaderMobileHeight + anchors.stackMd at each level', () => {
-    const low = deriveSpacing(-3)
-    const zero = deriveSpacing(0)
-    const high = deriveSpacing(3)
-    expect(low.step.stickyHeaderClearanceMobile).toBe(77)
-    expect(low.step.stickyHeaderClearanceMobile).toBe(
-      low.step.appShellHeaderMobileHeight + low.anchors.stackMd,
-    )
-    expect(zero.step.stickyHeaderClearanceMobile).toBe(109)
-    expect(high.step.stickyHeaderClearanceMobile).toBe(141)
-    expect(high.step.stickyHeaderClearanceMobile).toBe(
-      high.step.appShellHeaderMobileHeight + high.anchors.stackMd,
-    )
-  })
-
-  test('every level: each clearance exceeds ONLY the header it exists to clear, exactly by anchors.stackMd', () => {
+  test('every level: the clearance exceeds the header it exists to clear, exactly by anchors.stackMd', () => {
     for (let level = -3; level <= 3; level++) {
       const { step, anchors } = deriveSpacing(level)
       expect(step.stickyHeaderClearance - step.appShellHeaderHeight).toBe(anchors.stackMd)
-      expect(step.stickyHeaderClearanceMobile - step.appShellHeaderMobileHeight).toBe(
-        anchors.stackMd,
-      )
     }
   })
 })
@@ -206,10 +188,9 @@ describe('buildDensityCss', () => {
     // REM, not px — see the input-height describe block below for why.
     expect(css).toContain('--vx-space-input-height: 3.4375rem;')
     expect(css).toContain('--vx-space-control-height: 3.4375rem;')
-    // 77 (desktop) / 141 (mobile), not the anchor/scale/step multiplier result for an 84px base —
-    // both are DERIVED (own header + anchors.stackMd), see the dedicated describe block above.
+    // 77, not the anchor/scale/step multiplier result for an 84px base — it is DERIVED (the header
+    // plus anchors.stackMd), see the dedicated describe block above.
     expect(css).toContain('--vx-space-sticky-header-clearance: 77px;')
-    expect(css).toContain('--vx-space-sticky-header-clearance-mobile: 141px;')
     // JS-number-only constants (Timeline's bulletSize, VX chart geometry, Progress's size) have no
     // CSS var to override — see `spaceDecls`'s doc in `tokens/index.ts`.
     expect(css).not.toContain('--vx-space-timeline-bullet')
@@ -233,10 +214,11 @@ describe('buildDensityCss', () => {
     const jsNumberOnly = [
       'space-timeline-bullet', // Timeline defaultProps.bulletSize
       'space-progress-bar-size', // Progress defaultProps.size
+      'space-table-header-height', // Table.extend styles.th height
+      'space-table-row-height', // Table.extend styles.td height
       'space-sidebar-account-menu-width', // Menu width prop
       'space-sidebar-settings-menu-width', // Menu width prop
       'space-app-shell-header-height', // AppShell header/navbar props
-      'space-app-shell-header-mobile-height',
       'space-app-shell-navbar-width',
       'space-app-shell-navbar-rail-width',
       'space-mobile-nav-bar-height', // AppShell footer.height prop

package/src/tokens/index.ts

@@ -159,6 +159,23 @@ export const VX = {
   // radius knob (see `RADIUS_STEP.pill`'s doc in `tokens/palette.ts`).
   radiusPill: 'var(--vx-radius-pill)',
 
+  // Controls tier sizing (`docs/CONTROLS-SPEC.md` §5) — `var()` refs onto the density-tracking
+  // `--vx-space-*` declarations `spaceDecls` emits above (same ref pattern as `radiusCard`/
+  // `radiusCtrl`), so a home/control reads ONE source for its tier height whether it's Mantine
+  // chrome (`cssVariablesResolver`/`CTL_THEME`) or a Mantine-free composed layout.
+  space: {
+    controlHeightTag: 'var(--vx-space-control-height-tag)',
+    controlHeightWidget: 'var(--vx-space-control-height-widget)',
+    controlHeightCtl: 'var(--vx-space-control-height-ctl)',
+    touchControlHeight: 'var(--vx-space-touch-control-height)',
+    pageBarRowHeight: 'var(--vx-space-page-bar-row-height)',
+    sectionHeaderHeight: 'var(--vx-space-section-header-height)',
+    widgetHeaderHeight: 'var(--vx-space-widget-header-height)',
+    sidebarBlockRowHeight: 'var(--vx-space-sidebar-block-row-height)',
+    controlGap: 'var(--vx-space-control-gap)',
+    sheetRowHeight: 'var(--vx-space-sheet-row-height)',
+  },
+
   // Secondary-line color (back-compat alias; now theme-aware via --vx-line2)
   line2Dark: 'var(--vx-line2)',
 
@@ -418,6 +435,15 @@ function frameworkPrimitives(side: Side, data: PaletteData, legacyAliases: boole
  * the two lists can never drift apart — mirrors `frameworkDerived`'s own single-source reasoning for
  * the radii.
  *
+ * The ten controls-tier anchors/one-offs (`controlHeightTag`/`Widget`/`Ctl`, `touchControlHeight`,
+ * `pageBarRowHeight`, `sectionHeaderHeight`, `widgetHeaderHeight`, `sidebarBlockRowHeight`,
+ * `controlGap`, `sheetRowHeight` — `docs/CONTROLS-SPEC.md` §5) are a DELIBERATE exception to the
+ * "has at least one real consumer today" rule below: `theme/ctl-theme.tsx`'s `CTL_THEME` and the
+ * `cssVariablesResolver`'s `-ctl`/`-icon` var sets consume the four control-height anchors this
+ * commit; `PageBar`/`WidgetHeader`/the sidebar blocks (wave 3/4) consume the six one-offs. Emitted
+ * now, ahead of that second wave, rather than left as JS-only — unlike the seventeen genuinely
+ * dead-weight keys below, these are forward-declared framework surface, not vestigial.
+ *
  * `SPACE_FIXED` (Timeline `lineWidth`, 1px borders, the ReadingProgress bar height, SegmentedControl's
  * `segmentedTrackInset`) is deliberately NEVER part of this list — it never moves, so a var would
  * only invite someone to think it does.
@@ -428,7 +454,7 @@ function frameworkPrimitives(side: Side, data: PaletteData, legacyAliases: boole
  * resolved `SpaceValues` as a JS NUMBER instead, in one of three ways:
  * `{timelineBullet,progressBarSize}` are Mantine `defaultProps` (`theme/index.ts`'s Timeline/
  * Progress); `{sidebarAccountMenuWidth,sidebarSettingsMenuWidth,mobileNavMenuWidth,
- * appShellHeaderHeight,appShellHeaderMobileHeight,appShellNavbarWidth,appShellNavbarRailWidth,
+ * appShellHeaderHeight,appShellNavbarWidth,appShellNavbarRailWidth,
  * mobileNavBarHeight}` are numeric Mantine component props (Menu `width`, AppShell `header`/
  * `navbar`/`footer`); and `{chartLegendGap,chartMarginTop,chartMarginRight,chartMarginRightAxis,
  * chartMarginBottom,chartMarginLeft,chartDotR}` are visx SVG props via
@@ -465,6 +491,14 @@ function spaceDecls(space: SpaceValues): string[] {
     // `ActionIcon.extend` `vars`), single-sourced from the SAME `controlHeight` anchor
     // `space-input-height` reads from (`SPACE_ANCHORS_BASE`'s doc in `tokens/palette.ts`).
     decl('space-control-height', pxRem(space.anchors.controlHeight)),
+    // Controls tier heights (`docs/CONTROLS-SPEC.md` §5) — same rem-plus-`--mantine-scale`
+    // reconstruction as `space-input-height`/`space-control-height` above; `theme/ctl-theme.tsx`'s
+    // `CTL_THEME` and the `cssVariablesResolver`'s `-ctl`/`-icon` var sets both wrap these in the
+    // matching `calc(... * var(--mantine-scale))`.
+    decl('space-control-height-tag', pxRem(space.anchors.controlHeightTag)),
+    decl('space-control-height-widget', pxRem(space.anchors.controlHeightWidget)),
+    decl('space-control-height-ctl', pxRem(space.anchors.controlHeightCtl)),
+    decl('space-touch-control-height', pxRem(space.anchors.touchControlHeight)),
     decl('space-stack-xs', `${space.anchors.stackXs}px`),
     decl('space-stack-sm', `${space.anchors.stackSm}px`),
     decl('space-stack-md', `${space.anchors.stackMd}px`),
@@ -472,11 +506,9 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-stack-xl', `${space.anchors.stackXl}px`),
     // The CSS-module spacing sweep's one-offs (docs/STATUS.md) — same single-source reasoning,
     // grouped to match `SPACE_STEP_BASE`'s own grouping in tokens/palette.ts.
-    // Responsive pair (Decision 3) — `stickyHeaderClearance` is the desktop (`>= sm`) value,
-    // `stickyHeaderClearanceMobile` the mobile (`< sm`) override; a consumer CSS module picks
-    // whichever matches its own breakpoint (see `content/prose.module.css`).
+    // ONE value at every viewport since 1.26.0 — the AppShell header is a single 48px row (law
+    // C14), so the `-mobile` override of the old Decision-3 responsive pair is gone.
     decl('space-sticky-header-clearance', `${space.step.stickyHeaderClearance}px`),
-    decl('space-sticky-header-clearance-mobile', `${space.step.stickyHeaderClearanceMobile}px`),
     decl('space-nav-icon-gap', `${space.step.navIconGap}px`),
     decl('space-sidebar-region-gap', `${space.step.sidebarRegionGap}px`),
     decl('space-prose-quote-inset-y', `${space.step.proseQuoteInsetY}px`),
@@ -553,7 +585,6 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-sidebar-child-list-indent', `${space.step.sidebarChildListIndent}px`),
     decl('space-sidebar-child-row-inset-y', `${space.step.sidebarChildRowInsetY}px`),
     decl('space-sidebar-child-row-indent', `${space.step.sidebarChildRowIndent}px`),
-    decl('space-app-header-mobile-actions-height', `${space.step.appHeaderMobileActionsHeight}px`),
     decl('space-mobile-nav-tab-gap', `${space.step.mobileNavTabGap}px`),
     decl('space-mobile-nav-icon-size', `${space.step.mobileNavIconSize}px`),
     decl('space-mobile-nav-tab-inset-y', `${space.step.mobileNavTabInsetY}px`),
@@ -573,11 +604,20 @@ function spaceDecls(space: SpaceValues): string[] {
     decl('space-stat-card-gap', `${space.step.statCardGap}px`),
     decl('space-virtual-row-inset-y', `${space.step.virtualRowInsetY}px`),
     decl('space-virtual-row-inset-x', `${space.step.virtualRowInsetX}px`),
+    // Controls tier row/gap heights (`docs/CONTROLS-SPEC.md` §5) — the current commit's consumers
+    // are `theme/ctl-theme.tsx` (`--vx-space-control-gap`) and the wave-3/4 homes (`PageBar`,
+    // `WidgetHeader`, sidebar blocks, the mobile `Filters (n)` sheet) landing next.
+    decl('space-page-bar-row-height', pxRem(space.step.pageBarRowHeight)),
+    decl('space-section-header-height', pxRem(space.step.sectionHeaderHeight)),
+    decl('space-widget-header-height', pxRem(space.step.widgetHeaderHeight)),
+    decl('space-sidebar-block-row-height', pxRem(space.step.sidebarBlockRowHeight)),
+    decl('space-control-gap', `${space.step.controlGap}px`),
+    decl('space-sheet-row-height', pxRem(space.step.sheetRowHeight)),
     // `chartLegendGap`/`chartMarginTop`/`chartMarginRight`/`chartMarginBottom`/`chartMarginLeft`/
     // `chartDotR`/`progressBarSize`/`timelineBullet` are DELIBERATELY absent — see this function's
     // doc for why (JS-number-only consumers, zero `var()` reads). `appShellHeaderHeight`/
-    // `appShellHeaderMobileHeight`/`appShellNavbarWidth`/`appShellNavbarRailWidth` join that list —
-    // `shell/index.tsx` reads all four as JS numbers via `useBasaltSpacing()` (Mantine's `AppShell`
+    // `appShellNavbarWidth`/`appShellNavbarRailWidth` join that list —
+    // `shell/index.tsx` reads all three as JS numbers via `useBasaltSpacing()` (Mantine's `AppShell`
     // `header`/`navbar` props take numbers, not `var()` strings), so a `--vx-space-app-shell-*` decl
     // here would have had zero consumers, framework-wide, the same dead-weight shape this function's
     // doc already calls out for the chart/Progress/Timeline group. `sidebarAccountMenuWidth`/