basalt-ui 1.30.2 → 1.31.0

package/src/styles.css

@@ -210,6 +210,47 @@
     background-color: var(--basalt-scrollbar-thumb-hover);
   }
 
+  /* Bottom-anchored toasts clear the shell's bottom bar + safe area (docs/CONTROLS-SPEC.md §2). */
+  .mantine-Notifications-root[data-position^='bottom'] {
+    bottom: calc(
+      var(--app-shell-footer-offset, 0px) + env(safe-area-inset-bottom, 0px) +
+        var(--mantine-spacing-md)
+    );
+  }
+
+  /* Pointer tier: an invisible hit-area expansion to at least `--vx-hit` (44px coarse, 24px fine),
+     no layout change. `::after`, not `::before` — Mantine's Button owns `::before` for its loading
+     overlay. `overflow: visible` is load-bearing: Button/ActionIcon roots clip to their box, which
+     would clip the overlay; the clip only serves their `[data-loading]` overlay, so it stays then.
+     Adopters: `data-basalt-hit` on the control, or `data-basalt-hit-scope` on a home whose
+     `button`/`a` descendants (consumer-supplied) adopt it.
+     DECISION: the axis is `pointer: coarse` (the PRIMARY input, via `--vx-hit`), never
+     `any-pointer` — a touch laptop's mouse-first session must not inflate every hit area.
+     OVERLAP CAP: a host with neighbours sets `--vx-hit-gap` (its real gap between controls); the
+     expansion is then limited to that gap in total (half per side), so adjacent hit boxes never
+     overlap and a later sibling never steals a tap. Unset = uncapped (an isolated control). The
+     `+ 2px` is the control's own 1px border (Mantine buttons carry one, transparent or not): `100%`
+     is the PADDING box, the gap is measured between border boxes.
+     `position: relative` is the ::after's containing block; an adopter that must be
+     absolute/sticky sets its own `position` in an unlayered rule, which outranks this layer. */
+  :is([data-basalt-hit], [data-basalt-hit-scope] :is(button, a)) {
+    position: relative;
+  }
+
+  :is([data-basalt-hit], [data-basalt-hit-scope] :is(button, a)):not([data-loading]) {
+    overflow: visible;
+  }
+
+  :is([data-basalt-hit], [data-basalt-hit-scope] :is(button, a))::after {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    translate: -50% -50%;
+    width: min(max(100%, var(--vx-hit)), calc(100% + 2px + var(--vx-hit-gap, 100vmax)));
+    height: min(max(100%, var(--vx-hit)), calc(100% + 2px + var(--vx-hit-gap, 100vmax)));
+  }
+
   /* Print: hide the BasaltShell chrome so only page content prints.
      Scoped to AppShell's own class hooks, NOT to bare nav/header/footer. The element form matched
      any landmark on the page — a consumer with a real <nav> and no BasaltShell silently printed a

package/src/surfaces.ts

@@ -66,6 +66,7 @@ export const PLUGIN_RULE_ID_LIST = [
   'agent-no-raw-usechat',
   'ai-sdk-major',
   'no-import-meta-env',
+  'raw-breakpoint',
 ] as const
 
 /** One registered oxlint plugin rule id — the literal union of {@link PLUGIN_RULE_ID_LIST}. */
@@ -262,12 +263,19 @@ export const SURFACES = {
       'inline-display',
       'raw-html-layout',
       'hidden-inline-style',
+      // The CSS-text twin of `raw-breakpoint` (below) — a width @media, an undeclared @container
+      // name/literal, or a non-coarse pointer query, the shape a JSX-only AST rule cannot see.
+      'raw-media-query',
     ],
     // The chrome half of the plugin: the shell, the card idiom, the page title and the scroll
     // doctrine. `hand-rolled-shell` sits here rather than on a shell-shaped surface because
     // `BasaltShell` IS the root barrel's promise (docs/CONTROLS-SPEC.md §6 wave 6).
     pluginRules: [
       'hand-rolled-shell',
+      // The size-class axis's one JSX escape hatch (docs/CONTROLS-SPEC.md §6) is reserved
+      // for BasaltShell/AppSidebar/MobileNav/AppBrand (`SHELL_HOME_NAMES`, configs/oxlint-plugin.js)
+      // — the same shell promise `hand-rolled-shell` polices, one axis over.
+      'raw-breakpoint',
       'card-inset',
       'in-body-page-title',
       'raw-scroll-container',
@@ -291,7 +299,7 @@ export const SURFACES = {
       "no second cssVariablesResolver — don't hand-build createTheme or re-add the resolver basalt already installs",
     ],
     description:
-      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useBreakpoint, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)',
+      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass (useBreakpoint on notice), NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)',
     optionalPeers: [
       'react-markdown',
       'remark-gfm',

package/src/theme/controls.module.css

@@ -61,6 +61,13 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
   box-shadow: var(--field-depth);
 }
 
