basalt-ui 1.7.0 → 1.9.0

package/src/cli/index.ts

@@ -675,8 +675,105 @@ function resolvePeerFlags(cwd: string, flags: ScaffoldFlags): PeerFlags {
   }
 }
 
+/**
+ * Where the seed engine is running relative to the consumer's git repo — decides which
+ * repo-root-shaped seeds are safe to write. `init`/`sync` compute it once per run via
+ * `resolvePlacement` and print the matching skip notices themselves; `managedFiles` only reads it.
+ */
+type PlacementFlags = {
+  /** True when the package directory IS the detected repo root, or no `.git` exists anywhere above
+   *  it (a consumer not using git keeps today's behaviour exactly). False means the package lives
+   *  in a subdirectory of the repo (a monorepo's `web/`, say) — lefthook and GitHub Actions both
+   *  only read config at the repo root, so seeding either one there is worse than not seeding at
+   *  all. */
+  isPackageRepoRoot: boolean
+  /** Absolute path of the detected repo root. Meaningful only when `isPackageRepoRoot` is false —
+   *  otherwise it equals the package dir and is never read. */
+  repoRoot: string
+  /** Absolute path of a `query-client.ts` already present elsewhere under the package's `src/` (the
+   *  consumer relocated it — e.g. to `src/lib/query-client.ts`), or null. The seed's OWN
+   *  destination is deliberately excluded here — that exact-path case is handled by the ordinary
+   *  skip-if-exists logic every seed file already goes through, unchanged. */
+  relocatedQueryClient: string | null
+}
+
+/** The default placement — today's single-package-at-repo-root behaviour, unconditionally. */
+const ROOT_PLACEMENT: PlacementFlags = {
+  isPackageRepoRoot: true,
+  repoRoot: '',
+  relocatedQueryClient: null,
+}
+
+/**
+ * Walks up from `dir` looking for a `.git` entry — ordinarily a directory, but a git worktree or
+ * submodule points it at a FILE instead, and both still mean "this directory is the repo root".
+ * Stops at the filesystem root. Returns `dir` itself when no `.git` is found anywhere, so a
+ * consumer not using git falls back to today's behaviour exactly.
+ */
+function findRepoRoot(dir: string): string {
+  let current = dir
+  for (;;) {
+    if (existsSync(resolve(current, '.git'))) return current
+    const parent = dirname(current)
+    if (parent === current) return dir
+    current = parent
+  }
+}
+
+/**
+ * First path under `dir` (recursive) whose basename is `filename`, or null. Skips dependency/build
+ * dirs, mirroring `walkSourceFiles`'s scoping.
+ */
+function findFileNamed(dir: string, filename: string): string | null {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return null
+  }
+  for (const name of entries) {
+    if (name === 'node_modules' || name === '.git' || name === 'dist') continue
+    const abs = resolve(dir, name)
+    let isDir: boolean
+    try {
+      isDir = statSync(abs).isDirectory()
+    } catch {
+      continue
+    }
+    if (isDir) {
+      const found = findFileNamed(abs, filename)
+      if (found !== null) return found
+    } else if (name === filename) {
+      return abs
+    }
+  }
+  return null
+}
+
+/**
+ * Absolute path of a `query-client.ts` living elsewhere under the package's `src/`, or null. The
+ * seed's own destination is excluded — reseeding on top of a RELOCATED client (the failure this
+ * exists to prevent) is a different case from the seed's own path already being occupied, which the
+ * ordinary skip-if-exists logic handles unchanged.
+ */
+function findRelocatedQueryClient(cwd: string): string | null {
+  const seedAbs = resolve(cwd, 'src/query-client.ts')
+  const found = findFileNamed(resolve(cwd, 'src'), 'query-client.ts')
+  return found !== null && found !== seedAbs ? found : null
+}
+
+/** Resolve a run's placement flags once, from the consumer cwd. */
+function resolvePlacement(cwd: string): PlacementFlags {
+  const repoRoot = findRepoRoot(cwd)
+  return {
+    isPackageRepoRoot: repoRoot === cwd,
+    repoRoot,
+    relocatedQueryClient: findRelocatedQueryClient(cwd),
+  }
+}
+
 /** The full managed-file manifest. Stable, declarative — the single source of truth for init/sync. */
