basalt-ui 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.8.0](https://github.com/jkrumm/basalt-ui/compare/v1.7.0...v1.8.0) (2026-08-02)
+
+
+### Features
+
+* give the stat card's threshold rail a good tone ([49e795f](https://github.com/jkrumm/basalt-ui/commit/49e795f2f0da85334953bf6280ca108c730d532c))
+
 # [1.7.0](https://github.com/jkrumm/basalt-ui/compare/v1.6.0...v1.7.0) (2026-08-02)
 
 

package/agent/skills/basalt-design/SKILL.md

@@ -133,8 +133,11 @@ structure, the accent only points.
   `mantine-shade-index` (a shade-pinned color — `c="yellow.7"` is one fixed swatch in both schemes;
   use `VX.status.*` or the bare hue name), `raw-html-layout`, `inline-spacing`, `inline-display`.
   Only the Mantine-free `src/charts/**` may use raw `<div>` (still with `VX.*` tokens).
-- **Reach for the shipped composite before wrapping one.** A `StatCard` past a threshold takes
-  `tone="warn" | "bad"` (an accent rail down its leading edge); a chart goes in `ChartCard`. Wrapping
+- **Reach for the shipped composite before wrapping one.** A `StatCard` carrying a threshold verdict
+  takes `tone="good" | "warn" | "bad"` (an accent rail down its leading edge). Omitting `tone` is not
+  the same as `"good"` — omitted means "fine, or nothing measured" and stays untinted, so `"good"` is
+  a positive assertion you opt into for a value that earned it (`0 min` downtime), never a default.
+  A chart goes in `ChartCard`. Wrapping
   a shipped card in a hand-positioned `Box` to add a mark it already has is how an app grows a second
   card idiom — one the guard cannot recognize as a card, and therefore cannot police. If a composite
   genuinely can't express what you need, that is a gap to report, not to route around.

package/dist/dashboard/stat-card.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 /** 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';
 export type StatCardProps = {
     /** Mono uppercase micro-label (docs/DESIGN-SPEC.md §3: 12.5px, tracking 0.06em, faint). */
     label: string;
@@ -16,7 +16,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;
 };
 export declare function StatCard({ label, value, delta, deltaPeriod, sparkline, menu, tone, }: StatCardProps): import("react").JSX.Element;

package/dist/dashboard/stat-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stat-card.d.ts","sourceRoot":"","sources":["../../src/dashboard/stat-card.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,sGAAsG;AACtG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAA;AAWzC,MAAM,MAAM,aAAa,GAAG;IAC1B,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;kGAC8F;IAC9F,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,qFAAqF;IACrF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;yFACqF;IACrF,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB,CAAA;AAED,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,IAAI,EACJ,IAAI,GACL,EAAE,aAAa,+BAqFf"}
+{"version":3,"file":"stat-card.d.ts","sourceRoot":"","sources":["../../src/dashboard/stat-card.tsx"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,sGAAsG;AACtG,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAYlD,MAAM,MAAM,aAAa,GAAG;IAC1B,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;kGAC8F;IAC9F,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,qFAAqF;IACrF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;+EAG2E;IAC3E,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB,CAAA;AAED,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,IAAI,EACJ,IAAI,GACL,EAAE,aAAa,+BAyFf"}

package/dist/dashboard/stat-card.js

@@ -4,6 +4,7 @@ import { DeltaBadge } from "./delta-badge.js";
 import { VX } from "../tokens/index.js";
 const TONE_RAIL_WIDTH = 3;
 const TONE_LABEL = {
+  good: "Within the good threshold",
   warn: "Past the warning threshold",
   bad: "Past the severe threshold"
 };
@@ -50,7 +51,11 @@ 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/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;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"}
+{"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;AAuTD;;;;;;;;;;;;;;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

@@ -78,7 +78,7 @@ const DEFAULT_GUARD_CONFIG = {
   severity: {}
 };
 const GRACE_PERIOD_KINDS = {
-  "mantine-shade-index": "introduced 1.7.0 \u2014 promote to error in 1.8.0"
+  "mantine-shade-index": "introduced 1.7.0 \u2014 promote to error in 1.9.0"
 };
 function severityOf(kind, cfg) {
   return cfg.severity?.[kind] ?? (kind in GRACE_PERIOD_KINDS ? "warn" : "error");

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.7.0
+# basalt-ui v1.8.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,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.7.0
+Version: 1.8.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

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

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,10 @@
  * @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" />
  */
 import { Box, Card, Group, VisuallyHidden } from '@mantine/core'
 import type { ReactNode } from 'react'
@@ -38,13 +45,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 +72,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 +121,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')

package/src/guard/index.ts

@@ -282,8 +282,11 @@ 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.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>> = {
@@ -291,7 +294,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.9.0',
 }
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */

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