+/* An input cannot host the `[data-basalt-hit]` ::after overlay, so its touch floor is real height. */
+@media (pointer: coarse) {
+  .input {
+    min-height: var(--vx-hit);
+  }
+}
+
 .input[data-variant='default'] {
   --field-depth: var(--vx-shadow-raised);
 }

package/src/theme/ctl-theme.tsx

@@ -48,6 +48,12 @@ import {
 import type { MantineSize, MantineThemeOverride } from '@mantine/core'
 import type { ReactNode } from 'react'
 
+// Mantine's typed prop bags reject `data-*` literals; a spread carries the hit-area attribute in.
+// Lives here (not `./index`, which imports THIS module) rather than the reverse, so `./index`'s own
+// USE of it (alongside `CTL_THEME`/`CtlSlot`) closes no new import cycle. `./index` does not
+// re-export it — it stays internal, reachable only through that import (see `./index`'s own doc).
+export const HIT_ATTR: Record<string, true> = { 'data-basalt-hit': true }
+
 /** The `MantineThemeOverride` a `<CtlSlot>` provides — see this module's doc for the merge/
  * precedence contract. Exported so a consumer composing its own slot (a bespoke home not covered
  * by `PageBar`/`Section`/the sidebar blocks) can reach the SAME tier without re-declaring it. */
@@ -63,7 +69,9 @@ export const CTL_THEME: MantineThemeOverride = {
     NativeSelect: NativeSelect.extend({ defaultProps: { size: 'ctl' } }),
     // The theme keys are the component names Mantine's own `useProps` looks up — `RadioGroup`, not
     // `Radio.Group` (`RadioGroup.mjs`: `useProps("RadioGroup", …)`).
-    Radio: Radio.extend({ defaultProps: { size: 'ctl' } }),
+    Radio: Radio.extend({
+      defaultProps: { size: 'ctl', attributes: { label: HIT_ATTR } },
+    }),
     // Mantine types `RadioGroup.size` as a CLOSED `MantineSize`, while `Radio`, `Checkbox`,
     // `Checkbox.Group`, `Switch` and `Switch.Group` all type theirs OPEN
     // (`MantineSize | (string & {})`) — verified in the installed 9.3.0 `.d.ts` files, so this is an
@@ -71,9 +79,13 @@ export const CTL_THEME: MantineThemeOverride = {
     // runtime `getSize` interpolates the string identically for all six. The cast restores what
     // every sibling type already allows; it widens nothing.
     RadioGroup: Radio.Group.extend({ defaultProps: { size: 'ctl' as MantineSize } }),
-    Checkbox: Checkbox.extend({ defaultProps: { size: 'ctl' } }),
+    Checkbox: Checkbox.extend({
+      defaultProps: { size: 'ctl', attributes: { label: HIT_ATTR } },
+    }),
     CheckboxGroup: Checkbox.Group.extend({ defaultProps: { size: 'ctl' } }),
-    Switch: Switch.extend({ defaultProps: { size: 'ctl' } }),
+    Switch: Switch.extend({
+      defaultProps: { size: 'ctl', attributes: { track: HIT_ATTR } },
+    }),
     SwitchGroup: Switch.Group.extend({ defaultProps: { size: 'ctl' } }),
   },
 }

package/src/theme/floating.module.css

@@ -33,3 +33,39 @@
 .menuItem[data-menu-active]:not(:disabled):not([data-disabled]) {
   background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent);
 }
