basalt-ui 1.5.0 → 1.7.0

package/src/guard/check-source.test.ts

@@ -1,7 +1,7 @@
 /**
  * Unit tests for checkSource — the pure (text, relPath, cfg) → Finding[] core.
  *
- * Covers all 19 guard kinds. Co-located with the guard, excluded from tsc
+ * Covers all 20 guard kinds. Co-located with the guard, excluded from tsc
  * (tsconfig exclude: src/**\/*.test.ts), run via `bun test`.
  *
  * The walker/reporter half is covered by the integration test in
@@ -154,6 +154,68 @@ describe('off-identity-accent', () => {
   })
 })
 
+// ── 4b. mantine-shade-index ──────────────────────────────────────────────────
+
+describe('mantine-shade-index', () => {
+  it('flags a shade-pinned text color (c="yellow.7")', () => {
+    const f = find(`<Text c="yellow.7">stale</Text>`)
+    expect(kinds(f)).toContain('mantine-shade-index')
+  })
+
+  it('flags bg="blue.4" and color="red.6"', () => {
+    expect(kinds(find(`<Box bg="blue.4" />`))).toContain('mantine-shade-index')
+    expect(kinds(find(`<ThemeIcon color="red.6" />`))).toContain('mantine-shade-index')
+  })
+
+  it('flags the var() form for a non-surface hue', () => {
+    const f = find(`const a = { color: 'var(--mantine-color-yellow-7)' }`)
+    expect(kinds(f)).toContain('mantine-shade-index')
+  })
+
+  it('flags the var() form in a .css file too — unlike the prop-only kinds', () => {
+    const f = find(`.a { color: var(--mantine-color-red-6); }`, 'src/app.css')
+    expect(kinds(f)).toContain('mantine-shade-index')
+  })
+
+  // The two kinds partition the space: gray/dark var() steps are surface color and belong to
+  // off-system-surface-var, so a single violation must never report under both.
+  it('leaves gray/dark var() steps to off-system-surface-var', () => {
+    const f = find(`const a = { background: 'var(--mantine-color-gray-3)' }`)
+    expect(kinds(f)).toContain('off-system-surface-var')
+    expect(kinds(f)).not.toContain('mantine-shade-index')
+  })
+
+  it('does NOT flag a bare status hue — it resolves per scheme, which is the point', () => {
+    expect(kinds(find(`<Text c="red">down</Text>`))).not.toContain('mantine-shade-index')
+    expect(kinds(find(`<ThemeIcon color="green" />`))).not.toContain('mantine-shade-index')
+  })
+
+  it('does NOT flag c="dimmed" or a token ref', () => {
+    expect(kinds(find(`<Text c="dimmed">age</Text>`))).not.toContain('mantine-shade-index')
+    expect(kinds(find(`<Text c={VX.status.warn}>age</Text>`))).not.toContain('mantine-shade-index')
+  })
+
+  it('does NOT flag a theme-allow line', () => {
+    const f = find(`<Text c="yellow.7" /> // theme-allow: design exception`)
+    expect(kinds(f)).not.toContain('mantine-shade-index')
+  })
+
+  it('is disabled by the mantineShadeIndex knob', () => {
+    const f = checkSource(`<Text c="yellow.7" />`, PATH, {
+      ...DEFAULT_GUARD_CONFIG,
+      mantineShadeIndex: false,
+    })
+    expect(kinds(f)).not.toContain('mantine-shade-index')
+  })
+
+  // The grace-minor doctrine (package CLAUDE.md): a kind that rejects previously-passing code
+  // lands as `warn` for one minor. Deleting its GRACE_PERIOD_KINDS entry in 1.7.0 flips this.
+  it('lands as a warning, not an error, for its grace minor', () => {
+    const f = find(`<Text c="yellow.7" />`)
+    expect(f.find((x) => x.kind === 'mantine-shade-index')?.severity).toBe('warn')
+  })
+})
+
 // ── 5. raw-spacing ───────────────────────────────────────────────────────────
 
 describe('raw-spacing', () => {

package/src/guard/index.ts

@@ -58,6 +58,20 @@ const WITH_BORDER_PROP = /\bwithBorder\b(?!\s*=\s*\{\s*false\s*\})/
 // Raw Mantine ramp step used for surface color — gray/dark + a step digit.
 const OFF_SYSTEM_SURFACE_VAR = /var\(--mantine-color-(gray|dark)-\d/g
 
+// A SHADE-PINNED Mantine color: the dotted JSX form (`c="yellow.7"`) or the var() form
+// (`var(--mantine-color-red-6)`). Both name one fixed swatch that does NOT flip across color
+// schemes — see the `mantineShadeIndex` doc in guard/types.ts for why the bare hue name is fine and
+// the pinned step is not.
+//
+// The var() half deliberately excludes gray-/dark-, which `off-system-surface-var` already owns, so
+// a surface violation reports once under one kind rather than twice under two.
+//
+// The JSX half is prop-shaped (`c="yellow.7"` needs the `=`), which CSS text has no syntax for, so
+// it cannot fire in a `.css` file; the var() half is a real violation in CSS and is meant to fire
+// there. That split is why this kind, unlike its prop-only neighbours, carries no `appliesTo` gate.
+const MANTINE_SHADE_INDEX =
+  /\b(?:color|c|bg|backgroundColor|borderColor)\s*=\s*\{?\s*['"][a-z]+\.\d\b|var\(--mantine-color-(?!gray-|dark-)[a-z]+-\d/g
+
 // Raw lowercase JSX layout/surface element with inline style and layout/surface prop — line-scoped.
 const RAW_HTML_TAG = /<(?:div|span|section|header|nav|footer|aside|main|article|ul|ol)\b/
 const INLINE_STYLE = /style=\{\{/
@@ -241,6 +255,7 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
   spacingSteps: DEFAULT_SPACING_STEPS,
   rawRadius: true,
   forbiddenAccents: DEFAULT_FORBIDDEN_ACCENTS,
+  mantineShadeIndex: true,
   rawSurface: true,
   cardWithBorder: true,
   offSystemSurfaceVar: true,
@@ -266,14 +281,18 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * someone remembering. Adding a kind here is part of shipping it; removing the entry IS the
  * promotion, and belongs in its own commit so the changelog says enforcement got stricter.
  *
- * Empty today: every shipped kind is past its grace period. The next new kind goes here first.
+ * `mantine-shade-index` landed in 1.7.0 and is the sole entry — it rejects `c="yellow.7"`, which
+ * previously passed, and the one real consumer has several. Promote it in 1.8.0 by deleting the
+ * entry.
  *
  * @example
  * const GRACE: Partial<Record<GuardKind, string>> = {
  *   'raw-font-family': 'introduced 1.4.0 — promote to error in 1.5.0',
  * }
  */
