basalt-ui 1.41.0 → 2.0.0

package/dist/tokens/index.js

@@ -1,715 +1,23 @@
-import {
-  buildPaletteData,
-  RADIUS,
-  RADIUS_STEP,
-  ROW_LINE_HEIGHT,
-  SHADOW,
-  SPACE,
-  SPACE_SCALE,
-  SPACE_STEP
-} from "./palette.js";
-import { SIZE_CLASSES, sizeClassMaxEm } from "./size-classes.js";
-import { HIT_COARSE, HIT_FINE } from "../common/hit-floor.js";
-import { BASALT_VX_FAMILIES } from "../common/vx-families.js";
-import { vxFamilyOf } from "../common/vx-family.js";
 import { BP, p } from "./palette.js";
-import { DEFAULT_DERIVE_CONFIG, deriveTokens, resolveDeriveConfig } from "./derive.js";
-import { deriveRadius } from "./palette.js";
-import { deriveSpacing } from "./palette.js";
+import { CONTAINER_CLASSES, CONTAINER_GRID_BREAKPOINTS, CONTAINER_KEYS } from "./size-classes.js";
 import {
-  CONTAINER_CLASSES,
-  CONTAINER_GRID_BREAKPOINTS,
-  CONTAINER_KEYS,
-  resolveContainerClass,
-  SIZE_CLASSES as SIZE_CLASSES2
-} from "./size-classes.js";
-const alpha = (token, a) => `color-mix(in srgb, ${token} ${Math.round(a * 100)}%, transparent)`;
-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
-};
-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",
-  // 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
-};
-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
-};
-function chartMargin(opts) {
-  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
-  };
-}
-const decl = (name, value) => `  --vx-${name}: ${value};`;
-function pxRem(px) {
-  return `${px / 16}rem`;
-}
-const groupSide = (prefix, map, side) => Object.entries(map).map(([key, pair]) => decl(`${prefix}${key}`, pair[side])).join("\n");
-function frameworkPrimitivesAliases() {
-  return [
-    "  /* Deprecated camelCase aliases \u2014 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");
-}
-function frameworkPrimitives(side, data, legacyAliases) {
-  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, 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}
-${frameworkPrimitivesAliases()}` : canonical;
-}
-function spaceDecls(space) {
-  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).
-  ];
-}
-const CORE_SPACE_VARS = new Set(
-  Object.keys(SPACE).map((key) => `space-${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`)
-);
-function isCoreSpaceDecl(line) {
-  const name = /^ {2}--vx-([\w-]+):/.exec(line)?.[1];
-  return name !== void 0 && CORE_SPACE_VARS.has(name);
-}
-const DEFAULT_SPACE_VALUES = {
-  anchors: SPACE,
-  scale: SPACE_SCALE,
-  step: SPACE_STEP,
-  rowLineHeight: ROW_LINE_HEIGHT
-};
-function frameworkDerivedAliases(data) {
-  return [
-    "  /* Deprecated camelCase aliases \u2014 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");
-}
-function frameworkDerived(data, only, legacyAliases) {
-  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}
-${frameworkDerivedAliases(data)}` : canonical;
-}
-function assertConsumerVxName(name) {
-  const family = vxFamilyOf(name);
-  if (!BASALT_VX_FAMILIES.includes(family)) return;
-  throw new Error(
-    `[basalt] ${name} is inside basalt's own --vx-${family} family \u2014 name your series group something basalt does not own (groupTokens('app', \u2026)).`
-  );
-}
-function seriesTokens(map, prefix = "") {
-  const out = {};
-  for (const key of Object.keys(map)) {
-    if (process.env.NODE_ENV !== "production") assertConsumerVxName(`--vx-${prefix}${String(key)}`);
-    out[key] = `var(--vx-${prefix}${String(key)})`;
-  }
-  return out;
-}
-function defineSeries(map) {
-  return map;
-}
-function groupTokens(name, map) {
-  return seriesTokens(map, `${name}-`);
-}
-const MANTINE_SCHEME_ATTRIBUTE = "data-mantine-color-scheme";
-const indent = (block) => block.split("\n").map((line) => line === "" ? line : `  ${line}`).join("\n");
-const MOBILE_MEDIA = `@media (max-width: ${sizeClassMaxEm(SIZE_CLASSES.medium)})`;
-const coarseHitBlock = `@media (pointer: coarse) {
-  :root {
-    --vx-hit: ${HIT_COARSE}px;
-  }
-}`;
-function spaceMobileDecls(space) {
-  return [
-    decl("space-card-inset-x", `${space.scale.xs}px`),
-    decl("space-section-gap", `${space.anchors.stackSm}px`)
-  ];
-}
-function mobileLadderBlock(space) {
-  return `${MOBILE_MEDIA} {
-  :root {
-${indent(spaceMobileDecls(space).join("\n"))}
-  }
-}`;
-}
-function buildPaletteCss(opts = {}, data = buildPaletteData()) {
-  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}
-${extraDerived}` : derivedBlock;
-  const side = (s) => {
-    const extra = Object.entries(groups).map(([prefix, map]) => groupSide(prefix, map, s)).join("\n");
-    const framework = frameworkPrimitives(s, data, legacyAliases);
-    return extra ? `${framework}
-${extra}` : framework;
-  };
-  const rootBlock = only === "core" ? `:root {
-${derived}
-}
-${coarseHitBlock}` : `:root {
-${derived}
-}
-${mobileLadderBlock(DEFAULT_SPACE_VALUES)}
-${coarseHitBlock}`;
-  if (opts.scheme === void 0 && opts.defaultScheme === void 0 && !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 = {
-    dark: opts.scheme?.darkValue ?? "dark",
-    light: opts.scheme?.lightValue ?? "light"
-  };
-  const defaultScheme = opts.defaultScheme ?? "dark";
-  const order = defaultScheme === "light" ? ["light", "dark"] : ["dark", "light"];
-  const blocks = [rootBlock];
-  for (const s of order) {
-    const selector = s === defaultScheme ? `:root,
-:root[${attribute}='${value[s]}']` : `:root[${attribute}='${value[s]}']`;
-    if (opts.mediaFallback === true && s !== defaultScheme) {
-      blocks.push(`@media (prefers-color-scheme: ${s}) {
-  :root {
-${indent(side(s))}
-  }
-}`);
-    }
-    blocks.push(`${selector} {
-${side(s)}
-}`);
-  }
-  return blocks.join("\n");
-}
-const FONT_VAR_NAMES = {
-  sans: "--basalt-font-sans",
-  head: "--basalt-font-head",
-  mono: "--basalt-font-mono"
-};
-function buildFontsCss(fonts) {
-  if (!fonts) return "";
-  const decls = Object.keys(FONT_VAR_NAMES).filter((key) => fonts[key] !== void 0).map((key) => {
-    const value = fonts[key];
-    if (/[{};]|\/\*/.test(value)) {
-      throw new Error(
-        `Invalid fonts.${key}: a font-family stack must not contain "{", "}", ";" or "/*" \u2014 got ${JSON.stringify(value)}`
-      );
-    }
-    return `  ${FONT_VAR_NAMES[key]}: ${value};`;
-  });
-  if (decls.length === 0) return "";
-  return `:root {
-${decls.join("\n")}
-}`;
-}
-function buildRadiusCss(radius) {
-  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;
-}`;
-}
-function buildDensityCss(space) {
-  if (!space) return "";
-  return `:root {
-${spaceDecls(space).join("\n")}
-}
-${mobileLadderBlock(space)}`;
-}
+  alpha,
+  buildPaletteCss,
+  defineSeries,
+  groupTokens,
+  seriesTokens,
+  VX
+} from "./core.js";
 export {
   BP,
-  BREAKPOINTS,
   CONTAINER_CLASSES,
   CONTAINER_GRID_BREAKPOINTS,
   CONTAINER_KEYS,
-  DEFAULT_DERIVE_CONFIG,
-  SIZE_CLASSES2 as SIZE_CLASSES,
   VX,
   alpha,
-  buildDensityCss,
-  buildFontsCss,
   buildPaletteCss,
-  buildRadiusCss,
-  chartMargin,
   defineSeries,
-  deriveRadius,
-  deriveSpacing,
-  deriveTokens,
   groupTokens,
   p,
-  pxRem,
-  resolveContainerClass,
-  resolveDeriveConfig,
   seriesTokens
 };