basalt-ui 1.40.3 → 2.0.0

package/dist/tokens/core.js

@@ -0,0 +1,708 @@
+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,
+  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()`) — the chart legend applies it via inline
+  // `style`, and this is the one static (level-0) value; `createBasaltTheme({ density })` has no
+  // wiring into chart render props yet, so this number does NOT move live with the knob (same
+  // "dev slider/production JS defaultProps" gap as Timeline's `bulletSize` — see `deriveSpacing`'s
+  // doc in tokens/palette.ts).
+  legendGap: SPACE_STEP.chartLegendGap,
+  legendFontSize: TEXT.sm,
+  // The type scale (px numbers — see TEXT above). Use in inline styles and visx SVG props;
+  // use `var(--vx-text-*)` in CSS modules.
+  text: TEXT,
+  // Single source for the card corner radius — shared by the Mantine-free ChartCard and the
+  // Mantine chrome (Card/Paper resolve to this SAME token). One knob, so cards never diverge.
+  radiusCard: "var(--vx-radius-card)",
+  // Single source for the control corner radius (inputs, search, buttons, segmented track).
+  radiusCtrl: "var(--vx-radius-ctrl)",
+  // Fully-rounded pill affordance (scroll-to-bottom button, chips) — fixed, does not track the
+  // radius knob (see `RADIUS_STEP.pill`'s doc in `tokens/palette.ts`).
+  radiusPill: "var(--vx-radius-pill)",
+  // The pointer-tier hit floor: 44px under `(pointer: coarse)` (WCAG 2.5.5), 24px otherwise
+  // (2.5.8). Density-exempt; `[data-basalt-hit]::after` in `styles.css` reads it.
+  hit: "var(--vx-hit)",
+  // Controls tier sizing (`docs/CONTROLS-SPEC.md` §5) — `var()` refs onto the density-tracking
+  // `--vx-space-*` declarations `spaceDecls` emits above (same ref pattern as `radiusCard`/
+  // `radiusCtrl`), so a home/control reads ONE source for its tier height whether it's Mantine
+  // chrome (`cssVariablesResolver`/`CTL_THEME`) or a Mantine-free composed layout.
+  space: {
+    controlHeightTag: "var(--vx-space-control-height-tag)",
+    controlHeightWidget: "var(--vx-space-control-height-widget)",
+    controlHeightCtl: "var(--vx-space-control-height-ctl)",
+    pageBarRowHeight: "var(--vx-space-page-bar-row-height)",
+    sectionHeaderHeight: "var(--vx-space-section-header-height)",
+    widgetHeaderHeight: "var(--vx-space-widget-header-height)",
+    sidebarBlockRowHeight: "var(--vx-space-sidebar-block-row-height)",
+    controlGap: "var(--vx-space-control-gap)",
+    sheetRowHeight: "var(--vx-space-sheet-row-height)"
+  },
+  // Secondary-line color (back-compat alias; now theme-aware via --vx-line2)
+  line2Dark: "var(--vx-line2)",
+  // Semantic fills — consistent opacity across all charts
+  good: "var(--vx-good)",
+  goodSoft: "var(--vx-good-soft)",
+  bad: "var(--vx-bad)",
+  warn: "var(--vx-warn)",
+  goodSolid: "var(--vx-good-solid)",
+  badSolid: "var(--vx-bad-solid)",
+  warnSolid: "var(--vx-warn-solid)",
+  // Reference/dashed lines for thresholds
+  goodRef: "var(--vx-good-ref)",
+  badRef: "var(--vx-bad-ref)",
+  warnRef: "var(--vx-warn-ref)",
+  // Neutral primary line/text color — the default for single-series, no-signal marks
+  // ("white/gray per theme"). Same value as the NEUTRAL.line pair.
+  line: "var(--vx-line)",
+  line2: "var(--vx-line2)",
+  // Axis label + axis stroke colors (theme-aware). Exposed as flat refs so a bespoke chart that
+  // renders raw <text> labels or axis lines (without the Axis* primitives) needs no hook.
+  axis: "var(--vx-axis)",
+  axisStroke: "var(--vx-axis-stroke)",
+  // Grid, hover, legend
+  grid: "var(--vx-grid)",
+  crosshair: "var(--vx-crosshair)",
+  dotStroke: "var(--vx-dot-stroke)",
+  legendText: "var(--vx-legend-text)",
+  // Tooltip chrome — muted (secondary) text inside a bespoke tooltip. The other tooltip vars
+  // (bg/text/border/shadow) reach the engine tooltip as `--ts-chart-tooltip-*` (`charts/theme.ts`);
+  // this one is flattened onto `VX` too because bespoke-tooltip authors reached for `VX.muted` (the
+  // general ink-ramp muted) instead and got the wrong token — same pattern as `VX.muted` below.
+  tooltipMuted: "var(--vx-tooltip-muted)",
+  // Base neutral for hairlines / muted text / overlays — apply opacity via alpha()
+  neutral: "var(--vx-neutral)",
+  // Ink text ramp (docs/DESIGN-SPEC.md §2) — primary/emphasis/secondary/tertiary body text.
+  ink: "var(--vx-ink)",
+  ink2: "var(--vx-ink2)",
+  muted: "var(--vx-muted)",
+  faint: "var(--vx-faint)",
+  // The accent as INK — primary series, active-nav icon, links, focus rings. Read against the PAGE,
+  // so it inverts across schemes (light on dark, deep on light).
+  accent: "var(--vx-accent)",
+  accentHover: "var(--vx-accent-hover)",
+  // The accent as SURFACE — a filled control that carries a label. Squeezed between white-text
+  // contrast and page contrast, so it is the same hex in both schemes (see ACCENT in palette.ts).
+  // Mantine's `--mantine-color-<primary>-filled` is bridged onto this, so it drives ALL filled
+  // chrome; a raw `--vx-accent` fill would be unreadable on dark. Fills use THIS, never `accent`.
+  accentFill: "var(--vx-accent-fill)",
+  accentFillHover: "var(--vx-accent-fill-hover)",
+  onAccent: "var(--vx-on-accent)",
+  // Layout separators (header bottom rule, sidebar child indent) — distinct from `surface.border`.
+  divider: "var(--vx-divider)",
+  // Depth shadows — a whisper shadow + a 1px ring baked into the value (never a `border` prop).
+  shadowCard: "var(--vx-shadow-card)",
+  shadowCtrl: "var(--vx-shadow-ctrl)",
+  // Raised interactive controls — drop + a 1px INSET edge, the one depth every raised Button/
+  // ActionIcon variant shares (works over a fill, a tint or a panel alike; see SHADOW.raised).
+  shadowRaised: "var(--vx-shadow-raised)",
+  // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a real drop shadow.
+  shadowOverlay: "var(--vx-shadow-overlay)",
+  // App surfaces (cards, borders) — shared with the Mantine chrome
+  surface: {
+    bg: "var(--vx-surface-bg)",
+    panel: "var(--vx-surface-panel)",
+    panelHover: "var(--vx-surface-panel-hover)",
+    elevated: "var(--vx-surface-elevated)",
+    subtle: "var(--vx-surface-subtle)",
+    overlay: "var(--vx-surface-overlay)",
+    // floating layer (menus, popovers, modals, drawers)
+    field: "var(--vx-surface-field)",
+    // input field surface (slightly inset on a panel)
+    border: "var(--vx-surface-border)",
+    // "line" — strong border
+    hairline: "var(--vx-surface-hairline)"
+    // card ring only
+  },
+  // Score / zone status scale (excellent → poor)
+  status: {
+    excellent: "var(--vx-status-excellent)",
+    good: "var(--vx-status-good)",
+    warn: "var(--vx-status-warn)",
+    bad: "var(--vx-status-bad)",
+    neutral: "var(--vx-status-neutral)"
+  },
+  // Shared sizing — single-sourced from the `SPACE_STEP` chart-margin steps (density-tracking; same
+  // static-value/no-live-wiring note as `legendGap` above).
+  margin: {
+    top: SPACE_STEP.chartMarginTop,
+    right: SPACE_STEP.chartMarginRight,
+    bottom: SPACE_STEP.chartMarginBottom,
+    left: SPACE_STEP.chartMarginLeft
+  },
+  minPxPerTick: 55,
+  /**
+   * Floor on a chart's plot rect height, in px (the 1.x chart frame). A legend wrapping to five rows at
+   * phone width used to eat a fixed `height={240}` toward zero and the plot simply stopped
+   * rendering — the plot never shrinks past this, the frame grows instead (or, under `fill`, the
+   * legend rolls up).
+   */
+  minPlotHeight: 120,
+  /** Every floating chart overlay portalled to `document.body` — a pinned tooltip, the legend's
+   * `All N` disclosure and its backdrop — shares one stacking value, so they always stack the same
+   * way relative to page chrome and to each other. */
+  zIndexFloating: 9999
+};
+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
+};
+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;
+}
+const SERIES_GROUP = /* @__PURE__ */ Symbol("basalt.series-group");
+function groupTokens(name, map) {
+  const refs = seriesTokens(map, `${name}-`);
+  Object.defineProperty(refs, SERIES_GROUP, { value: { prefix: `${name}-`, map } });
+  return refs;
+}
+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 = groups.map((group) => groupSide(group[SERIES_GROUP].prefix, group[SERIES_GROUP].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)}`;
+}
+export {
+  BP,
+  BREAKPOINTS,
+  CONTAINER_CLASSES,
+  CONTAINER_GRID_BREAKPOINTS,
+  CONTAINER_KEYS,
+  DEFAULT_DERIVE_CONFIG,
+  SIZE_CLASSES2 as SIZE_CLASSES,
+  VX,
+  alpha,
+  buildDensityCss,
+  buildFontsCss,
+  buildPaletteCss,
+  buildRadiusCss,
+  defineSeries,
+  deriveRadius,
+  deriveSpacing,
+  deriveTokens,
+  groupTokens,
+  p,
+  pxRem,
+  resolveContainerClass,
+  resolveDeriveConfig,
+  seriesTokens
+};