+
+/*
+ * Modal as a bottom sheet at the `compact` size class (docs/DESIGN-CORE.md § Layout, elevation,
+ * shapes): anchored
+ * to the bottom edge, full width, radius on the top corners only, safe-area bottom padding. The
+ * literal is `sizeClassMaxEm(SIZE_CLASSES.medium)`, pinned by `breakpoint-literals.test.ts`.
+ * `.sheetBody` is the Modal body; it reaches the trailing button row `overlays.confirm`
+ * renders (Mantine `Group`), stretching the buttons to full width at the `--vx-hit` floor.
+ */
+@media (max-width: 52.49375em) {
+  .sheetInner {
+    align-items: flex-end;
+    padding: 0;
+  }
+
+  .sheetContent {
+    flex: 0 0 100%;
+    max-width: 100%;
+    /* theme-allow css-raw-surface — top corners only, the shape of a sheet. `!important`: the
+       Modal content is a Paper whose theme `styles.root` writes `border-radius` inline. */
+    border-radius: var(--vx-radius-card) var(--vx-radius-card) 0 0 !important;
+  }
+
+  .sheetBody {
+    padding-bottom: calc(var(--mantine-spacing-md) + env(safe-area-inset-bottom, 0px));
+  }
+
+  .sheetBody > :global(.mantine-Group-root):last-child {
+    flex-wrap: nowrap;
+  }
+
+  .sheetBody > :global(.mantine-Group-root):last-child > button {
+    flex: 1;
+    min-height: var(--vx-hit);
+  }
+}

package/src/theme/floating.module.css.d.ts

@@ -5,5 +5,8 @@
 declare const classes: {
   readonly closeButton: string
   readonly menuItem: string
+  readonly sheetBody: string
+  readonly sheetContent: string
+  readonly sheetInner: string
 }
 export default classes

package/src/theme/index.ts

