basalt-ui 1.5.0 → 1.7.0

package/dist/guard/index.d.ts

@@ -9,7 +9,7 @@ export type { Finding, GuardConfig, GuardKind, GuardSeverity };
 /** Shared default config — CLI and tests import this to avoid duplication. */
 export declare const DEFAULT_GUARD_CONFIG: GuardConfig;
 /**
- * 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
@@ -51,6 +51,12 @@ export declare const GUARD_RULES: {
         readonly appliesTo: (relPath: string) => boolean;
         readonly message: "For an off-identity accent use blue/gray or a status hue (red/green/orange/yellow).";
     };
+    readonly 'mantine-shade-index': {
+        readonly kind: "mantine-shade-index";
+        readonly pattern: RegExp;
+        readonly enabled: (cfg: GuardConfig) => boolean;
+        readonly 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.";
+    };
     readonly 'raw-spacing': {
         readonly kind: "raw-spacing";
         readonly pattern: (cfg: GuardConfig) => RegExp;

package/dist/guard/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE7E,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;AAsO9D,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAmBlC,CAAA;AAgTD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;gCA0BL,WAAW;;;;;;gCAaX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAQX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAMX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;CAOmB,CAAA;AAUjD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,EAAE,CAiPtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE7E,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;AAoP9D,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAoBlC,CAAA;AAoTD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;gCA0BL,WAAW;;;;;;;gCAcX,WAAW;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAQX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAMX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;CAOmB,CAAA;AAUjD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,EAAE,CA2PtF"}

package/dist/guard/index.js

@@ -13,6 +13,7 @@ const SURFACE_SHADOW = /\bboxShadow\s*:\s*(?!['"`]?[^'"`]*(?:var\(|\$\{))['"`][^
 const CARD_SURFACE_TAG = /<(?:Card|Paper)(?![\w.])(?:=>|[^>])*?>/g;
 const WITH_BORDER_PROP = /\bwithBorder\b(?!\s*=\s*\{\s*false\s*\})/;
 const OFF_SYSTEM_SURFACE_VAR = /var\(--mantine-color-(gray|dark)-\d/g;
+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;
 const RAW_HTML_TAG = /<(?:div|span|section|header|nav|footer|aside|main|article|ul|ol)\b/;
 const INLINE_STYLE = /style=\{\{/;
 const LAYOUT_SURFACE_PROP = /\b(?:display|padding|margin|gap|flex|grid|border|background|width|height)\b/;
@@ -59,6 +60,7 @@ const DEFAULT_GUARD_CONFIG = {
   spacingSteps: DEFAULT_SPACING_STEPS,
   rawRadius: true,
   forbiddenAccents: DEFAULT_FORBIDDEN_ACCENTS,
+  mantineShadeIndex: true,
   rawSurface: true,
   cardWithBorder: true,
   offSystemSurfaceVar: true,
@@ -75,7 +77,9 @@ const DEFAULT_GUARD_CONFIG = {
   exemptRules: {},
   severity: {}
 };
-const GRACE_PERIOD_KINDS = {};
+const GRACE_PERIOD_KINDS = {
+  "mantine-shade-index": "introduced 1.7.0 \u2014 promote to error in 1.8.0"
+};
 function severityOf(kind, cfg) {
   return cfg.severity?.[kind] ?? (kind in GRACE_PERIOD_KINDS ? "warn" : "error");
 }
@@ -283,6 +287,12 @@ 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) => cfg.mantineShadeIndex,
+    message: 'Shade-pinned Mantine color \u2014 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) => new RegExp(
@@ -469,6 +479,11 @@ function checkSource(text, relPath, cfg) {
         findings.push({ relPath, line: i + 1, token: m[0], kind: "off-system-surface-var" });
       }
     }
+    if (GUARD_RULES["mantine-shade-index"].enabled(cfg)) {
+      for (const m of line.matchAll(GUARD_RULES["mantine-shade-index"].pattern)) {
+        findings.push({ relPath, line: i + 1, token: m[0], kind: "mantine-shade-index" });
+      }
+    }
     if (GUARD_RULES["raw-html-layout"].enabled(cfg) && ruleApplies("raw-html-layout", relPath) && RAW_HTML_TAG.test(line) && INLINE_STYLE.test(line) && LAYOUT_SURFACE_PROP.test(line)) {
       findings.push({ relPath, line: i + 1, token: "<raw-html style>", kind: "raw-html-layout" });
     }

package/dist/guard/types.d.ts

@@ -1,12 +1,12 @@
 /**
  * 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. */
