basalt-ui 1.6.0 → 1.8.0

package/AGENTS.md

@@ -8,7 +8,7 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 
 | Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard, EmptyState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                                              |
+| `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                          |
 | `basalt-ui/charts`          | headless        | visx chart primitives, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [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)
+
+
+### Bug Fixes
+
+* correct the shipped depth and active-nav doctrine in the agent rules ([38e0f39](https://github.com/jkrumm/basalt-ui/commit/38e0f396012064aaee0ca7b252dabea3c281d5e3))
+
+
+### Features
+
+* close the three gaps that let a consumer fork the card idiom ([d83988b](https://github.com/jkrumm/basalt-ui/commit/d83988b12c38287c42b3c3148493c614380e27b9))
+
 # [1.6.0](https://github.com/jkrumm/basalt-ui/compare/v1.5.0...v1.6.0) (2026-07-31)
 
 

package/agent/rules/basalt-mantine.md

@@ -55,11 +55,13 @@ Restraint is the #1 lever — neutrals carry the surface, the accent only points
   labels, links, primary buttons, focus rings, and the leader bar in meters. It does **NOT** appear
   on borders, large fills, every icon, or secondary/routine buttons. Don't flood blue — "ink earns
   its color."
-- **Active nav = panel bg + `shadow-card`** + an **accent-colored icon** + weight-600 ink text.
-  Inactive = muted text, faint icon; hover = ink-6% tint. This is baked into the theme's NavLink
-  defaults (`--nl-*` vars) and holds for _every_ render path, including a consumer's router `<Link>`
-  passed via `renderNavLink`. Child items indent with a 1px `divider` left border; active child =
-  accent text, weight 600.
+- **Active nav = an ink-9% tint** + an **accent-colored icon** + weight-600 ink text — **no panel
+  fill and no shadow**. It is a _selected row_, not a raised control; a panel-filled, shadowed row
+  reads as a button sitting in the nav rather than as the current location. Inactive = muted text,
+  faint icon, hover ink-6%; an active row hovers one step further to ink-13%. This is baked into
+  the theme's NavLink defaults (`--nl-*` vars) and holds for _every_ render path, including a
+  consumer's router `<Link>` passed via `renderNavLink`. Child items indent with a 1px `divider`
+  left border; active child = accent text, weight 600.
 - **Buttons**: the primary action = filled accent (`variant="filled"`), **exactly one per view**.
   Every other/secondary action = `variant="default"` (neutral). Do **not** use a colored
   `variant="light"` for routine actions.
@@ -67,7 +69,7 @@ Restraint is the #1 lever — neutrals carry the surface, the accent only points
   `color="teal"` (vivid turquoise) or a saturated emerald. Status (`red`/`green`/`orange`/`yellow`)
   is for signal only, kept muted — never raw Material/AntD.
 - **Dark mode** is cool-neutral zinc (`#27272a`-family panels on a darker `#18181b`-mixed page) —
-  not steel-blue, not pure black. Lift elevation via `shadow-card`'s whisper shadow + inset ring;
+  not steel-blue, not pure black. Lift elevation via the depth tokens' whisper shadow + inset ring;
   the accent uses its lighter shade (`#8ec5ff`) on dark to avoid glow/bleed **as INK** — links,
   active-nav icons, chart lines, focus ring. A FILLED control is the opposite case: it keeps the
   deep `#0077bd` fill and a white label in both schemes, because a light fill cannot carry white
@@ -75,7 +77,8 @@ Restraint is the #1 lever — neutrals carry the surface, the accent only points
   `--vx-accent`.
 - **Light mode** is never pure-white page + pure-black text (harsh halation). Page is a
   slightly-darker zinc mix (`#ececee`-ish) than the panel (`#f4f4f5`) so cards lift subtly off it;