@@ -43,6 +43,7 @@ import {
   Notification,
   NumberInput,
   Pagination,
+  PaginationControl,
   Paper,
   PasswordInput,
   PillsInput,
@@ -81,12 +82,14 @@ import type { PaletteData, RadiusValues, SpaceValues } from '../tokens/palette'
 import { DEFAULT_DERIVE_CONFIG, isDefaultDeriveConfig, resolveDeriveConfig } from '../tokens/derive'
 import type { DeriveConfig } from '../tokens/derive'
 import { pxRem, VX } from '../tokens'
+import { SIZE_CLASS_BREAKPOINTS } from '../tokens/size-classes'
 import type { BasaltFontsConfig } from '../tokens'
 import controlsClasses from './controls.module.css'
 import floatingClasses from './floating.module.css'
 import navLinkClasses from './nav-link.module.css'
 import segmentedControlClasses from './segmented-control.module.css'
 import timelineClasses from './timeline.module.css'
+import { HIT_ATTR } from './ctl-theme'
 
 /**
  * The `fonts` option's resolved shape — defined in `basalt-ui/tokens` (`BasaltFontsConfig`,
@@ -101,7 +104,9 @@ export type { BasaltFontsConfig } from '../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.
+// merge/precedence contract. `HIT_ATTR` is deliberately NOT in this list: it has no consumer of its
+// own (consolidation doctrine — adopt or delete), and stays reachable only through the internal
+// `./ctl-theme` import above, for this file's own use below.
 export { CTL_THEME, CtlSlot, type CtlSlotProps } from './ctl-theme'
 
 // `ThemeToggle` moved into this directory (C1 consolidation, merging the former `theme-toggle/`
@@ -182,6 +187,12 @@ function pinShades(
   return out as unknown as MantineColorsTuple
 }
 
+// Mantine's typed prop bags reject `data-*` literals; a spread carries the hit-area attribute in.
+// Defined in `./ctl-theme` (imported above) rather than here: `CTL_THEME` there is a top-level
+// `const` built eagerly at module load, so a `HIT_ATTR` defined in THIS file and imported back from
+// `ctl-theme.tsx` would close an import cycle this file's own line 107 doesn't already have — the
+// existing direction (this file depends on `ctl-theme.tsx`, not the reverse) is what keeps it safe.
+
 /** The shipped, config-independent palette data — `baseTheme` / `cssVariablesResolver` below are
  * built from this once, at module load. */
 const DEFAULT_PALETTE_DATA = buildPaletteData(DEFAULT_DERIVE_CONFIG)
@@ -422,6 +433,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
   const { radius = DEFAULT_RADIUS_VALUES, spacing = DEFAULT_SPACE_VALUES } = options
   const { ACCENT, FILL } = data
   return createTheme({
+    breakpoints: SIZE_CLASS_BREAKPOINTS,
     primaryColor: 'blue',
     // ONE shade in both schemes — a filled control is a SURFACE, and the accent surface is the same
     // hex either way (see `ACCENT.accentFill`). The scheme-inverting half of the accent lives in
@@ -670,6 +682,8 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
         classNames: { wrapper: controlsClasses.inputWrapper, input: controlsClasses.input },
       }),
       TextInput: TextInput.extend({ defaultProps: { size: 'md' } }),
+      // The stepper chevrons sit ~15px apart, so neither can own a 44px overlay; the coarse
+      // `.input` min-height floor (theme/controls.module.css) is the touch floor.
       NumberInput: NumberInput.extend({ defaultProps: { size: 'md' } }),
       PasswordInput: PasswordInput.extend({ defaultProps: { size: 'md' } }),
       Select: Select.extend({ defaultProps: { size: 'md' } }),
@@ -986,10 +1000,16 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // under it but shows every scrolled row straight through the title once one does (the mobile
       // filter sheet, the shell's "More" nav sheet). The header stays sticky; only its own
       // background moves back to opaque, matching the content box it sits above rather than the page
-      // behind it. Title = head font; close button = the ghost idiom (floating.module.css).
+      // behind it. Title = head font; close button = the ghost idiom (floating.module.css). Below the
+      // `medium` size class the Modal is a bottom sheet (floating.module.css `sheet*`).
       Modal: Modal.extend({
-        defaultProps: { radius: radius.floating },
-        classNames: { close: floatingClasses.closeButton },
+        defaultProps: { radius: radius.floating, closeButtonProps: { ...HIT_ATTR } },
+        classNames: {
+          close: floatingClasses.closeButton,
+          inner: floatingClasses.sheetInner,
+          content: floatingClasses.sheetContent,
+          body: floatingClasses.sheetBody,
+        },
         styles: {
           content: {
             backgroundColor: 'var(--vx-surface-overlay)',
@@ -1067,7 +1087,15 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // The v9 thumb indicator is a center dot painted in the TRACK color — over the remapped
       // neutral track it read as an artifact, so it's disabled: clean track, plain thumb, accent
       // fill when checked (`--switch-color` defaults to the primary filled shade = the accent).
-      Switch: Switch.extend({ defaultProps: { withThumbIndicator: false } }),
+      // `track` is the Switch's <label>, so the invisible `--vx-hit` overlay (`data-basalt-hit`)
+      // still toggles it. Checkbox/Radio boxes are bare <input>s under a plain <div> — an overlay
+      // there would swallow clicks, so only their `label` (a real <label>) carries it.
+      Switch: Switch.extend({
+        defaultProps: {
+          withThumbIndicator: false,
+          attributes: { track: HIT_ATTR },
+        },
+      }),
       // The tab-list bottom rule (and the inactive-tab hover underline) is a layout separator, not
       // control chrome — it reads the divider token instead of the heavy gray-3/dark-4 line
       // (controls.module.css; custom properties are stripped from `styles` objects). The active tab
@@ -1091,6 +1119,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // `useStyles`), so re-pointing that var here wins on every render path. Without this, a dark-mode
       // Checkbox/Radio paints a white checkmark on the light accent fill — invisible.
       Checkbox: Checkbox.extend({
+        defaultProps: { attributes: { label: HIT_ATTR } },
         vars: (theme, props) => ({
           root: {
             // `iconColor` is an explicit call-site override, and `outline` paints the mark in the
@@ -1101,6 +1130,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
         }),
       }),
       Radio: Radio.extend({
+        defaultProps: { attributes: { label: HIT_ATTR } },
         vars: (theme, props) => ({
           root: {
             '--radio-icon-color':
@@ -1113,6 +1143,12 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
           root: { '--pagination-active-color': onColorFor(theme, props) },
         }),
       }),
+      // `Pagination`'s own controls (prev/next/page buttons) resolve `PaginationControl`'s
+      // defaultProps independently of the parent — `data-basalt-hit` here is what closes the
+      // gap Switch/Checkbox/Radio already close at their own theme entries.
+      PaginationControl: PaginationControl.extend({
+        defaultProps: { ...HIT_ATTR },
+      }),
       Stepper: Stepper.extend({
         vars: (theme, props) => ({ root: { '--stepper-icon-color': onColorFor(theme, props) } }),
       }),
@@ -1556,7 +1592,7 @@ function hasFontsConfig(fonts: BasaltFontsConfig | undefined): fonts is BasaltFo
 /**
  * Build the Basalt theme, optionally merged with consumer overrides. Overrides win on conflict
  * (Mantine `mergeThemeOverrides` is last-wins), so a consumer can retune any field without
- * forking the base.
+ * forking the base — except `breakpoints`, which is always derived from `SIZE_CLASSES`.
  *
  * Pass `{ derive }` to retune the palette identity instead of the shipped default, `{ fonts }` to
  * retune the three-font system, `{ radius }` to retune the two radius anchors, and/or `{ density }`
@@ -1578,7 +1614,7 @@ function hasFontsConfig(fonts: BasaltFontsConfig | undefined): fonts is BasaltFo
  * — it is only lost if a consumer's own `overrides.other` explicitly sets that same key.
  */
 export function createBasaltTheme(
-  overrides?: MantineThemeOverride,
+  overrides?: Omit<MantineThemeOverride, 'breakpoints'>,
   options?: CreateBasaltThemeOptions,
 ): MantineThemeOverride {
   const resolvedConfig = resolveDeriveConfig(options?.derive)
@@ -1610,5 +1646,7 @@ export function createBasaltTheme(
   if (hasFontsConfig(fontsConfig)) {
     theme = mergeThemeOverrides(theme, { other: { basaltFonts: fontsConfig } })
   }
-  return overrides ? mergeThemeOverrides(theme, overrides) : theme
+  if (!overrides) return theme
+  // `theme.breakpoints` is derived from `SIZE_CLASSES` — a JS caller's override is dropped.
+  return { ...mergeThemeOverrides(theme, overrides), breakpoints: SIZE_CLASS_BREAKPOINTS }
 }

package/src/theme/nav-link.module.css

@@ -21,6 +21,13 @@
   font-weight: 600;
 }
 
+/* Touch floor: rows are adjacent (1px gap), so an overlay would overlap — the row itself is 44. */
+@media (pointer: coarse) {
+  .root {
+    min-height: var(--vx-hit);
+  }
+}
+
 /* Active + hover — one step stronger than the resting active fill, so a pointer over the active row
  * still reads as feedback rather than as a flat, unresponsive selection. */
 @media (hover: hover) {

package/src/tokens/index.ts

@@ -16,11 +16,12 @@ import {
   ROW_LINE_HEIGHT,
   SHADOW,
   SPACE,
-  SPACE_FIXED,
   SPACE_SCALE,
   SPACE_STEP,
 } from './palette'
 import type { PaletteData, RadiusValues, SpaceValues } from './palette'
+import { SIZE_CLASSES, sizeClassMaxEm } from './size-classes'
+import { HIT_COARSE, HIT_FINE } from '../common/hit-floor'
 
 // The raw hue families + pair-picker — the building blocks a consumer's series module composes
 // (`hrv: p(BP.blue)`). The doctrine sends every consumer here, so they are public surface, not
@@ -159,11 +160,9 @@ export const VX = {
   // Fully-rounded pill affordance (scroll-to-bottom button, chips) — fixed, does not track the
   // radius knob (see `RADIUS_STEP.pill`'s doc in `tokens/palette.ts`).
   radiusPill: 'var(--vx-radius-pill)',
-  // The WCAG 2.5.5/2.5.8 touch-target floor (44px), fixed — does not track the density knob (see
-  // `SPACE_FIXED.spaceTouchTarget`'s doc in `tokens/palette.ts`). For a hit area with no `ctl`-tier
-  // home to size it — a consumer's own `@media (pointer: coarse)` CSS-module rule reads the same
-  // `--vx-space-touch-target` var this resolves to.
-  spaceTouchTarget: 'var(--vx-space-touch-target)',
+  // The pointer-tier hit floor: 44px under `(pointer: coarse)` (WCAG 2.5.5), 24px otherwise
+  // (2.5.8). Density-exempt; `[data-basalt-hit]::after` in `styles.css` reads it.
+  hit: 'var(--vx-hit)',
 
   // 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`/
@@ -173,7 +172,6 @@ export const VX = {
     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)',
@@ -292,18 +290,10 @@ export const VX = {
    * legend rolls up).
    */
   minPlotHeight: 120,
-  /**
-   * The measured CONTAINER width, in px, below which a chart resolves to its phone tier
-   * (`resolveChartTier`, `docs/CHARTS-SPEC.md` §8): one step smaller legend and tick fonts,
-   * tightened margin floors, a smaller crosshair dot, a narrower tooltip, and a two-entry legend
-   * rollup.
-   *
-   * Deliberately NOT a media query and NOT a `theme.breakpoints` value. A chart in a two-column
-   * grid cell on a 1440px desktop is as narrow as one on a phone, and only the element's own
-   * measured box knows that — the viewport does not. It also keeps the chart layer Mantine-free:
-   * `theme.breakpoints` lives on the coupled side of the boundary.
-   */
-  phoneChartWidth: 480,
+  /** Every floating chart overlay portalled to `document.body` — a pinned tooltip, the legend's
+   * `All N` disclosure and its backdrop — shares one stacking value, so they always stack the same
+   * way relative to page chrome and to each other. */
+  zIndexFloating: 9999,
 } as const
 
 /**
@@ -317,13 +307,13 @@ export const VX = {
  * `styles.floor.test.ts`).
  *
  * Only breakpoints that are genuinely a CSS-authored `@media` belong here. A component that can
- * measure its own box uses the measurement instead (`VX.phoneChartWidth`), and Mantine chrome uses
+ * measure its own box uses the measurement instead (`CONTAINER_CLASSES`), and Mantine chrome uses
  * `theme.breakpoints`.
  */
 export const BREAKPOINTS = {
   /**
    * `content/article-layout.module.css` — below this the TOC rail is dropped and the article
-   * collapses to a single centred column. Well above the `sm` (48em/768px) shell breakpoint on
+   * collapses to a single centred column. Well above the `sm` (52.5em/840px) shell breakpoint on
    * purpose: the rail needs the prose measure PLUS its own width plus the column gap, which runs
    * out long before the shell goes mobile.
    */
@@ -484,7 +474,7 @@ 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`,
+ * The nine controls-tier anchors/one-offs (`controlHeightTag`/`Widget`/`Ctl`,
  * `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
@@ -548,7 +538,6 @@ function spaceDecls(space: SpaceValues): string[] {
     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`),
@@ -774,10 +763,9 @@ function frameworkDerived(data: PaletteData, only: 'core' | 'all', legacyAliases
     // only in this static block, never in `buildRadiusCss`'s dynamic override (see
     // `RADIUS_STEP.pill`'s doc).
     decl('radius-pill', `${RADIUS_STEP.pill}px`),
-    // The WCAG touch-target floor — fixed, density-EXEMPT, so it lives only in this static block,
-    // never in `buildDensityCss`'s dynamic override (same law as `radius-pill` above; see
-    // `SPACE_FIXED.spaceTouchTarget`'s doc).
-    decl('space-touch-target', `${SPACE_FIXED.spaceTouchTarget}px`),
+    // The pointer tier's fine default — density-EXEMPT, so it lives only in this static block
+    // (same law as `radius-pill` above). `coarseHitBlock` re-points it to 44px.
+    decl('hit', `${HIT_FINE}px`),
     ...(only === 'core' ? space.filter(isCoreSpaceDecl) : space),
     // Article-density Prose measure (docs/CONTENT-SPEC.md §5) — theme-independent, like the radii.
     decl('prose-measure', '72ch'),
@@ -944,7 +932,9 @@ const indent = (block: string): string =>
  * properties exist, so the number cannot be a `var()`. Held here as a constant rather than inlined
  * so the emitter and the modules can be grepped as one set.
  */
-const MOBILE_MEDIA = '@media (max-width: 47.99375em)'
+const MOBILE_MEDIA = `@media (max-width: ${sizeClassMaxEm(SIZE_CLASSES.medium)})`
+
+const coarseHitBlock = `@media (pointer: coarse) {\n  :root {\n    --vx-hit: ${HIT_COARSE}px;\n  }\n}`
 
 /**
  * The MOBILE INSET LADDER, and this function is its ONE home — framework-wide, not per module.
@@ -1032,8 +1022,8 @@ export function buildPaletteCss(
   // consumer never receives the base pair the block exists to override.
   const rootBlock =
     only === 'core'
-      ? `:root {\n${derived}\n}`
-      : `:root {\n${derived}\n}\n${mobileLadderBlock(DEFAULT_SPACE_VALUES)}`
+      ? `:root {\n${derived}\n}\n${coarseHitBlock}`
+      : `:root {\n${derived}\n}\n${mobileLadderBlock(DEFAULT_SPACE_VALUES)}\n${coarseHitBlock}`
 
   // The legacy shape — kept verbatim, and only reachable when the caller asked for nothing.
   if (opts.scheme === undefined && opts.defaultScheme === undefined && !opts.mediaFallback) {

package/src/tokens/palette.ts

@@ -321,11 +321,6 @@ const SPACE_ANCHORS_BASE = {
    * 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
-   * table. Floored at 30px in {@link deriveSpacing} (C15's "floor 30 at density −3"). */
-  touchControlHeight: 36,
 } as const
 
 /**
@@ -618,9 +613,8 @@ const SPACE_STEP_BASE = {
    *
    *  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. */
+   *  keeps 6px of breathing room a side, still clears `controlHeight` (42) for a `size="md"`
+   *  control, and is the 44px touch floor (WCAG 2.5.5). */
   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
@@ -696,12 +690,9 @@ const SPACE_STEP_BASE = {
   mobileNavTabInsetY: 2,
   /** Active-pill inset around the slot icon, horizontal. */
   mobileNavTabInsetX: 12,
-  /** Menu/sheet row height. Floored at 40px in `deriveSpacing` — a deliberate design choice, not
-   *  a WCAG floor: it's the row height shared with the desktop sidebar rows, above the WCAG 2.5.8
-   *  AA minimum (24px) and below the 2.5.5 AAA figure (44px, the size `mobileNavBarHeight`/
-   *  `sheetRowHeight` still hold to) — the shortest box that still reads as ONE row vocabulary with
-   *  the sidebar instead of a bespoke touch size. */
-  mobileNavRowHeight: 40,
+  /** Menu/sheet row height — the WCAG 2.5.5 44px target, floored at 44 in `deriveSpacing` (the
+   *  pointer tier's `--vx-hit` is the same number under `(pointer: coarse)`). */
+  mobileNavRowHeight: 44,
   /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
    *  `sidebarSettingsMenuWidth` directly above. */
   mobileNavMenuWidth: 232,
@@ -853,18 +844,6 @@ export const SPACE_FIXED = {
    * `[-3, 3]` range can produce) for no compensating benefit, since the two radii it sits between
    * never move independently of each other. */
   segmentedTrackInset: 2,
-  /**
-   * The WCAG 2.5.5/2.5.8 touch-target floor (44px) for a hit area that has no `ctl`-tier home to
-   * size it — a raw CSS-module rule bumping a control's hit area under `@media (pointer: coarse)`
-   * (C5 consolidation: argo carried three such rules with a hand-picked 44/46px literal apiece).
-   * Density-exempt for the same reason `touchControlHeight`'s FLOOR is: a target this small must
-   * never shrink further, whatever the density knob says elsewhere. Unlike the rest of this
-   * object, this ONE key IS emitted as a `--vx-*` var (`tokens/index.ts`'s `space-touch-target`) —
-   * the others stay JS-only because nothing outside the framework's own components reads them, but
-   * this floor's whole purpose is being read by a CONSUMER's own `.module.css`, which cannot
-   * import a JS ref at all.
-   */
-  spaceTouchTarget: 44,
 } as const
 
 /**
@@ -1095,7 +1074,6 @@ export function deriveSpacing(level: number): SpaceValues {
   anchors.controlHeightTag = Math.max(18, anchors.controlHeightTag)
   anchors.controlHeightWidget = Math.max(22, anchors.controlHeightWidget)
   anchors.controlHeightCtl = Math.max(28, anchors.controlHeightCtl)
-  anchors.touchControlHeight = Math.max(30, anchors.touchControlHeight)
 
   const mappedStep = mapSpaceGroup(SPACE_STEP_BASE, level, multiplier)
   // WCAG 2.5.8 minimum interactive-target size — see this function's doc for why the trigger's
@@ -1112,7 +1090,7 @@ export function deriveSpacing(level: number): SpaceValues {
   // box) would render at 47px if the floor stopped at 48. +1 buys back exactly the pixel the seam
   // claims, so the tappable bar itself still measures >= 48.
   mappedStep.mobileNavBarHeight = Math.max(49, mappedStep.mobileNavBarHeight)
-  mappedStep.mobileNavRowHeight = Math.max(40, mappedStep.mobileNavRowHeight)
+  mappedStep.mobileNavRowHeight = Math.max(44, mappedStep.mobileNavRowHeight)
   // Same floor family, same reason — `sheetRowHeight`'s own doc names it "same floor family as
   // `mobileNavRowHeight`", but nothing enforced that below level 0 until now.
   mappedStep.sheetRowHeight = Math.max(44, mappedStep.sheetRowHeight)

package/src/tokens/size-classes.ts

@@ -0,0 +1,46 @@
+/**
+ * The two responsive tables (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) — pure data, Mantine-free. Each
+ * value is the class's minimum width in px.
+ *
+ * A `@media`/`@container` condition cannot read a custom property, so CSS writes the literal and
+ * `breakpoint-literals.test.ts` pins every literal to these tables.
+ */
+
+/** Viewport classes — shell chrome only (bottom bar / rail / sidebar, aside docking). */
+export const SIZE_CLASSES = { compact: 0, medium: 840, expanded: 1200 } as const
+
+/** A component's own inline size — card chrome, chart tier, forms. No CSS reads it yet. */
+export const CONTAINER_CLASSES = { micro: 0, compact: 240, regular: 480, wide: 800 } as const
+
+export type ContainerClass = keyof typeof CONTAINER_CLASSES
+
+/** The class a MEASURED inline size falls in (`px` is a min-width boundary, so 240 is `compact`). */
+export function resolveContainerClass(px: number): ContainerClass {
+  if (px >= CONTAINER_CLASSES.wide) return 'wide'
+  if (px >= CONTAINER_CLASSES.regular) return 'regular'
+  if (px >= CONTAINER_CLASSES.compact) return 'compact'
+  return 'micro'
+}
+
+/**
+ * `theme.breakpoints`, derived — a consumer cannot retune it. Mantine needs all five keys:
+ * `base` (no key) is compact, `xs`/`sm` open the medium class, `md`/`lg`/`xl` the expanded one, so
+ * every `visibleFrom`/`hiddenFrom` in the package stays "desktop chrome" from `sm` up.
+ */
+export const SIZE_CLASS_BREAKPOINTS = {
+  xs: `${SIZE_CLASSES.medium / 16}em`,
+  sm: `${SIZE_CLASSES.medium / 16}em`,
+  md: `${SIZE_CLASSES.expanded / 16}em`,
+  lg: `${SIZE_CLASSES.expanded / 16}em`,
+  xl: `${SIZE_CLASSES.expanded / 16}em`,
+} as const
+
+/** A px width as the `em` length media queries use (16px root). */
+export function toEm(px: number): string {
+  return `${Number((px / 16).toFixed(5))}em`
+}
+
+/** The `max-width` complement of a class boundary — 0.1px under it, Mantine's own convention. */
+export function sizeClassMaxEm(minPx: number): string {
+  return toEm(minPx - 0.1)
+}

package/dist/shell/isomorphic-layout-effect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"isomorphic-layout-effect.d.ts","sourceRoot":"","sources":["../../src/shell/isomorphic-layout-effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAmB,MAAM,OAAO,CAAA;AAElD,eAAO,MAAM,yBAAyB,kBAA8D,CAAA"}