basalt-ui 1.6.0 → 1.7.0

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/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":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAI9C;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,GACP,OAAO,GACP,OAAO,GACP,eAAe,GACf,UAAU,GACV,MAAM,GACN,OAAO,GACP,SAAS,GACT,KAAK,CAAA;AAET;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,eAAe,GAAG,eAAe,CAAA;AAExE;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,iBAAiB,GAAG,UAAU,GAAG,YAAY,GAAG,cAAc,CAAA;AAElF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IAChC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAA;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAA;CACzB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAA;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAA;CACrC,CAAA;AAID,KAAK,WAAW,GAAG;IACjB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAA;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAChD;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;QACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KACjC,CAAA;IACD;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;CAC1C,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACtC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAC5B,CAAA;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,WAAW,CAAA;AA8BpD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2S2B,CAAA;AAIhD;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,qBAMiB,CAAA;AAIxC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,sBAMiB,CAAA;AAIzC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,MAAM,CAAqC,CAAA;AAEnG;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzC,OAAO,CAET"}
+{"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

@@ -214,8 +214,10 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
 }
 
 /*
- * 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.
  */
@@ -240,7 +242,7 @@ html[data-mantine-color-scheme] .inputWrapper[data-variant='default']:not([data-
 
 /*
  * 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/vite.d.ts

@@ -25,6 +25,12 @@ export type BasaltViteOptions = {
     basaltSrc?: string;
     /** App version surfaced via the `__APP_VERSION__` define. Defaults to `0.0.0`. */
     version?: string;
+    /**
+     * Print a one-time notice when `basalt-ui init` has never been run in this project (no
+     * `.basalt/manifest.json` found at or above the cwd) — see `warnIfUnenforced`. Default `true`.
+     * Set `false` to adopt the components without the toolchain and stop being told about it.
+     */
+    enforcementNotice?: boolean;
 };
 export declare function basaltViteConfig(opts: BasaltViteOptions): UserConfig;
 export type BasaltAppOptions = {

package/dist/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAA6B,YAAY,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAI/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAyEpE;AAgBD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD,mGAAmG;IACnG,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAA;IAChE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,wFAAwF;IACxF,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3B,oFAAoF;IACpF,GAAG,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,qBAAqB,CAAA;KAAE,CAAA;IACvF,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClD,CAAA;AAuZD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAMzE"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAA6B,YAAY,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAI/E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AA6CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAgFpE;AAgBD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD,mGAAmG;IACnG,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAA;IAChE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mGAAmG;IACnG,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,wFAAwF;IACxF,KAAK,CAAC,EAAE,KAAK,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC3B,oFAAoF;IACpF,GAAG,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,qBAAqB,CAAA;KAAE,CAAA;IACvF,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClD,CAAA;AAuZD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAMzE"}

package/dist/vite.js

@@ -1,10 +1,30 @@
-import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { searchForWorkspaceRoot } from "vite";
 import { SURFACE } from "./tokens/palette.js";
 import { resolveColorMix } from "./vite-color-mix.js";
+const UNENFORCED_SEARCH_DEPTH = 3;
+let unenforcedNoticePrinted = false;
+function warnIfUnenforced(cwd) {
+  if (unenforcedNoticePrinted) return;
+  let dir = cwd;
+  for (let i = 0; i <= UNENFORCED_SEARCH_DEPTH; i++) {
+    if (existsSync(resolve(dir, ".basalt/manifest.json"))) return;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  unenforcedNoticePrinted = true;
+  console.warn(
+    "\n[basalt-ui] Installed, but `basalt-ui init` has never run here \u2014 no oxlint preset, no theme\n            guard, no agent rules. You have the components and none of the enforcement.\n            Fix: `bunx basalt-ui init`, then add `oxlint . && basalt-ui check-theme` as your\n            lint script. Silence: pass `enforcementNotice: false` to basaltViteConfig().\n"
+  );
+}
 function basaltViteConfig(opts) {
   const { port, host, allowedHosts, apiTarget, version = "0.0.0" } = opts;
   const basaltSrc = opts.basaltSrc ?? process.env["BASALT_LOCAL"];
+  if (opts.enforcementNotice !== false && basaltSrc === void 0) {
+    warnIfUnenforced(process.cwd());
+  }
   const config = {
     define: {
       __APP_VERSION__: JSON.stringify(process.env["BUILD_VERSION"] ?? version),

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.6.0
+# basalt-ui v1.7.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,11 +19,11 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.6.0
+Version: 1.7.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
-Description: BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard, EmptyState, SettingsSection/SettingsRow/DangerZone)
+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)
 Layer: mantine-coupled
 Rule: basalt-mantine
 OptionalPeers: react-markdown@^10.1.0, remark-gfm@^4.0.1, shiki@^4.3.0, beautiful-mermaid@^1.1.0

package/package.json

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

package/src/cli/index.ts

@@ -80,6 +80,15 @@ export type BasaltConfig = {
    * surface tokens. Default: `true` (ON). Set `false` to disable the `off-system-surface-var` check.
    */
   offSystemSurfaceVar?: boolean
+  /**
+   * Flag a SHADE-PINNED Mantine color — `c="yellow.7"`, `bg="blue.4"`,
+   * `var(--mantine-color-red-6)`. A pinned step is one fixed swatch in BOTH color schemes, so it
+   * cannot stay legible in either; route a verdict color through `VX.status.*` / `--vx-status-*`,
+   * or drop the index (`c="red"`) and let the theme resolve the shade per scheme. `gray-*`/`dark-*`
+   * in `var()` form belong to `off-system-surface-var` instead. Default: `true` (ON). Set `false`
+   * to disable the `mantine-shade-index` check.
+   */
+  mantineShadeIndex?: boolean
   /**
    * Flag raw lowercase JSX layout/surface elements (`div`/`span`/`section`/…) carrying an inline
    * `style={{}}` with a layout/surface property — steer to a Mantine layout primitive
@@ -348,6 +357,7 @@ export function checkTheme(cwd: string = process.cwd()): number {
     spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
     rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
     forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
+    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
     rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
     cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
     offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,
@@ -1827,6 +1837,7 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
     spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
     rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
     forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
+    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
     rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
     cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
     offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,

package/src/dashboard/index.ts

@@ -1,5 +1,5 @@
 export { DeltaBadge, type DeltaBadgeProps } from './delta-badge'
-export { StatCard, type StatCardProps } from './stat-card'
+export { StatCard, type StatCardProps, type StatCardTone } from './stat-card'
 export { EmptyState, type EmptyStateProps } from './empty-state'
 export {
   SettingsSection,

package/src/dashboard/stat-card.tsx

@@ -8,6 +8,15 @@
  * `src/dashboard` stays @visx-free — `sparkline` is a plain `ReactNode` slot, never a chart import
  * here. Pass a `LineSparkline`/`BarSparkline` from `basalt-ui/charts` at the call site.
  *
+ * `tone` marks the card as past a threshold with an accent rail down its leading edge. It exists
+ * because `value` is typed `string`: without it, a card whose number has crossed a threshold reads
+ * exactly as calm as one that hasn't, and the only way out from the consumer side is to wrap the
+ * card in a hand-rolled positioned `<Box>` — which is a second card idiom in the app, drawn by code
+ * the guard has no way to recognize as one. The rail is the largest signal available without
+ * touching the value's own type: full card height, overlaying the card's edge rather than adding to
+ * it, so layout is unchanged. `undefined` renders nothing at all — absence of a reading is neither a
+ * good one nor a bad one, and must never be tinted.
+ *
  * @example
  * import { StatCard } from 'basalt-ui'
  * import { LineSparkline } from 'basalt-ui/charts'
@@ -18,12 +27,28 @@
  *   delta={4.2}
  *   sparkline={<LineSparkline data={history} width={160} height={32} />}
  * />
+ *
+ * @example
+ * // Past a threshold — an accent rail down the leading edge, value untouched.
+ * <StatCard label="Downtime" value="29 min" tone="bad" />
  */
-import { Card, Group } from '@mantine/core'
+import { Box, Card, Group, VisuallyHidden } from '@mantine/core'
 import type { ReactNode } from 'react'
 import { DeltaBadge } from './delta-badge'
 import { VX } from '../tokens'
 
+/** A threshold verdict on the card's value. `undefined` is never tinted — see the module docblock. */
+export type StatCardTone = 'warn' | 'bad'
+
+/** The rail's width, in px. Wide enough to read as a deliberate mark at a glance, narrow enough
+ * that it cannot be mistaken for the card's own edge. */
+const TONE_RAIL_WIDTH = 3
+
+const TONE_LABEL: Record<StatCardTone, string> = {
+  warn: 'Past the warning threshold',
+  bad: 'Past the severe threshold',
+}
+
 export type StatCardProps = {
   /** Mono uppercase micro-label (docs/DESIGN-SPEC.md §3: 12.5px, tracking 0.06em, faint). */
   label: string
@@ -38,9 +63,20 @@ export type StatCardProps = {
   sparkline?: ReactNode
   /** Optional header-right slot (e.g. a ghost "..." menu trigger) — consumer-owned. */
   menu?: ReactNode
+  /** Threshold verdict — draws an accent rail down the card's leading edge and announces itself to
+   * assistive tech. Omit it for a reading that is fine, and for one that is absent. */
+  tone?: StatCardTone
 }
 
-export function StatCard({ label, value, delta, deltaPeriod, sparkline, menu }: StatCardProps) {
+export function StatCard({
+  label,
+  value,
+  delta,
+  deltaPeriod,
+  sparkline,
+  menu,
+  tone,
+}: StatCardProps) {
   return (
     <Card
       style={{
@@ -56,8 +92,31 @@ export function StatCard({ label, value, delta, deltaPeriod, sparkline, menu }:
         flexDirection: 'column',
         gap: 'var(--vx-space-stat-card-gap)',
         overflow: 'hidden',
+        // Anchors the tone rail. Set unconditionally so a card's stacking context does not change
+        // depending on whether it happens to have crossed a threshold this render.
+        position: 'relative',
       }}
+      data-tone={tone}
     >
+      {tone !== undefined && (
+        <>
+          {/* The rail is decoration; the verdict it encodes is real information, so it is also
+              stated in text for anyone who cannot see a 3px colour bar. Colour alone is never the
+              only carrier of a threshold. */}
+          <VisuallyHidden>{TONE_LABEL[tone]}</VisuallyHidden>
+          <Box
+            aria-hidden="true"
+            style={{
+              position: 'absolute',
+              insetBlock: 0,
+              insetInlineStart: 0,
+              width: TONE_RAIL_WIDTH,
+              background: tone === 'bad' ? VX.status.bad : VX.status.warn,
+            }}
+          />
+        </>
+      )}
+
       <Group justify="space-between" align="flex-start" wrap="nowrap" gap="xs">
         <span
           style={{

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
   /**