-export type GuardKind = 'raw-hex' | 'raw-color-fn' | 'localstorage-theme' | 'off-identity-accent' | 'raw-spacing' | 'raw-radius' | 'raw-surface' | 'card-with-border' | 'off-system-surface-var' | 'raw-html-layout' | 'inline-spacing' | 'inline-display' | 'raw-visx-axis' | 'raw-motion-value' | 'unframed-chart' | 'chart-missing-aria-label' | 'raw-form-control' | 'sub-16-input-font' | 'raw-font-family';
+/** 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' | 'card-with-border' | 'off-system-surface-var' | 'raw-html-layout' | 'inline-spacing' | 'inline-display' | 'raw-visx-axis' | 'raw-motion-value' | 'unframed-chart' | 'chart-missing-aria-label' | 'raw-form-control' | 'sub-16-input-font' | 'raw-font-family';
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.
  *
@@ -59,6 +59,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/dist/guard/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guard/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,cAAc,GACd,oBAAoB,GACpB,qBAAqB,GACrB,aAAa,GACb,YAAY,GACZ,aAAa,GACb,kBAAkB,GAClB,wBAAwB,GACxB,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,GAClB,gBAAgB,GAChB,0BAA0B,GAC1B,kBAAkB,GAClB,mBAAmB,GACnB,iBAAiB,CAAA;AAErB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAA;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;CACjC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,wGAAwG;IACxG,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,2GAA2G;IAC3G,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC,sGAAsG;IACtG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAA;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;IAC1D;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAA;CAC7D,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guard/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,cAAc,GACd,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,GACrB,aAAa,GACb,YAAY,GACZ,aAAa,GACb,kBAAkB,GAClB,wBAAwB,GACxB,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,GAClB,gBAAgB,GAChB,0BAA0B,GAC1B,kBAAkB,GAClB,mBAAmB,GACnB,iBAAiB,CAAA;AAErB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAA;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;CACjC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,wGAAwG;IACxG,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;IACnC,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,2GAA2G;IAC3G,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC,sGAAsG;IACtG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAA;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;IAC1D;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAA;CAC7D,CAAA"}

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './motion/i
 export { BasaltShell, NavCountBadge, AppSidebar, SidebarSearch, type SidebarSearchConfig, SidebarAccount, MobileNav, AppBreadcrumbs, type BreadcrumbLinkRenderer, PageHeaderProvider, PageActions, PageActionsOutlet, type SidebarSection, type SidebarItem, type BasaltShellProps, type BrandConfig, type SettingsMenuItem, type AppSidebarProps, type MobileNavItem, type MobileNavSection, type NavLinkRenderer, type MobileNavLinkRenderer, type AccountBadgeTone, type BasaltIdentity, type BasaltRole, type BasaltPlan, type AccountMenuItem, type BasaltAccountState, type BasaltAccountActions, type BasaltAccountProps, } from './shell/index.js';
 export { type BasaltRegister, type Slot, type Series, type SeriesKey, type AsyncState, assertNever, type StandardSchemaV1, } from './register.js';
 export { createPersistedState, type PersistedStateOptions, useOnlineStatus, readPersistedValue, } from './state.js';
-export { DeltaBadge, type DeltaBadgeProps, StatCard, type StatCardProps, EmptyState, type EmptyStateProps, SettingsSection, type SettingsSectionProps, SettingsRow, type SettingsRowProps, DangerZone, type DangerZoneProps, } from './dashboard/index.js';
+export { DeltaBadge, type DeltaBadgeProps, StatCard, type StatCardProps, type StatCardTone, EmptyState, type EmptyStateProps, SettingsSection, type SettingsSectionProps, SettingsRow, type SettingsRowProps, DangerZone, type DangerZoneProps, } from './dashboard/index.js';
 export { ConnectivityProvider, ConnectivityIndicator, useConnectivity } from './connectivity/index.js';
 export type { ConnectivityStatus, ConnectivitySnapshot, ConnectivityProviderProps, ConnectivityOverride, } from './connectivity/index.js';
 export type { SurfaceSpec, RuleName, SkillName } from './surfaces.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,mBAAmB,EACnB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC5E,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAC1E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/E,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,KAAK,mBAAmB,EACxB,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,sBAAsB,EAC3B,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,SAAS,CAAA;AAKhB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,UAAU,EACf,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,eAAe,EACf,kBAAkB,GACnB,MAAM,SAAS,CAAA;AAGhB,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,QAAQ,EACR,KAAK,aAAa,EAClB,UAAU,EACV,KAAK,eAAe,EACpB,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAC7F,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,gBAAgB,CAAA;AAKvB,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAClE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAU9C,OAAO,EACL,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,qBAAqB,GACtB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAClF,YAAY,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,SAAS,EACT,cAAc,GACf,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,mBAAmB,EACnB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC5E,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AAC1E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/E,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,KAAK,mBAAmB,EACxB,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,sBAAsB,EAC3B,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,SAAS,CAAA;AAKhB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,UAAU,EACf,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,eAAe,EACf,kBAAkB,GACnB,MAAM,SAAS,CAAA;AAGhB,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,QAAQ,EACR,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,UAAU,EACV,KAAK,eAAe,EACpB,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAC7F,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,gBAAgB,CAAA;AAKvB,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAClE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAU9C,OAAO,EACL,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,qBAAqB,GACtB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAClF,YAAY,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,SAAS,EACT,cAAc,GACf,MAAM,SAAS,CAAA"}

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

@@ -130,8 +130,8 @@ export declare const SURFACES: {
         readonly layer: "mantine-coupled";
         readonly rule: "mantine";
         readonly skill: readonly ["basalt-app", "basalt-design"];
-        readonly guardKinds: readonly ["raw-motion-value", "card-with-border", "raw-form-control", "sub-16-input-font"];
-        readonly description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard, EmptyState, SettingsSection/SettingsRow/DangerZone)";
+        readonly guardKinds: readonly ["raw-motion-value", "card-with-border", "raw-form-control", "sub-16-input-font", "mantine-shade-index"];
+        readonly description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)";
         readonly optionalPeers: readonly ["react-markdown", "remark-gfm", "shiki", "beautiful-mermaid"];
         readonly forbiddenImports: readonly [];
     };

package/dist/surfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surfaces.d.ts","sourceRoot":"","sources":["../src/surfaces.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"surfaces.d.ts","sourceRoot":"","sources":["../src/surfaces.ts"],"names":[],"mappings":"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"}

package/dist/surfaces.js

@@ -22,8 +22,14 @@ 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"],
-    description: "BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard, EmptyState, SettingsSection/SettingsRow/DangerZone)",
+    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 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/dist/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 {

package/dist/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAOlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AASvD,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AAm3BD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAmJ/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CA+BtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AA+DA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAOlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AASvD,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AAk5BD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAmJ/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,oBAAoB,EAChC,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CA+BtB"}