basalt-ui 1.26.0 → 1.28.0

package/src/theme/nav-link.module.css

@@ -1,60 +1,71 @@
 /*
- * Active nav row = heavier weight over the ink tint `--nl-bg` carries (set in theme/index.ts,
- * applied unconditionally by Mantine's own `[data-active]` CSS). NO depth: an active row is a
- * SELECTED ROW, not a raised control — it deliberately reads as a stronger version of the hover
- * tint rather than as a button, so the row never competes with the real filled controls around it.
+ * Active nav row = an ACCENT-tinted fill plus heavier weight, so the row reads unambiguously as
+ * SELECTED rather than merely hovered (docs/DESIGN-SPEC.md §5). The fill was previously the ink
+ * tint `--nl-bg` carries (theme/index.ts) at 9% — visually indistinguishable from the 6% ink hover
+ * tint on a dark surface, which is what let a hovered row read as a second active item. NO depth:
+ * an active row is a SELECTED ROW, not a raised control.
+ *
+ * `[data-active]` is the ONLY style hook here — `use-nav.ts` already resolves exactly one winner
+ * per route and stamps `data-active` on it, so keying these selectors on `aria-current="page"` too
+ * only risked a second, looser router-native match repainting a row basalt's own model disagreed
+ * with. `aria-current` stays on the DOM (React Router/TanStack Router set it) for a11y; it is just
+ * not a CSS hook.
  *
  * Applied at the THEME level via `classNames` so it reaches EVERY NavLink render path — including a
- * consumer's router `<Link>` mounted through `SidebarItem.Anchor`, which a shell-scoped CSS
- * module never
- * sees. Mantine's `styles` prop only takes flat inline properties (a nested `&[data-active]` there
- * throws a React warning), so the state selectors live here. React Router's NavLink marks the
- * active item via `aria-current` rather than the `active` prop's `data-active`, so both states are
- * matched.
+ * consumer's router `<Link>` mounted through `SidebarItem.Anchor`, which a shell-scoped CSS module
+ * never sees. Mantine's `styles` prop only takes flat inline properties (a nested `&[data-active]`
+ * there throws a React warning), so the state selectors live here.
  */
