basalt-ui 1.27.0 → 1.28.0

package/src/controls/select-filter.tsx

@@ -30,6 +30,8 @@
  * />
  */
 import type { ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { EnumField, FieldHandle, StringField } from '../state'
 import { EnumFilter } from './enum-filter'
 
@@ -45,7 +47,7 @@ export type FilterOption = {
   readonly disabled?: boolean
 }
 
-type SelectFilterCommon = {
+type SelectFilterCommon = BasaltProps & {
   readonly label: string
   readonly icon?: ReactNode
   /** Adds a `Clear` action that writes the field back to its fallback. */
@@ -78,6 +80,14 @@ export type SelectFilterProps<T extends string> = SelectFilterEnumProps<T> | Sel
 export function SelectFilter<T extends string>(props: SelectFilterEnumProps<T>): ReactNode
 export function SelectFilter(props: SelectFilterStringProps): ReactNode
 export function SelectFilter<T extends string>(props: SelectFilterProps<T>): ReactNode {
+  // F-ERR-1: without this, a `field` that never arrived surfaces as
+  // `undefined is not an object (evaluating 'field.use')` from inside `EnumFilter`, caught by
+  // `BasaltErrorBoundary` and rendered as a blank subtree. `field` is not optional in the type, so
+  // this only ever fires on untyped JS, a `props` object built at runtime, or a store key that
+  // resolved to nothing — all three of which the message now names.
+  assertRequiredProps('SelectFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
   const { field, ...rest } = props
 
   // Two arms, one body — and they are not the same code to the compiler. `field.kind` is a NESTED

package/src/controls/slider-control.tsx

@@ -0,0 +1,159 @@
+/**
+ * `SliderControl` — a `field.number` as an inspector row (`docs/ASIDE-SPEC.md` §1 "Inspector", G7).
+ * Bound like every other control on this subpath: it takes `field`, never `value`/`onChange`/`size`
+ * (C2/C5), and `min`/`max`/`step` come off the HANDLE rather than the call site, so the track's
+ * grain is the field's own declaration and not a second copy of it.
+ *
+ * **It is a ROW on every surface, and that is deliberate.** Unlike the filters it has no pill form:
+ * a chip whose label is a number, opening a popover holding a track, is two presses to change a
+ * value the row states and edits in place. So it renders {@link PanelRow} regardless of
+ * `useFilterSurface()`, and it is not a filter — it registers no `{ isActive, reset }` with a
+ * `FilterSet`, never counts toward `Filters (n)`, and never answers `Reset all`. Its home is an
+ * aside body or a section body, not a bar row.
+ *
+ * **The write lands on drag END, not on every frame.** A slider emits a value per pointer move; on
+ * the URL lane that is one navigation per pixel. The draft is local while dragging and commits
+ * once — the same law `NumberFilter`'s stepper states for keystrokes.
+ *
+ * @example
+ * // piCycle: field.number({ fallback: 1, min: 0, max: 2, step: 0.05 })
+ * <SliderControl
+ *   field={weights.field.piCycle}
+ *   label="Pi Cycle Top"
+ *   hint="The 111DMA / 350DMA×2 crossover."
+ *   format={(v) => `${v.toFixed(2)}×`}
+ * />
+ *
+ * @example
+ * // A COMPOSITION row: the readout states the metric's own reading beside the weight, and the
+ * // switch that governs the row rides the label line — neither is the field's value, so both are
+ * // overrides rather than a `format`.
+ * <SliderControl
+ *   field={weights.field.piCycle}
+ *   label="Pi Cycle Top"
+ *   readout="0.35 · ×1.00"
+ *   end={<Switch checked={on} onChange={toggle} aria-label="Include Pi Cycle Top" />}
+ *   disabled={!on}
+ * />
+ */
+import { Slider } from '@mantine/core'
+import { useEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
+import type { FieldHandle, NumberField } from '../state'
+import { PanelRow } from './panel-row'
+
+export type SliderControlProps = BasaltProps & {
+  readonly field: FieldHandle<NumberField>
+  /** The row's label, and the thumb's accessible name. */
+  readonly label: string
+  /** Info glyph + tooltip beside the label — see {@link PanelRow}. */
+  readonly hint?: string
+  /**
+   * The mono readout on the label line. The raw number when omitted, so a unit, a precision or a
+   * ratio is one function rather than a second row.
+   *
+   * @default String(v)
+   */
+  readonly format?: (v: number) => string
+  /**
+   * Replaces the formatted value in the row's readout slot.
+   *
+   * `format` prints the FIELD; this prints whatever the row is actually about. The composition row
+   * that motivated it states a metric's reading beside its weight — `0.35 · ×1.00` — which is one
+   * mono string over two numbers, only one of which this control owns. Prefer `format` whenever the
+   * readout is the field's own value. A FUNCTION form receives the live drag value, so a composed
+   * readout tracks the thumb per frame instead of updating on drag end.
+   */
+  readonly readout?: ReactNode | ((value: number) => ReactNode)
+  /**
+   * A control riding the LABEL line, forwarded to {@link PanelRow.end} — a `Switch` and, by design,
+   * almost nothing else. The composition row's use case is enabling the metric the slider weights:
+   * the toggle governs the row, so it cannot live inside the track it disables.
+   */
+  readonly end?: ReactNode
+  readonly disabled?: boolean
+}
+
+export function SliderControl(props: SliderControlProps): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('SliderControl', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, label, hint, format, readout, end, disabled, className, style } = props
+  const [value, setValue] = field.use()
+  const draft = useDraggedNumber(value, setValue)
+
+  return (
+    <PanelRow
+      label={label}
+      readout={
+        typeof readout === 'function'
+          ? readout(draft.value)
+          : (readout ?? (format ?? String)(draft.value))
+      }
+      {...(hint !== undefined && { hint })}
+      {...(end !== undefined && { end })}
+      {...(disabled === true && { disabled: true })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
+    >
+      <Slider
+        // The tier, stated by the control the way every control on this subpath does
+        // (`docs/CONTROLS-SPEC.md` §3) — `Slider` is deliberately absent from `CTL_THEME`, see
+        // `theme/ctl-theme.tsx`'s note, so the row's slot cannot supply it.
+        size="ctl"
+        // The drag tooltip is off: the row already prints the value, in mono, in a fixed place —
+        // a bubble that follows the thumb states the same number twice and jumps while reading.
+        label={null}
+        thumbLabel={label}
+        // The FIELD's declaration, straight off the handle. An undeclared bound leaves Mantine's own
+        // default (0..100) rather than passing `undefined` through as a bound.
+        {...(field.min !== undefined && { min: field.min })}
+        {...(field.max !== undefined && { max: field.max })}
+        {...(field.step !== undefined && { step: field.step })}
+        {...(disabled === true && { disabled: true })}
+        value={draft.value}
+        onChange={draft.set}
+        onChangeEnd={draft.commit}
+      />
+    </PanelRow>
+  )
+}
+
+/**
+ * A local draft that follows the thumb and lands on the field once, on `onChangeEnd` — plus the
+ * usual outside-change backstop (`Reset all`, a deep link, a back navigation, the codec's clamp).
+ *
+ * `seen` is what separates the two directions, exactly as in `SearchFilter`'s debounce and
+ * `NumberFilter`'s commit: it holds the last value this hook itself committed, so an incoming change
+ * it did not cause is the only thing that overwrites the draft mid-drag.
+ */
+function useDraggedNumber(
+  value: number,
+  setValue: (next: number) => void,
+): { value: number; set: (next: number) => void; commit: (next: number) => void } {
+  const [draft, setDraft] = useState(value)
+  const seen = useRef(value)
+  const commitRef = useRef(setValue)
+  commitRef.current = setValue
+
+  useEffect(() => {
+    if (seen.current === value) return
+    seen.current = value
+    setDraft(value)
+  }, [value])
+
+  return {
+    value: draft,
+    set: setDraft,
+    commit: (next) => {
+      setDraft(next)
+      if (next === value) return
+      seen.current = next
+      commitRef.current(next)
+    },
+  }
+}

package/src/controls/sync-button.tsx

@@ -23,10 +23,12 @@
 import { ActionIcon, Button, Tooltip } from '@mantine/core'
 import { useEffect, useState } from 'react'
 import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
 import { IconSlot } from '../theme/icon-slot'
 import classes from './sync-button.module.css'
 
-export type SyncButtonProps = {
+export type SyncButtonProps = BasaltProps & {
   syncing: boolean
   /** Last successful completion. `undefined`/`null` renders no age at all. */
   lastCompletedAt?: number | Date | null
@@ -134,6 +136,8 @@ export function SyncButton({
   scope,
   label = 'Sync',
   error,
+  className,
+  style,
 }: SyncButtonProps): ReactNode {
   const age = useRelativeAge(lastCompletedAt)
   // Wherever the label is not painted — every `global` mount, and a `page` mount below `sm` — the
@@ -172,7 +176,12 @@ export function SyncButton({
       withArrow
     >
       {scope === 'global' ? (
-        <ActionIcon variant="default" {...control}>
+        <ActionIcon
+          variant="default"
+          {...control}
+          {...(className !== undefined && { className })}
+          {...(style !== undefined && { style })}
+        >
           <IconSlot>
             <RefreshGlyph spinning={syncing} />
           </IconSlot>
@@ -180,7 +189,8 @@ export function SyncButton({
       ) : (
         <Button
           variant="default"
-          className={classes.pageButton}
+          className={cx(classes.pageButton, className)}
+          {...(style !== undefined && { style })}
           leftSection={
             <IconSlot>
               <RefreshGlyph spinning={syncing} />

package/src/controls/toggle-filter.tsx

@@ -1,46 +1,64 @@
 /**
  * `ToggleFilter` — a boolean field as one pill (`docs/CONTROLS-SPEC.md` §3). The only filter whose
  * pill has no popover: there is nothing to choose, so the pill IS the control and a press flips it.
- * In the sheet it becomes a `Switch` row, where a 44px row with an explicit on/off affordance reads
- * better than a chip whose state is a border colour.
+ * The sheet form is the panel form (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a
+ * Drawer") — a `PanelRow` whose control rides the label line, the ONE row every panel/sheet surface
+ * draws that way (`docs/ASIDE-SPEC.md` §3): a switch is atomic and needs no width, so the
+ * label-above law every other row follows would only cost it a second line.
  *
  * @example
  * // errorsOnly: field.boolean(false)
  * <ToggleFilter field={filters.field.errorsOnly} label="Errors only" />
  */
 import { Switch } from '@mantine/core'
+import { useId } from 'react'
 import type { ReactNode } from 'react'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { BooleanField, FieldHandle } from '../state'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
 import { FilterPill } from './filter-pill'
-import { sheetRowClassNames } from './filter-sheet'
+import { PanelRow } from './panel-row'
 
-export type ToggleFilterProps = {
+export type ToggleFilterProps = BasaltProps & {
   readonly field: FieldHandle<BooleanField>
   readonly label: string
   readonly icon?: ReactNode
 }
 
-export function ToggleFilter({ field, label, icon }: ToggleFilterProps): ReactNode {
+export function ToggleFilter(props: ToggleFilterProps): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('ToggleFilter', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, label, icon, className, style } = props
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
+  const id = useId()
   useFilterRegistration(!field.isDefault(value), () => {
     field.clear()
   })
 
-  if (surface === 'sheet') {
-    // The `Switch` IS the row — no wrapping div. `sheetRowClassNames` stretches its own `<label>`
-    // across the full 44px, so the whole row is the touch target rather than the middle 20px of it
-    // (C15). A wrapper div would put the height on a non-interactive box instead.
+  // The sheet form is the panel form (`docs/CONTROLS-SPEC.md` §3: "sheet = panel rows inside a
+  // Drawer") — the switch rides the label line on both surfaces, the one row whose control does.
+  if (surface === 'panel' || surface === 'sheet') {
     return (
-      <Switch
-        classNames={sheetRowClassNames}
-        checked={value}
+      <PanelRow
         label={label}
-        labelPosition="left"
-        onChange={(event) => {
-          setValue(event.currentTarget.checked)
-        }}
+        htmlFor={id}
+        end={
+          <Switch
+            id={id}
+            aria-label={label}
+            checked={value}
+            onChange={(event) => {
+              setValue(event.currentTarget.checked)
+            }}
+          />
+        }
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
       />
     )
   }
@@ -55,6 +73,8 @@ export function ToggleFilter({ field, label, icon }: ToggleFilterProps): ReactNo
       onClick={() => {
         setValue(!value)
       }}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     />
   )
 }

package/src/controls/view-tabs.tsx

@@ -6,12 +6,17 @@
  * The responsive swap lives HERE, not at the call site (C9), and it is CSS — `visibleFrom` /
  * `hiddenFrom`, one mount each, never a JS media query (which renders differently on the server than
  * on the first client paint). Below `sm` a set of three or fewer stays a full-width
- * `SegmentedControl`; past that a track cannot hold readable labels on a phone, so it becomes a
+ * `SegmentedControl` — PROVIDED every label actually fits it (`panel-row.tsx`'s `useTrackFits`,
+ * shared with `PanelChoice` so the two width gates cannot drift); past either gate it becomes a
  * `Select`.
  *
  * `only` is how a tab that exists on ONE viewport is declared instead of hand-rolling a second
  * control: `'sm-up'` keeps it off the phone form, `'sm-down'` keeps it off the desktop form.
  *
+ * Inside a `PageAside` it renders as a panel ROW — label above, a full-width track or a `Select`
+ * (`docs/ASIDE-SPEC.md` §3). A view switch in a panel is legal; the page bar's tab slot stays its
+ * default home, and `only` has no meaning there (the panel is one width).
+ *
  * @example
  * <ViewTabs
  *   field={strength.field.tab}
@@ -24,8 +29,14 @@
  */
 import { SegmentedControl, Select } from '@mantine/core'
 import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { EnumField, FieldHandle } from '../state'
 import classes from './controls.module.css'
+import { useFilterSurface } from './filter-context'
+import { useControlName } from './filter-sheet'
+import { PanelChoice, PanelRow, useTrackFits } from './panel-row'
 
 /** Past three options the phone form is a `Select`, not a track. */
 const PHONE_TRACK_MAX = 3
@@ -37,7 +48,7 @@ export type ViewTabsOption<T extends string> = {
   readonly only?: 'sm-up' | 'sm-down'
 }
 
-export type ViewTabsProps<T extends string> = {
+export type ViewTabsProps<T extends string> = BasaltProps & {
   readonly field: FieldHandle<EnumField<T>>
   /** Defaults to `field.options` (every declared value, labelled by `store.labels()`). */
   readonly options?: readonly ViewTabsOption<T>[]
@@ -51,12 +62,17 @@ export type ViewTabsProps<T extends string> = {
   readonly label?: string
 }
 
-export function ViewTabs<T extends string>({
-  field,
-  options,
-  label = 'View',
-}: ViewTabsProps<T>): ReactNode {
+export function ViewTabs<T extends string>(props: ViewTabsProps<T>): ReactNode {
+  // F-ERR-1 — without this a missing `field` surfaces as `undefined is not an object
+  // (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('ViewTabs', props, ['field'], {
+    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
+  })
+  const { field, options, label = 'View', className, style } = props
   const [value, setValue] = field.use()
+  const surface = useFilterSurface()
+  const inPanel = surface === 'panel'
+  const { labelId, nameProps } = useControlName(label, inPanel)
   const all: readonly ViewTabsOption<T>[] =
     options ?? field.options.map((option) => ({ value: option.value as T, label: option.label }))
 
@@ -68,6 +84,36 @@ export function ViewTabs<T extends string>({
     setValue(next as T)
   }
 
+  const phoneData = phone.map((option) => ({ value: option.value, label: option.label }))
+  const phoneCountFits = phone.length <= PHONE_TRACK_MAX
+  // Called UNCONDITIONALLY, even on the panel branch that never renders the phone form — a hook
+  // may not sit behind the `if (inPanel) return …` below (`react-hooks/rules-of-hooks`), and
+  // `useTrackFits` no-ops cheaply when `countFits` is false or its root never mounts. The same
+  // width gate `PanelChoice` runs (`panel-row.tsx`'s `useTrackFits` doc) — the count cap is the
+  // cheap first gate, a fit check underneath it is what actually decides.
+  const { rootRef: phoneRootRef, fits: phoneFits } = useTrackFits(
+    phoneCountFits,
+    phoneData.map((d) => d.value).join('|'),
+  )
+
+  // The panel form. `only` is dropped on purpose: it exists to declare a tab that belongs to ONE
+  // viewport, and a panel is not a viewport — every declared option is offered.
+  if (inPanel) {
+    return (
+      <PanelRow
+        label={label}
+        labelId={labelId}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      >
+        <PanelChoice nameProps={nameProps} value={value} options={all} onChange={commit} />
+      </PanelRow>
+    )
+  }
+
+  // No single root: exactly one of the two forms below is visible at once (CSS `visibleFrom`/
+  // `hiddenFrom`, law C9), so `className`/`style` land on both — whichever one paints is the one a
+  // reader ever sees carrying them.
   return (
     <>
       <SegmentedControl
@@ -77,16 +123,21 @@ export function ViewTabs<T extends string>({
         value={value}
         data={desktop.map((option) => ({ value: option.value, label: option.label }))}
         onChange={commit}
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
       />
-      {phone.length <= PHONE_TRACK_MAX ? (
+      {phoneFits ? (
         <SegmentedControl
+          ref={phoneRootRef}
           aria-label={label}
           hiddenFrom="sm"
           size="ctl"
           fullWidth
           value={value}
-          data={phone.map((option) => ({ value: option.value, label: option.label }))}
+          data={phoneData}
           onChange={commit}
+          {...(className !== undefined && { className })}
+          {...(style !== undefined && { style })}
         />
       ) : (
         <Select
@@ -96,10 +147,11 @@ export function ViewTabs<T extends string>({
           // BOUNDED, not greedy — see `.phoneSelect`'s comment in `controls.module.css`. This is the
           // control owning its own responsive form (law C9), which is also why it is not a `w` prop
           // at the call site (C5, `basalt/control-size-literal`).
-          className={classes.phoneSelect}
+          className={cx(classes.phoneSelect, className)}
+          {...(style !== undefined && { style })}
           value={value}
           allowDeselect={false}
-          data={phone.map((option) => ({ value: option.value, label: option.label }))}
+          data={phoneData}
           onChange={(next) => {
             if (next !== null) commit(next)
           }}

package/src/controls-dates/date-range-picker.tsx

@@ -24,9 +24,16 @@
  */
 import { DatePicker } from '@mantine/dates'
 import type { ReactNode } from 'react'
+import { assertRequiredProps } from '../common/validate'
 import type { RangeCustomPickerProps } from '../controls/range-filter'
 
-export function DateRangePicker({ value, onChange }: RangeCustomPickerProps): ReactNode {
+export function DateRangePicker(props: RangeCustomPickerProps): ReactNode {
+  // F-ERR-1 — without this a missing `value` surfaces as `undefined is not an object
+  // (evaluating 'value.from')`, caught by `BasaltErrorBoundary`.
+  assertRequiredProps('DateRangePicker', props, ['value'], {
+    value: "pass `{ from, to }` — usually injected by `RangeFilter`'s `customPicker`.",
+  })
+  const { value, onChange } = props
   return (
     <DatePicker
       type="range"

package/src/dashboard/delta-badge.tsx

@@ -2,5 +2,9 @@
  * `DeltaBadge` moved to `src/widget-header/` (docs/CONTROLS-SPEC.md §2.2) so `WidgetHeader` can
  * compose it Mantine-free. Re-exported here unchanged so this deep import path — and `StatCard`'s
  * own `./delta-badge` import — keep working without a wave-3 edit.
+ *
+ * `basalt-ui/widget-header` is canonical — this alias exists only so `basalt-ui/dashboard`-style
+ * deep imports keep resolving; the root barrel (`src/index.ts`) sources `DeltaBadge` from
+ * `../widget-header`, not from here.
  */
-export { DeltaBadge, type DeltaBadgeProps } from '../widget-header/delta-badge'
+export { DeltaBadge, type DeltaBadgeProps, type DeltaPolarity } from '../widget-header/delta-badge'

package/src/dashboard/empty-state.tsx

@@ -1,8 +1,8 @@
 /**
  * EmptyState — a centered icon/title/description/action stack for empty data regions (no shipped
- * illustration assets — `icon` is a plain, faint-rendered `ReactNode` slot). `variant="page"` uses
- * generous vertical padding for a full-page empty state; `variant="section"` is compact, for an
- * empty card/panel region.
+ * illustration assets — `icon` is a plain, faint-rendered `ReactNode` slot). `tier="page"` uses
+ * generous vertical padding for a full-page empty state; `tier="section"` is compact, for an
+ * empty card/panel region (`variant` is the deprecated spelling of the same prop — audit B #19).
  *
  * @example
  * import { EmptyState } from 'basalt-ui'
@@ -12,48 +12,89 @@
  *   title="No results"
  *   description="Try adjusting your filters or search terms."
  *   action={<Button onClick={onReset}>Clear filters</Button>}
- *   variant="section"
+ *   tier="section"
  * />
  */
 import { Center, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
 import { VX } from '../tokens'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
 
-export type EmptyStateProps = {
-  /** Optional glyph slot, rendered faint at ~28-32px. No shipped illustration assets. */
-  icon?: ReactNode
-  /** Head-font title (18px, weight 550, ink). */
-  title: string
-  /**
-   * Muted 15px description, capped at ~360px so it reads as a short explanation. Optional: a
-   * compact panel ("No data yet") should not have to invent a second sentence, and five argo
-   * features wrapped this component solely to avoid doing so.
-   */
-  description?: string
-  /** Optional call-to-action rendered below the description. */
-  action?: ReactNode
-  /** `'page'` (default) = generous padding for a full-page state; `'section'` = compact. */
-  variant?: 'page' | 'section'
-}
+/** The five boxes `EmptyState` paints, and the whole styling seam it offers (`common/props.ts`). */
+export type EmptyStateSlot = 'root' | 'icon' | 'title' | 'description' | 'action'
+
+export type EmptyStateProps = BasaltProps &
+  SlotStylesProps<EmptyStateSlot> & {
+    /** Optional glyph slot, rendered faint at ~28-32px. No shipped illustration assets. */
+    icon?: ReactNode
+    /** Head-font title (18px, weight 550, ink). */
+    title: string
+    /**
+     * Muted 15px description, capped at ~360px so it reads as a short explanation. Optional: a
+     * compact panel ("No data yet") should not have to invent a second sentence, and five argo
+     * features wrapped this component solely to avoid doing so.
+     */
+    description?: string
+    /** Optional call-to-action rendered below the description. */
+    action?: ReactNode
+    /** How loud this state is: `'page'` (default) = generous padding for a full-page state;
+     * `'section'` = compact. */
+    tier?: 'page' | 'section'
+    /** @deprecated Renamed to `tier` (audit B #19) — `tier` is the package's word for "how loud is
+     * this". Still honoured; `tier` wins when both are passed. */
+    variant?: 'page' | 'section'
+  }
+
+// The finest density-tracking rhythm step (`--vx-space-stack-xs`, 4px at level 0) scaled by an
+// exact integer, so the padding renders at today's px value at level 0 and rides the same
+// `1 + 0.1 * level` multiplier every other `--vx-space-*` token does at every other density level
+// (`docs/STATUS.md`'s density pass) — `LoadingState`'s `'page'` variant shares `PAGE_PADDING_Y`,
+// same concept: a page-level async/empty region's vertical padding.
+const STACK_XS = 'var(--vx-space-stack-xs, 0.25rem)'
+const PAGE_PADDING_Y = `calc(${STACK_XS} * 16)` // 64px at level 0
+const PAGE_PADDING_X = `calc(${STACK_XS} * 6)` // 24px at level 0
+const SECTION_PADDING_Y = `calc(${STACK_XS} * 8)` // 32px at level 0
+const SECTION_PADDING_X = `calc(${STACK_XS} * 5)` // 20px at level 0
 
 export function EmptyState({
   icon,
   title,
   description,
   action,
-  variant = 'page',
+  tier,
+  variant,
+  className,
+  style,
+  classNames,
 }: EmptyStateProps) {
+  const resolved = tier ?? variant ?? 'page'
   return (
     <Stack
       align="center"
       gap="xs"
+      className={cx(classNames?.root, className)}
       style={{
-        padding: variant === 'page' ? '64px 24px' : '32px 20px',
+        padding:
+          resolved === 'page'
+            ? `${PAGE_PADDING_Y} ${PAGE_PADDING_X}`
+            : `${SECTION_PADDING_Y} ${SECTION_PADDING_X}`,
         textAlign: 'center',
+        ...style,
       }}
     >
-      {icon && <Center style={{ width: 32, height: 32, color: VX.faint }}>{icon}</Center>}
+      {icon && (
+        // 32px is a fixed glyph-box size, not a density-tracking inset — no `--vx-icon-*` token
+        // exists for a generic (non-`WidgetHeader`-tiered) icon slot, so it stays a structural rem.
+        <Center
+          {...(classNames?.icon !== undefined && { className: classNames.icon })}
+          style={{ width: '2rem', height: '2rem', color: VX.faint }}
+        >
+          {icon}
+        </Center>
+      )}
       <span
+        className={classNames?.title}
         style={{
           fontFamily: 'var(--basalt-font-head)',
           fontStretch: '88%',
@@ -65,9 +106,15 @@ export function EmptyState({
         {title}
       </span>
       {description !== undefined && (
-        <span style={{ fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }}>{description}</span>
+        // 360px (22.5rem) is a reading-width cap, not a density inset — kept structural.
+        <span
+          className={classNames?.description}
+          style={{ fontSize: VX.text.md, color: VX.muted, maxWidth: '22.5rem' }}
+        >
+          {description}
+        </span>
       )}
-      {action}
+      {action !== undefined && <div className={classNames?.action}>{action}</div>}
     </Stack>
   )
 }