-const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {}
+const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {
+  'mantine-shade-index': 'introduced 1.7.0 — promote to error in 1.8.0',
+}
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
 function severityOf(kind: GuardKind, cfg: GuardConfig): GuardSeverity {
@@ -561,7 +580,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 19 guard kinds. The triad test asserts
+ * The closed registry of all 20 guard kinds. The triad test asserts
  * `surface.guardKinds ⊆ keyof GUARD_RULES` at runtime.
  *
  * raw-surface, raw-html-layout, and sub-16-input-font are handled inline in checkSource
@@ -612,6 +631,13 @@ export const GUARD_RULES = {
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message: 'For an off-identity accent use blue/gray or a status hue (red/green/orange/yellow).',
   },
+  'mantine-shade-index': {
+    kind: 'mantine-shade-index',
+    pattern: MANTINE_SHADE_INDEX,
+    enabled: (cfg: GuardConfig) => cfg.mantineShadeIndex,
+    message:
+      'Shade-pinned Mantine color — one fixed swatch in BOTH color schemes, so it cannot stay legible in either. Use VX.status.* / --vx-status-* for a verdict color, or the bare hue name (c="red") to let the theme resolve the shade per scheme.',
+  },
   'raw-spacing': {
     kind: 'raw-spacing',
     pattern: (cfg: GuardConfig) =>
@@ -842,6 +868,16 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       }
     }
 
