basalt-ui 1.40.3 → 2.0.0

package/src/tokens/index.ts

@@ -1,1185 +1,18 @@
 /**
- * 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`.
+ * `basalt-ui/tokens` — the Mantine-free token layer's public surface. The implementation lives in
+ * `./core` (internal: the provider, CLI and theme import it from there); only what a consumer
+ * names is re-exported here.
  */
-
-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 here, so they are public surface, not
-// palette internals; dropping them from this barrel 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. Exposed so a
-// consumer can retune the palette identity via `createBasaltTheme(overrides, { derive })` (see
-// `../theme`) without hand-picking hexes. `buildPaletteData`/`PaletteData` stay internal (not
-// re-exported here) — a consumer reaches a derived palette through `createBasaltTheme`, 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 } from './size-classes'
 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()`) — ChartLegend 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) are only exposed via `useVxTheme()` (see `charts/theme.tsx`); 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 `SPACE_STEP.chartMargin*` (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 (`ChartFrame`). 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
-
-/** Resolved chart plot-area margins — the return shape of {@link chartMargin}. */
-export type ChartMargin = { top: number; right: number; bottom: number; left: number }
-
-/**
- * Chart plot-area margins — `VX.margin` widened for an `AxisRightNumeric`'s tick labels, and/or
- * overridden per side. A token can't express "only when a right axis is rendered", so this is a
- * function, not a second static token — also the seam that could one day track `density`
- * (`VX.margin` itself is frozen at the level-0 snapshot; see `deriveSpacing`'s JSDoc).
- *
- * Law, applied in this order: start from `VX.margin`; when `rightAxis` is true, widen `right` to
- * `Math.max(VX.margin.right, <right-axis minimum>)` (`SPACE_STEP.chartMarginRightAxis`); then any
- * explicitly passed side wins last (including overriding `rightAxis`'s widened `right`).
- * `chartMargin()` with no args deep-equals `VX.margin`.
- *
- * Returns a NEW object every call — memoize at the call site (`useMemo`), the same way `Bars`
- * already memoizes its own margin.
- */
-export function chartMargin(opts?: {
-  /** Reserve room for an `AxisRightNumeric`'s tick labels. */
-  rightAxis?: boolean
-  top?: number
-  right?: number
-  bottom?: number
-  left?: number
-}): ChartMargin {
-  const widenedRight = opts?.rightAxis
-    ? Math.max(VX.margin.right, SPACE_STEP.chartMarginRightAxis)
-    : VX.margin.right
-  return {
-    top: opts?.top ?? VX.margin.top,
-    right: opts?.right ?? widenedRight,
-    bottom: opts?.bottom ?? VX.margin.bottom,
-    left: opts?.left ?? VX.margin.left,
-  }
-}
-
-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,chartMarginRightAxis,
- * 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
-}
-
-/**
- * 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 } {
-  return seriesTokens(map, `${name}-`)
-}
-
-/**
- * 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 (e.g. `{ '': SERIES, 'activity-': ACTIVITY }`). */
-  groups?: Record<string, SeriesMap>
-  /** 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 = Object.entries(groups)
-      .map(([prefix, map]) => groupSide(prefix, 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 it) 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. Importable
- * from `basalt-ui/tokens` — `BasaltProvider`'s bridge (`../provider`) calls this directly to append
- * declarations to its injected `<style>`; an SSR/custom-injection consumer with
- * `injectPalette={false}` calls it themselves (see the JSDoc on that prop).
- */
-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. Importable from
- * `basalt-ui/tokens`, same SSR/custom-injection use as `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)}`
-}
+  alpha,
+  buildPaletteCss,
+  defineSeries,
+  groupTokens,
+  seriesTokens,
+  VX,
+  type ColorPair,
+  type SeriesGroup,
+  type SeriesMap,
+} from './core'