-function managedFiles(peers: PeerFlags): ManagedFile[] {
+function managedFiles(peers: PeerFlags, placement: PlacementFlags = ROOT_PLACEMENT): ManagedFile[] {
   // ── managed: exactly what Claude reads ──────────────────────────────────────
   const rules: ManagedFile[] = RULE_NAMES.map((name) => ({
     dest: `.claude/rules/basalt-${name}.md`,
@@ -804,10 +901,16 @@ function managedFiles(peers: PeerFlags): ManagedFile[] {
   // type) — both are documented optional peers, so seeding either scaffold without its peer(s)
   // installed would ship a file with an unresolved import.
   const scaffolds: ManagedFile[] = []
-  if (peers.hasQuery) scaffolds.push(queryClient)
+  if (peers.hasQuery && placement.relocatedQueryClient === null) scaffolds.push(queryClient)
   if (peers.hasRouter && peers.hasQuery) scaffolds.push(rootRoute)
 
-  return [...rules, ...skills, claudeBlock, design, oxfmt, lefthook, ci, oxlintrc, ...scaffolds]
+  // lefthook.yml / .github/workflows/check.yml are repo-root-shaped: lefthook and GitHub Actions
+  // only ever read config at the repo root, so a package living in a subdirectory (a monorepo's
+  // `web/`) skips both rather than relocating them — the repo root very often already has its own
+  // lefthook/CI config, and writing over or beside it is worse than not writing at all.
+  const rootTooling: ManagedFile[] = placement.isPackageRepoRoot ? [lefthook, ci] : []
+
+  return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
 }
 
 type Manifest = {
@@ -1041,7 +1144,8 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   const manifest = readManifest(cwd)
   migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
   const peers = resolvePeerFlags(cwd, scaffoldFlags)
-  const files = managedFiles(peers)
+  const placement = resolvePlacement(cwd)
+  const files = managedFiles(peers, placement)
 
   let written = 0
   let skipped = 0
@@ -1082,6 +1186,28 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(', ')}`,
     )
   }
+  // lefthook.yml / .github/workflows/check.yml are repo-root-shaped — neither lefthook nor GitHub
+  // Actions reads config from anywhere but the repo root, so a package living in a subdirectory
+  // skips both rather than relocating them into a spot nothing reads.
+  if (!placement.isPackageRepoRoot) {
+    console.log(
+      `basalt-ui init: skipped lefthook.yml (this package is not the repo root — repo root ` +
+        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
+        'node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.',
+    )
+    console.log(
+      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root — ` +
+        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
+        'repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.',
+    )
+  }
+  if (placement.relocatedQueryClient !== null) {
+    console.log(
+      `basalt-ui init: skipped src/query-client.ts (found an existing query client at ` +
+        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
+        're-seeding at the original path.',
+    )
+  }
   // query-client.ts / __root.tsx reference the optional TanStack peers directly — seeding them
   // without the peer installed would ship an unresolved import. Hint how to opt in instead.
   if (!peers.hasQuery) {
@@ -1132,7 +1258,8 @@ export function sync(opts: SyncOptions = {}, cwd: string = process.cwd()): numbe
   const manifest = readManifest(cwd)
   if (!opts.check) migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
   const peers = resolvePeerFlags(cwd, {})
-  const files = managedFiles(peers)
+  const placement = resolvePlacement(cwd)
+  const files = managedFiles(peers, placement)
 
   let updated = 0
   let recreated = 0
@@ -1182,6 +1309,28 @@ export function sync(opts: SyncOptions = {}, cwd: string = process.cwd()): numbe
     else updated++
   }
 
+  // Placement notices — informational, never affect the exit code (a skipped tooling seed or a
+  // relocated scaffold is a legitimate consumer choice, not a sync failure).
+  if (!placement.isPackageRepoRoot) {
+    console.log(
+      `basalt-ui sync: skipped lefthook.yml (this package is not the repo root — repo root ` +
+        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
+        'node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.',
+    )
+    console.log(
+      `basalt-ui sync: skipped .github/workflows/check.yml (this package is not the repo root — ` +
+        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
+        'repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.',
+    )
+  }
+  if (placement.relocatedQueryClient !== null) {
+    console.log(
+      `basalt-ui sync: skipped src/query-client.ts (found an existing query client at ` +
+        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
+        're-seeding at the original path.',
+    )
+  }
+
   if (opts.check) {
     if (driftLines.length > 0) {
       console.error('basalt-ui sync --check: locally-drifted managed files:')

package/src/cli/placement-engine.test.ts

@@ -81,6 +81,25 @@ function silenced<T>(fn: () => T): T {
   }
 }
 
+/** Captures both console.log and console.error — init()/sync() interleave the two. */
+function capture(fn: () => number): { code: number; log: string } {
+  const originalLog = console.log
+  const originalError = console.error
+  let log = ''
+  console.log = (...args: unknown[]) => {
+    log += `${args.join(' ')}\n`
+  }
+  console.error = (...args: unknown[]) => {
+    log += `${args.join(' ')}\n`
+  }
+  try {
+    return { code: fn(), log }
+  } finally {
+    console.log = originalLog
+    console.error = originalError
+  }
+}
+
 describe('managed vs seed placement', () => {
   it('init places rules AND skills as managed files, plus the toolchain seeds', () => {
     silenced(() => init(dir))
@@ -192,3 +211,88 @@ describe('--check performs zero writes', () => {
     expect(snapshotDir()).toEqual(drifted)
   })
 })
+
+// A real consumer's repo root (an API + collector) had its dashboard package in `web/`, one level
+// below the repo `.git`. `init`/`sync` used to seed lefthook.yml, .github/workflows/check.yml, and
+// src/query-client.ts relative to the PACKAGE dir regardless — none of which anything reads from
+// there, and re-created on every sync even after the consumer relocated them by hand.
+describe('repo-root-shaped seeds (lefthook.yml / check.yml / query-client.ts)', () => {
+  it('package IS the repo root (a bare .git dir present): writes lefthook.yml and check.yml, unchanged', () => {
+    mkdirSync(join(dir, '.git'))
+    silenced(() => init(dir))
+    expect(existsSync(join(dir, 'lefthook.yml'))).toBe(true)
+    expect(existsSync(join(dir, '.github/workflows/check.yml'))).toBe(true)
+  })
+
+  it('no .git anywhere in the tree: falls back to writing lefthook.yml and check.yml, unchanged', () => {
+    silenced(() => init(dir))
+    expect(existsSync(join(dir, 'lefthook.yml'))).toBe(true)
+    expect(existsSync(join(dir, '.github/workflows/check.yml'))).toBe(true)
+  })
+
+  it('package lives in a subdirectory of the repo: init skips both tooling seeds, notes the repo root, exits 0', () => {
+    mkdirSync(join(dir, '.git'))
+    const webDir = join(dir, 'web')
+    mkdirSync(webDir, { recursive: true })
+    writeFileSync(join(webDir, 'package.json'), JSON.stringify({ name: 'web' }))
+
+    const { code, log } = capture(() => init(webDir))
+
+    expect(code).toBe(0)
+    expect(existsSync(join(webDir, 'lefthook.yml'))).toBe(false)
+    expect(existsSync(join(webDir, '.github/workflows/check.yml'))).toBe(false)
+    expect(log).toContain('lefthook.yml')
+    expect(log).toContain('.github/workflows/check.yml')
+    expect(log).toContain(dir)
+    // Repo-root-shaped seeds are skipped; everything else still seeds normally.
+    expect(existsSync(join(webDir, 'DESIGN.md'))).toBe(true)
+    expect(existsSync(join(webDir, '.oxlintrc.json'))).toBe(true)
+  })
+
+  it('package lives in a subdirectory of the repo: sync ALSO skips both tooling seeds and notes it, exits 0', () => {
+    mkdirSync(join(dir, '.git'))
+    const webDir = join(dir, 'web')
+    mkdirSync(webDir, { recursive: true })
+    writeFileSync(join(webDir, 'package.json'), JSON.stringify({ name: 'web' }))
+    silenced(() => init(webDir))
+
+    const { code, log } = capture(() => sync({}, webDir))
+
+    expect(code).toBe(0)
+    expect(existsSync(join(webDir, 'lefthook.yml'))).toBe(false)
+    expect(existsSync(join(webDir, '.github/workflows/check.yml'))).toBe(false)
+    expect(log).toContain('lefthook.yml')
+  })
+
+  it('an existing query-client.ts elsewhere under src/ suppresses the seed and names the found file', () => {
+    writeFileSync(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: 'fixture', dependencies: { '@tanstack/react-query': '^5.101.0' } }),
+    )
+    write('src/lib/query-client.ts', 'export const queryClient = 1\n')
+
+    const { code, log } = capture(() => init(dir))
+
+    expect(code).toBe(0)
+    expect(existsSync(join(dir, 'src/query-client.ts'))).toBe(false)
+    expect(read('src/lib/query-client.ts')).toBe('export const queryClient = 1\n')
+    expect(log).toContain('src/lib/query-client.ts')
+  })
+
+  it('an existing query-client.ts elsewhere under src/ keeps suppressing the seed on sync', () => {
+    writeFileSync(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: 'fixture', dependencies: { '@tanstack/react-query': '^5.101.0' } }),
+    )
+    silenced(() => init(dir))
+    expect(existsSync(join(dir, 'src/query-client.ts'))).toBe(true)
+    rmSync(join(dir, 'src/query-client.ts'))
+    write('src/lib/query-client.ts', 'export const queryClient = 1\n')
+
+    const { code, log } = capture(() => sync({}, dir))
+
+    expect(code).toBe(0)
+    expect(existsSync(join(dir, 'src/query-client.ts'))).toBe(false)
+    expect(log).toContain('src/lib/query-client.ts')
+  })
+})

package/src/dashboard/stat-card.test.tsx

@@ -0,0 +1,81 @@
+/**
+ * `StatCard`'s threshold rail — the one behavior in this component that carries information rather
+ * than layout, and the one where a regression is silent: a wrong rail colour still renders a
+ * perfectly good-looking card.
+ *
+ * Two invariants, both asserted against real rendered markup:
+ *
+ *  1. EVERY tone states its verdict in TEXT. The rail is `aria-hidden` decoration; colour alone must
+ *     never be the only carrier of a threshold (WCAG 1.4.1), so a `VisuallyHidden` string ships with
+ *     it — for `good` no less than for `bad`.
+ *  2. OMISSION IS NOT `good`. `tone` undefined means "fine, OR nothing measured", and those two are
+ *     the same untinted card on purpose. A card with no reading must not be able to render green by
+ *     leaving the prop off, so the absence case asserts no rail and no verdict text at all — which a
+ *     future `tone = tone ?? 'good'` style default would immediately fail.
+ *
+ * No jsdom is configured in this repo (see `theme/use-basalt-spacing.test.tsx`'s doc) —
+ * `renderToStaticMarkup` inside a real `MantineProvider` is enough here, since the rail is an inline
+ * style on server-rendered markup.
+ */
+import { MantineProvider } from '@mantine/core'
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { StatCard } from './stat-card'
+import type { StatCardTone } from './stat-card'
+
+function render(tone?: StatCardTone) {
+  return renderToStaticMarkup(
+    <MantineProvider>
+      <StatCard label="Downtime · last 24h" value="0 min" tone={tone} />
+    </MantineProvider>,
+  )
+}
+
+const TONES: { tone: StatCardTone; token: string; verdict: string }[] = [
+  { tone: 'good', token: 'var(--vx-status-good)', verdict: 'Within the good threshold' },
+  { tone: 'warn', token: 'var(--vx-status-warn)', verdict: 'Past the warning threshold' },
+  { tone: 'bad', token: 'var(--vx-status-bad)', verdict: 'Past the severe threshold' },
+]
+
+describe('every tone draws its rail from the per-scheme status token', () => {
+  for (const { tone, token } of TONES) {
+    test(tone, () => {
+      const markup = render(tone)
+      // A hex here would be one scheme's colour frozen into both — the rail has to re-resolve with
+      // the palette, including under a consumer's `derive` retune.
+      expect(markup).toContain(`background:${token}`)
+      expect(markup).toContain(`data-tone="${tone}"`)
+    })
+  }
+})
+
+describe('every tone also states its verdict in text', () => {
+  for (const { tone, verdict } of TONES) {
+    test(tone, () => {
+      expect(render(tone)).toContain(verdict)
+    })
+  }
+})
+
+describe('omitting tone is not "good" — it is untinted, and says nothing', () => {
+  const markup = render()
+
+  test('no rail is drawn', () => {
+    expect(markup).not.toContain('var(--vx-status-')
+  })
+
+  test('the card carries no data-tone at all', () => {
+    // Part of the same contract, and the half a consumer can style against: `[data-tone]` must not
+    // match an unmarked card. A default of any kind — including a placeholder like `tone ?? 'none'`
+    // that draws no rail — would put the attribute back and break that selector silently.
+    expect(markup).not.toContain('data-tone')
+  })
+
+  test('no verdict is announced', () => {
+    for (const { verdict } of TONES) expect(markup).not.toContain(verdict)
+  })
+
+  test('the value still renders — the card is normal, just unmarked', () => {
+    expect(markup).toContain('0 min')
+  })
+})

package/src/dashboard/stat-card.tsx

@@ -15,7 +15,10 @@
  * 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.
+ * good one nor a bad one, and must never be tinted. `'good'` is a deliberate positive verdict, never
+ * the meaning of omission: it exists for the threshold where the calm number IS the finding (zero
+ * downtime over the window), and a card that has measured nothing must not be able to reach green by
+ * leaving the prop off.
  *
  * @example
  * import { StatCard } from 'basalt-ui'
@@ -31,6 +34,22 @@
  * @example
  * // Past a threshold — an accent rail down the leading edge, value untouched.
  * <StatCard label="Downtime" value="29 min" tone="bad" />
+ *
+ * @example
+ * // The earned zero — a measured value worth asserting, not a card that merely has no reading.
+ * <StatCard label="Downtime · last 24h" value="0 min" tone="good" />
+ *
+ * @example
+ * // The honest gate. A zero can be synthesized as well as measured — a downtime figure derived
+ * // from outage rows reads 0 both when probes ran clean AND when no probe cycle was ingested at
+ * // all, because a dead collector opens no outage row either. `tone` is a positive assertion
+ * // about a reading, so the gate belongs on whether a reading exists, not on whether the number
+ * // happens to be defined — those are separate facts. Gate on measured coverage instead:
+ * <StatCard
+ *   label="Downtime · last 24h"
+ *   value={`${downtimeMinutes} min`}
+ *   tone={hasCoverage ? (downtimeMinutes === 0 ? 'good' : 'bad') : undefined}
+ * />
  */
 import { Box, Card, Group, VisuallyHidden } from '@mantine/core'
 import type { ReactNode } from 'react'
@@ -38,13 +57,14 @@ 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'
+export type StatCardTone = 'good' | '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> = {
+  good: 'Within the good threshold',
   warn: 'Past the warning threshold',
   bad: 'Past the severe threshold',
 }
@@ -64,7 +84,9 @@ export type StatCardProps = {
   /** 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. */
+   * assistive tech. Omitting it is NOT `'good'`: omitted covers a reading that is fine AND one that
+   * is absent, and stays untinted so a card with nothing measured can never render green. Pass
+   * `'good'` only to assert a measured value that has earned the verdict. */
   tone?: StatCardTone
 }
 
@@ -111,7 +133,11 @@ export function StatCard({
               insetBlock: 0,
               insetInlineStart: 0,
               width: TONE_RAIL_WIDTH,
-              background: tone === 'bad' ? VX.status.bad : VX.status.warn,
+              // `StatCardTone`'s members are `VX.status` keys by construction, so the rail reads the
+              // per-scheme `--vx-status-*` solid directly — never a hex, so it re-resolves in both
+              // schemes and under a consumer's `derive` retune. Contrast against
+              // `--vx-surface-panel` is measured in `theme/contrast.test.ts`.
+              background: VX.status[tone],
             }}
           />
         </>

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

@@ -209,7 +209,8 @@ describe('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.
+  // lands as `warn` for one minor. Deleting its GRACE_PERIOD_KINDS entry flips this — scheduled
+  // for 1.9.0, deferred one minor because 1.8.0 shipped the same day as 1.7.0 (see the entry).
   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')
@@ -408,6 +409,16 @@ describe('raw-html-layout', () => {
     const f = find(`<div style={{ display: 'flex' }} /> // theme-allow`)
     expect(kinds(f)).not.toContain('raw-html-layout')
   })
+
+  it('does NOT flag a raw <div> with inline display:flex in a chart file — the Flex/Grid/Group remedy is @mantine/*, banned in the Mantine-free chart layer', () => {
+    const f = find(`<div style={{ display: 'flex', gap: 8 }} />`, CHART_PATH)
+    expect(kinds(f)).not.toContain('raw-html-layout')
+  })
+
+  it('still flags the same literal in a non-chart path (the check is not globally weakened)', () => {
+    const f = find(`<div style={{ display: 'flex', gap: 8 }} />`, PATH)
+    expect(kinds(f)).toContain('raw-html-layout')
+  })
 })
 
 // ── 10. inline-spacing ───────────────────────────────────────────────────────
@@ -526,6 +537,16 @@ describe('inline-display', () => {
     const f = find(`<Box style={{ display: 'flex' }} /> // theme-allow`)
     expect(kinds(f)).not.toContain('inline-display')
   })
+
+  it('does NOT flag display: "flex" in a chart file — the Flex/Grid/Group remedy is @mantine/*, banned in the Mantine-free chart layer', () => {
+    const f = find(`<Box style={{ display: 'flex' }} />`, CHART_PATH)
+    expect(kinds(f)).not.toContain('inline-display')
+  })
+
+  it('still flags the same literal in a non-chart path (the check is not globally weakened)', () => {
+    const f = find(`<Box style={{ display: 'flex' }} />`, PATH)
+    expect(kinds(f)).toContain('inline-display')
+  })
 })
 
 // ── 12. raw-visx-axis ────────────────────────────────────────────────────────