-  text = near-black ink (`#262626`). Depth comes from `shadow-card` (whisper shadow + 1px ring), not
+  text = near-black ink (`#262626`). Depth comes from a whisper shadow with a 1px ring baked in
+  (`shadow-card` for panels, `shadow-raised` for controls — see "Elevation, density & shape"), not
   a plain hairline border.
 
 ## Bridging Mantine ↔ charts
@@ -143,12 +146,23 @@ section divider, not card depth) are both fine.
   consumer code must compose Mantine layout/surface primitives — `Box`, `Flex`, `Grid`,
   `SimpleGrid`, `Stack`, `Group`, `Paper`, `Card` — instead of raw `<div>`/`<span>` with inline
   `style`. Raw HTML with inline layout/surface styling defeats the token system.
-- **Mechanical enforcement.** `basalt-ui check-theme` adds five surface guard kinds (each a config knob,
+- **Mechanical enforcement.** `basalt-ui check-theme` adds six surface guard kinds (each a config knob,
   default ON; `theme-allow` line-comment escape): `off-system-surface-var` (raw ramp-step vars),
-  `card-with-border` (`withBorder` on a `Card`/`Paper`), `raw-html-layout` (raw `<div>`/`<span>` with
-  inline layout/surface styling), `inline-spacing` (inline spacing literals), `inline-display`
-  (inline `display` literals). The Mantine-free `src/charts/**` is the only place raw `<div>` is
-  allowed — and it must still use `VX.*` tokens.
+  `card-with-border` (`withBorder` on a `Card`/`Paper`), `mantine-shade-index` (a shade-pinned color —
+  see below), `raw-html-layout` (raw `<div>`/`<span>` with inline layout/surface styling),
+  `inline-spacing` (inline spacing literals), `inline-display` (inline `display` literals). The
+  Mantine-free `src/charts/**` is the only place raw `<div>` is allowed — and it must still use `VX.*`
+  tokens. `oxlint` adds `basalt/card-inset`, which catches the other half of the same card drift: an
+  explicit `p`/`padding`/`radius` on a `Card`/`Paper` instead of the xs/sm inset and the theme radius.
+
+**Never pin a shade index on a color.** `c="yellow.7"`, `bg="blue.4"`, `var(--mantine-color-red-6)` —
+each names one fixed swatch that is identical in light and dark, so a shade legible on the dark page
+is the one that fails contrast on the light one. Two correct forms: `VX.status.*` /
+`--vx-status-warn|bad|good` for a verdict color (emitted per scheme, contrast guaranteed by the
+derivation), or the bare hue name (`c="red"`, `color="green"`) to let the theme pick the step. The
+`mantine-shade-index` guard kind catches the pinned form; `gray`/`dark` steps in `var()` belong to
+`off-system-surface-var` instead. Note the distinction from `off-identity-accent`, which polices
+_which hue_ you reach for and permits the bare status names on purpose — this kind polices the index.
 
 ## Scroll regions
 
@@ -190,34 +204,60 @@ shape doctrine lives here; the spacing/radius/type **tokens** are in basalt-toke
   radius token (`radius="md"` / `var(--vx-radius-card)`) + `VX.shadowCard` + `VX.surface.*`.
   Mechanically enforced by `basalt-ui check-theme`'s `raw-surface` guard. Outer spacing comes from the
   parent `Stack`/`SimpleGrid` gap, not an intrinsic card margin.
-- **Depth = `shadow-card`, not a plain hairline** (see `docs/DESIGN-SPEC.md` in the basalt-ui repo,
-  doctrine inversion #1 — this supersedes the old "never a drop shadow" rule). Elevation tiers: 0 flat (no shadow — body,
-  page bg); 1 surface (`shadow-card` on `canvas` — cards, panels, chart cards); 2 elevated (same
-  `shadow-card`, `surface-elevated` bg — tooltips, lifted cards); 3 focus (2px primary outline —
-  focused control). `Card`/`Paper` default to the `shadow-card` shadow (no `withBorder`), and the
-  Mantine-free `ChartCard` matches them (`VX.shadowCard` + `--vx-radius-card` radius). The same
-  inversion applies to every **`variant="default"` control surface**, not just Card/Paper: Button,
-  ActionIcon, and the field idiom (Input/TextInput/…) all render panel/field bg + `shadow-card`
-  with a _transparent_ 1px border box (never `border: none` — the box stays so focus/error can
-  recolor it with no layout shift). `--mantine-color-default-border` is pinned to `transparent` in
-  `cssVariablesResolver`, which is the ONE lever that kills the stock hairline for every
-  default-variant component at once (`defaultVariantColorsResolver`'s `variant === 'default'`
-  branch reads that single var); the shadow itself is added per-component in
-  `controls.module.css`, since Mantine never declares one for `default`. Layout dividers (header
-  bottom border, sidebar section separators) still use plain borders — only card/control depth
-  moved to shadow. (Genuinely floating elements — modals, popovers, menus — get elevation from
-  Mantine's own shadow scale, not from the card token.) `CheckboxCard`/`RadioCard` (`withBorder`,
-  their own default) and `Chip` (its own default, internally `variant="filled"` — Chip has no
-  literal `"default"`) get the SAME triad — panel bg + `shadow-card`, border dropped — via
-  dedicated rules in `controls.module.css`; `PillsInput` reuses the Input field idiom's `classNames`
-  wiring directly (it renders `InputBase` under its own `__staticSelector`, so the base `Input`
-  theme entry never reached it). A dedicated test, `src/theme/border-coverage.test.ts`, mechanically
-  enumerates every `@mantine/core` component whose shipped CSS declares a border and asserts it's
-  either a themed `baseTheme.components` key or a reasoned `BORDER_ALLOWLIST` entry — this is what
-  catches the NEXT unthemed bordered component (Button/ActionIcon shipped with no `.extend()` block
-  at all, which no consumer-source guard can ever see).
-- **The shadow-card ring must land on the box that carries the surface's `border-radius`.**
-  `shadow-card`/`shadow-ctrl` bakes a 1px ring into the shadow value itself, and the ring is drawn
+- **Depth = a whisper shadow with a 1px ring baked in, not a plain hairline** (see
+  `docs/DESIGN-SPEC.md` in the basalt-ui repo, doctrine inversion #1 — this supersedes the old
+  "never a drop shadow" rule). **Three depth tiers, split control-vs-panel-vs-floating:**
+  - **`shadow-card` — panels.** A surface that HOLDS content: `Card`, `Paper`, `Notification`,
+    `ChartCard`, `SettingsSection`. Its light-mode ring is an **outset** 1px hairline; dark is a
+    deeper drop + an inset 4%-white rim.
+  - **`shadow-raised` — interactive controls.** Anything you click or type into: Button,
+    ActionIcon, the field idiom (Input/TextInput/PillsInput/…), the sidebar search trigger, header
+    icon buttons, `Chip`, `CheckboxCard`/`RadioCard`, the agent composer. **Never an outset ring** —
+    dark is drop + an inset 8%-white rim, light is drop only. That is what lets ONE value ride a
+    saturated fill, a 13% tint and a neutral panel alike: an outset ring paints in the color of
+    whatever it is drawn over, so `shadow-card`'s pale hairline would read as a grey outline around
+    a colored button, while an inset edge is drawn over the control's own background. The
+    light/dark asymmetry is deliberate — a light-mode edge would have to be a _darkening_, which
+    reads as a border (uniform) or a double bottom rule (bottom-only); both were tried and
+    rejected. Don't tidy the two schemes into one shape.
+  - **`shadow-overlay` — detached floating surfaces.** Tooltip, Popover, Menu, Combobox, Modal,
+    Drawer — they sit _above_ the page rather than on it. Resolved in `theme/index.ts`; not
+    Mantine's own shadow scale.
+
+  Focus is a fourth tier and **layers**: a 2px accent ring drawn OVER the resting depth, never
+  replacing it.
+
+  **The dividing line is control-vs-panel, not component-by-component.** Two controls sitting side
+  by side must never land on different tokens — a `size="md"` Input beside a `size="md"` Button
+  (pinned to the same height by `--vx-space-control-height`), or the header's search trigger and
+  icon button. Closing exactly that split is why `shadow-raised` exists.
+
+  **Emphasis is fill weight, not depth.** Every Button/ActionIcon variant that owns a box takes the
+  SAME resting depth: `default` / `filled` / `light` → `shadow-raised` unmodified; `outline` →
+  ring-free `shadow-ctrl` (its real 1px accent border already is its edge); `subtle` → **flat in
+  both states** (a text affordance, not an object — its hover is a neutral ink-6% tint and nothing
+  more). **Depth is static — no variant moves or changes depth on hover or press.** A hover lift
+  and a materializing `subtle` shadow were both tried and reverted; don't reintroduce either.
+  Disabled is flat and grounded. Reduced motion drops the transition, never the resting depth.
+
+  Mechanics: every default-variant control renders its bg + depth with a _transparent_ 1px border
+  box (never `border: none` — the box stays so focus/error can recolor it with no layout shift).
+  `--mantine-color-default-border` is pinned to `transparent` in `cssVariablesResolver`, the ONE
+  lever that kills the stock hairline for every default-variant component at once
+  (`defaultVariantColorsResolver`'s `variant === 'default'` branch reads that single var); the
+  shadow itself is added per-component in `controls.module.css`, since Mantine never declares one
+  for `default`. `PillsInput` reuses the Input field idiom's `classNames` wiring directly (it
+  renders `InputBase` under its own `__staticSelector`, so the base `Input` theme entry never
+  reached it). Layout dividers (header bottom border, sidebar section separators) still use plain
+  borders — only card/control depth moved to shadow. A dedicated test,
+  `src/theme/border-coverage.test.ts`, mechanically enumerates every `@mantine/core` component
+  whose shipped CSS declares a border and asserts it's either a themed `baseTheme.components` key
+  or a reasoned `BORDER_ALLOWLIST` entry — this is what catches the NEXT unthemed bordered
+  component (Button/ActionIcon shipped with no `.extend()` block at all, which no consumer-source
+  guard can ever see).
+
+- **The ring must land on the box that carries the surface's `border-radius`.**
+  `shadow-card`/`shadow-raised` bakes a 1px ring into the shadow value itself, and the ring is drawn
   by the shadowed box's OWN corners — it never reads correctly against a different element's radius
   (the Input wrapper bug: a `position: relative` box with `border-radius: 0` drew a square ring
   around the 8px-rounded `<input>` inside it). Background usually co-locates with the radius since

package/agent/rules/basalt-tokens.md

@@ -13,7 +13,9 @@ basalt-ui ships one color/type/spacing/radius identity shared by the Mantine chr
 charts. The **identity is modern zinc** (see `docs/DESIGN-SPEC.md` in the basalt-ui repo) —
 **cool-neutral zinc surfaces**
 (Tailwind zinc family) on both light and dark, low-contrast panel lift on a slightly darker page,
-depth via a whisper shadow + 1px ring (`shadow-card`) rather than a hairline border, carrying
+depth via a whisper shadow + 1px ring (`shadow-card` on panels, `shadow-raised` on interactive
+controls, `shadow-overlay` on floating surfaces — see basalt-mantine.md) rather than a hairline
+border, carrying
 **one saturated sky-blue accent**, split by ROLE: as INK (links, active-nav icon, chart
 lines, focus ring) it is `#0077bd` light / `#8ec5ff` dark; as a FILLED SURFACE it is
 `#0077bd` in BOTH schemes with a WHITE label (`--vx-accent-fill`, never `--vx-accent`). Neutrals do ~90% of the

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

@@ -19,7 +19,7 @@ one that exists. Lower layers fill gaps; they never override a higher layer.
 2. **Shipped `basalt-*` rules** (`.claude/rules/basalt-{tokens,charts,mantine,state}.md`) — the
    universal law AND its enforcement: the Basalt modern-zinc palette + saturated sky accent,
    one-hue-per-metric, neutral structure, gradient defaults, the three-tier token contract, the
-   shadow-card elevation/density doctrine.
+   elevation/density doctrine.
 3. **This skill** — only the loop and the judgment, where the above are silent.
 
 If a consumer `DESIGN.md` does not exist yet, the app has not been scaffolded — run `/basalt-app`
@@ -93,8 +93,9 @@ links, primary buttons, focus rings, and the leader bar in meters. It stays off:
 borders, large fills, every icon, secondary buttons. "Ink earns its color" — neutral does the
 structure, the accent only points.
 
-- **Active nav = panel bg + `shadow-card` + accent-colored icon + weight-600 ink text**, never a
-  full accent fill. The theme bakes this into `NavLink` for every render path — don't re-color it.
+- **Active nav = an ink-9% tint + accent-colored icon + weight-600 ink text** — no panel fill, no
+  shadow, and never a full accent fill. It's a selected row, not a raised control. The theme bakes
+  this into `NavLink` for every render path — don't re-color it.
 - **Buttons:** exactly one filled-accent primary CTA per view; every other action is
   `variant="default"` (neutral). Avoid colored `variant="light"` for routine actions.
 - **Status:** positive deltas `color="green"` (forest), never `teal`/turquoise/saturated emerald.
@@ -115,15 +116,31 @@ structure, the accent only points.
   inline-override a surface's `border`/`borderRadius`/`boxShadow`/`backgroundColor` — use the
   radius token + `VX.surface.*` / the shadow-card token. Mechanically enforced by
   `basalt-ui check-theme`'s `raw-surface` guard.
+- **Depth splits control-vs-panel-vs-floating** — three tokens, not one. Panels holding content
+  (Card/Paper/Notification/ChartCard) take `shadow-card`; anything you click or type into (Button,
+  ActionIcon, inputs, chips, the search trigger) takes `shadow-raised`, whose ring is INSET so one
+  value rides a fill, a tint and a panel alike; detached floating surfaces (Tooltip/Popover/Menu/
+  Modal/Drawer) take `shadow-overlay`. Depth is static — nothing lifts or gains a shadow on hover,
+  and emphasis is carried by fill weight, never z-height. Full doctrine in the `basalt-mantine`
+  rule.
 - **Strict surfaces & primitives.** The theme runs a strict surface system: Mantine components read
   raw ramp steps directly, so `cssVariablesResolver` **collapses the ramp steps onto the
-  `--vx-surface-*` tokens** — one `shadow-card` treatment, one card bg, one radius across every
+  `--vx-surface-*` tokens** — one depth token per tier, one card bg, one radius across every
   component (AppShell, Table, Input, Divider, Tabs, Popover, Accordion, cards). Consumer code must
   **use Mantine layout primitives** (`Box`/`Flex`/`Grid`/`SimpleGrid`/`Stack`/`Group`/`Paper`/`Card`),
-  not raw `<div>`/`<span>` with inline `style`. `check-theme` adds four guard kinds to enforce this
+  not raw `<div>`/`<span>` with inline `style`. `check-theme` adds five guard kinds to enforce this
   (default ON, `theme-allow` escape): `off-system-surface-var` (raw ramp-step vars),
-  `raw-html-layout`, `inline-spacing`, `inline-display`. Only the Mantine-free `src/charts/**` may
-  use raw `<div>` (still with `VX.*` tokens).
+  `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` 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.
 
 **Anti-slop checklist:** no pure `#000`/`#fff`; one accent locked page-wide; neutral does the
 structure, accent only points; don't flood blue; hierarchy via scale/weight/contrast/space, not

package/agent/templates/CLAUDE-block.md.tpl

@@ -31,8 +31,9 @@ defer to DESIGN.md.
 dark-first professional surface — not a showcase. Ignore `/frontend-design`'s push toward a "BOLD
 aesthetic direction", gradient meshes, noise/grain, and dramatic motion. Here: the shipped
 three-font system (Nunito Sans body, Hubot Sans condensed headings, JetBrains Mono for every
-numeral/micro-label), depth via `shadow-card` (a whisper shadow + 1px ring, never a decorative drop
-shadow), neutral zinc-by-default with the single saturated accent spent only when earned (trend /
+numeral/micro-label), depth via a whisper shadow + 1px ring (`shadow-card` on panels,
+`shadow-raised` on controls — never a decorative drop shadow, never a hover lift), neutral
+zinc-by-default with the single saturated accent spent only when earned (trend /
 signal / categorical separation). Restraint **is** the identity.
 
 <!-- basalt:end -->

package/agent/templates/DESIGN.md.tpl

@@ -21,7 +21,8 @@ law, the law wins.
 ## Identity
 
 {{APP_NAME}} inherits the basalt-ui identity verbatim: modern zinc surfaces, one earned saturated
-sky-blue accent, `shadow-card` elevation, dense-by-default spacing, and the three-font system. The
+sky-blue accent, the `shadow-card` / `shadow-raised` / `shadow-overlay` depth split,
+dense-by-default spacing, and the three-font system. The
 law itself — every hex, role split, and enforcement rule — lives in the `basalt-tokens` and
 `basalt-mantine` rules (`.claude/rules/basalt-{tokens,mantine}.md`) and `docs/DESIGN-SPEC.md` in
 the basalt-ui repo; it is **not** restated here. Confirm or restate any intentional identity shift

package/configs/oxlint-plugin.js

@@ -81,6 +81,27 @@ function isNumericLiteral(node) {
   return node !== null && node.type === 'Literal' && typeof node.value === 'number'
 }
 
+/**
+ * An absolute CSS length written as a STRING — `'10px'`, `"1.5rem"`, `'0.75em'`.
+ *
+ * Mantine's `size` / `fz` props accept a scale token (`"xs"`…`"xl"`) OR any CSS length, and the
+ * second form is the one that leaves the token system. A string is not a numeric literal, so every
+ * `size="10px"` in an app slipped past the numeric-only check these two rules used to be.
+ *
+ * `em`/relative ratios are included on `size` (a `2em` icon is still an off-scale dimension) but
+ * the message names the right escape for each rule, so the two are not merged into one check.
+ */
+const CSS_LENGTH_STRING = /^-?\d*\.?\d+(?:px|rem|em)$/
+
+function isCssLengthString(node) {
+  return (
+    node !== null &&
+    node.type === 'Literal' &&
+    typeof node.value === 'string' &&
+    CSS_LENGTH_STRING.test(node.value.trim())
+  )
+}
+
 /** Unwraps a JSXExpressionContainer to its inner expression; passes any other node through. */
 function unwrapExpressionContainer(node) {
   return node !== null && node.type === 'JSXExpressionContainer' ? node.expression : node
@@ -126,7 +147,59 @@ const noRawFontSize = {
   },
 }
 
-// ── Rule 2 — card-inset ─────────────────────────────────────────────────────────────────────────
+// ── Rule 2 — raw-size-literal ───────────────────────────────────────────────────────────────────
+
+const RAW_SIZE_LITERAL_MESSAGE =
+  'Raw CSS length on a size prop — use the scale ("xs".."xl"), or fz={VX.text.*} when the type ' +
+  'scale has no step for it. (basalt/raw-size-literal)'
+
+/** The size-ish JSX props a CSS-length string can leave the token system through. */
+const SIZE_ATTRS = new Set(['size', 'fz', 'fontSize'])
+
+/**
+ * A CSS length written as a STRING on a size prop — `<Text size="10px">`, `<ThemeIcon size="2rem">`,
+ * `<Text fz="0.8rem">`. This is the hole `no-raw-font-size` left open: it only ever tested for a
+ * NUMERIC literal, so every string form walked straight past it.
+ *
+ * Its own rule id rather than a widening of `no-raw-font-size`, for two reasons. It covers `size`,
+ * which is not always a font size — on `Text` it is, on `ThemeIcon`/`ActionIcon` it is a box
+ * dimension — so one shared id would mean a consumer silencing the icon case also silences every
+ * off-scale font size, the bundled-rule mistake the three boundary rules were split apart to avoid.
+ * And a separate id can carry its own severity: this rule ships `warn` in the consumer preset for
+ * one minor (the grace-minor doctrine in the package CLAUDE.md — it rejects code that previously
+ * passed, and majors are banned here, so a consumer has no semver channel warning them). Widening
+ * `no-raw-font-size` in place would have promoted it to `error` on upgrade with no such runway.
+ *
+ * Numeric `size={32}` is deliberately NOT flagged. It is the documented Mantine idiom for icon
+ * dimensions and flagging it would fire on nearly every icon in an app for no design-system gain —
+ * the token system has an opinion about type scale and spacing, not about how many pixels wide one
+ * glyph box is.
+ */
+const rawSizeLiteral = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow raw CSS-length strings on size/fz/fontSize props.',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (getFilename(context).includes('/src/tokens/')) return {}
+
+    return {
+      JSXAttribute(node) {
+        const name = node.name?.name
+        if (typeof name !== 'string' || !SIZE_ATTRS.has(name)) return
+        const value = unwrapExpressionContainer(node.value)
+        if (!isCssLengthString(value)) return
+        if (hasThemeAllow(context, node)) return
+        context.report({ node, message: RAW_SIZE_LITERAL_MESSAGE })
+      },
+    }
+  },
+}
+
+// ── Rule 3 — card-inset ─────────────────────────────────────────────────────────────────────────
 
 const CARD_TAGS = new Set(['Card', 'Paper'])
 
