basalt-ui 1.5.0 → 1.6.0

package/dist/tokens/palette.js

@@ -44,6 +44,37 @@ const SHADOW = {
     light: "0 1px 2px rgba(28,25,23,0.12)",
     dark: "0 1px 2px rgba(0,0,0,0.35)"
   },
+  /**
+   * Interactive-control depth — the ONE value every raised Button/ActionIcon/Input variant shares
+   * (`docs/DESIGN-SPEC.md` §5's Button idiom). Exists rather than reusing `card` because `card`'s
+   * ring is OUTSET, and an outset ring paints in the color of whatever it is drawn over: fine
+   * between neutral panels, but on light scheme it resolves to `--vx-surface-hairline` and draws a
+   * pale grey outline around a saturated `filled` button, which reads as a rendering defect.
+   *
+   * THE TWO SCHEMES ARE SHAPED DIFFERENTLY, and the asymmetry is the whole design — do NOT "tidy"
+   * them into one shape. Both were arrived at by elimination, on screen:
+   *
+   *   - DARK = drop + a full inset rim. Its edge is a LIGHTENING, so it cannot collide with the
+   *     dark drop below the box; a uniform lightening on a dark surface reads as rim light wrapping
+   *     a raised object, which is exactly right.
+   *
+   *   - LIGHT = drop ONLY, no edge at all. A light-mode edge would have to be a DARKENING (there is
+   *     nothing lighter than a near-white control to lighten with), and every position for one
+   *     fails: a uniform dark ring does not read as depth, it reads as a BORDER — it made `default`
+   *     and `light` look like outlined buttons and every form field look boxed. Moving it to the
+   *     bottom edge alone then put a dark inner line directly above the dark drop, i.e. a visible
+   *     DOUBLE BOTTOM BORDER. There is no third position, because a light-mode raised object's only
+   *     honest cue is the shadow it casts. So light casts one and draws nothing.
+   *
+   * Consequence to know, on light only: a `default` control nested in a Card shares
+   * `--vx-surface-panel` with it and has no boundary but the drop. That is accepted — a wrong-
+   * looking border on every control in the app is worse than a soft edge in one nesting case. If it
+   * ever needs more, raise the DROP. Do not reintroduce an edge; both shapes have been tried.
+   */
+  raised: {
+    light: "0 1px 2px rgba(28,25,23,0.10)",
+    dark: "0 1px 2px rgba(0,0,0,0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)"
+  },
   // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a REAL drop shadow, a
   // step above `card`, so detached surfaces read as lifted off the page (`docs/DESIGN-SPEC.md` §5).
   // Unlike `card`, no embedded ring: floating surfaces carry a real 1px `--vx-surface-border` so

package/dist/tokens.css