+    // mantine-shade-index — the sibling of off-system-surface-var above, partitioned by hue: that
+    // kind owns gray/dark (surface color), this one owns every other shade-pinned step (verdict and
+    // accent color). Both halves of the pattern (JSX prop + var()) run in every file type; see the
+    // pattern's own comment for why this kind carries no appliesTo gate.
+    if (GUARD_RULES['mantine-shade-index'].enabled!(cfg)) {
+      for (const m of line.matchAll(GUARD_RULES['mantine-shade-index'].pattern as RegExp)) {
+        findings.push({ relPath, line: i + 1, token: m[0], kind: 'mantine-shade-index' })
+      }
+    }
+
     // raw-html-layout: 3-condition conjunction on the same line — gated via GUARD_RULES entry.
     if (
       GUARD_RULES['raw-html-layout'].enabled!(cfg) &&

package/src/guard/types.ts

@@ -1,17 +1,18 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 19 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 20 violation kinds the theme guard can emit.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 19 theme-guard violation kinds. */
+/** The 20 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
   | 'localstorage-theme'
   | 'off-identity-accent'
+  | 'mantine-shade-index'
   | 'raw-spacing'
   | 'raw-radius'
   | 'raw-surface'
@@ -82,6 +83,21 @@ export type GuardConfig = {
   readonly rawRadius: boolean
   /** Off-identity Mantine accent families forbidden as chrome accents. */
   readonly forbiddenAccents: readonly string[]
+  /**
+   * Flag a SHADE-PINNED Mantine color — `c="yellow.7"`, `bg="blue.4"`, `var(--mantine-color-red-6)`.
+   *
+   * This is the sibling of `off-identity-accent`, and the two are deliberately disjoint. That kind
+   * polices WHICH hue you reach for and permits the bare status names (`c="red"`, `color="green"`)
+   * on purpose: they resolve through the theme, so they flip correctly across color schemes. This
+   * kind polices the SHADE INDEX, which does not — a pinned step is one fixed swatch in both
+   * schemes, so a `yellow.7` legible on the dark page is the one that fails contrast on the light
+   * one. Status color belongs on `VX.status.*` (`--vx-status-warn|bad|good|…`), which is emitted per
+   * scheme.
+   *
+   * `gray-*`/`dark-*` in `var()` form are excluded here because `off-system-surface-var` already
+   * owns them (surface color, its own message). Default true.
+   */
+  readonly mantineShadeIndex: boolean
   /** Flag ad-hoc inline surface styling (border/borderRadius/boxShadow literals). Default true. */
   readonly rawSurface: boolean
   /**

package/src/index.ts

@@ -76,6 +76,7 @@ export {
   type DeltaBadgeProps,
   StatCard,
   type StatCardProps,
+  type StatCardTone,
   EmptyState,
   type EmptyStateProps,
   SettingsSection,

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/surfaces.ts

@@ -186,9 +186,15 @@ export const SURFACES = {
     layer: 'mantine-coupled',
     rule: 'mantine',
     skill: ['basalt-app', 'basalt-design'],
-    guardKinds: ['raw-motion-value', 'card-with-border', 'raw-form-control', 'sub-16-input-font'],
+    guardKinds: [
+      'raw-motion-value',
+      'card-with-border',
+      'raw-form-control',
+      'sub-16-input-font',
+      'mantine-shade-index',
+    ],
     description:
-      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard, EmptyState, SettingsSection/SettingsRow/DangerZone)',
+      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)',
     optionalPeers: ['react-markdown', 'remark-gfm', 'shiki', 'beautiful-mermaid'],
     forbiddenImports: [], // the no-charts/tokens-reexport invariant is comment-only today; Phase-4 plugin
   },

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,32 +62,162 @@ 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;
+  }
 }
 
 /*
- * CheckboxCard / RadioCard (`withBorder`, the default): panel bg + `shadow-card`, no border — the
- * same triad as Card/Paper. Mantine's own border-color rule wraps `[data-with-border]` in
+ * CheckboxCard / RadioCard (`withBorder`, the default): panel bg + depth, no border — the same
+ * triad as Card/Paper, but on `shadow-raised`, since a selection card is something you click (the
+ * control-vs-panel line, see the header above). Mantine's own border-color rule wraps
+ * `[data-with-border]` in
  * `:where()` (0 specificity), so a plain class + real attribute selector ((0,2,0)) already wins;
  * no `html[…]` prefix fight needed, same reasoning as Button/ActionIcon above.
  */
@@ -84,7 +225,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,12 +237,12 @@ 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);
 }
 
 /*
  * Focus = accent border (via --input-bd-focus above) + a subtle accent ring layered over the
- * resting `--field-depth`, so the field keeps its shadow-card depth while focused.
+ * resting `--field-depth`, so the field keeps its `shadow-raised` depth while focused.
  */
 .input:focus,
 .input:focus-within {