@@ -456,6 +529,7 @@ export default {
   meta: { name: 'basalt' },
   rules: {
     'no-raw-font-size': noRawFontSize,
+    'raw-size-literal': rawSizeLiteral,
     'card-inset': cardInset,
     'chart-in-raw-surface': chartInRawSurface,
     'raw-scroll-container': rawScrollContainer,

package/configs/oxlint.json

@@ -17,6 +17,7 @@
     "import/no-duplicates": "error",
     "import/no-unassigned-import": "off",
     "basalt/no-raw-font-size": "error",
+    "basalt/raw-size-literal": "warn",
     "basalt/card-inset": "error",
     "basalt/chart-in-raw-surface": "error",
     "basalt/raw-scroll-container": "off",

package/dist/cli/index.d.ts

@@ -41,6 +41,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

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

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

package/dist/cli/index.js

@@ -109,6 +109,7 @@ function checkTheme(cwd = process.cwd()) {
     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,
@@ -962,6 +963,7 @@ async function guardHook(cwd = process.cwd()) {
     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/dist/dashboard/index.d.ts

@@ -1,5 +1,5 @@
 export { DeltaBadge, type DeltaBadgeProps } from './delta-badge.js';
-export { StatCard, type StatCardProps } from './stat-card.js';
+export { StatCard, type StatCardProps, type StatCardTone } from './stat-card.js';
 export { EmptyState, type EmptyStateProps } from './empty-state.js';
 export { SettingsSection, type SettingsSectionProps, SettingsRow, type SettingsRowProps, DangerZone, type DangerZoneProps, } from './settings-section.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA"}

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

@@ -1,4 +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 = 'good' | 'warn' | 'bad';
 export type StatCardProps = {
     /** Mono uppercase micro-label (docs/DESIGN-SPEC.md §3: 12.5px, tracking 0.06em, faint). */
     label: string;
@@ -13,6 +15,11 @@ 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. 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 }: StatCardProps): import("react").JSX.Element;
+export declare function StatCard({ label, value, delta, deltaPeriod, sparkline, menu, tone, }: StatCardProps): import("react").JSX.Element;
 //# sourceMappingURL=stat-card.d.ts.map

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":"AAsBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,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;CACjB,CAAA;AAED,wBAAgB,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,aAAa,+BA8D5F"}
+{"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

@@ -1,8 +1,22 @@
-import { jsx, jsxs } from "react/jsx-runtime";
-import { Card, Group } from "@mantine/core";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Box, Card, Group, VisuallyHidden } from "@mantine/core";
 import { DeltaBadge } from "./delta-badge.js";
 import { VX } from "../tokens/index.js";
-function StatCard({ label, value, delta, deltaPeriod, sparkline, menu }) {
+const TONE_RAIL_WIDTH = 3;
+const TONE_LABEL = {
+  good: "Within the good threshold",
+  warn: "Past the warning threshold",
+  bad: "Past the severe threshold"
+};
+function StatCard({
+  label,
+  value,
+  delta,
+  deltaPeriod,
+  sparkline,
+  menu,
+  tone
+}) {
   return /* @__PURE__ */ jsxs(
     Card,
     {
@@ -19,9 +33,33 @@ function StatCard({ label, value, delta, deltaPeriod, sparkline, menu }) {
         // theme-allow: Card root as a flex column — Mantine Card takes no layout props
         flexDirection: "column",
         gap: "var(--vx-space-stat-card-gap)",
-        overflow: "hidden"
+        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,
       children: [
+        tone !== void 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(VisuallyHidden, { children: TONE_LABEL[tone] }),
+          /* @__PURE__ */ jsx(
+            Box,
+            {
+              "aria-hidden": "true",
+              style: {
+                position: "absolute",
+                insetBlock: 0,
+                insetInlineStart: 0,
+                width: TONE_RAIL_WIDTH,
+                // `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]
+              }
+            }
+          )
+        ] }),
         /* @__PURE__ */ jsxs(Group, { justify: "space-between", align: "flex-start", wrap: "nowrap", gap: "xs", children: [
           /* @__PURE__ */ jsx(
             "span",

package/dist/guard/index.d.ts

@@ -9,7 +9,7 @@ export type { Finding, GuardConfig, GuardKind, GuardSeverity };
 /** Shared default config — CLI and tests import this to avoid duplication. */
 export declare const DEFAULT_GUARD_CONFIG: GuardConfig;
 /**
- * The closed registry of all 19 guard kinds. The triad test asserts
+ * The closed registry of all 20 guard kinds. The triad test asserts
  * `surface.guardKinds ⊆ keyof GUARD_RULES` at runtime.
  *
  * raw-surface, raw-html-layout, and sub-16-input-font are handled inline in checkSource
@@ -51,6 +51,12 @@ export declare const GUARD_RULES: {
         readonly appliesTo: (relPath: string) => boolean;
         readonly message: "For an off-identity accent use blue/gray or a status hue (red/green/orange/yellow).";
     };
+    readonly 'mantine-shade-index': {
+        readonly kind: "mantine-shade-index";
+        readonly pattern: RegExp;
+        readonly enabled: (cfg: GuardConfig) => boolean;
+        readonly message: "Shade-pinned Mantine color — one fixed swatch in BOTH color schemes, so it cannot stay legible in either. Use VX.status.* / --vx-status-* for a verdict color, or the bare hue name (c=\"red\") to let the theme resolve the shade per scheme.";
+    };
     readonly 'raw-spacing': {
         readonly kind: "raw-spacing";
         readonly pattern: (cfg: GuardConfig) => RegExp;

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

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