@@ -206,6 +206,7 @@ html[data-mantine-color-scheme='dark'] {
   --vx-divider: color-mix(in srgb, #ffffff 6%, transparent);
   --vx-shadow-card: 0 1px 3px rgba(0,0,0,0.4), inset 0 0 0 1px color-mix(in srgb, #ffffff 4%, transparent);
   --vx-shadow-ctrl: 0 1px 2px rgba(0,0,0,0.35);
+  --vx-shadow-raised: 0 1px 2px rgba(0,0,0,0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent);
   --vx-shadow-overlay: 0 8px 24px rgba(0,0,0,0.5);
   --vx-surface-bg: #27272a;
   --vx-surface-panel: #2b2b2e;
@@ -269,6 +270,7 @@ html[data-mantine-color-scheme='light'] {
   --vx-divider: color-mix(in srgb, #e5e5e5 65%, transparent);
   --vx-shadow-card: 0 1px 2px rgba(28,25,23,0.05), 0 0 0 1px var(--vx-surface-hairline);
   --vx-shadow-ctrl: 0 1px 2px rgba(28,25,23,0.12);
+  --vx-shadow-raised: 0 1px 2px rgba(28,25,23,0.10);
   --vx-shadow-overlay: 0 8px 24px rgba(28,25,23,0.10);
   --vx-surface-bg: #f2f2f5;
   --vx-surface-panel: #fafafd;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.5.0
+# basalt-ui v1.6.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.5.0
+Version: 1.6.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/agent/stick-to-bottom.tsx

@@ -81,7 +81,8 @@ const LazyStickToBottom = lazy(() =>
                   border: 'none',
                   cursor: 'pointer',
                   backgroundColor: 'var(--vx-surface-panel)',
-                  boxShadow: 'var(--vx-shadow-card)',
+                  // Control depth, not panel depth — this is a real <button> (DESIGN-SPEC §2).
+                  boxShadow: 'var(--vx-shadow-raised)',
                   color: 'var(--vx-faint)',
                   fontFamily: 'var(--basalt-font-mono)',
                   fontSize: VX.text.md,

package/src/agent-chat/composer.tsx

@@ -76,13 +76,14 @@ export function Composer({
     disabled,
     onChange: (event) => setValue(event.currentTarget.value),
     onKeyDown: handleKeyDown,
-    // Composer input surface (docs/DESIGN-SPEC.md §5): panel + shadow-card, control radius (6px,
-    // VX.radiusCtrl) — the ring
-    // lives in the shadow, so the input carries no separate border.
+    // Composer input surface (docs/DESIGN-SPEC.md §5): panel + control radius (6px, VX.radiusCtrl);
+    // the ring lives in the shadow, so the input carries no separate border. Depth is deliberately
+    // NOT set here — it arrives from the themed `.input` class (theme/controls.module.css), which
+    // also grounds it when disabled. A `boxShadow` in this `styles` object renders as an INLINE
+    // style and would beat that class unconditionally, leaving a disabled composer raised.
     styles: {
       input: {
         backgroundColor: 'var(--vx-surface-panel)',
-        boxShadow: 'var(--vx-shadow-card)',
         borderRadius: VX.radiusCtrl,
         border: 'none',
       },

package/src/shell/app-sidebar.module.css

@@ -6,7 +6,7 @@
  * line is the child-list left guide (`--vx-divider`). Never reintroduce brand/section/footer
  * borders.
  *
- * The active fill, shadow-card depth and icon-accent color live in the Mantine theme
+ * The active tint and icon-accent color live in the Mantine theme
  * (`NavLink.extend` + `theme/nav-link.module.css`) so they apply to EVERY render path, including a
  * consumer's router `<Link>` via `renderNavLink` (which never sees this CSS module). This module
  * owns the shell-local layout (docs/DESIGN-SPEC.md §5) and the INACTIVE state (muted text, faint
@@ -50,7 +50,7 @@
 }
 
 /* Hover — ink-6% tint + ink text, for inactive rows only (an active row already carries the
- * theme's panel/shadow-card treatment and keeps its own hover via `--nl-hover`). */
+ * theme's stronger ink-9% tint and keeps its own hover via `--nl-hover`). */
 @media (hover: hover) {
   .link:not([data-active]):not([aria-current='page']):hover {
     background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
@@ -316,16 +316,14 @@
 
 /*
  * Active child = accent text, weight 600, NO fill (docs/DESIGN-SPEC.md §5) — unlike a top-level
- * active row (panel + shadow-card). Overrides the `--nl-*` custom properties the theme sets
- * inline on the SAME NavLink root, so `!important` is required; `box-shadow` cancels the theme
- * module's active shadow-card.
+ * active row (ink-9% tint). Overrides the `--nl-*` custom properties the theme sets inline on the
+ * SAME NavLink root, so `!important` is required.
  */
 .childList :global(.mantine-NavLink-root[data-active]),
 .childList :global(.mantine-NavLink-root[aria-current='page']) {
   --nl-color: var(--vx-accent) !important;
   --nl-bg: transparent !important;
   --nl-hover: color-mix(in srgb, var(--vx-ink) 5%, transparent) !important;
-  box-shadow: none !important;
 }
 
 /* Child hover (inactive) — ink-5% + ink, one step quieter than the parent rows' 6%. Outranks the

package/src/shell/sidebar-search.module.css

@@ -1,6 +1,8 @@
 /*
  * Sidebar search trigger — replicates the former header search trigger (panel surface +
- * shadow-card, control radius, faint icon/label, mono Kbd) at full width inside the sidebar.
+ * shadow-raised, control radius, faint icon/label, mono Kbd) at full width inside the sidebar.
+ * `shadow-raised` is the shared CONTROL depth — §5 specifies this trigger and the header icon
+ * button as a matched pair, so the two must never drift onto different depth tokens.
  */
 
 .trigger {
@@ -12,7 +14,7 @@
   padding: 0 var(--vx-space-row-inset-x);
   border-radius: var(--vx-radius-ctrl);
   background-color: var(--vx-surface-panel);
-  box-shadow: var(--vx-shadow-card);
+  box-shadow: var(--vx-shadow-raised);
   color: var(--vx-faint);
 }
 

package/src/theme/controls.module.css

@@ -6,10 +6,19 @@
 
 /*
  * Field idiom (docs/DESIGN-SPEC.md §5): inputs read slightly inset on the panel — field surface
- * (white on light, a page-bg step below panel on dark), depth via `shadow-card` (a whisper shadow
- * + ring baked into the one value — DESIGN-SPEC doctrine inversion #1: depth is `shadow-card`, not
- * a hairline; borders-as-borders stay reserved for layout dividers), faint placeholder, and an
+ * (white on light, a page-bg step below panel on dark), depth via `shadow-raised` (a whisper shadow
+ * + ring baked into the one value — DESIGN-SPEC doctrine inversion #1: depth is a shadow, not a
+ * hairline; borders-as-borders stay reserved for layout dividers), faint placeholder, and an
  * accent border on focus (Mantine's own `:focus` rule swaps `--input-bd` to `--input-bd-focus`).
+ *
+ * `shadow-raised` — the SAME token Button/ActionIcon take below, and that sharing is deliberate.
+ * A `size="md"` Input and a `size="md"` Button are pinned to identical heights by
+ * `--vx-space-control-height`, so they are read as one row of controls; when the buttons moved onto
+ * `shadow-raised` and the fields stayed on `shadow-card`, that row visibly split in two. Panels
+ * (Card/Paper/Notification/ChartCard/SettingsSection) keep `shadow-card` — the line is
+ * control-vs-panel, not component-by-component. Its inset ring also suits a field better than
+ * `card`'s outset one ever did: an outset ring draws a boundary AROUND the box, while an inset edge
+ * darkens the field's own rim, which is what "recessed into the panel" actually looks like.
  * The `--input-bd` box itself stays a TRANSPARENT 1px border (not `border: none`) so focus can
  * recolor the same box with no layout shift, and `[data-error]` still wins a real red border.
  *
@@ -30,13 +39,15 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
 }
 
 /*
- * Depth lands on the INPUT ELEMENT, never on the wrapper above — `--vx-shadow-card` bakes a 1px
+ * Depth lands on the INPUT ELEMENT, never on the wrapper above — `--vx-shadow-raised` bakes a 1px
  * ring into the shadow, and the ring follows the shadowed box's OWN `border-radius`, not any other
  * element's. Mantine's input wrapper (`.m_6c018570`) is a bare `position: relative` box with
  * `border-radius: 0`; the ring drawn there squares off around the rounded input inside it and leaks
  * visible corner nubs. The input element itself carries `border-radius: var(--input-radius)`
- * (Input.css), so the ring follows the rounded edge exactly. This is the general rule for the token
- * — see shadow-surfaces.test.ts.
+ * (Input.css), so the ring follows the rounded edge exactly. `raised`'s ring being INSET rather than
+ * outset does not soften this: an inset ring is drawn by the same box and follows the same corners,
+ * so a mismatch leaks nubs on the inside of the corner instead of the outside. This is the general
+ * rule for every depth token — see shadow-surfaces.test.ts.
  *
  * Mantine never declares a `box-shadow` on the input at any specificity, so a plain `.input` class
  * (0,1,0) wins uncontested. `--field-depth` carries the resting shadow so the `:focus` rule below
@@ -51,27 +62,155 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
 }
 
 .input[data-variant='default'] {
-  --field-depth: var(--vx-shadow-card);
+  --field-depth: var(--vx-shadow-raised);
+}
+
+/*
+ * Button / ActionIcon depth (docs/DESIGN-SPEC.md §5's Button idiom; the header's search trigger and
+ * icon button are specified there as a matched pair and both land on `shadow-raised`, same as the
+ * field above).
+ *
+ * THE LAW: depth says "this is a control surface"; it is NOT the emphasis axis. Emphasis lives
+ * entirely in fill weight (`filled` > `light`/`outline` > `subtle`), exactly as every surveyed
+ * system resolves it — Material 3's filled button, Radix's `solid`, and Primer's primary all rank
+ * by fill and saturation, never by z-height. So every variant that OWNS A BOX gets the same
+ * resting depth, and only the tier that owns no box stays flat.
+ *
+ * This replaces a `default`-only rule that inverted the hierarchy in practice: `default` was the
+ * one variant carrying depth, so the SECONDARY button read as a physical object while the primary
+ * (`filled`) read as paint on the page. Raising the rest is what removes the inversion — flattening
+ * `default` instead would fix it too, but it is not open to us: DESIGN-SPEC doctrine inversion #1
+ * ("depth is a shadow, not a hairline") already raised Card/Paper/Input/Chip/CheckboxCard, so a flat
+ * Button would be the only flat control in a row of raised ones — most visibly beside a
+ * `size="md"` TextInput, which the `--vx-space-control-height` coupling in theme/index.ts pins to
+ * the exact same height.
+ *
+ * ONE depth value for the raised family, and it is `shadow-raised` — a drop plus a 1px INSET edge:
+ *   - `default`/`filled`/`light` all take it, unmodified. The shared value is the point. An earlier
+ *     revision split them (`default` on `shadow-card`, the rest on ring-free `shadow-ctrl`) and
+ *     `default` visibly read a step more three-dimensional than the other two: it was the only one
+ *     with a DEFINED EDGE, and on dark it also carried a wider blur. A soft drop alone reads as
+ *     "something is under this"; a crisp boundary is what actually reads as an object. Landing them
+ *     on one value is what closed that gap — `default` came down (no more 3px/0.4 dark blur, no
+ *     outset ring), `filled`/`light` came up (they gained an edge at all).
+ *   - The edge is INSET, which is exactly why one value can cover all three — see `SHADOW.raised`
+ *     in tokens/palette.ts for the full reasoning. Short version: an outset ring paints in the color
+ *     of what it is drawn over, so `card`'s pale hairline ring would read as a grey outline around a
+ *     saturated `filled` button on light scheme; an inset edge is drawn over the control's OWN
+ *     background and works on a fill, a 13% tint and a neutral panel alike. It also keeps `default`
+ *     legible inside a Card, where button and card share `--vx-surface-panel` and the inset edge is
+ *     the only thing separating them (its border is pinned `transparent` by
+ *     `cssVariablesResolver`, which kills the stock hairline `defaultVariantColorsResolver` draws
+ *     for EVERY default-variant control — so this edge really is its only one).
+ *   - `outline` is the one raised variant NOT on it: it already carries a real 1px accent border,
+ *     and an inset edge tucked just inside a border is muddy. It takes ring-free `shadow-ctrl`
+ *     instead — the same token, for the same reason, that SegmentedControl's active segment uses to
+ *     say "this is the lifted one". Its border is its edge, so it is not missing one.
+ *
+ * `subtle` is the one tier that owns no box — it is a text affordance, not an object, and every
+ * system surveyed keeps that tier flat. It stays flat in BOTH states here: its hover is Mantine's
+ * own background tint and nothing else, which is exactly how the spec's "ghost icon button" (§5:
+ * transparent, faint icon, hover ink-6% + ink icon) already behaved. Button's `subtle` and
+ * ActionIcon's therefore need no asymmetry between them. See the note below the variant rules for
+ * why an earlier hover-depth attempt was reverted.
+ *
+ * Mantine never declares a `box-shadow` on either component at ANY specificity, so a plain
+ * module-class + attribute selector wins uncontested — no `html[...]` prefix fight, unlike the
+ * input-variable overrides above. Depth rides `--ctrl-depth` rather than landing on `box-shadow`
+ * directly (the same indirection `.input` uses for `--field-depth`) so the disabled rule below
+ * moves ONE variable instead of restating a value per variant.
+ */
+.buttonRoot,
+.actionIconRoot {
+  --ctrl-depth: 0 0 transparent;
+
+  box-shadow: var(--ctrl-depth);
+  transition: box-shadow 120ms ease;
+}
+
+.buttonRoot[data-variant='default'],
+.buttonRoot[data-variant='filled'],
+.buttonRoot[data-variant='light'] {
+  --ctrl-depth: var(--vx-shadow-raised);
+}
+
+.actionIconRoot[data-variant='default'],
+.actionIconRoot[data-variant='filled'],
+.actionIconRoot[data-variant='light'] {
+  --ctrl-depth: var(--vx-shadow-raised);
+}
+
+.buttonRoot[data-variant='outline'] {
+  --ctrl-depth: var(--vx-shadow-ctrl);
+}
+
+.actionIconRoot[data-variant='outline'] {
+  --ctrl-depth: var(--vx-shadow-ctrl);
+}
+
+/*
+ * DEPTH HERE IS STATIC. No variant changes depth or position on hover or press — the raised variants
+ * already get hover feedback from Mantine's own background change, so anything layered on top just
+ * restates a signal that is already there. Two attempts at adding one were made and both reverted,
+ * for reasons worth keeping:
+ *
+ *   - A 1px `translateY` lift on hover, reversed on press. It restated the background change AND
+ *     cost something real: Floating UI measures a transformed rect, so a Tooltip or Popover anchored
+ *     to the button visibly shifts with it.
+ *   - `subtle` materializing into `shadow-raised` on hover. The theory was that `subtle` owns no box
+ *     at rest, so gaining one under the cursor is the affordance rather than decoration. In practice
+ *     `shadow-raised`'s INSET edge is a hard rim, and a rim appearing around a ghost button makes it
+ *     read as an `outline` button rather than as a text affordance that lit up — the tint alone
+ *     already says "pressable", and the rim says something else entirely. `subtle` is now flat in
+ *     BOTH states, which also collapses an asymmetry that had to be documented twice: Button's
+ *     `subtle` and ActionIcon's ghost icon button finally behave identically.
+ *
+ * DON'T REINTRODUCE EITHER. If a future pass wants `subtle` to gain depth on hover, the token to
+ * reach for is ring-free `shadow-ctrl`, not `shadow-raised` — the drop is the part that reads as
+ * lift, the rim is the part that read as wrong.
+ */
+
+/*
+ * Disabled is flat and grounded — a raised control reads as pressable, which is the one thing a
+ * disabled control must not do. Mantine's own disabled rule (Button.css/ActionIcon.css) recolors
+ * background and text but never touches the shadow, so nothing here fights it; the `[data-loading]`
+ * exclusion mirrors that same rule, keeping a loading button's chrome intact while it works.
+ * Written as real (0,3,0) selectors rather than a `:where()` group so this outranks the (0,2,0)
+ * variant rules above on specificity alone, independent of source order.
+ */
+.buttonRoot:disabled:not([data-loading]),
+.buttonRoot[data-disabled]:not([data-loading]),
+.actionIconRoot:disabled:not([data-loading]),
+.actionIconRoot[data-disabled]:not([data-loading]) {
+  --ctrl-depth: 0 0 transparent;
 }
 
 /*
- * Button / ActionIcon (`default` variant): the SAME shadow-card depth as the field above and as
- * Card/Paper (docs/DESIGN-SPEC.md §5: "search trigger … panel + shadow-card", "icon button …
- * panel + shadow-card"). Background and border already resolve centrally, through
- * `--mantine-color-default`/`-border` (theme/index.ts's `cssVariablesResolver`) — the
- * `default-border` var is pinned to `transparent` there, which is what kills the stock 1px
- * hairline `defaultVariantColorsResolver`'s `variant === 'default'` branch draws for EVERY
- * default-variant control (Button, ActionIcon, Chip, CheckboxCard, RadioCard, …), not just these
- * two. Only the shadow is a fresh declaration (Mantine never sets one for `default`), so no
- * `html[...]` specificity fight is needed to win it — a plain module-class + attribute selector is
- * deterministic. `filled`/`subtle`/`light` variants are untouched by the attribute scope.
+ * Fields ground when disabled for the same reason, and this rule is why the field/button split had
+ * to close on BOTH sides: buttons got the treatment above when they moved onto `shadow-raised`,
+ * while inputs — which sat on `shadow-card` at the time — never had one at all, so a disabled
+ * TextInput stayed raised. Once fields joined the same depth family that gap became a visible
+ * inconsistency inside one form rather than a quiet oversight.
+ *
+ * `:disabled` covers the real `<input>`/`<textarea>`; `[data-disabled]` covers the composite fields
+ * (Select, MultiSelect, DatePicker) where Mantine disables a readonly input via the attribute
+ * instead. No `[data-loading]` exclusion here — inputs have no loading state, unlike Button.
  */
-.buttonRoot[data-variant='default'] {
-  box-shadow: var(--vx-shadow-card);
+.input:disabled,
+.input[data-disabled] {
+  --field-depth: 0 0 transparent;
 }
 
-.actionIconRoot[data-variant='default'] {
-  box-shadow: var(--vx-shadow-card);
+/*
+ * Reduced motion drops the fade, never the shadow: a static shadow is not motion, and removing it
+ * would strip the very hierarchy this pass exists to establish from the users who asked for less
+ * animation. `subtle`'s hover depth still lands — it just lands instantly.
+ */
+@media (prefers-reduced-motion: reduce) {
+  .buttonRoot,
+  .actionIconRoot {
+    transition: none;
+  }
 }
 
 /*
@@ -84,7 +223,7 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
 .radioCardRoot[data-with-border] {
   background-color: var(--vx-surface-panel);
   border-color: transparent;
-  box-shadow: var(--vx-shadow-card);
+  box-shadow: var(--vx-shadow-raised);
 }
 
 /*
@@ -96,7 +235,7 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
  */
 .chipLabel:not([data-checked]):not([data-disabled]) {
   background-color: var(--vx-surface-panel);
-  box-shadow: var(--vx-shadow-card);
+  box-shadow: var(--vx-shadow-raised);
 }
 
 /*

package/src/theme/index.ts

@@ -342,6 +342,24 @@ const basaltVariantColorResolver: VariantColorsResolver = (input) => {
     return autoContrast ? { ...resolved, color: on } : resolved
   }
 
+  // `subtle`: hover is a NEUTRAL ink tint, not Mantine's accent tint
+  // (`--mantine-color-{c}-light`). `docs/DESIGN-SPEC.md` §5 specifies the ghost idiom as "hover
+  // ink-6% + ink icon", and a subtle Button had never followed it — it hovered into a saturated
+  // accent block that read as a filled control appearing under the cursor. Fixing it HERE rather
+  // than in controls.module.css is what makes Button and ActionIcon agree: both resolve `subtle`
+  // through this one function, and §5's ghost icon button and a `variant="subtle"` Button are meant
+  // to be the same idiom at two sizes.
+  //
+  // Scoped to the DEFAULT color on purpose. An explicitly-colored subtle control (`color="red"` on a
+  // destructive text action) carries its hue as the whole signal, so neutralizing its hover would
+  // erase the one thing that marks it dangerous — those keep Mantine's own tinted hover.
+  if (input.variant === 'subtle') {
+    const isDefaultColor = input.color === undefined || input.color === input.theme.primaryColor
+    return isDefaultColor
+      ? { ...resolved, hover: `color-mix(in srgb, var(--vx-ink) 6%, transparent)` }
+      : resolved
+  }
+
   if (input.variant !== 'light') return resolved
   const ink = `var(--mantine-color-${colorName}-light-color)`
   return {
@@ -526,17 +544,26 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
         },
       }),
       // "Ink earns its color" — a nav selection is UI state, not the identity accent on the LABEL.
-      // The active item is panel bg + `shadow-card` (forced here at the THEME level via NavLink's
-      // `--nl-*` vars, so it holds for every render path — including a consumer's router `<Link>`
-      // via `renderNavLink`, which never sees the shell CSS module); the active ICON is
-      // accent-colored via `nav-link.module.css` (targets the `[data-position='left']` leftSection,
-      // which the flat `vars`/`styles` API can't express conditionally on `[data-active]`).
+      // The active item is a SELECTED ROW, not a raised control: the same ink-tint idiom as the
+      // hover state (one step stronger, ink-9%), no panel fill and no `shadow-card` — a raised,
+      // panel-filled row read as a button sitting in the nav rather than as the current location.
+      // Selection is carried by the tint + ink text + weight 600 + the accent icon instead. Forced
+      // here at the THEME level via NavLink's `--nl-*` vars so it holds for every render path —
+      // including a consumer's router `<Link>` via `renderNavLink`, which never sees the shell CSS
+      // module; the active ICON is accent-colored via `nav-link.module.css` (targets the
+      // `[data-position='left']` leftSection, which the flat `vars`/`styles` API can't express
+      // conditionally on `[data-active]`).
+      //
+      // `--nl-hover` (ink-13%) only ever reaches an ACTIVE row in practice — the inactive hover is
+      // set at ink-6% by higher-specificity `:not([data-active])` rules in `nav-link.module.css` /
+      // `app-sidebar.module.css` — so it exists to keep the active row responding to the pointer
+      // now that its rest state sits in the same tint family as an inactive hover.
       NavLink: NavLink.extend({
         vars: () => ({
           root: {
-            '--nl-bg': 'var(--vx-surface-panel)',
+            '--nl-bg': 'color-mix(in srgb, var(--vx-ink) 9%, transparent)',
             '--nl-color': 'var(--vx-ink)',
-            '--nl-hover': 'color-mix(in srgb, var(--vx-ink) 6%, transparent)',
+            '--nl-hover': 'color-mix(in srgb, var(--vx-ink) 13%, transparent)',
           },
           children: {},
         }),
@@ -570,7 +597,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
           label: { fontSize: VX.text.md, lineHeight: 'var(--vx-space-row-line-height)' },
         },
       }),
-      // Field idiom (docs/DESIGN-SPEC.md §5): field surface + `shadow-card` depth + faint placeholder,
+      // Field idiom (docs/DESIGN-SPEC.md §5): field surface + `shadow-raised` depth + faint placeholder,
       // accent border + subtle accent ring on focus — see controls.module.css. The two slots carry
       // different halves of it: the `wrapper` is where Mantine declares the `--input-*` vars, the
       // `input` is the box that actually paints the surface (bg + radius) and therefore the only
@@ -625,16 +652,19 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       PillsInput: PillsInput.extend({
         classNames: { wrapper: controlsClasses.inputWrapper, input: controlsClasses.input },
       }),
-      // Button / ActionIcon (`default` variant): same `shadow-card` depth as every other control
-      // surface (docs/DESIGN-SPEC.md §5: "search trigger … panel + shadow-card", "icon button …
-      // panel + shadow-card"; doctrine inversion #1). Background already resolves through the shared
+      // Button / ActionIcon: depth for EVERY variant that owns a box (docs/DESIGN-SPEC.md §5's
+      // Button idiom; doctrine inversion #1) — `default`/`filled`/`light` on the shared
+      // `shadow-raised`, `outline` on ring-free `shadow-ctrl`, `subtle` flat at rest. Emphasis stays
+      // in fill weight,
+      // never in z-height. Background for `default` already resolves through the shared
       // `--mantine-color-default` var (→ `--vx-surface-panel`, see cssVariablesResolver below) and
-      // the border through `--mantine-color-default-border` (→ transparent, same resolver) — neither
+      // its border through `--mantine-color-default-border` (→ transparent, same resolver) — neither
       // component had a `.extend()` block at all before this, which is why they never picked up
-      // either. Only the shadow needs adding here, in controls.module.css: Mantine's own
-      // `[data-variant='default']` rule never declares a `box-shadow`, so no specificity fight is
-      // needed to win one. `filled`/`subtle`/`light` variants are untouched — scoped by attribute
-      // selector in the CSS, not here.
+      // either. Everything else — the per-variant depth and the disabled/reduced-motion grounding —
+      // lives in controls.module.css, where the variant scoping
+      // is an attribute selector: Mantine declares no `box-shadow` on either component at any
+      // specificity, so none of it needs a specificity fight. Nothing about depth is expressible in
+      // the flat `styles` objects here, which is the whole reason that file exists.
       //
       // Density coupling: mirrors Input's `--input-height` override above — Mantine's OWN
       // `--button-height-md`/`--ai-size` (via `--ai-size-md`) are global, non-retunable statics
@@ -679,7 +709,8 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // real attribute selectors ((0,2,0)) — Mantine's own rule wraps the same attribute in `:where()`
       // (0 specificity, landing at (0,1,0) total), so no `html[…]` prefix fight is needed here either.
       // Neither component sets a background of its own, so panel bg is added alongside the shadow —
-      // the same panel-bg + shadow-card + no-border triad as Card/Paper.
+      // the same panel-bg + depth + no-border triad as Card/Paper — on `shadow-raised`, the shared
+      // CONTROL depth, not Card/Paper's `shadow-card`: a selection card is something you click.
       CheckboxCard: CheckboxCard.extend({
         classNames: { card: controlsClasses.checkboxCardRoot },
       }),
@@ -1099,8 +1130,8 @@ function buildCssVariablesResolver(data: PaletteData): CSSVariablesResolver {
       '--mantine-color-body': `var(--vx-surface-bg, ${SURFACE.bg.light})`, // page background
       '--mantine-color-default': `var(--vx-surface-panel, ${SURFACE.panel.light})`, // cards / default controls
       '--mantine-color-default-hover': `var(--vx-surface-elevated, ${SURFACE.elevated.light})`,
-      // THE central lever for doctrine inversion #1 on CONTROLS (docs/DESIGN-SPEC.md §8): depth is
-      // `shadow-card`, never a hairline, for every `variant="default"` control — not just Card/Paper.
+      // THE central lever for doctrine inversion #1 on CONTROLS (docs/DESIGN-SPEC.md §8): depth is a
+      // shadow, never a hairline, for every `variant="default"` control — not just Card/Paper.
       // `defaultVariantColorsResolver`'s `variant === 'default'` branch reads this ONE var for every
       // component that uses it (Button, ActionIcon, Chip, CheckboxCard, RadioCard, …), so pointing it
       // at `transparent` kills the stock 1px hairline everywhere at once. `transparent`, not `border:

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

@@ -1,19 +1,19 @@
 /*
- * Active nav row = heavier weight + card depth, applied at the THEME level via `classNames` so it
- * reaches EVERY NavLink render path — including a consumer's router `<Link>` mounted through
- * `renderNavLink`, 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.
+ * 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.
  *
- * The row's background comes from `--nl-bg` (set in theme/index.ts, applies unconditionally via
- * Mantine's own `[data-active]` CSS) — `shadow-card` is added here because there's no `--nl-*` var
- * for depth.
+ * Applied at the THEME level via `classNames` so it reaches EVERY NavLink render path — including a
+ * consumer's router `<Link>` mounted through `renderNavLink`, 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.
  */
 .root[data-active],
 .root[aria-current='page'] {
   font-weight: 600;
-  box-shadow: var(--vx-shadow-card);
 }
 
 /*