-.root[data-active],
-.root[aria-current='page'] {
+.root[data-active] {
+  background-color: color-mix(in srgb, var(--vx-accent) 12%, transparent);
   font-weight: 600;
 }
 
+/* Active + hover — one step stronger than the resting active fill, so a pointer over the active row
+ * still reads as feedback rather than as a flat, unresponsive selection. */
+@media (hover: hover) {
+  .root[data-active]:hover {
+    background-color: color-mix(in srgb, var(--vx-accent) 16%, transparent);
+  }
+}
+
 /*
  * Active-icon accent: only the leftSection (the icon, `data-position="left"`) turns accent-colored
  * — the label stays ink (via `--nl-color`). Targets Mantine's own `data-position` attribute rather
  * than a custom class, so the rightSection (child-expand chevron) is untouched.
  */
-.root[data-active] [data-position='left'],
-.root[aria-current='page'] [data-position='left'] {
+.root[data-active] [data-position='left'] {
   color: var(--vx-accent);
 }
 
 /*
  * Inactive rows: muted text, faint icon (docs/DESIGN-SPEC.md §5 Sidebar — "inactive = muted text,
  * faint icon"). Mantine's own NavLink.css never sets a color on the base rule — it only colors the
- * label under `[data-active]`/`[aria-current='page']` — so an inactive row otherwise falls through
- * to the ambient `--mantine-color-text` (ink), same reasoning as the active-icon rule above.
+ * label under `[data-active]` — so an inactive row otherwise falls through to the ambient
+ * `--mantine-color-text` (ink), same reasoning as the active-icon rule above.
  */
-.root:not([data-active]):not([aria-current='page']) {
+.root:not([data-active]) {
   color: var(--vx-muted);
 }
 
-.root:not([data-active]):not([aria-current='page']) [data-position='left'] {
+.root:not([data-active]) [data-position='left'] {
   color: var(--vx-faint);
 }
 
 /*
- * Inactive hover — the ink-6% ghost tint + ink text/icon (docs/DESIGN-SPEC.md §5). Lives here (not
- * only in the shell module) so a consumer's `SidebarItem.Anchor` path gets the same hover;
- * Mantine's own
- * hover fill uses `:where(scheme) .m_*:hover` (gray-0/dark-6), which this outranks on specificity.
- * Active rows keep their panel fill + `--nl-hover` untouched.
+ * Inactive hover — the ink-5% ghost tint + ink text/icon (docs/DESIGN-SPEC.md §5; dropped from 6%
+ * so it reads clearly below the active row's 12% accent fill instead of nearly matching its old 9%
+ * ink fill). Lives here (not only in the shell module) so a consumer's `SidebarItem.Anchor` path
+ * gets the same hover; Mantine's own hover fill uses `:where(scheme) .m_*:hover` (gray-0/dark-6),
+ * which this outranks on specificity. Active rows keep their accent fill above, untouched here.
  */
 @media (hover: hover) {
-  .root:not([data-active]):not([aria-current='page']):hover {
-    background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent);
+  .root:not([data-active]):hover {
+    background-color: color-mix(in srgb, var(--vx-ink) 5%, transparent);
     color: var(--vx-ink);
   }
 
-  .root:not([data-active]):not([aria-current='page']):hover [data-position='left'] {
+  .root:not([data-active]):hover [data-position='left'] {
     color: var(--vx-ink);
   }
 }

package/src/theme/segmented-control.module.css

@@ -13,6 +13,28 @@
   font-weight: 600;
 }
 
+/*
+ * Mantine's own `.control` ships `flex: 1` with no `min-width` override, so its initial value
+ * (`auto`) floors every option at its min-content width — a `fullWidth` track therefore still
+ * splits UNEVENLY (a long label's column stays wider than its siblings) instead of dividing the
+ * track equally, which is what `fullWidth` promises. `min-width: 0` lets flex-basis (not content)
+ * decide each column's share; Mantine's own `.label` already carries `overflow: hidden` +
+ * `text-overflow: ellipsis`, so a label that no longer fits its equal share truncates instead of
+ * forcing the column wide.
+ *
+ * Scoped to `[data-full-width]` — the same attribute Mantine's own CSS keys `display: flex` off
+ * (`SegmentedControl.css`) — because a bare `.control { min-width: 0 }` regressed the OTHER shape:
+ * a non-`fullWidth` track (two or three options in a `Section`/`StatCard` header's `actions` slot)
+ * is shrink-to-fit by design, and stripping every segment's min-content floor let a squeezing
+ * ancestor collapse it below its own labels' natural width with no ellipsis at all ("Absolute"
+ * clipped to "Absolut"). Outside `fullWidth`, `.control` keeps the browser's own `min-width: auto`
+ * — the ordinary flex-item protection — and the root's own `min-width: max-content`
+ * (`theme/index.ts`'s `SegmentedControl.extend`) is the backstop above it.
+ */
+[data-full-width] .control {
+  min-width: 0;
+}
+
 /*
  * Numeric segment labels read mono `VX.text.xs` (`docs/CONTROLS-SPEC.md` §3 last paragraph, C7) —
  * a consumer opts in with a bare `data-numeric` attribute on the `SegmentedControl` itself (an

package/src/theme/segmented-control.module.css.d.ts

@@ -4,5 +4,6 @@
  */
 declare const classes: {
   readonly label: string
+  readonly control: string
 }
 export default classes

package/src/theme-lab/boot.ts

@@ -0,0 +1,140 @@
+/**
+ * Theme-lab boot — the production-entry half of the theme lab, split out of `index.tsx` on purpose.
+ *
+ * `applyOverrides(loadOverrides())` is called at PRODUCTION module scope by every consumer's
+ * `main.tsx` (see `README.md`'s "Wire the runtime" section) to re-apply a persisted tuning session
+ * on load — but `index.tsx` also hosts `ThemeLabControls` (11 `@mantine/core` imports) and
+ * re-exports `DeriveControls`, which is DEV-tool UI. None of the three boot functions should assume
+ * a browser: `readVar` in particular used to append a probe `<span>` to `document.body` with no
+ * guard at all, which threw outright under SSR.
+ *
+ * What is actually enforced (`boot.test.ts`): every DOM-touching export is a no-op / empty-result
+ * with no `document`, never a throw, and this module statically imports nothing from `@mantine/*` or
+ * React. There is no `basalt-ui/theme-lab/boot` subpath and no dist-layering check on it — a prod
+ * entry still imports `basalt-ui/theme-lab` and gets `index.tsx`, which re-exports this module
+ * alongside `ThemeLabControls`. Whether a bundler actually tree-shakes the unused Mantine UI back out
+ * of a prod build that only calls `applyOverrides`/`loadOverrides`/`readVar` is bundler-dependent,
+ * not something this split guarantees on its own.
+ */
+
+export type ColorTunable = { var: string; label: string }
+export type ColorGroup = { title: string; items: ColorTunable[] }
+export type Overrides = Record<string, string>
+
+/** Gradient strength knobs (percent values, theme-independent). */
+export const AREA_TOP_VAR = '--vx-area-top'
+export const AREA_BOTTOM_VAR = '--vx-area-bottom'
+
+/**
+ * Structural `--vx-*` vars worth tuning by eye — the ones `tokens/palette.ts` hand-authors and
+ * that never move with the derive config (ColorInput is hex-only, so `rgba()`/`color-mix()` chrome
+ * vars like `--vx-axis` / `--vx-grid` are intentionally omitted regardless).
+ *
+ * Identity/color tuning lives exclusively in `DeriveControls` (one accent seed + bounded knobs,
+ * `tokens/derive.ts`) — every `--vx-*` var GENERATED from that config (the accent family, the 12
+ * categorical fills, the ink ramp, most of the surface stops, the `good`/`warn`/`bad`
+ * status/semantic hues) has been pruned from here on purpose: hand-tuning a hex the derive engine
+ * regenerates on every render is a dead knob. What remains is a low-level inspector for the
+ * genuinely NON-derived structural tokens only.
+ *
+ * Generic by design: argo's domain series (Health / Strength / Walking) are NOT shipped — a
+ * consumer passes its own series groups to `ThemeLabControls` via the `groups` prop.
+ */
+export const COLOR_GROUPS: ColorGroup[] = [
+  {
+    // `excellent` (top-of-scale grade) and `neutral` (mid-scale) keep their own hand-authored BP
+    // families — unlike `good`/`warn`/`bad`, which are the SAME derived hues as `Semantic` and are
+    // not independently tunable here.
+    title: 'Status (chart-only)',
+    items: [
+      { var: '--vx-status-excellent', label: 'Excellent' },
+      { var: '--vx-status-neutral', label: 'Neutral' },
+    ],
+  },
+  {
+    // Chart line/dot chrome — hand-authored off the zinc `BP.gray`/`BP.white`/`BP.darkGray`
+    // families, independent of the derive config.
+    title: 'Chart chrome',
+    items: [
+      { var: '--vx-line', label: 'Line' },
+      { var: '--vx-line2', label: 'Line 2' },
+      { var: '--vx-dot-stroke', label: 'Dot stroke' },
+    ],
+  },
+  {
+    // The floating-layer surface (menus, popovers, tooltips, modals, drawers) — the one SURFACE
+    // stop the derive engine has no law for, so it stays a hand-picked hex/color-mix().
+    title: 'Surface',
+    items: [{ var: '--vx-surface-overlay', label: 'Overlay' }],
+  },
+]
+
+const COLOR_VARS = COLOR_GROUPS.flatMap((g) => g.items.map((i) => i.var))
+const MANAGED_VARS = [...COLOR_VARS, AREA_TOP_VAR, AREA_BOTTOM_VAR]
+
+const KEY = 'basalt-theme-lab'
+
+/** SSR-safe: with no `document` (and so no `localStorage`), returns an empty overrides map. */
+export function loadOverrides(): Overrides {
+  if (typeof document === 'undefined') return {}
+  try {
+    const raw = localStorage.getItem(KEY)
+    return raw ? (JSON.parse(raw) as Overrides) : {}
+  } catch {
+    return {}
+  }
+}
+
+export function saveOverrides(o: Overrides): void {
+  if (typeof document === 'undefined') return
+  try {
+    localStorage.setItem(KEY, JSON.stringify(o))
+  } catch {
+    // private mode / quota — tuning just won't persist
+  }
+}
+
+/**
+ * Clears every managed var, then re-applies the given overrides. The single mutation point.
+ * SSR-safe: with no `document`, this is a no-op.
+ */
+export function applyOverrides(o: Overrides): void {
+  if (typeof document === 'undefined') return
+  const el = document.documentElement
+  for (const v of MANAGED_VARS) el.style.removeProperty(v)
+  for (const [k, val] of Object.entries(o)) {
+    if (val) el.style.setProperty(k, val)
+  }
+}
+
+/**
+ * Current value of a color var as a hex `ColorInput` can display (reflects any active override or
+ * the stylesheet default). SSR-safe: with no `document`, returns `''`.
+ *
+ * Reading the custom property directly is not enough: an UNREGISTERED custom property computes to
+ * its literal source text, so a `color-mix()`-derived token (every surface — see `SURFACE` in
+ * tokens/palette.ts) comes back as the string `"color-mix(in srgb, #3f3f46 50%, #27272a)"`, which
+ * ColorInput cannot parse — it renders an empty swatch. Painting the var onto a probe element and
+ * reading a real COLOR property instead forces the browser to resolve it to an rgb triple.
+ */
+export function readVar(name: string): string {
+  if (typeof document === 'undefined') return ''
+  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim()
+  if (raw.startsWith('#')) return raw
+  if (!raw) return ''
+
+  const probe = document.createElement('span')
+  probe.style.display = 'none'
+  probe.style.color = `var(${name})`
+  document.body.appendChild(probe)
+  const computed = getComputedStyle(probe).color
+  probe.remove()
+
+  const channels = computed.match(/[\d.]+/g)
+  if (!channels || channels.length < 3) return raw
+  const hex = channels
+    .slice(0, 3)
+    .map((c) => Math.round(Number(c)).toString(16).padStart(2, '0'))
+    .join('')
+  return `#${hex}`
+}

package/src/theme-lab/index.tsx

@@ -42,123 +42,32 @@ import { useState } from 'react'
 import type { ReactNode } from 'react'
 import { BP } from '../tokens/palette'
 import { VX } from '../tokens'
+import {
+  applyOverrides,
+  AREA_BOTTOM_VAR,
+  AREA_TOP_VAR,
+  COLOR_GROUPS,
+  loadOverrides,
+  readVar,
+  saveOverrides,
+} from './boot'
+import type { ColorGroup, ColorTunable, Overrides } from './boot'
 
 export { DeriveControls } from './derive-controls'
 export type { DeriveControlsProps } from './derive-controls'
 
-export type ColorTunable = { var: string; label: string }
-export type ColorGroup = { title: string; items: ColorTunable[] }
-export type Overrides = Record<string, string>
-
-/** Gradient strength knobs (percent values, theme-independent). */
-export const AREA_TOP_VAR = '--vx-area-top'
-export const AREA_BOTTOM_VAR = '--vx-area-bottom'
-
-/**
- * Structural `--vx-*` vars worth tuning by eye — the ones `tokens/palette.ts` hand-authors and
- * that never move with the derive config (ColorInput is hex-only, so `rgba()`/`color-mix()` chrome
- * vars like `--vx-axis` / `--vx-grid` are intentionally omitted regardless).
- *
- * Identity/color tuning lives exclusively in {@link DeriveControls} (one accent seed + bounded
- * knobs, `tokens/derive.ts`) — every `--vx-*` var GENERATED from that config (the accent family,
- * the 12 categorical fills, the ink ramp, most of the surface stops, the `good`/`warn`/`bad`
- * status/semantic hues) has been pruned from here on purpose: hand-tuning a hex the derive engine
- * regenerates on every render is a dead knob. What remains is a low-level inspector for the
- * genuinely NON-derived structural tokens only.
- *
- * Generic by design: argo's domain series (Health / Strength / Walking) are NOT shipped — a
- * consumer passes its own series groups to {@link ThemeLabControls} via the `groups` prop.
- */
-export const COLOR_GROUPS: ColorGroup[] = [
-  {
-    // `excellent` (top-of-scale grade) and `neutral` (mid-scale) keep their own hand-authored BP
-    // families (`p(BP.forest)` / `p(BP.gray, 1, 2)`) — unlike `good`/`warn`/`bad`, which are the
-    // SAME derived hues as `Semantic` and are not independently tunable here.
-    title: 'Status (chart-only)',
-    items: [
-      { var: '--vx-status-excellent', label: 'Excellent' },
-      { var: '--vx-status-neutral', label: 'Neutral' },
-    ],
-  },
-  {
-    // Chart line/dot chrome — hand-authored off the zinc `BP.gray`/`BP.white`/`BP.darkGray`
-    // families, independent of the derive config.
-    title: 'Chart chrome',
-    items: [
-      { var: '--vx-line', label: 'Line' },
-      { var: '--vx-line2', label: 'Line 2' },
-      { var: '--vx-dot-stroke', label: 'Dot stroke' },
-    ],
-  },
-  {
-    // The floating-layer surface (menus, popovers, tooltips, modals, drawers) — the one SURFACE
-    // stop the derive engine has no law for, so it stays a hand-picked hex/color-mix().
-    title: 'Surface',
-    items: [{ var: '--vx-surface-overlay', label: 'Overlay' }],
-  },
-]
-
-const COLOR_VARS = COLOR_GROUPS.flatMap((g) => g.items.map((i) => i.var))
-const MANAGED_VARS = [...COLOR_VARS, AREA_TOP_VAR, AREA_BOTTOM_VAR]
-
-const KEY = 'basalt-theme-lab'
-
-export function loadOverrides(): Overrides {
-  try {
-    const raw = localStorage.getItem(KEY)
-    return raw ? (JSON.parse(raw) as Overrides) : {}
-  } catch {
-    return {}
-  }
-}
-
-export function saveOverrides(o: Overrides): void {
-  try {
-    localStorage.setItem(KEY, JSON.stringify(o))
-  } catch {
-    // private mode / quota — tuning just won't persist
-  }
-}
-
-/** Clears every managed var, then re-applies the given overrides. The single mutation point. */
-export function applyOverrides(o: Overrides): void {
-  const el = document.documentElement
-  for (const v of MANAGED_VARS) el.style.removeProperty(v)
-  for (const [k, val] of Object.entries(o)) {
-    if (val) el.style.setProperty(k, val)
-  }
-}
-
-/**
- * Current value of a color var as a hex `ColorInput` can display (reflects any active override or
- * the stylesheet default).
- *
- * Reading the custom property directly is not enough: an UNREGISTERED custom property computes to
- * its literal source text, so a `color-mix()`-derived token (every surface — see `SURFACE` in
- * tokens/palette.ts) comes back as the string `"color-mix(in srgb, #3f3f46 50%, #27272a)"`, which
- * ColorInput cannot parse — it renders an empty swatch. Painting the var onto a probe element and
- * reading a real COLOR property instead forces the browser to resolve it to an rgb triple.
- */
-export function readVar(name: string): string {
-  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim()
-  if (raw.startsWith('#')) return raw
-  if (!raw) return ''
-
-  const probe = document.createElement('span')
-  probe.style.display = 'none'
-  probe.style.color = `var(${name})`
-  document.body.appendChild(probe)
-  const computed = getComputedStyle(probe).color
-  probe.remove()
-
-  const channels = computed.match(/[\d.]+/g)
-  if (!channels || channels.length < 3) return raw
-  const hex = channels
-    .slice(0, 3)
-    .map((c) => Math.round(Number(c)).toString(16).padStart(2, '0'))
-    .join('')
-  return `#${hex}`
+// Re-exported from `./boot` — SSR-safe, Mantine-free. `basalt-ui/theme-lab` keeps resolving both
+// halves through this one barrel; see `boot.ts`'s module doc for why they were split out.
+export {
+  applyOverrides,
+  AREA_BOTTOM_VAR,
+  AREA_TOP_VAR,
+  COLOR_GROUPS,
+  loadOverrides,
+  readVar,
+  saveOverrides,
 }
+export type { ColorGroup, ColorTunable, Overrides }
 
 /** Quick-pick Blueprint swatches (mid stop of each family) for the color inputs. */
 const SWATCHES: string[] = [

package/src/theme-toggle/index.tsx

@@ -24,6 +24,7 @@ import { useReducedMotion } from '@mantine/hooks'
 import { AnimatePresence, motion } from 'motion/react'
 import { useRef, useState } from 'react'
 import { MOTION_SPRING } from '../motion'
+import type { BasaltProps } from '../common/props'
 
 type Scheme = 'light' | 'dark' | 'auto'
 
@@ -108,7 +109,7 @@ function SchemeGlyph({ dark, reduceMotion }: { dark: boolean; reduceMotion: bool
   )
 }
 
-export type ThemeToggleProps = {
+export type ThemeToggleProps = BasaltProps & {
   /** Delay (ms) before the direct-select popover opens on hover/focus. Default 150. */
   openDelay?: number
   /** Delay (ms) before it closes after the pointer/focus leaves. Default 200. */
@@ -120,7 +121,12 @@ function nextScheme(current: Scheme): Scheme {
   return CYCLE[(CYCLE.indexOf(current) + 1) % CYCLE.length]!
 }
 
-export function ThemeToggle({ openDelay = 150, closeDelay = 200 }: ThemeToggleProps = {}) {
+export function ThemeToggle({
+  openDelay = 150,
+  closeDelay = 200,
+  className,
+  style,
+}: ThemeToggleProps = {}) {
   const { colorScheme, setColorScheme } = useMantineColorScheme()
   const resolved = useComputedColorScheme('dark')
   const reduceMotion = useReducedMotion()
@@ -151,7 +157,8 @@ export function ThemeToggle({ openDelay = 150, closeDelay = 200 }: ThemeTogglePr
         <ActionIcon
           variant="subtle"
           color="gray"
-          style={{ borderRadius: 'var(--vx-radius-ctrl)' }}
+          {...(className !== undefined && { className })}
+          style={{ borderRadius: 'var(--vx-radius-ctrl)', ...style }}
           aria-label={`Theme: ${LABEL[colorScheme]}. Click to cycle, hover to pick directly.`}
           onClick={() => setColorScheme(nextScheme(colorScheme))}
           onMouseEnter={scheduleOpen}

package/src/tokens/index.ts

@@ -279,6 +279,49 @@ export const VX = {
     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,
+  /**
+   * The measured CONTAINER width, in px, below which a chart resolves to its phone tier
+   * (`resolveChartTier`, `docs/CHARTS-SPEC.md` §8): one step smaller legend and tick fonts,
+   * tightened margin floors, a smaller crosshair dot, a narrower tooltip, and a two-entry legend
+   * rollup.
+   *
+   * Deliberately NOT a media query and NOT a `theme.breakpoints` value. A chart in a two-column
+   * grid cell on a 1440px desktop is as narrow as one on a phone, and only the element's own
+   * measured box knows that — the viewport does not. It also keeps the chart layer Mantine-free:
+   * `theme.breakpoints` lives on the coupled side of the boundary.
+   */
+  phoneChartWidth: 480,
+} 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 (`VX.phoneChartWidth`), 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` (48em/768px) 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}. */
@@ -454,7 +497,8 @@ function frameworkPrimitives(side: Side, data: PaletteData, legacyAliases: boole
  * 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,
+ * 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
@@ -572,7 +616,6 @@ function spaceDecls(space: SpaceValues): string[] {
     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-top', `${space.step.sidebarBrandInsetTop}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`),
@@ -616,10 +659,11 @@ function spaceDecls(space: SpaceValues): string[] {
     // `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` join that list —
-    // `shell/index.tsx` reads all three as JS numbers via `useBasaltSpacing()` (Mantine's `AppShell`
-    // `header`/`navbar` 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
+    // `appShellNavbarWidth`/`appShellNavbarRailWidth`/`appShellAsideWidth`/`appShellAsideRailWidth`
+    // join that list —
+    // `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).