basalt-ui 1.25.0 → 1.27.0

package/src/tokens/palette.ts

@@ -302,6 +302,23 @@ const SPACE_ANCHORS_BASE = {
    * Input tracks it at every density level instead of only coinciding at level 0 (the defect this
    * anchor fixes — Mantine's own `--button-height-md`/`--ai-size` are static, density-blind). */
   controlHeight: CONTROL_HEIGHT_BASE,
+  /** The `size="icon"` count-tag height (`docs/CONTROLS-SPEC.md` §5) — inline chip / table-cell
+   * count badge. Floored at 18px in {@link deriveSpacing} (same "negative level can't collapse a
+   * real control below a legible/tappable minimum" reasoning as `sidebarSearchTriggerHeight`'s WCAG
+   * floor, one notch tighter since a count tag is a badge, not a primary interactive target). */
+  controlHeightTag: 20,
+  /** The `size="icon"` ActionIcon height (`docs/CONTROLS-SPEC.md` §5) — `WidgetHeader
+   * tier="widget"` actions. Floored at 22px in {@link deriveSpacing}. */
+  controlHeightWidget: 24,
+  /** The `size="ctl"` Mantine tier's resolved height (`docs/CONTROLS-SPEC.md` §5, C5) —
+   * `PageBar`/`Section`/table toolbar/sidebar-block controls. Floored at 28px in
+   * {@link deriveSpacing}. */
+  controlHeightCtl: 30,
+  /** The touch hit-area size (`::before`) every home control expands to below `sm` (C15,
+   * `docs/CONTROLS-SPEC.md` §5) — independent of the visible `controlHeightCtl` box, same shape as
+   * `mobileNavBarHeight`/`mobileNavRowHeight`'s Apple HIG 44pt / WCAG 2.5.5 floors elsewhere in this
+   * table. Floored at 30px in {@link deriveSpacing} (C15's "floor 30 at density −3"). */
+  touchControlHeight: 36,
 } as const
 
 /**
@@ -355,14 +372,13 @@ const SPACE_STEP_BASE = {
   timelineBullet: 22,
 
   // ── Shared across ≥2 sites (structural — must render at the same value) ──────────────────────
-  // `stickyHeaderClearance`/`stickyHeaderClearanceMobile` USED to live here as ONE independent base
-  // literal (84) — they don't any more. Both are DERIVED, post-`step`, from their OWN AppShell
-  // header (`appShellHeaderHeight` / `appShellHeaderMobileHeight` below) instead (see
-  // {@link deriveSpacing}'s doc for why): an independent literal could drift from the header it's
-  // supposed to clear, which is exactly what happened (84 < 96, under-clearing the mobile header at
-  // every level before this fix) — and a SINGLE derived value still over-cleared the desktop header
-  // by 60px, since the desktop header is less than half the mobile one's height. `SpaceValues.step`
-  // still carries both keys — see that type's own doc — they're just not part of this BASE table.
+  // `stickyHeaderClearance` USED to live here as an independent base literal (84) — it doesn't any
+  // more. It is DERIVED, post-`step`, from the AppShell header it exists to clear
+  // (`appShellHeaderHeight` below) instead (see {@link deriveSpacing}'s doc for why): an independent
+  // literal could drift from that header, which is exactly what happened. `SpaceValues.step` still
+  // carries the key — see that type's own doc — it is just not part of this BASE table. The
+  // `stickyHeaderClearanceMobile` sibling went with the two-row mobile header in 1.26.0: the header
+  // is one 48px row at every viewport now, so one clearance covers both.
   /** NavLink leftSection icon-to-label gap — shared by `theme/nav-link.module.css` (every render
    * path) and `shell/app-sidebar.module.css`'s own `.link` rule (belt-and-suspenders on the same
    * DOM), and reused verbatim for `.footerBtn`/`.accountRow`'s icon gap (their own doc comments call
@@ -572,36 +588,28 @@ const SPACE_STEP_BASE = {
   /** Settings-menu `<Menu width={…}>` (`app-sidebar.tsx`). */
   sidebarSettingsMenuWidth: 200,
 
-  // ── shell/app-header.module.css ───────────────────────────────────────────────────────────────
-  /** Mobile two-row header's page-actions row height. */
-  appHeaderMobileActionsHeight: 52,
-
   // ── shell/index.tsx (AppShell dimensions) ──────────────────────────────────────────────
   /** AppShell desktop header bar height — sized to hold one row of `size="md"` controls, so it
    *  tracks `controlHeight`. Its level-0 coincidence with `appShellNavbarRailWidth` below is a
    *  coincidence, not a law: this is a horizontal bar's HEIGHT (governed by control height), that
    *  is a vertical rail's WIDTH (governed by icon footprint). They stay separate entries. */
+  /** AppShell header bar height — ONE value at every viewport since 1.26.0 (law C14,
+   *  `docs/CONTROLS-SPEC.md` §2.1). The pre-1.26.0 `appShellHeaderMobileHeight` (97) existed only
+   *  because the mobile header wrapped to a second, always-reserved page-actions row; `PageBar`
+   *  folds that row's overflow into a kebab and moves its filters/tabs into the page flow, so the
+   *  bar is 48px on a phone too and there is no sum to keep in step any more. */
   appShellHeaderHeight: 48,
-  /** AppShell mobile (two-row) header height. Not one concept but a sum: row 1 + `app-header.
-   *  module.css`'s wrap row-gap (`--mantine-spacing-sm`) + `appHeaderMobileActionsHeight`. Two of
-   *  those three addends already track density, so the container must too — held fixed, row 1's
-   *  budget collapses 52px -> 12px across the level range.
+  /** AppShell navbar width, expanded — ONE entry for both the `base` (mobile, where the navbar is
+   *  permanently collapsed and unused — see `MobileNav`) and the expanded `sm` value: the same
+   *  `.root` at full width, genuinely one concept.
    *
-   *  KEEP THIS EQUAL TO THE SUM. At level 0: 32 (row 1) + 13 (`SPACE_SCALE.sm`) + 52
-   *  (`appHeaderMobileActionsHeight`) = 97. It was 96 while `SPACE_SCALE.sm` was 12; the
-   *  component-roominess retune raised that addend, and leaving the total at 96 silently took the
-   *  pixel out of row 1 instead — which is what ate the last of its WCAG 2.5.8 target-size margin at
-   *  density -3 (`theme/density-relations.test.ts` measures row 1 as the REMAINDER of this sum, so
-   *  the total is the only place the budget can come from). Raise this whenever `SPACE_SCALE.sm` or
-   *  `appHeaderMobileActionsHeight` moves. Better still, make it unnecessary: computing this the way
-   *  `stickyHeaderClearance*` already is — post-`step`, from its own addends rather than as an
-   *  independent literal — would make the drift impossible instead of merely re-tuned. That is the
-   *  same refactor, and the same reasoning, this PR applied to the clearances; it is worth doing to
-   *  this one too, and it stays a follow-up only because it moves every non-zero level's value. */
-  appShellHeaderMobileHeight: 97,
-  /** AppShell navbar width, expanded — ONE entry for both the `base` (mobile drawer) and the
-   *  expanded `sm` value: the same `.root` at full width, genuinely one concept. */
-  appShellNavbarWidth: 216,
+   *  256, up from 216. At 216 the column was 196px of usable text after `.root`'s 10px inset a side,
+   *  and the sidebar carries more than nav rows: a block row is `label · meta`, an account row is
+   *  `avatar · name · plan`, and a `Recents` entry is a sentence. Every one of them was ellipsizing
+   *  in the second word. 256 is also the width the shell's own dropdowns already assume
+   *  (`sidebarAccountMenuWidth` 220 + the row inset), so the menu no longer overhangs the column it
+   *  belongs to. */
+  appShellNavbarWidth: 256,
   /** AppShell navbar width, collapsed icon rail. Separate from `appShellHeaderHeight` above
    *  despite sharing 48 at level 0 (see that entry's note). */
   appShellNavbarRailWidth: 48,
@@ -685,6 +693,33 @@ const SPACE_STEP_BASE = {
   virtualRowInsetY: 8,
   /** `data/virtual-list.tsx`'s skeleton row horizontal inset. */
   virtualRowInsetX: 12,
+
+  // ── Controls — homes/tiers (`docs/CONTROLS-SPEC.md` §5) ──────────────────────────────────────
+  /** `PageBar` row height (row 1 or row 2, each measured independently — the bar's own overall
+   *  height is the sum published as `--basalt-page-bar-h`, computed by `PageBar` itself, not a
+   *  static token). */
+  pageBarRowHeight: 40,
+  /** `WidgetHeader tier="section"` row height. */
+  sectionHeaderHeight: 36,
+  /** `WidgetHeader tier="widget"` row height. */
+  widgetHeaderHeight: 28,
+  /** Sidebar block list-item row height. */
+  sidebarBlockRowHeight: 32,
+  /** Gap between adjacent controls inside a home (filter pills, action buttons). */
+  controlGap: 6,
+  /** Mobile bottom-sheet row height (the `Filters (n)` drawer, a block's More-sheet row) — Apple
+   *  HIG 44pt / WCAG 2.5.5 AAA, same floor family as `mobileNavRowHeight`. */
+  sheetRowHeight: 44,
+  /** `BasaltDataTable`'s header row. Its own entry rather than a reuse of `sectionHeaderHeight`
+   *  (which is 36 too at level 0): one is a heading's box, this is a table's `th`, and a density
+   *  pass that wants denser table rows must not be forced to shrink every section header with them.
+   *  Mantine sizes both `th` and `td` from ONE `verticalSpacing` prop, so a 36/40 pair is
+   *  unreachable through it — both are applied in `theme/index.ts`'s `Table.extend` as JS numbers,
+   *  which is why (like `progressBarSize`) neither is emitted as a `--vx-*` var. */
+  tableHeaderHeight: 36,
+  /** `BasaltDataTable`'s body row — one step taller than the header, so the mono uppercase `th`
+   *  reads as a label band over roomier data rows rather than as the first row of the data. */
+  tableRowHeight: 40,
 } as const
 
 /**
@@ -723,17 +758,14 @@ export const SPACE_FIXED = {
 export type SpaceValues = {
   anchors: { [K in keyof typeof SPACE_ANCHORS_BASE]: number }
   scale: { [K in keyof typeof SPACE_SCALE_BASE]: number }
-  /** `SPACE_STEP_BASE`'s one-offs PLUS `stickyHeaderClearance`/`stickyHeaderClearanceMobile`, NEITHER
-   * of which is in that base table — both are computed after the rest of `step`, one from
-   * `appShellHeaderHeight` (desktop) and one from `appShellHeaderMobileHeight` (mobile), see
+  /** `SPACE_STEP_BASE`'s one-offs PLUS `stickyHeaderClearance`, which is NOT in that base table —
+   * it is computed after the rest of `step`, from `appShellHeaderHeight`, see
    * {@link deriveSpacing}'s doc. Kept on this same `step` object (not split into a third group)
-   * because every consumer reads them exactly like any other one-off — only their DERIVATION
-   * differs. Two keys, not one, because the clearance is RESPONSIVE (Decision 3): a consumer picks
-   * whichever one matches the breakpoint it's rendering at — see `docs/CONTENT-SPEC.md` §5 and
-   * `content/prose.module.css`/`content/article-layout.module.css` for the CSS-side split. */
+   * because every consumer reads it exactly like any other one-off — only its DERIVATION differs.
+   * ONE key, not the pre-1.26.0 responsive pair: the AppShell header is a single 48px row at every
+   * viewport now (law C14, `docs/CONTROLS-SPEC.md` §2.1), so there is no second header to clear. */
   step: { [K in keyof typeof SPACE_STEP_BASE]: number } & {
     stickyHeaderClearance: number
-    stickyHeaderClearanceMobile: number
   }
   /** NavLink row line-height (`theme/index.ts`'s row-geometry styles) — additive, not
    * multiplicative; see {@link deriveSpacing}'s doc for why. */
@@ -805,8 +837,8 @@ const ROW_LINE_HEIGHT_STEP = 1 / 30
  * from a single integer `level` (`docs/DESIGN-SPEC.md` §4-adjacent) — the spacing analog of
  * {@link deriveRadius}. `level: 0` reproduces the shipped identity exactly (locked by
  * `theme/spacing.test.ts` and `tokens/density.test.ts`) for every value EXCEPT
- * `step.stickyHeaderClearance`/`step.stickyHeaderClearanceMobile` — see the third bullet below for
- * why those are a deliberate exception.
+ * `step.stickyHeaderClearance` — see the third bullet below for why that one is a deliberate
+ * exception.
  *
  * The law: a MULTIPLIER, `1 + 0.1 * level`, applied to every `SPACE_ANCHORS_BASE`/
  * `SPACE_SCALE_BASE`/`SPACE_STEP_BASE` constant, then rounded (see {@link scaleSpace}) — a
@@ -831,30 +863,24 @@ const ROW_LINE_HEIGHT_STEP = 1 / 30
  *    (and, transitively, the collapsed rail's `ActionIcon` variant, which reads this same resolved
  *    value) below the accessible floor (22px at level -3) while also crowding out its fixed-size icon
  *    and `Kbd` chip.
- *  - `step.stickyHeaderClearance` (desktop) and `step.stickyHeaderClearanceMobile` (mobile) are not
- *    scaled off their own base AT ALL — `SPACE_STEP_BASE` has no such key any more (see that table's
- *    doc). Both are computed AFTER the rest of `step`, RESPONSIVELY, one per AppShell breakpoint:
- *    `stickyHeaderClearance = step.appShellHeaderHeight + anchors.stackMd` (desktop, `>= sm`) and
- *    `stickyHeaderClearanceMobile = step.appShellHeaderMobileHeight + anchors.stackMd` (mobile,
- *    `< sm` — the SAME `sm`/48em breakpoint the AppShell header itself switches on, `shell/index.tsx`).
- *    A SINGLE clearance value (this law's own prior shape) can only be tuned against ONE header, and
- *    whichever one it under-shoots stays broken: the original independent literal (84) was tuned only
- *    against the desktop header (48) and under-cleared the mobile header (96) by 12px at level 0
- *    already, before density entered the picture; deriving ONE value off the taller mobile header
- *    fixed that under-clear but then OVER-cleared the desktop header by 60px (108 vs. the 48px header
- *    needs) — dead space above every anchored heading and a TOC rail shoved down on the common
- *    (desktop) path. Splitting into two responsive values fixes both directions at once: each clears
- *    ONLY its own header, with the SAME `anchors.stackMd` breathing room (not a bare `+ 0`) so a
- *    scrolled-to heading doesn't sit flush against the header's bottom edge — density-tracking, like
- *    the header height it's added to, so the margin itself never freezes at one notch. Level 0:
- *    desktop `48 + 12 = 60` (a deliberate BREAK from the pre-split 84/108 — see `theme/spacing.test.ts`
- *    for why `stickyHeaderClearance` alone is exempt from the byte-identity gate every other spacing
- *    token is held to), mobile `96 + 12 = 108` (unchanged from the pre-split single-value law).
- *    **Consumer coupling (accepted, not hidden):** both values assume `BasaltShell`'s own AppShell
- *    header heights — a `./content` consumer NOT rendering inside `BasaltShell` (e.g. `Prose`/
- *    `ArticleLayout` standalone) gets clearance numbers tuned for a header it may not have, and must
- *    override `--vx-space-sticky-header-clearance`/`--vx-space-sticky-header-clearance-mobile`
- *    itself. Documented on the `./content` surface too (`docs/CONTENT-SPEC.md` §5), not only here.
+ *  - `step.stickyHeaderClearance` is not scaled off its own base AT ALL — `SPACE_STEP_BASE` has no
+ *    such key any more (see that table's doc). It is computed AFTER the rest of `step`, as
+ *    `step.appShellHeaderHeight + anchors.stackMd`. An independent literal can only be tuned against
+ *    ONE header height and then drifts from it: the original 84 was tuned against a 48px desktop
+ *    header and under-cleared the pre-1.26.0 96px mobile one by 12px at level 0, before density
+ *    entered the picture at all. Deriving it removes that whole failure mode — and since 1.26.0 the
+ *    AppShell header is ONE 48px row at every viewport (law C14), so the `stickyHeaderClearanceMobile`
+ *    half of the old responsive pair is deleted rather than re-derived. The `+ anchors.stackMd`
+ *    breathing room (not a bare `+ 0`) keeps a scrolled-to heading off the header's bottom edge, and
+ *    tracks density like the header height it is added to, so the margin never freezes at one notch.
+ *    Level 0: `48 + 12 = 60` (a deliberate BREAK from the pre-derivation 84 — see
+ *    `theme/spacing.test.ts` for why `stickyHeaderClearance` alone is exempt from the byte-identity
+ *    gate every other spacing token is held to).
+ *    **Consumer coupling (accepted, not hidden):** the value assumes `BasaltShell`'s own AppShell
+ *    header height — a `./content` consumer NOT rendering inside `BasaltShell` (e.g. `Prose`/
+ *    `ArticleLayout` standalone) gets a clearance number tuned for a header it may not have, and must
+ *    override `--vx-space-sticky-header-clearance` itself. Documented on the `./content` surface too
+ *    (`docs/CONTENT-SPEC.md` §5), not only here.
  *
  * `rowLineHeight` is the ONE exception to the multiplier entirely: `1.35 + ROW_LINE_HEIGHT_STEP *
  * level`, ADDITIVE, its own gentler, INDEPENDENT coefficient (see {@link ROW_LINE_HEIGHT_STEP}'s own
@@ -939,6 +965,13 @@ export function deriveSpacing(level: number): SpaceValues {
   anchors.stackMd = stackUnit * 3
   anchors.stackLg = stackUnit * 4
   anchors.stackXl = stackUnit * 6
+  // Control-tier floors (`docs/CONTROLS-SPEC.md` §5, C15) — same "negative level can't collapse a
+  // real control below its accessible/legible minimum" guardrail as `sidebarSearchTriggerHeight`'s
+  // WCAG 2.5.8 floor and the mobile-nav Apple HIG floors below.
+  anchors.controlHeightTag = Math.max(18, anchors.controlHeightTag)
+  anchors.controlHeightWidget = Math.max(22, anchors.controlHeightWidget)
+  anchors.controlHeightCtl = Math.max(28, anchors.controlHeightCtl)
+  anchors.touchControlHeight = Math.max(30, anchors.touchControlHeight)
 
   const mappedStep = mapSpaceGroup(SPACE_STEP_BASE, level, multiplier)
   // WCAG 2.5.8 minimum interactive-target size — see this function's doc for why the trigger's
@@ -949,14 +982,15 @@ export function deriveSpacing(level: number): SpaceValues {
   // sidebar search trigger's 24px floor directly above.
   mappedStep.mobileNavBarHeight = Math.max(48, mappedStep.mobileNavBarHeight)
   mappedStep.mobileNavRowHeight = Math.max(44, mappedStep.mobileNavRowHeight)
+  // Same floor family, same reason — `sheetRowHeight`'s own doc names it "same floor family as
+  // `mobileNavRowHeight`", but nothing enforced that below level 0 until now.
+  mappedStep.sheetRowHeight = Math.max(44, mappedStep.sheetRowHeight)
   const step: SpaceValues['step'] = {
     ...mappedStep,
-    // RESPONSIVE, one per AppShell breakpoint — each DERIVED from its own header, plus
-    // density-tracking breathing room — see this function's doc (third bullet, Decision 3) for the
-    // full rationale, and `theme/spacing.test.ts` for why `stickyHeaderClearance` alone is exempt
-    // from the level-0 byte-identity gate.
+    // DERIVED from the header it clears, plus density-tracking breathing room — see this function's
+    // doc (third bullet) for the full rationale, and `theme/spacing.test.ts` for why
+    // `stickyHeaderClearance` alone is exempt from the level-0 byte-identity gate.
     stickyHeaderClearance: mappedStep.appShellHeaderHeight + anchors.stackMd,
-    stickyHeaderClearanceMobile: mappedStep.appShellHeaderMobileHeight + anchors.stackMd,
   }
 
   return {
@@ -989,9 +1023,9 @@ export const SPACE_SCALE = DEFAULT_SPACE_VALUES.scale
 
 /** Density-tracking one-offs at the shipped identity — see `SPACE_STEP_BASE`'s doc. `deriveSpacing(0)`'s
  * `step`, UNCHANGED from the shipped identity (locked by `theme/spacing.test.ts`) EXCEPT
- * `stickyHeaderClearance` (originally 84, then a single derived 108, now the desktop half of the
- * Decision-3 responsive split at 60) and its new `stickyHeaderClearanceMobile` sibling (108) — the
- * deliberate level-0 breaks in the density work; see `deriveSpacing`'s doc (third bullet) for why. */
+ * `stickyHeaderClearance` (originally 84, then a single derived 108, now 60 — derived from the one
+ * 48px AppShell header) — the deliberate level-0 break in the density work; see `deriveSpacing`'s
+ * doc (third bullet) for why. */
 export const SPACE_STEP = DEFAULT_SPACE_VALUES.step
 
 /** NavLink row line-height at the shipped identity (`1.35`) — `deriveSpacing(0)`'s `rowLineHeight`,

package/src/widget-header/delta-badge.test.tsx

@@ -0,0 +1,60 @@
+/**
+ * `DeltaBadge` — sign-driven tone/glyph, `withGlyph`, custom `format`, and `period` (docs/
+ * DESIGN-SPEC.md §5). Mantine-free, so no `MantineProvider` wrapper is needed.
+ *
+ * CSS-module class hashes are unavailable under `bun test` (see `app-mobile-nav.test.tsx`'s doc) —
+ * every query below goes through text content, never `classes.*`.
+ */
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { DeltaBadge } from './delta-badge'
+
+describe('sign drives tone and glyph', () => {
+  test('positive renders the up glyph and the formatted magnitude', () => {
+    render(<DeltaBadge value={12.4} />)
+    expect(screen.getByText('▲')).toBeDefined()
+    expect(screen.getByText('12.4%')).toBeDefined()
+  })
+
+  test('negative renders the down glyph and the formatted magnitude', () => {
+    render(<DeltaBadge value={-3.1} />)
+    expect(screen.getByText('▼')).toBeDefined()
+    expect(screen.getByText('3.1%')).toBeDefined()
+  })
+
+  test('zero renders the formatted magnitude with no glyph', () => {
+    render(<DeltaBadge value={0} />)
+    expect(screen.getByText('0.0%')).toBeDefined()
+    expect(screen.queryByText('▲')).toBeNull()
+    expect(screen.queryByText('▼')).toBeNull()
+  })
+})
+
+test('withGlyph={false} suppresses the glyph even for a signed value', () => {
+  render(<DeltaBadge value={12.4} withGlyph={false} />)
+  expect(screen.getByText('12.4%')).toBeDefined()
+  expect(screen.queryByText('▲')).toBeNull()
+})
+
+test('a zero value never shows a glyph, even with withGlyph={true}', () => {
+  render(<DeltaBadge value={0} withGlyph={true} />)
+  expect(screen.queryByText('▲')).toBeNull()
+  expect(screen.queryByText('▼')).toBeNull()
+})
+
+test('a custom format overrides the default percentage label', () => {
+  render(<DeltaBadge value={182} format={(v) => `${Math.abs(v)}ms`} withGlyph={false} />)
+  expect(screen.getByText('182ms')).toBeDefined()
+  expect(screen.queryByText('182.0%')).toBeNull()
+})
+
+test('period renders after the value, in the same badge', () => {
+  render(<DeltaBadge value={4.2} period="MoM" />)
+  expect(screen.getByText('4.2%')).toBeDefined()
+  expect(screen.getByText('MoM')).toBeDefined()
+})
+
+test('omitting period renders no extra text', () => {
+  render(<DeltaBadge value={4.2} />)
+  expect(screen.queryByText('MoM')).toBeNull()
+})

package/src/widget-header/delta-badge.tsx

@@ -0,0 +1,57 @@
+/**
+ * DeltaBadge — the KPI trend chip (docs/DESIGN-SPEC.md §5): mono 11.5px weight 600, status-color
+ * text on a status-13% tint, control radius, 2px/7px padding, optional ▲/▼ glyph at 9px. Sign
+ * alone drives the tone — positive reads as success, negative as danger, zero as a neutral faint
+ * tint with no glyph. The label never carries a leading "+"; pass `format` to control the
+ * magnitude string (defaults to a one-decimal percentage of the absolute value).
+ *
+ * Mantine-free (plain `<span>` + this folder's CSS module, docs/CONTROLS-SPEC.md §2.2) so
+ * `WidgetHeader` can compose it from inside `charts/` without tripping `basalt/token-layer-
+ * boundary` or `check-dist-layering.mjs`.
+ *
+ * @example
+ * import { DeltaBadge } from 'basalt-ui'
+ *
+ * <DeltaBadge value={12.4} />                          // ▲ 12.4%, success tint
+ * <DeltaBadge value={-3.1} />                           // ▼ 3.1%, danger tint
+ * <DeltaBadge value={0} />                              // 0.0%, neutral faint tint, no glyph
+ * <DeltaBadge value={182} format={(v) => `${Math.abs(v)}ms`} withGlyph={false} />
+ */
+import { alpha, VX } from '../tokens'
+import classes from './widget-header.module.css'
+
+export type DeltaBadgeProps = {
+  /** Signed delta driving tone (positive/negative/zero) and, by default, the label magnitude. */
+  value: number
+  /** Formats the value into the label text. Defaults to `${Math.abs(value).toFixed(1)}%`. */
+  format?: (value: number) => string
+  /** Render the ▲/▼ direction glyph. Defaults to `true`; a zero value never shows a glyph. */
+  withGlyph?: boolean
+  /** Optional comparison timeframe rendered directly after the value in a dimmer shade of the same
+   * tone (e.g. `MoM`, `WoW`, `YTD`) — states what the delta is measured against without a hover. */
+  period?: string | undefined
+}
+
+const defaultFormat = (value: number): string => `${Math.abs(value).toFixed(1)}%`
+
+export function DeltaBadge({
+  value,
+  format = defaultFormat,
+  withGlyph = true,
+  period,
+}: DeltaBadgeProps) {
+  const tone = value > 0 ? VX.status.good : value < 0 ? VX.status.bad : VX.faint
+  const glyph = value > 0 ? '▲' : value < 0 ? '▼' : undefined
+  const showGlyph = withGlyph && glyph !== undefined
+
+  return (
+    <span
+      className={classes.deltaBadge}
+      style={{ backgroundColor: alpha(tone, 0.13), color: tone }}
+    >
+      {showGlyph && <span className={classes.deltaGlyph}>{glyph}</span>}
+      {format(value)}
+      {period !== undefined && <span className={classes.deltaPeriod}>{period}</span>}
+    </span>
+  )
+}

package/src/widget-header/index.ts

@@ -0,0 +1,2 @@
+export { WidgetHeader, type WidgetHeaderProps } from './widget-header'
+export { DeltaBadge, type DeltaBadgeProps } from './delta-badge'

package/src/widget-header/no-mantine.test.ts

@@ -0,0 +1,33 @@
+/**
+ * `src/widget-header/**` must stay Mantine-free (docs/CONTROLS-SPEC.md §2.2) — so `ChartCard`
+ * (inside the `charts/` boundary) can compose `WidgetHeader`/`DeltaBadge` without tripping
+ * `basalt/token-layer-boundary` or `check-dist-layering.mjs`. Source-level regex check, same idiom
+ * as `styles.floor.test.ts`'s direct read of shipped text — independent of oxlint, which only runs
+ * over changed files locally and could be skipped.
+ *
+ * The pattern matches an actual import/re-export specifier, not any mention of "@mantine" in
+ * prose — this module's own doc comments say "Mantine-free" and name `@mantine/*` on purpose.
+ */
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, test } from 'bun:test'
+
+const WIDGET_HEADER_DIR = dirname(fileURLToPath(import.meta.url))
+const MANTINE_IMPORT = /(?:from|import)\s*\(?\s*['"]@mantine\//
+
+const sourceFiles = readdirSync(WIDGET_HEADER_DIR).filter(
+  (name) =>
+    (name.endsWith('.ts') || name.endsWith('.tsx')) &&
+    !name.endsWith('.test.ts') &&
+    !name.endsWith('.test.tsx'),
+)
+
+describe('src/widget-header — Mantine-free', () => {
+  for (const name of sourceFiles) {
+    test(`${name} imports no '@mantine/*' module`, () => {
+      const text = readFileSync(join(WIDGET_HEADER_DIR, name), 'utf8')
+      expect(text).not.toMatch(MANTINE_IMPORT)
+    })
+  }
+})