package/src/guard/index.ts

@@ -282,8 +282,14 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * promotion, and belongs in its own commit so the changelog says enforcement got stricter.
  *
  * `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.
+ * previously passed, and the one real consumer has several. Its promotion is **deferred to 1.10.0**,
+ * for the second time and for the same reason both times: the runway is measured in consumer
+ * upgrades, not in version numbers. 1.8.0 shipped the same day as 1.7.0, so promoting there would
+ * have given no runway at all. 1.9.0 then carried the chart-layer batch the same consumer asked
+ * for — bundling a build-breaking promotion into the minor they upgrade for the fixes turns a
+ * routine bump into an unplanned refactor, which is precisely what the grace minor exists to
+ * prevent. 1.10.0 is the first minor they can take the promotion on its own. Promote it by deleting
+ * the entry (its own commit).
  *
  * @example
  * const GRACE: Partial<Record<GuardKind, string>> = {
@@ -291,7 +297,7 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * }
  */
 const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {
-  'mantine-shade-index': 'introduced 1.7.0 — promote to error in 1.8.0',
+  'mantine-shade-index': 'introduced 1.7.0 — promote to error in 1.10.0',
 }
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
@@ -685,8 +691,12 @@ export const GUARD_RULES = {
     kind: 'raw-html-layout',
     pattern: RAW_HTML_TAG, // handled inline (3-condition conjunction); entry keeps registry complete
     enabled: (cfg: GuardConfig) => cfg.rawHtmlLayout,
-    // JSX-tag-shaped (`<div style={{...}}>`) — never appears in CSS text.
-    appliesTo: (relPath) => !relPath.endsWith('.css'),
+    // JSX-tag-shaped (`<div style={{...}}>`) — never appears in CSS text. Also excluded from
+    // chart files: the remedy (Box/Flex/Grid/Stack/Group) is `@mantine/*`, and src/charts/** is a
+    // lint-enforced Mantine-free layer (basalt/token-layer-boundary) — so inside a chart file the
+    // finding is unactionable, not merely inconvenient, and the only "fix" would be a theme-allow
+    // comment written inside the very directory this rule protects.
+    appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
     message:
       'Raw HTML element with inline layout/surface styling — use a Mantine layout primitive (Box/Flex/Grid/Stack/Group).',
   },
@@ -701,8 +711,12 @@ export const GUARD_RULES = {
     pattern: INLINE_DISPLAY,
     enabled: (cfg: GuardConfig) => cfg.inlineDisplay,
     // JSX-object-shaped (`display: 'flex'`, quoted value) — CSS never quotes a keyword value
-    // (`display: flex;` is bare), so the pattern's quote anchor can never match real CSS.
-    appliesTo: (relPath) => !relPath.endsWith('.css'),
+    // (`display: flex;` is bare), so the pattern's quote anchor can never match real CSS. Also
+    // excluded from chart files: the remedy (Flex/Grid/Group) is `@mantine/*`, and src/charts/**
+    // is a lint-enforced Mantine-free layer (basalt/token-layer-boundary) — so inside a chart file
+    // the finding is unactionable, not merely inconvenient, and the only "fix" would be a
+    // theme-allow comment written inside the very directory this rule protects.
+    appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
     message: 'Use <Flex>/<Grid>/<Group> instead of an inline display:flex/grid.',
   },
   'raw-visx-axis': {

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