basalt-ui 1.41.0 → 2.0.1

package/src/tokens/core.ts

@@ -0,0 +1,1163 @@
+/**
+ * Mantine-free token + palette layer.
+ *
+ * This module is PURE DATA + string helpers — ZERO `@mantine/*` imports (lint-enforced).
+ * Colors are CSS custom properties under the `--vx-*` prefix (do NOT rename the prefix).
+ * They resolve per color scheme in CSS, so `VX.*` works in components AND in non-component
+ * files. Apply opacity via `alpha(token, a)` (never raw `rgba()`) so the hue keeps resolving.
+ *
+ * Grounded in argo `packages/charts/src/{tokens,palette,theme-vars,utils/color}.ts`.
+ */
+
+import {
+  buildPaletteData,
+  RADIUS,
+  RADIUS_STEP,
+  ROW_LINE_HEIGHT,
+  SHADOW,
+  SPACE,
+  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'
+import { BASALT_VX_FAMILIES } from '../common/vx-families'
+import { vxFamilyOf } from '../common/vx-family'
+
+// The raw hue families + pair-picker — the building blocks a consumer's series module composes
+// (`hrv: p(BP.blue)`). The doctrine sends every consumer to `basalt-ui/tokens`, so they are public
+// surface, not palette internals; dropping them from the public barrel (`./index`) hard-fails the
+// consumer's build (1.0.0 bug, pinned by scripts/export-surface.json).
+export { BP, p } from './palette'
+
+// The six-knob derive engine — the generator behind the shipped default palette. Internal: the
+// public barrel (`./index`) does not re-export it; a consumer retunes the palette identity via
+// `createBasaltTheme(overrides, { derive })` (see `../theme`) without hand-picking hexes, and
+// reaches a derived palette through that, not by building `--vx-*` CSS for a custom config directly.
+export { DEFAULT_DERIVE_CONFIG, deriveTokens, resolveDeriveConfig } from './derive'
+export type { DeriveConfig, DerivedPalette } from './derive'
+
+// The radius analog of the derive engine — the law behind `createBasaltTheme(overrides, { radius })`
+// (see `../theme`). `RADIUS`/`RADIUS_STEP` stay internal to the theme layer; a consumer retunes the
+// two anchors through `createBasaltTheme`, not by calling `deriveRadius` directly (it is exposed for
+// the law itself to be inspectable/testable, same rationale as `deriveTokens`).
+export { deriveRadius } from './palette'
+export type { RadiusValues } from './palette'
+
+// The density analog of the derive engine — the law behind `createBasaltTheme(overrides, {
+// density })` (see `../theme`). `SPACE`/`SPACE_SCALE`/`SPACE_STEP`/`ROW_LINE_HEIGHT` stay internal
+// to the theme layer; a consumer retunes them through `createBasaltTheme`, not by calling
+// `deriveSpacing` directly (it is exposed for the law itself to be inspectable/testable, same
+// rationale as `deriveRadius`).
+export { deriveSpacing } from './palette'
+export type { SpaceValues } from './palette'
+
+// The two responsive tables — MIGRATING recipes and the raw-breakpoint guard messages send
+// consumers here for them; `migrating-imports.test.ts` pins that every documented import resolves.
+export {
+  CONTAINER_CLASSES,
+  CONTAINER_GRID_BREAKPOINTS,
+  CONTAINER_KEYS,
+  resolveContainerClass,
+  SIZE_CLASSES,
+} from './size-classes'
+export type { ContainerClass } from './size-classes'
+
+/** A per-theme color pair: a hue keeps its identity but shifts shade across schemes. */
+export type ColorPair = { light: string; dark: string }
+
+/** A map of token name → per-theme color pair (the input shape for series/group builders). */
+export type SeriesMap = Record<string, ColorPair>
+
+/**
+ * Apply opacity to any palette token, theme-aware. Use instead of raw `rgba()` so the
+ * underlying hue still resolves per color scheme.
+ *
+ *   alpha(VX.neutral, 0.5)        // muted hairline
+ *   alpha(VX.status.warn, 0.1)    // zone-band fill
+ */
+export const alpha = (token: string, a: number): string =>
+  `color-mix(in srgb, ${token} ${Math.round(a * 100)}%, transparent)`
+
+/**
+ * VX tokens — `var(--vx-*)` string refs + non-color sizing constants. Colors resolve per
+ * color scheme in CSS, so `VX.*` works in components AND in non-component files. Never
+ * reference raw hex in chart files — use `VX.*` / `alpha()`.
+ *
+ * The framework ships ONLY generic primitives — no domain `VX.series` tree (apps rebuild
+ * that with `seriesTokens` / `groupTokens` against their own series maps).
+ */
+/**
+ * The type scale — the ONE owned ladder, in px.
+ *
+ * Type is a token axis like color / spacing / radius / motion: a single edit point, never a
+ * hardcoded literal at a call site. Every font-size in the framework resolves to a step here.
+ *
+ * Two representations are DERIVED from this one object, so they cannot drift:
+ *  • `VX.text.*` — plain numbers, for inline `style` objects and visx SVG props (React appends
+ *    `px`; SVG presentation attributes can't resolve `var()`, so a ref string would break charts).
+ *  • `--vx-text-*` — the CSS-var form (`11px`, …), for CSS modules and the Mantine theme.
+ *
+ * The Mantine theme additionally re-expresses the ladder through Mantine's `rem()` (see
+ * `theme/index.ts`), so the component surface scales with the user's browser font-size AND with
+ * `--mantine-scale`. `md` is the body step; `lg` is pinned at exactly 16px because it doubles as
+ * the iOS input floor (see the `styles.css` floor — Safari zooms the viewport on focus below 16px).
+ *
+ * ## Adding a rung
+ *
+ * The ladder is hand-tuned per ROLE, not generated — but it is not arbitrary either, and the
+ * constraint is what keeps a "just add the size I need" request from dissolving it. Every adjacent
+ * pair sits between **1.06× and 1.17×**, so a new rung must too:
+ *
+ *  • Below the range, two rungs are visually the same size and the ladder stops being a choice —
+ *    the guard would then report a size for which two tokens are equally "right".
+ *  • Above it, the jump reads as a different type system rather than the next step of this one.
+ *
+ * That test is what admitted `nano` (11/10 = 1.10) and `display` (30/26 = 1.154, the second-widest
+ * step, which is the shape a display tier is supposed to have), and what rejected a 20px rung
+ * between `xl` (18) and `h2` (21): 21/20 = 1.05 is below the floor, and `h2` is already 1px away
+ * from any 20px site. A size the ladder declines to grow a rung for is a size that should snap to
+ * its nearest step — not a `theme-allow`.
+ *
+ * A rung is also a ROLE, not just a number. `nano` and `display` are both deliberately named for
+ * where they belong (a label engraved inside a drawn object; a numeral read from across a room)
+ * rather than for a position, because the failure mode of a bare `xxs`/`xxl` is that it becomes the
+ * escape hatch for every size the ladder was meant to prevent.
+ */
+const TEXT = {
+  nano: 10, // engraved/graphic label INSIDE a drawn object (a plate face, a dial, a chip) — never UI copy or prose
+  micro: 11, // mono uppercase micro-label (table th, Menu.Label, sidebar/section headers, axis ticks)
+  xs: 12.5, // delta badges, tooltip meta, dense chrome, StatCard labels
+  sm: 13.5, // table/stat numerals, chart tooltip, legend
+  md: 15, // BODY — nav rows, menu items, timeline, labels, prose; chart/card titles
+  lg: 16, // breadcrumb current — ALSO the iOS input floor (do not lower)
+  xl: 18, // section titles
+  h2: 21, // article-density Prose h2 (docs/CONTENT-SPEC.md §5)
+  kpi: 24, // the StatCard hero numeral (density pass: 31 → 24, tighter/less shouty)
+  h1: 26, // article-density Prose h1 (docs/CONTENT-SPEC.md §5)
+  display: 30, // a numeral read at arm's length (a keypad readout, a timer, a kiosk figure) — not a heading
+} as const
+
+export const VX = {
+  // Non-color sizing constants
+  // Stroke WEIGHTS, not spacing — deliberately fixed, never density-tracking (see
+  // `SPACE_STEP_BASE`'s "charts" group doc in tokens/palette.ts).
+  lineWidth: 2.5,
+  line2Width: 2,
+  axisFont: TEXT.micro,
+  // A discrete visual footprint (not a stroke weight), so — unlike `lineWidth`/`line2Width` above —
+  // it DOES track density; single-sourced from `SPACE_STEP.chartDotR` (see that constant's doc).
+  dotR: SPACE_STEP.chartDotR,
+  // The ONE dashed pattern — plotted stroke, legend swatch, tooltip swatch all read this.
+  dashArray: '6 4' as const,
+  // Legend layout — single-sourced from `SPACE_STEP.chartLegendGap` (density-tracking; see that
+  // constant's doc). Still a raw number here (not `var()`) — the chart legend applies it via inline
+  // `style`, and this is the one static (level-0) value; `createBasaltTheme({ density })` has no
+  // wiring into chart render props yet, so this number does NOT move live with the knob (same
+  // "dev slider/production JS defaultProps" gap as Timeline's `bulletSize` — see `deriveSpacing`'s
+  // doc in tokens/palette.ts).
+  legendGap: SPACE_STEP.chartLegendGap,
+  legendFontSize: TEXT.sm,
+
+  // The type scale (px numbers — see TEXT above). Use in inline styles and visx SVG props;
+  // use `var(--vx-text-*)` in CSS modules.
+  text: TEXT,
+
+  // Single source for the card corner radius — shared by the Mantine-free ChartCard and the
+  // Mantine chrome (Card/Paper resolve to this SAME token). One knob, so cards never diverge.
+  radiusCard: 'var(--vx-radius-card)',
+  // Single source for the control corner radius (inputs, search, buttons, segmented track).
+  radiusCtrl: 'var(--vx-radius-ctrl)',
+  // 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 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`/
+  // `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)',
+    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)',
+
+  // Semantic fills — consistent opacity across all charts
+  good: 'var(--vx-good)',
+  goodSoft: 'var(--vx-good-soft)',
+  bad: 'var(--vx-bad)',
+  warn: 'var(--vx-warn)',
+  goodSolid: 'var(--vx-good-solid)',
+  badSolid: 'var(--vx-bad-solid)',
+  warnSolid: 'var(--vx-warn-solid)',
+
+  // Reference/dashed lines for thresholds
+  goodRef: 'var(--vx-good-ref)',
+  badRef: 'var(--vx-bad-ref)',
+  warnRef: 'var(--vx-warn-ref)',
+
+  // Neutral primary line/text color — the default for single-series, no-signal marks
+  // ("white/gray per theme"). Same value as the NEUTRAL.line pair.
+  line: 'var(--vx-line)',
+  line2: 'var(--vx-line2)',
+
+  // Axis label + axis stroke colors (theme-aware). Exposed as flat refs so a bespoke chart that
+  // renders raw <text> labels or axis lines (without the Axis* primitives) needs no hook.
+  axis: 'var(--vx-axis)',
+  axisStroke: 'var(--vx-axis-stroke)',
+
+  // Grid, hover, legend
+  grid: 'var(--vx-grid)',
+  crosshair: 'var(--vx-crosshair)',
+  dotStroke: 'var(--vx-dot-stroke)',
+  legendText: 'var(--vx-legend-text)',
+
+  // Tooltip chrome — muted (secondary) text inside a bespoke tooltip. The other tooltip vars
+  // (bg/text/border/shadow) reach the engine tooltip as `--ts-chart-tooltip-*` (`charts/theme.ts`);
+  // this one is flattened onto `VX` too because bespoke-tooltip authors reached for `VX.muted` (the
+  // general ink-ramp muted) instead and got the wrong token — same pattern as `VX.muted` below.
+  tooltipMuted: 'var(--vx-tooltip-muted)',
+
+  // Base neutral for hairlines / muted text / overlays — apply opacity via alpha()
+  neutral: 'var(--vx-neutral)',
+
+  // Ink text ramp (docs/DESIGN-SPEC.md §2) — primary/emphasis/secondary/tertiary body text.
+  ink: 'var(--vx-ink)',
+  ink2: 'var(--vx-ink2)',
+  muted: 'var(--vx-muted)',
+  faint: 'var(--vx-faint)',
+
+  // The accent as INK — primary series, active-nav icon, links, focus rings. Read against the PAGE,
+  // so it inverts across schemes (light on dark, deep on light).
+  accent: 'var(--vx-accent)',
+  accentHover: 'var(--vx-accent-hover)',
+  // The accent as SURFACE — a filled control that carries a label. Squeezed between white-text
+  // contrast and page contrast, so it is the same hex in both schemes (see ACCENT in palette.ts).
+  // Mantine's `--mantine-color-<primary>-filled` is bridged onto this, so it drives ALL filled
+  // chrome; a raw `--vx-accent` fill would be unreadable on dark. Fills use THIS, never `accent`.
+  accentFill: 'var(--vx-accent-fill)',
+  accentFillHover: 'var(--vx-accent-fill-hover)',
+  onAccent: 'var(--vx-on-accent)',
+
+  // Layout separators (header bottom rule, sidebar child indent) — distinct from `surface.border`.
+  divider: 'var(--vx-divider)',
+
+  // Depth shadows — a whisper shadow + a 1px ring baked into the value (never a `border` prop).
+  shadowCard: 'var(--vx-shadow-card)',
+  shadowCtrl: 'var(--vx-shadow-ctrl)',
+  // Raised interactive controls — drop + a 1px INSET edge, the one depth every raised Button/
+  // ActionIcon variant shares (works over a fill, a tint or a panel alike; see SHADOW.raised).
+  shadowRaised: 'var(--vx-shadow-raised)',
+  // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a real drop shadow.
+  shadowOverlay: 'var(--vx-shadow-overlay)',
+
+  // App surfaces (cards, borders) — shared with the Mantine chrome
+  surface: {
+    bg: 'var(--vx-surface-bg)',
+    panel: 'var(--vx-surface-panel)',
+    panelHover: 'var(--vx-surface-panel-hover)',
+    elevated: 'var(--vx-surface-elevated)',
+    subtle: 'var(--vx-surface-subtle)',
+    overlay: 'var(--vx-surface-overlay)', // floating layer (menus, popovers, modals, drawers)
+    field: 'var(--vx-surface-field)', // input field surface (slightly inset on a panel)
+    border: 'var(--vx-surface-border)', // "line" — strong border
+    hairline: 'var(--vx-surface-hairline)', // card ring only
+  },
+
+  // Score / zone status scale (excellent → poor)
+  status: {
+    excellent: 'var(--vx-status-excellent)',
+    good: 'var(--vx-status-good)',
+    warn: 'var(--vx-status-warn)',
+    bad: 'var(--vx-status-bad)',
+    neutral: 'var(--vx-status-neutral)',
+  },
+
+  // Shared sizing — single-sourced from the `SPACE_STEP` chart-margin steps (density-tracking; same
+  // static-value/no-live-wiring note as `legendGap` above).
+  margin: {
+    top: SPACE_STEP.chartMarginTop,
+    right: SPACE_STEP.chartMarginRight,
+    bottom: SPACE_STEP.chartMarginBottom,
+    left: SPACE_STEP.chartMarginLeft,
+  },
+  minPxPerTick: 55,
+  /**
+   * Floor on a chart's plot rect height, in px (the 1.x chart frame). A legend wrapping to five rows at
+   * phone width used to eat a fixed `height={240}` toward zero and the plot simply stopped
+   * rendering — the plot never shrinks past this, the frame grows instead (or, under `fill`, the
+   * legend rolls up).
+   */
+  minPlotHeight: 120,
+  /** 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
+
+/**
+ * Layout breakpoints, in px, for the places CSS cannot read a custom property.
+ *
+ * A `@media` query's condition is resolved before custom properties exist, so
+ * `@media (max-width: var(--x))` is invalid CSS — a stylesheet with a responsive rule has no
+ * choice but to write the number. This constant is the other half of that literal: the CSS states
+ * the number and names the token beside it, and a test asserts the two agree
+ * (`content/article-layout.breakpoint.test.ts`, the same "literal must match the token" idiom as
+ * `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 (`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` (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.
+   */
+  article: 1200,
+} as const
+
+type Side = 'light' | 'dark'
+
+/** A CSS declaration line for a single `--vx-*` custom property. */
+const decl = (name: string, value: string): string => `  --vx-${name}: ${value};`
+
+/**
+ * A px number expressed as the plain rem STRING literal (16px base: `pxRem(6)` → `'0.375rem'`) —
+ * NOT Mantine's own `rem()` helper, which instead emits a `calc(...)` expression bound to
+ * `--mantine-scale` (a different value; that scaling happens at the Mantine-coupled call site
+ * instead — see `theme/index.ts`'s `Input.extend` `vars` for why `--vx-space-input-height` needs
+ * both halves). The SINGLE source for this conversion — `theme/index.ts` imports this instead of
+ * keeping its own copy, so the radius/spacing size-scale steps and this module's own rem-emitting
+ * vars (`--vx-space-input-height`) can never compute the conversion two different ways.
+ */
+export function pxRem(px: number): string {
+  return `${px / 16}rem`
+}
+
+/** Emit one prefixed group of pairs for a given scheme side. */
+const groupSide = (prefix: string, map: SeriesMap, side: Side): string =>
+  Object.entries(map)
+    .map(([key, pair]) => decl(`${prefix}${key}`, pair[side]))
+    .join('\n')
+
+/**
+ * The 16 deprecated camelCase aliases for `frameworkPrimitives`' per-scheme canonicals, each
+ * defined as `var(--vx-<canonical-kebab-name>)` so it can never drift from the value above it.
+ * Emitted as its own commented, trailing group (never interleaved with the canonicals) — gated by
+ * {@link BuildPaletteOpts.legacyAliases}, default on. See that option's doc for the migration
+ * rationale (1.4.0 kebab-case normalization).
+ */
+function frameworkPrimitivesAliases(): string {
+  return [
+    '  /* Deprecated camelCase aliases — removed in a future minor; migrate to the kebab names above. */',
+    decl('goodSolid', 'var(--vx-good-solid)'),
+    decl('badSolid', 'var(--vx-bad-solid)'),
+    decl('warnSolid', 'var(--vx-warn-solid)'),
+    decl('axisStroke', 'var(--vx-axis-stroke)'),
+    decl('dotStroke', 'var(--vx-dot-stroke)'),
+    decl('tooltipBg', 'var(--vx-tooltip-bg)'),
+    decl('tooltipText', 'var(--vx-tooltip-text)'),
+    decl('tooltipMuted', 'var(--vx-tooltip-muted)'),
+    decl('tooltipBorder', 'var(--vx-tooltip-border)'),
+    decl('tooltipShadow', 'var(--vx-tooltip-shadow)'),
+    decl('legendText', 'var(--vx-legend-text)'),
+    decl('accentHover', 'var(--vx-accent-hover)'),
+    decl('accentFill', 'var(--vx-accent-fill)'),
+    decl('accentFillHover', 'var(--vx-accent-fill-hover)'),
+    decl('onAccent', 'var(--vx-on-accent)'),
+    decl('surface-panelHover', 'var(--vx-surface-panel-hover)'),
+  ].join('\n')
+}
+
+/**
+ * Built-in framework primitives for a given scheme side — STATUS group, semantic solids,
+ * neutral line/axis/grid/tooltip chrome, legend text, and the surface ramp. Domain series
+ * (SERIES/ACTIVITY/USAGE) are NOT shipped — apps append them via `opts.groups`.
+ */
+function frameworkPrimitives(side: Side, data: PaletteData, legacyAliases: boolean): string {
+  const n = data.NEUTRAL
+  const s = data.SEMANTIC
+  const su = data.SURFACE
+  const ink = data.INK
+  const ac = data.ACCENT
+  const canonical = [
+    groupSide('status-', data.STATUS as SeriesMap, side),
+    decl('good-solid', s.good[side]),
+    decl('bad-solid', s.bad[side]),
+    decl('warn-solid', s.warn[side]),
+    decl('neutral', n.neutral[side]),
+    decl('line', n.line[side]),
+    decl('line2', n.line2[side]),
+    decl('axis', n.axis[side]),
+    decl('axis-stroke', n.axisStroke[side]),
+    decl('grid', n.grid[side]),
+    decl('crosshair', n.crosshair[side]),
+    decl('dot-stroke', n.dotStroke[side]),
+    decl('tooltip-bg', n.tooltipBg[side]),
+    decl('tooltip-text', n.tooltipText[side]),
+    decl('tooltip-muted', n.tooltipMuted[side]),
+    decl('tooltip-border', n.tooltipBorder[side]),
+    decl('tooltip-shadow', n.tooltipShadow[side]),
+    decl('legend-text', n.legendText[side]),
+    decl('ink', ink.ink[side]),
+    decl('ink2', ink.ink2[side]),
+    decl('muted', ink.muted[side]),
+    decl('faint', ink.faint[side]),
+    decl('accent', ac.accent[side]),
+    decl('accent-hover', ac.accentHover[side]),
+    decl('accent-fill', ac.accentFill[side]),
+    decl('accent-fill-hover', ac.accentFillHover[side]),
+    decl('on-accent', ac.onAccent[side]),
+    decl('divider', su.divider[side]),
+    decl('shadow-card', SHADOW.card[side]),
+    decl('shadow-ctrl', SHADOW.ctrl[side]),
+    decl('shadow-raised', SHADOW.raised[side]),
+    decl('shadow-overlay', SHADOW.overlay[side]),
+    decl('surface-bg', su.bg[side]),
+    decl('surface-panel', su.panel[side]),
+    decl('surface-panel-hover', su.panelHover[side]),
+    decl('surface-elevated', su.elevated[side]),
+    decl('surface-subtle', su.subtle[side]),
+    decl('surface-overlay', su.overlay[side]),
+    decl('surface-field', su.field[side]),
+    decl('surface-border', su.border[side]),
+    decl('surface-hairline', su.hairline[side]),
+  ].join('\n')
+  return legacyAliases ? `${canonical}\n${frameworkPrimitivesAliases()}` : canonical
+}
+
+/**
+ * The `--vx-space-*` declaration list for a resolved {@link SpaceValues} — every anchor and one-off
+ * that has at least one real `var()` consumer, plus the row line-height. Shared by
+ * `frameworkDerived` (emits the shipped defaults unconditionally, called with `DEFAULT_SPACE_
+ * VALUES`) and {@link buildDensityCss} (emits an OVERRIDING block for a retuned density level), so
+ * the two lists can never drift apart — mirrors `frameworkDerived`'s own single-source reasoning for
+ * the radii.
+ *
+ * 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
+ * `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.
+ *
+ * Deliberately DOES NOT emit a var for every `SpaceValues` number — `space.scale.*` (the generic
+ * Mantine spacing scale) and seventeen `space.step.*` keys have ZERO `var()` consumers anywhere in
+ * the framework or its tests beyond the CSS-emission test itself. Each is read straight off the
+ * 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,appShellNavbarWidth,appShellNavbarRailWidth,appShellAsideWidth,
+ * appShellAsideRailWidth,
+ * mobileNavBarHeight}` are numeric Mantine component props (Menu `width`, AppShell `header`/
+ * `navbar`/`footer`); and `{chartLegendGap,chartMarginTop,chartMarginRight,
+ * chartMarginBottom,chartMarginLeft,chartDotR}` are visx SVG props via
+ * `VX.legendGap`/`VX.margin`/`VX.dotR` in this file's own `VX` object. The full list is locked
+ * against the `SpaceValues` key set by `tokens/density.test.ts`'s declaration-set test, so adding a
+ * one-off silently omits nothing. A `--vx-space-*` declaration for any of them would be dead weight
+ * that only looked like the fix for
+ * the dev-slider/production gap those JS reads actually have (see `deriveSpacing`'s JSDoc in
+ * `tokens/palette.ts` for the real scope of that gap — it is materially bigger than "a var these
+ * numbers could round-trip through"). `theme.spacing` (the generic scale, JS) already resolves
+ * through `--mantine-spacing-*` on the PRODUCTION `createBasaltTheme({ density })` path
+ * (`theme/index.ts`'s `buildTheme`), so nothing downstream of the generic scale actually needed
+ * `--vx-space-scale-*` either — deleted along with the rest rather than kept as an unread alias.
+ */
+function spaceDecls(space: SpaceValues): string[] {
+  return [
+    decl('space-row-inset-x', `${space.anchors.rowInsetX}px`),
+    decl('space-row-inset-y', `${space.anchors.rowInsetY}px`),
+    // Additive law, not the multiplier — see `deriveSpacing`'s doc in `tokens/palette.ts`. No unit:
+    // `line-height` is a unitless CSS value.
+    decl('space-row-line-height', `${space.rowLineHeight}`),
+    // A `size: 'md'` Input's resolved height. Mantine's own `--input-height-md` is
+    // `calc(2.625rem * var(--mantine-scale))` (BOTH `styles.css` and `styles.layer.css`, verified
+    // in the installed package) — REM-relative to the root font size AND scale-aware, not a flat
+    // px. Emitting this in REM (via `pxRem`, not a bare `${…}px`) preserves the rem half; the
+    // `* var(--mantine-scale))` half is reconstructed at the Mantine-coupled call site
+    // (`theme/index.ts`'s `Input.extend` `vars`, which wraps this var in the matching `calc(...)`)
+    // — this module stays Mantine-free, so it cannot reference `--mantine-scale` itself. Flattening
+    // either half into a flat px would desync input height from the user's root font size (an
+    // accessibility regression) and from Mantine's global `--mantine-scale` knob.
+    decl('space-input-height', pxRem(space.anchors.inputHeight)),
+    // A `size: 'md'` Button's/ActionIcon's resolved height — SAME rem-plus-scale reasoning and
+    // reconstruction as `space-input-height` above (`theme/index.ts`'s `Button.extend`/
+    // `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-stack-xs', `${space.anchors.stackXs}px`),
+    decl('space-stack-sm', `${space.anchors.stackSm}px`),
+    decl('space-stack-md', `${space.anchors.stackMd}px`),
+    decl('space-stack-lg', `${space.anchors.stackLg}px`),
+    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.
+    // ONE value at every viewport since 1.26.0 — the AppShell header is a single
+    // `appShellHeaderHeight` 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-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`),
+    decl('space-prose-quote-indent', `${space.step.proseQuoteIndent}px`),
+    decl('space-prose-inline-code-inset-y', `${space.step.proseInlineCodeInsetY}px`),
+    decl('space-prose-inline-code-inset-x', `${space.step.proseInlineCodeInsetX}px`),
+    decl('space-prose-code-block-inset-y', `${space.step.proseCodeBlockInsetY}px`),
+    decl('space-prose-code-block-inset-x', `${space.step.proseCodeBlockInsetX}px`),
+    decl('space-prose-heading-anchor-gap', `${space.step.proseHeadingAnchorGap}px`),
+    decl('space-prose-table-cell-inset-y', `${space.step.proseTableCellInsetY}px`),
+    decl('space-prose-table-cell-inset-x', `${space.step.proseTableCellInsetX}px`),
+    decl('space-prose-chat-list-gap-bottom', `${space.step.proseChatListGapBottom}px`),
+    decl('space-prose-chat-list-indent', `${space.step.proseChatListIndent}px`),
+    decl('space-prose-chat-list-item-gap', `${space.step.proseChatListItemGap}px`),
+    decl('space-prose-chat-nested-list-gap', `${space.step.proseChatNestedListGap}px`),
+    decl('space-prose-chat-heading-gap-top', `${space.step.proseChatHeadingGapTop}px`),
+    decl('space-prose-chat-heading-gap-bottom', `${space.step.proseChatHeadingGapBottom}px`),
+    decl('space-prose-article-paragraph-gap', `${space.step.proseArticleParagraphGap}px`),
+    decl('space-prose-article-list-gap-top', `${space.step.proseArticleListGapTop}px`),
+    decl('space-prose-article-list-gap-bottom', `${space.step.proseArticleListGapBottom}px`),
+    decl('space-prose-article-list-indent', `${space.step.proseArticleListIndent}px`),
+    decl('space-prose-article-h1-gap-top', `${space.step.proseArticleH1GapTop}px`),
+    decl('space-prose-article-h1-gap-bottom', `${space.step.proseArticleH1GapBottom}px`),
+    decl('space-prose-article-heading-gap-top', `${space.step.proseArticleHeadingGapTop}px`),
+    decl('space-prose-article-heading-gap-bottom', `${space.step.proseArticleHeadingGapBottom}px`),
+    decl('space-prose-article-h2-rule-gap', `${space.step.proseArticleH2RuleGap}px`),
+    decl('space-prose-article-block-gap', `${space.step.proseArticleBlockGap}px`),
+    decl('space-article-column-gap', `${space.step.articleColumnGap}px`),
+    decl('space-article-toc-rail-width', `${space.step.articleTocRailWidth}px`),
+    decl('space-article-header-gap', `${space.step.articleHeaderGap}px`),
+    decl('space-article-header-padding-bottom', `${space.step.articleHeaderPaddingBottom}px`),
+    decl('space-article-header-margin-bottom', `${space.step.articleHeaderMarginBottom}px`),
+    decl('space-article-meta-row-gap', `${space.step.articleMetaRowGap}px`),
+    decl('space-article-footer-gap', `${space.step.articleFooterGap}px`),
+    decl('space-article-footer-margin-top', `${space.step.articleFooterMarginTop}px`),
+    decl('space-article-footer-padding-top', `${space.step.articleFooterPaddingTop}px`),
+    decl('space-article-nav-target-gap', `${space.step.articleNavTargetGap}px`),
+    decl('space-code-block-header-gap', `${space.step.codeBlockHeaderGap}px`),
+    decl('space-code-block-header-inset-y', `${space.step.codeBlockHeaderInsetY}px`),
+    decl('space-code-block-header-inset-right', `${space.step.codeBlockHeaderInsetRight}px`),
+    decl('space-code-block-content-inset-x', `${space.step.codeBlockContentInsetX}px`),
+    decl('space-code-block-header-right-gap', `${space.step.codeBlockHeaderRightGap}px`),
+    decl('space-code-block-body-inset-y', `${space.step.codeBlockBodyInsetY}px`),
+    decl('space-code-block-floating-copy-offset', `${space.step.codeBlockFloatingCopyOffset}px`),
+    decl('space-callout-inset-y', `${space.step.calloutInsetY}px`),
+    decl('space-callout-inset-x', `${space.step.calloutInsetX}px`),
+    decl('space-callout-title-row-gap', `${space.step.calloutTitleRowGap}px`),
+    decl('space-toc-root-gap', `${space.step.tocRootGap}px`),
+    decl('space-toc-link-inset-y', `${space.step.tocLinkInsetY}px`),
+    decl('space-toc-link-indent', `${space.step.tocLinkIndent}px`),
+    decl('space-toc-sub-indent', `${space.step.tocSubIndent}px`),
+    decl('space-article-card-tags-gap', `${space.step.articleCardTagsGap}px`),
+    decl('space-article-card-tag-inset-y', `${space.step.articleCardTagInsetY}px`),
+    decl('space-article-card-tag-inset-x', `${space.step.articleCardTagInsetX}px`),
+    decl('space-article-card-meta-gap-top', `${space.step.articleCardMetaGapTop}px`),
+    decl('space-guide-body-gap-bottom', `${space.step.guideBodyGapBottom}px`),
+    decl('space-guide-footer-gap-top', `${space.step.guideFooterGapTop}px`),
+    decl('space-guide-footer-inset-top', `${space.step.guideFooterInsetTop}px`),
+    decl('space-sidebar-search-gap', `${space.step.sidebarSearchGap}px`),
+    decl('space-sidebar-search-trigger-height', `${space.step.sidebarSearchTriggerHeight}px`),
+    decl('space-settings-row-inset-y', `${space.step.settingsRowInsetY}px`),
+    decl('space-settings-row-gap', `${space.step.settingsRowGap}px`),
+    decl('space-mermaid-container-inset', `${space.step.mermaidContainerInset}px`),
+    decl('space-sidebar-brand-inset-x', `${space.step.sidebarBrandInsetX}px`),
+    decl('space-sidebar-section-gap', `${space.step.sidebarSectionGap}px`),
+    decl('space-sidebar-account-inset-top', `${space.step.sidebarAccountInsetTop}px`),
+    decl('space-sidebar-account-inset-x', `${space.step.sidebarAccountInsetX}px`),
+    decl('space-sidebar-account-inset-bottom', `${space.step.sidebarAccountInsetBottom}px`),
+    decl('space-sidebar-avatar-size', `${space.step.sidebarAvatarSize}px`),
+    decl('space-sidebar-section-label-gap', `${space.step.sidebarSectionLabelGap}px`),
+    decl('space-sidebar-child-list-gap-top', `${space.step.sidebarChildListGapTop}px`),
+    decl('space-sidebar-child-list-gap-bottom', `${space.step.sidebarChildListGapBottom}px`),
+    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`),
+    // The page gutter — the ONE `appShell*` dimension that IS emitted, against the JS-number-only
+    // rule its five neighbours follow (see the note at the bottom of this list). It earns the
+    // exception because it is the most visible spacing number the framework ships — every page's
+    // left edge — and it was, until now, the one number the `--vx-*` layer did not expose at all, so
+    // a consumer retuning its identity through `createBasaltTheme` could not reach it and had to
+    // reach past the token layer into `AppShell.Main`'s own styles. Emitted in PLAIN PX, like every
+    // other inset/gap in this list and unlike the `pxRem` heights above it: the rem-plus-
+    // `var(--mantine-scale)` reconstruction exists so a CONTROL's box tracks the root font size and
+    // Mantine's global scale knob; a page gutter is a layout margin against a viewport, not a box
+    // sized to text, so scaling it with the font would make a large-type user's content column
+    // narrower rather than more legible.
+    decl('space-app-shell-inset', `${space.step.appShellInset}px`),
+    decl('space-app-shell-inset-mobile', `${space.step.appShellInsetMobile}px`),
+    // The header's breadcrumb floor — emitted for the same reason as the gutter pair above it and
+    // not for the JS-number reason its `appShell*` neighbours below are withheld for: this one has
+    // a real CSS consumer (`shell/app-header.module.css`'s `.lead`), which is the whole test this
+    // list applies. Plain px, like every other layout dimension here.
+    decl('space-app-shell-header-lead-min', `${space.step.appShellHeaderLeadMin}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`),
+    decl('space-mobile-nav-tab-inset-x', `${space.step.mobileNavTabInsetX}px`),
+    decl('space-mobile-nav-row-height', `${space.step.mobileNavRowHeight}px`),
+    decl('space-agent-rail-inset-x', `${space.step.agentRailInsetX}px`),
+    decl('space-agent-part-gap-top', `${space.step.agentPartGapTop}px`),
+    decl('space-agent-code-inset', `${space.step.agentCodeInset}px`),
+    decl('space-agent-error-inset-y', `${space.step.agentErrorInsetY}px`),
+    decl('space-agent-error-inset-x', `${space.step.agentErrorInsetX}px`),
+    decl('space-agent-scroll-button-gap-top', `${space.step.agentScrollButtonGapTop}px`),
+    decl('space-agent-message-inset-y', `${space.step.agentMessageInsetY}px`),
+    decl('space-agent-message-inset-x', `${space.step.agentMessageInsetX}px`),
+    decl('space-agent-transcript-inset', `${space.step.agentTranscriptInset}px`),
+    decl('space-badge-inset-y', `${space.step.badgeInsetY}px`),
+    decl('space-badge-inset-x', `${space.step.badgeInsetX}px`),
+    decl('space-stat-card-gap', `${space.step.statCardGap}px`),
+    // The card/section inset ladder — the three values `spaceMobileDecls` below re-points at `< sm`
+    // (see its doc for where the law lives and why it lives there).
+    decl('space-card-inset-y', `${space.step.cardInsetY}px`),
+    decl('space-card-inset-x', `${space.step.cardInsetX}px`),
+    decl('space-section-gap', `${space.step.sectionGap}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`/
+    // `appShellNavbarWidth`/`appShellNavbarRailWidth`/`appShellAsideWidth`/`appShellAsideRailWidth`
+    // join that list — but NOT `appShellInset`/`appShellInsetMobile`/`appShellHeaderLeadMin`, which
+    // are emitted above and carry their own reason for the exception —
+    // `shell/index.tsx` reads all five as JS numbers via `useBasaltSpacing()` (Mantine's `AppShell`
+    // `header`/`navbar`/`aside` 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`/
+    // `sidebarSettingsMenuWidth` join it too — `app-sidebar-account.tsx`/`app-sidebar.tsx` read both
+    // as JS numbers via `useBasaltSpacing()` (Mantine's `<Menu width={…}>` also takes a number).
+  ]
+}
+
+/**
+ * The `--vx-space-*` names that survive `only: 'core'` — DERIVED from the `SPACE` anchor keys, never
+ * hand-listed, so a new `SPACE_STEP` one-off is excluded the moment it is added and a renamed anchor
+ * follows automatically. `SPACE` is the generic ladder (the stack rhythm, the two control heights,
+ * the row insets); everything else `spaceDecls` emits is named for a basalt COMPONENT and is dead
+ * weight outside this framework — including `--vx-space-row-line-height`, which is the NavLink row's
+ * line-height rather than a general anchor and so is (deliberately) in neither set.
+ */
+const CORE_SPACE_VARS = new Set(
+  Object.keys(SPACE).map((key) => `space-${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`),
+)
+
+/**
+ * Does this `spaceDecls` line declare a core anchor? The name is read back out of the emitted line
+ * because {@link decl} is the single formatter for every one of them — the shape is fixed at one
+ * call site, so parsing it cannot drift, whereas tagging 104 declarations by hand could.
+ */
+function isCoreSpaceDecl(line: string): boolean {
+  const name = /^ {2}--vx-([\w-]+):/.exec(line)?.[1]
+  return name !== undefined && CORE_SPACE_VARS.has(name)
+}
+
+/** The shipped, level-0 spacing values — `frameworkDerived`'s `spaceDecls(...)` call below. No
+ * `createBasaltTheme({ density })` retuning applies here; that path calls `buildDensityCss` with a
+ * different resolved {@link SpaceValues} instead (see `../theme` and `../provider`). */
+const DEFAULT_SPACE_VALUES: SpaceValues = {
+  anchors: SPACE,
+  scale: SPACE_SCALE,
+  step: SPACE_STEP,
+  rowLineHeight: ROW_LINE_HEIGHT,
+}
+
+/**
+ * The 16 deprecated camelCase aliases for `frameworkDerived`'s theme-independent (`:root`)
+ * canonicals — the 12 `fill-hover-<family>` fills plus `good-soft`/`good-ref`/`bad-ref`/`warn-ref`.
+ * Each is a `var(--vx-<canonical-kebab-name>)` ref so it can never drift. Emitted as its own
+ * commented, trailing group — gated by {@link BuildPaletteOpts.legacyAliases}, default on.
+ */
+function frameworkDerivedAliases(data: PaletteData): string {
+  return [
+    '  /* Deprecated camelCase aliases — removed in a future minor; migrate to the kebab names above. */',
+    ...Object.keys(data.FILL).map((name) =>
+      decl(`fillHover-${name}`, `var(--vx-fill-hover-${name})`),
+    ),
+    decl('goodSoft', 'var(--vx-good-soft)'),
+    decl('goodRef', 'var(--vx-good-ref)'),
+    decl('badRef', 'var(--vx-bad-ref)'),
+    decl('warnRef', 'var(--vx-warn-ref)'),
+  ].join('\n')
+}
+
+/**
+ * Theme-independent scalars + semantic fills, defined once on `:root`.
+ *
+ * Area-gradient strength is a global knob (the theme lab overrides these two on `:root`
+ * to retune every line-area fill live). 0%/0% disables gradients app-wide.
+ */
+function frameworkDerived(data: PaletteData, only: 'core' | 'all', legacyAliases: boolean): string {
+  const space = spaceDecls(DEFAULT_SPACE_VALUES)
+  const canonical = [
+    decl('radius-card', `${RADIUS.card}px`),
+    decl('radius-ctrl', `${RADIUS.ctrl}px`),
+    // The two offset tiers (SegmentedControl indicator/Kbd/Code, Progress/scale-sm) — added so a
+    // component's inline `styles`/`style` can read the SAME source as `RADIUS_STEP.tight`/`.fine`
+    // instead of a hand-typed literal (see `theme/index.ts`'s component sweep).
+    decl('radius-tight', `${RADIUS_STEP.tight}px`),
+    decl('radius-fine', `${RADIUS_STEP.fine}px`),
+    // The floating tier (Modal/Tooltip/Popover/Notification, content code/mermaid blocks).
+    decl('radius-floating', `${RADIUS_STEP.floating}px`),
+    // The pill affordance (scroll-to-bottom button, chips) — fixed, level-invariant, so it lives
+    // 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 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'),
+    // The fill band (see FILL in palette.ts). Emitted on `:root`, NOT per scheme — a filled surface
+    // is the same hex in both, which is the whole point: it is squeezed between its white label and
+    // the page behind it, and only one luminance band satisfies both on both pages.
+    ...Object.entries(data.FILL).map(([name, hex]) => decl(`fill-${name}`, hex)),
+    // Hover is DERIVED from the fill, so retuning a fill (in the theme lab, or here) carries its
+    // hover along instead of leaving a stale pair. 88% of the fill over black lands ~0.128 luminance:
+    // a visible press-darkening that still clears AA for the white label (~5.9:1).
+    ...Object.keys(data.FILL).map((name) =>
+      decl(`fill-hover-${name}`, `color-mix(in srgb, var(--vx-fill-${name}) 88%, #000)`),
+    ),
+    // The type scale, emitted from the SAME `TEXT` object `VX.text` reads — CSS modules and the
+    // Mantine theme consume these; inline styles / visx read the numbers. One ladder, two forms.
+    ...Object.entries(TEXT).map(([step, px]) => decl(`text-${step}`, `${px}px`)),
+    decl('area-top', '22%'),
+    decl('area-bottom', '1%'),
+    decl('good', 'color-mix(in srgb, var(--vx-good-solid) 18%, transparent)'),
+    decl('good-soft', 'color-mix(in srgb, var(--vx-good-solid) 8%, transparent)'),
+    decl('bad', 'color-mix(in srgb, var(--vx-bad-solid) 18%, transparent)'),
+    decl('warn', 'color-mix(in srgb, var(--vx-warn-solid) 8%, transparent)'),
+    decl('good-ref', 'color-mix(in srgb, var(--vx-good-solid) 30%, transparent)'),
+    decl('bad-ref', 'color-mix(in srgb, var(--vx-bad-solid) 30%, transparent)'),
+    decl('warn-ref', 'color-mix(in srgb, var(--vx-warn-solid) 20%, transparent)'),
+  ].join('\n')
+  return legacyAliases ? `${canonical}\n${frameworkDerivedAliases(data)}` : canonical
+}
+
+/**
+ * Throw on a consumer series/group name inside a basalt-owned `--vx-*` family (`surface`, `space`,
+ * `ink`, …): `check-theme`'s `unknown-vx-token` judges every name there against what basalt emits,
+ * which is sound only while no consumer REF points there. Dev builds only (the call sits behind a
+ * literal NODE_ENV read); `unknown-vx-token` left the grace ledger at 1.36.0, which is when this
+ * went from a once-per-name warning to a throw. The families are the guard's own generated
+ * `BASALT_VX_FAMILIES`. Checked on the refs, not in `buildPaletteCss`, which runs on every first
+ * paint.
+ */
+function assertConsumerVxName(name: string): void {
+  const family = vxFamilyOf(name)
+  if (!BASALT_VX_FAMILIES.includes(family)) return
+  throw new Error(
+    `[basalt] ${name} is inside basalt's own --vx-${family} family — name your series group something basalt does not own (groupTokens('app', …)).`,
+  )
+}
+
+/**
+ * Wrap a map of `{ name: ColorPair }` into `var(--vx-<prefix><name>)` token refs — the runtime
+ * companion to `buildPaletteCss`. Lets a consumer define its own series and read stable refs.
+ *
+ * Returns an exact-keyed object: the return type mirrors the keys of the input map, so a renamed
+ * or removed key becomes a tsc error rather than silently widening to `Record<string, string>`.
+ */
+export function seriesTokens<const T extends SeriesMap>(
+  map: T,
+  prefix = '',
+): { [K in keyof T]: string } {
+  const out = {} as { [K in keyof T]: string }
+  for (const key of Object.keys(map) as (keyof T)[]) {
+    // Literal read at the branch, so a production bundle drops the check (common/dev-gate.test.ts).
+    if (process.env.NODE_ENV !== 'production') assertConsumerVxName(`--vx-${prefix}${String(key)}`)
+    out[key] = `var(--vx-${prefix}${String(key)})`
+  }
+  return out
+}
+
+/**
+ * Define a named series map. Identity passthrough — gives consumers a typed authoring entry
+ * point and preserves the exact literal keys of the input (const-generic so callers get back T,
+ * not the widened SeriesMap, enabling downstream exact-key checks in groupTokens / seriesTokens).
+ */
+export function defineSeries<const T extends SeriesMap>(map: T): T {
+  return map
+}
+
+/** Runtime key of the {@link SeriesGroup} brand. */
+const SERIES_GROUP: unique symbol = Symbol('basalt.series-group')
+
+/**
+ * The brand `groupTokens` puts on its return value. `BuildPaletteOpts.groups` takes these, so the
+ * `${name}-` key that emits the variables and the one that references them come from one call and
+ * cannot be spelled two ways.
+ */
+export type SeriesGroup = {
+  readonly [SERIES_GROUP]: { readonly prefix: string; readonly map: SeriesMap }
+}
+
+/**
+ * Build a single namespaced group's token refs (`var(--vx-<name>-<key>)`).
+ *
+ * Returns an exact-keyed object matching the keys of `map` — a stale or renamed key is a tsc
+ * error at the call site rather than a silent `Record<string, string>` widening.
+ */
+export function groupTokens<const T extends SeriesMap>(
+  name: string,
+  map: T,
+): { [K in keyof T]: string } & SeriesGroup {
+  const refs = seriesTokens(map, `${name}-`)
+  // Non-enumerable, symbol-keyed: a series key can never collide with the brand, and
+  // `Object.keys(refs)` still lists exactly the series.
+  Object.defineProperty(refs, SERIES_GROUP, { value: { prefix: `${name}-`, map } })
+  return refs as { [K in keyof T]: string } & SeriesGroup
+}
+
+/**
+ * The attribute + values the per-scheme blocks key off. Defaults reproduce Mantine's own toggle
+ * (`data-mantine-color-scheme` = `dark` / `light`), so a consumer only names the axis it differs
+ * on. Supplying this object at all switches the emitter onto the framework-neutral selector shape
+ * — see {@link BuildPaletteOpts.scheme}.
+ */
+export type ColorSchemeSelector = {
+  attribute?: string
+  darkValue?: string
+  lightValue?: string
+}
+
+/** Options for {@link buildPaletteCss}. */
+export type BuildPaletteOpts = {
+  /** Extra named series maps to emit under the given prefixes (each one is the return value of `groupTokens`). */
+  groups?: readonly SeriesGroup[]
+  /** Theme-independent derived declarations (gradients, semantic fills) emitted once on `:root`. */
+  derived?: string[]
+  /**
+   * Attribute + values the per-scheme blocks key off — for a consumer whose scheme toggle is not
+   * Mantine's (a static site on `data-theme`, say). Default: Mantine's own
+   * `data-mantine-color-scheme` = `dark` / `light`.
+   *
+   * Setting ANY of `scheme` / `defaultScheme` / `mediaFallback` moves the emitter off the legacy
+   * `html[…]` selector onto `:root[…]`. That is deliberate and load-bearing, NOT cosmetic:
+   *
+   *   `:root[data-theme='dark']`   0-2-0   ← what this path emits
+   *   `html[data-theme='dark']`    0-1-1
+   *   `[data-theme='dark']`        0-1-0   ← same as a bare `:root`, so source order decides
+   *
+   * A light-default site whose own `:root` block happens to come last would beat the third form
+   * outright — dark mode silently does nothing. `:root[…]` sits above both a bare `:root` and
+   * `html[…]`, and carries no assumption about the element the attribute lands on.
+   *
+   * The no-options path keeps emitting `html[data-mantine-color-scheme='…']` verbatim, because a
+   * basalt consumer may already override `--vx-*` under that exact selector — raising basalt's own
+   * specificity would silently win over their override.
+   */
+  scheme?: ColorSchemeSelector
+  /**
+   * Which scheme rides along on the bare `:root` block — the one that applies when the attribute
+   * is absent. Default: `'dark'` (the framework's own default scheme).
+   *
+   * `'none'` emits no bare-`:root` primitives at all: each scheme gets only its attribute block,
+   * and an unattributed document falls back to the theme-independent scalars alone. Pair it with
+   * `mediaFallback` unless the consumer always sets the attribute.
+   */
+  defaultScheme?: 'dark' | 'light' | 'none'
+  /**
+   * Also emit an `@media (prefers-color-scheme: …)` block for every scheme that is not the bare
+   * `:root` default, so a document with no attribute set follows the OS. Default: `false`.
+   *
+   * The block is a bare `:root` (0-1-0), so an explicit attribute block (0-2-0) always wins over
+   * it regardless of source order — the OS preference is a fallback, never an override.
+   */
+  mediaFallback?: boolean
+  /**
+   * How much of the SPACING set to emit. Default: `'all'` (every one of the 108 `--vx-space-*`
+   * declarations the framework's own components read).
+   *
+   * `'core'` keeps the 9 generic anchors — the stack rhythm, the two control heights, the row
+   * insets — and drops the 99 named for a specific basalt component
+   * (`--vx-space-agent-transcript-inset`, `--vx-space-toc-sub-indent`, …), taking the emitted set
+   * from 204 variables to 105. Nothing outside basalt's own React components reads those, so a
+   * framework-free consumer is carrying them for nothing.
+   *
+   * This is a SPACING filter only: color, radius, shadow, type and status variables are identical
+   * in both modes. The partition is derived from the `SPACE` key set rather than a maintained list
+   * — see {@link CORE_SPACE_VARS}.
+   */
+  only?: 'core' | 'all'
+  /**
+   * Whether to also emit the 32 deprecated camelCase aliases (`--vx-accentFill`, `--vx-tooltipBg`,
+   * `--vx-fillHover-gray`, …) alongside the canonical kebab-case names the 1.4.0 normalization
+   * introduced. Default: `true`, so an existing consumer's hand-written CSS referencing a
+   * camelCase name keeps resolving. Each alias is defined as `var(--vx-<canonical>)` — it can
+   * never drift from the value it aliases. Pass `false` once every reference in your own code has
+   * migrated to the kebab names to drop the extra 32 lines.
+   */
+  legacyAliases?: boolean
+}
+
+/** Mantine's own color-scheme attribute — the default {@link ColorSchemeSelector.attribute}. */
+const MANTINE_SCHEME_ATTRIBUTE = 'data-mantine-color-scheme'
+
+/** Indent an already-2-space-indented declaration block one level deeper (for `@media` nesting). */
+const indent = (block: string): string =>
+  block
+    .split('\n')
+    .map((line) => (line === '' ? line : `  ${line}`))
+    .join('\n')
+
+/**
+ * The `< sm` breakpoint, written the way a stylesheet has to write it — the SAME literal every
+ * basalt CSS module spells (`shell/app-header.module.css`, `dashboard/section.module.css`, …), and
+ * for the same reason `BREAKPOINTS` above exists: a `@media` condition is resolved before custom
+ * 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: ${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.
+ *
+ * The problem it answers: the desktop-shell pass took the page gutter from 20 to 8 below `sm`
+ * (`appShellInsetMobile`), and the card ladder INSIDE that gutter never moved — card insets stayed
+ * `xs`/`sm` and a `Section`'s gaps stayed `stackMd` at every width — so a 390px phone still read
+ * "content spacing too big" after the gutter fix. Two rungs close it: the card's horizontal inset
+ * steps `sm` -> `xs`, and the Section's gap steps `stackMd` -> `stackSm`.
+ *
+ * Why it lives HERE and not in the three CSS files that consume it: two of those three sites are
+ * INLINE styles in TSX (`dashboard/stat-card.tsx`, `charts/primitives/ChartCard.tsx`), and an
+ * inline style cannot carry a media query at all. The only surface that reaches all three is a
+ * custom property whose VALUE moves at the breakpoint, and the only stylesheet guaranteed present
+ * wherever those components render is this one — `BasaltProvider` injects `buildPaletteCss()`, and
+ * a component's own CSS module is loaded only if a bundler kept that module. So the law is one
+ * `@media` block emitted beside the base declarations it overrides, and every consuming site is a
+ * plain `var()` read with no breakpoint knowledge. A media query copied into three files (or into
+ * one component stylesheet reaching for `:global(:root)`) was the alternative, and it fails the
+ * same way twice: three copies drift, and one copy in a tree-shakeable module is a law that
+ * sometimes does not ship.
+ *
+ * This does NOT make the token layer responsive in general. It stays what `BREAKPOINTS`'s doc says
+ * it is — the layer that owns the NUMBER a media query has to write — and this is the one law whose
+ * consuming sites cannot write that query themselves. A dimension whose consumer is a CSS module
+ * keeps making the choice in that module (`appShellInset`/`appShellInsetMobile` still do).
+ */
+function spaceMobileDecls(space: SpaceValues): string[] {
+  return [
+    decl('space-card-inset-x', `${space.scale.xs}px`),
+    decl('space-section-gap', `${space.anchors.stackSm}px`),
+  ]
+}
+
+/** {@link spaceMobileDecls} as the `@media` block that overrides the base `:root` declarations —
+ *  same specificity, later in source order, so it wins below `sm` and nowhere else. */
+function mobileLadderBlock(space: SpaceValues): string {
+  return `${MOBILE_MEDIA} {\n  :root {\n${indent(spaceMobileDecls(space).join('\n'))}\n  }\n}`
+}
+
+/**
+ * Emit the `--vx-*` stylesheet: a `:root` block of theme-independent scalars, then the
+ * dark (default) and light primitive blocks under `html[data-mantine-color-scheme='…']`.
+ *
+ * The framework chrome (STATUS/SEMANTIC/SURFACE pairs + the framework DERIVED defaults) is
+ * built in, so an empty `buildPaletteCss()` already emits every framework var. Consumer
+ * `opts.groups` / `opts.derived` append on top (e.g. argo's domain SERIES/ACTIVITY/USAGE).
+ *
+ * `data` defaults to the static, shipped palette (`buildPaletteData()` at `DEFAULT_DERIVE_CONFIG`)
+ * — pass the result of `buildPaletteData(config)` to emit CSS for a retuned derive config instead
+ * (this is how `BasaltProvider` follows `createBasaltTheme`'s `{ derive }` option; see `../theme`
+ * and `../provider`).
+ *
+ * Dark is the default (`:root`) since the framework defaults to dark; the
+ * `[data-mantine-color-scheme]` selectors track Mantine's toggle on `<html>`.
+ *
+ * A non-Mantine consumer retargets all three of those choices — the attribute, which scheme rides
+ * the bare `:root`, and whether the OS preference is honoured — via `opts.scheme` /
+ * `opts.defaultScheme` / `opts.mediaFallback`. Setting any of them also moves the per-scheme
+ * selector from `html[…]` to the framework-neutral, higher-specificity `:root[…]`; see
+ * `BuildPaletteOpts.scheme` for why that is not cosmetic. With none of them set the output is
+ * byte-identical to what the framework has always emitted (pinned by
+ * `tests/palette-css.test.ts`).
+ */
+export function buildPaletteCss(
+  opts: BuildPaletteOpts = {},
+  data: PaletteData = buildPaletteData(),
+): string {
+  const groups = opts.groups ?? []
+  const legacyAliases = opts.legacyAliases ?? true
+  const only = opts.only ?? 'all'
+  const extraDerived = (opts.derived ?? []).map((d) => `  ${d}`).join('\n')
+  const derivedBlock = frameworkDerived(data, only, legacyAliases)
+  const derived = extraDerived ? `${derivedBlock}\n${extraDerived}` : derivedBlock
+  const side = (s: Side): string => {
+    const extra = groups
+      .map((group) => groupSide(group[SERIES_GROUP].prefix, group[SERIES_GROUP].map, s))
+      .join('\n')
+    const framework = frameworkPrimitives(s, data, legacyAliases)
+    return extra ? `${framework}\n${extra}` : framework
+  }
+  // The scalars, then the ONE `@media` block that re-points two of them below `sm` (see
+  // `spaceMobileDecls`). Dropped under `only: 'core'` for the same reason the declarations it
+  // overrides are: both vars are component-named one-offs, not `SPACE` anchors, so a core-only
+  // consumer never receives the base pair the block exists to override.
+  const rootBlock =
+    only === 'core'
+      ? `: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) {
+    return `${rootBlock}
+:root,
+html[data-mantine-color-scheme='dark'] {
+${side('dark')}
+}
+html[data-mantine-color-scheme='light'] {
+${side('light')}
+}`
+  }
+
+  const attribute = opts.scheme?.attribute ?? MANTINE_SCHEME_ATTRIBUTE
+  const value: Record<Side, string> = {
+    dark: opts.scheme?.darkValue ?? 'dark',
+    light: opts.scheme?.lightValue ?? 'light',
+  }
+  const defaultScheme = opts.defaultScheme ?? 'dark'
+  // Default scheme first, so its attribute block can absorb the bare `:root` instead of repeating
+  // ~40 declarations; `'none'` keeps the framework's dark-then-light order.
+  const order: Side[] = defaultScheme === 'light' ? ['light', 'dark'] : ['dark', 'light']
+
+  const blocks = [rootBlock]
+  for (const s of order) {
+    const selector =
+      s === defaultScheme
+        ? `:root,\n:root[${attribute}='${value[s]}']`
+        : `:root[${attribute}='${value[s]}']`
+    // The OS fallback for a scheme goes immediately before that scheme's own attribute block. It is
+    // a bare `:root` (0-1-0), so the attribute block (0-2-0) outranks it on specificity rather than
+    // on order — an explicit toggle always beats the OS preference, and the OS preference always
+    // beats the hardcoded default that a bare `:root` above it carries.
+    if (opts.mediaFallback === true && s !== defaultScheme) {
+      blocks.push(`@media (prefers-color-scheme: ${s}) {\n  :root {\n${indent(side(s))}\n  }\n}`)
+    }
+    blocks.push(`${selector} {\n${side(s)}\n}`)
+  }
+  return blocks.join('\n')
+}
+
+/**
+ * The `fonts` option's resolved shape — a full CSS font-family stack string per slot (with its own
+ * fallback chain), riding the `--basalt-font-sans/head/mono` override seam `styles.css` ships
+ * fallbacks for. Omitted keys keep the shipped fallback untouched. Lives here (not in `../theme`,
+ * which only re-exports the type) because its builder `buildFontsCss` below is a pure, Mantine-free
+ * string builder that belongs in the tokens layer — see `../theme`'s
+ * `CreateBasaltThemeOptions.fonts` for the production entry point that sets it.
+ */
+export type BasaltFontsConfig = {
+  sans?: string
+  head?: string
+  mono?: string
+}
+
+/** `{ basaltFonts key → --basalt-font-* var name }` — the one place the mapping is spelled out. */
+const FONT_VAR_NAMES = {
+  sans: '--basalt-font-sans',
+  head: '--basalt-font-head',
+  mono: '--basalt-font-mono',
+} as const satisfies Record<keyof BasaltFontsConfig, string>
+
+/**
+ * Build the `:root` block of `--basalt-font-*` declarations for a resolved `basaltFonts` config —
+ * only for the keys the consumer actually set (`createBasaltTheme(overrides, { fonts })`); an
+ * omitted key keeps the shipped `styles.css` fallback chain untouched. Empty string when `fonts` is
+ * absent or every key is omitted, so callers can unconditionally concatenate the result. Internal
+ * (not on the `basalt-ui/tokens` barrel) — `BasaltProvider`'s bridge (`../provider`) calls this
+ * directly to append declarations to its injected `<style>`.
+ */
+export function buildFontsCss(fonts: BasaltFontsConfig | undefined): string {
+  if (!fonts) return ''
+  const decls = (Object.keys(FONT_VAR_NAMES) as (keyof BasaltFontsConfig)[])
+    .filter((key) => fonts[key] !== undefined)
+    .map((key) => {
+      const value = fonts[key] as string
+      // A font stack is a plain declaration value — `{`/`}`/`;`/comment openers would let a
+      // config string break out of the emitted `<style>` declaration. Throw, don't sanitize,
+      // per the repo's validation convention (see `deriveTokens`'s accent-hex assert).
+      if (/[{};]|\/\*/.test(value)) {
+        throw new Error(
+          `Invalid fonts.${key}: a font-family stack must not contain "{", "}", ";" or "/*" — got ${JSON.stringify(value)}`,
+        )
+      }
+      return `  ${FONT_VAR_NAMES[key]}: ${value};`
+    })
+  if (decls.length === 0) return ''
+  return `:root {\n${decls.join('\n')}\n}`
+}
+
+/**
+ * Build the `:root` block of overriding `--vx-radius-*` declarations for a resolved
+ * `basaltRadius` value (`createBasaltTheme(overrides, { radius })`) — analog of {@link buildFontsCss}.
+ * Empty string when `radius` is absent (the default level-0 path never sets `theme.other.basaltRadius`
+ * in the first place), so callers can unconditionally concatenate the result. Internal, like
+ * `buildFontsCss` above.
+ */
+export function buildRadiusCss(radius: RadiusValues | undefined): string {
+  if (!radius) return ''
+  return `:root {
+  --vx-radius-card: ${radius.card}px;
+  --vx-radius-ctrl: ${radius.ctrl}px;
+  --vx-radius-tight: ${radius.tight}px;
+  --vx-radius-fine: ${radius.fine}px;
+  --vx-radius-floating: ${radius.floating}px;
+}`
+}
+
+/**
+ * Build the `:root` block of overriding `--vx-space-*` declarations for a resolved `basaltDensity`
+ * value (`createBasaltTheme(overrides, { density })`) — analog of {@link buildRadiusCss}, reusing
+ * the SAME `spaceDecls` list `frameworkDerived` emits the shipped defaults from (so the two can
+ * never drift). Empty string when `space` is absent (the default level-0 path never sets
+ * `theme.other.basaltDensity` in the first place), so callers can unconditionally concatenate the
+ * result. Importable from `basalt-ui/tokens`, same SSR/custom-injection use as `buildRadiusCss`
+ * above.
+ */
+export function buildDensityCss(space: SpaceValues | undefined): string {
+  if (!space) return ''
+  // The `< sm` ladder rides along, at the retuned level — without it a phone at `density: 2` would
+  // take the level-0 mobile inset from the static stylesheet and the level-2 base from this one,
+  // which is the only way the two rungs of one ladder could ever come from different levels.
+  return `:root {\n${spaceDecls(space).join('\n')}\n}\n${mobileLadderBlock(space)}`
+}