basalt-ui 1.6.0 → 1.8.0

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,21 @@ 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. Its promotion is **deferred to 1.9.0**:
+ * 1.8.0 shipped the same day as 1.7.0, so promoting on the next minor number would have given the
+ * consumer roughly no runway at all — which is the exact failure the grace minor exists to prevent,
+ * and the runway is measured in consumer upgrades, not in version numbers. Promote it by deleting
+ * the entry (its own commit).
  *
  * @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.9.0',
+}
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
 function severityOf(kind: GuardKind, cfg: GuardConfig): GuardSeverity {
@@ -561,7 +583,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 +634,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 +871,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/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/contrast.test.ts

@@ -24,7 +24,7 @@
 import { DEFAULT_THEME, getPrimaryShade, mergeMantineTheme } from '@mantine/core'
 import type { MantineTheme } from '@mantine/core'
 import { describe, expect, test } from 'bun:test'
-import { ACCENT, FILL, SURFACE } from '../tokens/palette'
+import { ACCENT, FILL, STATUS, SURFACE } from '../tokens/palette'
 import { baseTheme, cssVariablesResolver } from './index'
 
 const theme: MantineTheme = mergeMantineTheme(DEFAULT_THEME, baseTheme)
@@ -324,6 +324,23 @@ describe('doctrine inversion #1 reaches every default-variant CONTROL, not just
   })
 })
 
+describe("the StatCard tone rail reads against the panel it's drawn on", () => {
+  // The rail (`dashboard/stat-card.tsx`) is a 3px non-text mark carrying a threshold verdict, so it
+  // takes WCAG's 3:1 non-text floor against `--vx-surface-panel` — the card background it overlays,
+  // not the page — in BOTH schemes. Worth measuring rather than eyeballing for the same reason the
+  // fill band is: the status solids are DERIVED, so retuning the generator could sink one of them
+  // into the panel it sits on without anything else failing.
+  const TONES = ['good', 'warn', 'bad'] as const
+
+  for (const scheme of SCHEMES) {
+    for (const tone of TONES) {
+      test(`${tone} / ${scheme}`, () => {
+        expect(contrastRatio(STATUS[tone][scheme], SURFACE.panel[scheme])).toBeGreaterThanOrEqual(3)
+      })
+    }
+  }
+})
+
 describe('the shipped palette is the generator output at DEFAULT_DERIVE_CONFIG', () => {
   // A handful of exact hexes from `deriveTokens(DEFAULT_DERIVE_CONFIG)` (`tokens/derive.ts`) — the
   // shipped default identity (seed #0077bd, zinc, all four knobs at level 0). Drift here means

package/src/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/src/vite.ts

@@ -13,8 +13,13 @@
  *
  * NEVER reference `import.meta.env` here — this file is invoked inside the consumer's vite config
  * at config-evaluation time (plain Node), where only `process.env` exists.
+ *
+ * It also carries the enforcement notice (`warnIfUnenforced`): this is the one basalt seam that runs
+ * on every dev start and every build of a consumer app, so it is the only place that can tell an app
+ * it installed the components and skipped `basalt-ui init`.
  */
-import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
 import { searchForWorkspaceRoot } from 'vite'
 import type { HtmlTagDescriptor, Plugin, PluginOption, UserConfig } from 'vite'
 import { SURFACE } from './tokens/palette'
@@ -46,6 +51,55 @@ 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
+}
+
+/** How many directories up from `cwd` to look for `.basalt/manifest.json`. Three covers the common
+ * shapes: config at the app root, an app in `web/` or `apps/<name>/` under a repo root. */
+const UNENFORCED_SEARCH_DEPTH = 3
+
+/** Set once the notice has been printed, so a watch-mode restart doesn't reprint it every reload. */
+let unenforcedNoticePrinted = false
+
+/**
+ * Print one notice when basalt-ui is installed as a component library and nothing else.
+ *
+ * `basalt-ui init` is what places the oxlint preset, the theme-guard wiring, the lefthook stub and
+ * the agent rules. Skipping it leaves a consumer with the components and NONE of the enforcement —
+ * and, critically, no signal that this is the case. The failure is silent and cumulative: every
+ * hand-rolled `<Card withBorder radius="md" padding="lg">` renders perfectly, so the app drifts a
+ * card idiom at a time until someone looks at a screenshot and asks why the design system did
+ * nothing. The first real consumer reached seven such cards across six files that way.
+ *
+ * This is the only seam basalt owns that runs on every dev start and every build, which makes it
+ * the only place that can say so at the time it is still cheap to fix. It stays a notice, never an
+ * error: declining to adopt the toolchain is a legitimate choice, and a build that fails because a
+ * lint preset is absent would be a worse bug than the one this prevents.
+ */
+function warnIfUnenforced(cwd: string): void {
+  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
+  // oxlint-disable-next-line no-console -- a build-time notice has no other channel
+  console.warn(
+    '\n[basalt-ui] Installed, but `basalt-ui init` has never run here — 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',
+  )
 }
 
 export function basaltViteConfig(opts: BasaltViteOptions): UserConfig {
@@ -55,6 +109,13 @@ export function basaltViteConfig(opts: BasaltViteOptions): UserConfig {
   // on without editing its vite config. process.env (not import.meta.env) — this runs in Node.
   const basaltSrc = opts.basaltSrc ?? process.env['BASALT_LOCAL']
 
+  // Skipped under basaltSrc/BASALT_LOCAL: that path means basalt-ui itself is being developed from
+  // a sibling checkout (the playground, or a consumer debugging against local source), where the
+  // enforcement config lives in basalt's own repo and a manifest is not expected.
+  if (opts.enforcementNotice !== false && basaltSrc === undefined) {
+    warnIfUnenforced(process.cwd())
+  }
+
   const config: UserConfig = {
     define: {
       __APP_VERSION__: JSON.stringify(process.env['BUILD_VERSION'] ?? version),