basalt-ui 1.28.0 → 1.29.1

package/agent/rules/basalt-tokens.md

@@ -8,7 +8,7 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
 <!-- backed by: guard kinds — css-raw-surface, inline-font-size, off-identity-accent, off-system-surface-var, raw-color-fn, raw-font-family, raw-hex, raw-radius, raw-surface, surface-shadow-override, theme-allow-unscoped · oxlint rules — basalt/no-raw-font-size, basalt/raw-size-literal, basalt/token-layer-boundary -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
@@ -32,10 +32,9 @@ The accent is **split by ROLE**, and this is the one thing an author gets wrong:
   control always reads white on either page. **Never fill with `VX.accent`.**
 
 **The palette is DERIVED, not authored** (`tokens/derive.ts` from one seed + five bounded knobs), and
-a consumer retunes it through `createBasaltTheme(overrides?, { derive, fonts, radius, density })`.
-That is why no hex, no shade index and no pixel constant belongs in a rule, a doc or a component:
-every one of them is an output of a config the consumer may move. Read the values off `VX.*` and the
-theme; read the numbers, when you genuinely need them, off `tokens/palette.ts`.
+a consumer retunes it through `createBasaltTheme(overrides?, { derive, fonts, radius, density })` —
+no hex, shade index or pixel constant belongs in a rule, doc or component. Read values off `VX.*`
+and the theme; read raw numbers, if you need them, off `tokens/palette.ts`.
 
 ## Color — never a raw literal
 
@@ -44,28 +43,26 @@ theme; read the numbers, when you genuinely need them, off `tokens/palette.ts`.
   in non-component files) or through the Mantine theme (`color` / `c` / `bg`, `theme.colors`).
 - **Opacity is `alpha(token, a)`** (`color-mix`), never `rgba()` — so the hue keeps resolving per
   scheme.
-- **No off-identity Mantine accents.** `teal`/`violet`/`grape`/`indigo`/`pink` still render
-  on-palette (the theme reskins every family), and are rejected anyway because they signal
-  off-identity intent. Allowed: **`blue`** (the one earned hue), **`gray`**, and the status names
-  `red`/`green`/`orange`/`yellow`. A positive delta is `color="green"`, never `teal`.
-- **Never pin a shade index** — `c="yellow.7"`, `bg="blue.4"`, `var(--mantine-color-red-6)` each name
-  one fixed swatch that is identical in both schemes, so the shade that is legible on dark is the one
-  that fails on light. Use `VX.status.*` for a verdict, or the bare hue name and let the theme pick.
+- **No off-identity Mantine accents** — allowed: **`blue`** (the earned hue), **`gray`**, and the
+  status names `red`/`green`/`orange`/`yellow`. A positive delta is `color="green"`, never `teal`.
+- **Never pin a shade index** (`c="yellow.7"`, `var(--mantine-color-red-6)`) — one fixed swatch is
+  identical in both schemes, so what's legible on dark fails on light. Use `VX.status.*` or the
+  bare hue name.
 - **"Ink earns its color."** Default to neutral. A hue is justified by trend, signal/status, or
   genuine multi-series separation. The accent lands on the single primary CTA per view, focus rings,
   links and small status pops — never on borders, large fills, routine icons or secondary buttons.
 - **Categorical/series color is consumer data**, declared once through `defineSeries` →
-  `seriesTokens`/`groupTokens` and wired into `buildPaletteCss`, never a Mantine accent prop and
-  never an inline pair. `groupTokens(GROUP, MAP)` assumes the same map reaches
-  `BasaltProvider`'s `paletteOptions.groups` under the key `` `${GROUP}-` `` — **with the trailing
-  dash**, which is a CSS-var prefix and not a group name. Derive both from one `GROUP` constant;
-  a mismatch emits refs to variables the stylesheet never declares, with no tsc error and no
-  runtime throw — just unstyled charts.
+  `seriesTokens`/`groupTokens` and wired into `buildPaletteCss`, never a Mantine accent prop.
+  `groupTokens(GROUP, MAP)` assumes the map reaches `BasaltProvider`'s `paletteOptions.groups`
+  under the key `` `${GROUP}-` `` — **with the trailing dash**. Derive both from one `GROUP`
+  constant; a mismatch emits refs to variables the stylesheet never declares, silently.
 
 ## Surfaces — one collapsed token set
 
 `VX.surface` is exactly: `bg` · `panel` · `panelHover` · `elevated` · `subtle` · `overlay` ·
-`field` · `border` · `hairline`. Plus `VX.divider` — NOT a surface, the ONE seam/line token (every `AppShell` region edge + between-rows rule, ink-/white-alpha, holds under the derive knobs); `hairline` is the card ring, `border` the control/overlay line — neither is ever a seam.
+`field` · `border` · `hairline`. `VX.divider` is NOT a surface — the one seam/line token (every
+`AppShell` region edge + between-rows rule); `hairline` is the card ring, `border` the
+control/overlay line — neither is ever a seam.
 
 The theme **collapses Mantine's raw ramp steps onto those tokens** (`cssVariablesResolver` + theme
 `styles`), so every Mantine component — AppShell, Table, Input, Divider, Tabs, Popover, Accordion,
@@ -79,13 +76,12 @@ and never reach for a raw ramp-step var (`var(--mantine-color-gray-N)`).
   the integer that happens to equal `md` today; `radius="sm"`, never a numeric radius.
 - **Card radius has one source**, `VX.radiusCard` / `--vx-radius-card`: the Mantine chrome and the
   Mantine-free `ChartCard` resolve to the same token. Cards must never diverge.
-- **Sub-scale micro-spacing is legitimate and allowed raw** — a tight cluster below the scale's
-  first step has no token, so use the raw number rather than inventing a micro-token or peppering
-  `theme-allow`. The same permission holds in CSS modules: a declaration whose every literal is
-  micro does not fire. One non-micro value makes the whole declaration a finding, and an inline
-  style OBJECT in TSX still fires, because there the Mantine prop existed.
-- **Dense by default** — the framework targets compact surfaces; reach for the tighter step.
-- **Icons size through the icon's own `size` prop**, which is not spacing.
+- **Sub-scale micro-spacing is legitimate and allowed raw** — below the scale's first step, use the
+  raw number rather than inventing a micro-token. A CSS-module declaration whose every literal is
+  micro does not fire; one non-micro value makes it a finding, and an inline style OBJECT in TSX
+  still fires (there the Mantine prop existed).
+- **Dense by default** — reach for the tighter step. Icons size through their own `size` prop,
+  which is not spacing.
 
 ## Type
 
@@ -113,48 +109,31 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
 <Widget style={{ borderRadius: 3 }} />
 ```
 
-- **An annotation must START its comment** — after `//`, `/*`, `<!--`, a block gutter `*`, or
-  nothing but whitespace. Prose that merely MENTIONS the token waives nothing; a file documenting
-  its own waivers used to disarm itself.
-- **File scope is spelled, never inferred**: `theme-allow-file <id>… — <why>`, anywhere in the file.
-  A bare `theme-allow-file` waives nothing at all.
-- **A typo waives nothing.** A word in the id slot naming no rule is recorded as unknown; the
-  annotation still covers the ids it got right. Because the id slot is read strictly, a bare reason
-  needs a separator — `theme-allow: <why>` or `theme-allow <id> — <why>`, never `theme-allow <why>`.
-- **Three placements work, and both engines agree on all three**: the reported line, a comment-ONLY
-  line directly above it (reaching the first CODE line below, through the rest of its comment
-  block), and in CSS a trailing annotation reaching back over the declaration it terminates. A blank
-  line ends the reach — that is how you say "this comment is not about the next statement".
-- **JSON and `.webmanifest` take a member key**, since they cannot hold a comment. For a manifest
-  the first remedy is `basaltAppPlugin`, not a waiver: a hand-copied hex drifts from the palette.
-- **The three import-boundary rules honour no escape at all** (`visx-boundary`, `visx-tooltip`,
-  `token-layer-boundary`) — an architecture boundary a stray comment can switch off is the bypass
-  they exist to prevent. The agent-chat guards honour `basalt-agent-allow`, a separate token that
-  never waives a `theme-allow` finding, or the reverse.
-
-Unsupported shapes are asserted as unsupported in both engines' test grids (`src/guard/
-check-source.test.ts`, `configs/oxlint-plugin.test.ts`), so "unsupported" and "silently broken"
-cannot read the same. **Audit them**: `basalt-ui check-theme --audit-allows` re-runs the scan with each waiver
-neutralized, one at a time, and **exits 1 on a waiver that suppresses nothing** — a dead waiver
-silently covers the next real finding on that line. It judges plugin-rule waivers too, by re-running
-oxlint; where oxlint is unreachable the verdict is "cannot judge", never "dead". Its scope line is
-part of the report: `0 dead` is not `0 dead anywhere`.
+- **An annotation must START its comment** (`//`, `/*`, `<!--`, a `*` gutter, or bare whitespace) —
+  a mention mid-prose waives nothing.
+- **File scope is spelled, never inferred**: `theme-allow-file <id>… — <why>`, anywhere in the
+  file; a bare one waives nothing.
+- **A typo waives nothing** — an unrecognized id is recorded unknown, the rest of the annotation
+  still covers the ids it got right.
+- **Three placements agree in both engines**: the reported line, a comment-only line directly
+  above it, and (CSS) a trailing annotation reaching back over the declaration it terminates. A
+  blank line ends the reach.
+- **JSON/`.webmanifest` take a member key** — first remedy is `basaltAppPlugin`, not a waiver.
+- **The three import-boundary rules honour no escape at all**; the agent-chat guards honour
+  `basalt-agent-allow`, a separate token that never waives a `theme-allow` finding, or the reverse.
+
+**Audit them**: `basalt-ui check-theme --audit-allows` re-runs the scan with each waiver
+neutralized and **exits 1 on a waiver that suppresses nothing**; it judges plugin-rule waivers too
+by re-running oxlint. Scope is part of the report — `0 dead` is not `0 dead anywhere`.
 
 ## Wiring the guard
 
 `check-theme` reads `package.json`'s `"basalt"` key (`roots`, `exempt`, `include`, `profile`,
-`severity`, `exemptRules`, …). **`roots` is not optional in practice** — omitted, it falls back to
-`src` relative to cwd, which is zero files for anything under `apps/*/src`; `init` writes a real one
-and `doctor`'s `guard-scan` fails when it resolves to nothing. The scan also reaches each root's
-PARENT for its `index.html` and `public/` tree, because that is where a `theme-color` meta and a
-webmanifest's `background_color` live. Wire it as `oxlint . && basalt-ui check-theme` — what `init`
-seeds as `lint:basalt`.
-
-**When it fires, fix the source** — the right token first. `theme-allow` is for a documented
-exception; a palette-definition file belongs in `exempt`, not behind a comment.
-
-**The guard sees palette, not vocabulary.** A fork written by a token-fluent author uses exactly the
-right tokens, so no palette guard can see it — `basalt/shadow-basalt-export` catches an exact name
-collision and nothing else, and renaming the fork is what a fork's author does anyway. It is a
-tripwire, not coverage. The habit is the control: **check whether basalt already ships the thing
-before building it.**
+`severity`, `exemptRules`). **`roots` is not optional in practice** — omitted, it falls back to
+`src` relative to cwd (zero files under `apps/*/src`); `init` writes a real one. Wire it as
+`oxlint . && basalt-ui check-theme` — what `init` seeds as `lint:basalt`.
+
+**When it fires, fix the source** — the right token first; a palette-definition file belongs in
+`exempt`, not behind a comment. **The guard sees palette, not vocabulary** — a token-fluent fork
+uses exactly the right tokens, so `basalt/shadow-basalt-export` (an exact name collision) is a
+tripwire, not coverage. Check whether basalt already ships the thing before building it.

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

@@ -36,6 +36,8 @@ own `.oxlintrc.json` costs.
 ```tsx
 // main.tsx — CSS order is load-bearing: every @mantine/*/styles.layer.css, THEN basalt's
 import '@mantine/core/styles.layer.css'
+import '@mantine/notifications/styles.layer.css' // one per MOUNTED battery: notifications, spotlight…
+import '@mantine/spotlight/styles.layer.css'
 import 'basalt-ui/styles.css'
 import { BasaltProvider, createBasaltTheme } from 'basalt-ui'
 import { BasaltOverlays } from 'basalt-ui/commands'

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

@@ -2,32 +2,29 @@
 
 ## basalt-ui (managed — do not hand-edit)
 
-Placed by `bunx basalt-ui init` and refreshed by `basalt-ui sync` after every upgrade
-(`sync --check` gates drift in CI). Framework-owned: edit `DESIGN.md` or your own files instead —
-changes here are overwritten on the next sync.
+Placed by `bunx basalt-ui init`, refreshed by `basalt-ui sync` (`sync --check` gates drift in CI).
+Framework-owned: edit `DESIGN.md` or your own files — this block is overwritten on the next sync.
 
-**Stack:** React 19 + Mantine v9, themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`), Bun
-runtime, oxlint + oxfmt (no ESLint/Biome/Prettier), no Tailwind. Color comes from the three-tier
-`--vx-*` token system — read `VX.*` or a series token, never a raw hex/`rgb()`/`hsl()`. Charts are
-visx via `basalt-ui/charts`. `basalt-ui check-theme` plus the `basalt/*` oxlint rules are the teeth.
+**Stack:** React 19 + Mantine v9 themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`), Bun,
+oxlint + oxfmt (no ESLint/Biome/Prettier), no Tailwind. Color is the three-tier `--vx-*` token system —
+`VX.*` or a series token, never a raw hex. Charts are visx via `basalt-ui/charts`; `check-theme` + the
+`basalt/*` oxlint rules are the teeth.
 
 **Precedence — the only statement of it.** Highest wins; a lower layer fills gaps and never
 overrides a higher one:
 
 > consumer `DESIGN.md` (app deltas) > the six shipped `basalt-*` rules > the `basalt-*` skills
 
-**All six rules are law** — `basalt-tokens`, `basalt-mantine`, `basalt-charts`, `basalt-state`,
-`basalt-controls`, `basalt-batteries` in `.claude/rules/`, each carrying a generated
-`<!-- basalt:coverage -->` header naming what enforces it and what is only advisory. The skills
-(`/basalt-app`, `/basalt-design`, `/basalt-charts`) are the METHOD that obeys them, never law.
+**All six rules are law** — `basalt-{tokens,mantine,charts,state,controls,batteries}` in
+`.claude/rules/`, each with a generated `<!-- basalt:coverage -->` header naming what enforces it and
+what is only advisory. The skills (`/basalt-app`, `/basalt-design`, `/basalt-charts`) are METHOD, never law.
 
 **Run the LOCAL bin, not `bunx`** — `./node_modules/.bin/basalt-ui`, or a `package.json` script.
 `bunx` does not re-resolve a cached package, so it can answer for a version you upgraded away from;
 `init` is the one legitimate `bunx` invocation, because nothing is installed yet.
 
-**Before guessing an import, read the installed package's machine docs** — `llms.txt` (per-subpath
-import map) and `AGENTS.md`, at the install directory. In a workspace that is under the package that
-depends on basalt, not the repo root; `basalt-ui doctor`'s `basalt-resolves` line prints where.
+**Before guessing an import, read the installed package's `llms.txt` and `AGENTS.md`** — at the
+install directory (in a workspace, under the depending package; `basalt-ui doctor` prints where).
 
 @./DESIGN.md
 
@@ -37,4 +34,7 @@ noise/grain and dramatic motion. Here: the shipped three-font system, depth from
 with a 1px ring, neutral-by-default with the single accent spent only when earned — trend, signal,
 or genuine categorical separation. Restraint **is** the identity.
 
+**Chart-doctrine override.** A global `visx-charts` rule auto-loading on `**/charts/**` is generic
+non-basalt discipline; here `basalt-charts` supersedes it — compose `CartesianChart`.
+
 <!-- basalt:end -->

package/agent/templates/query-client.ts.tpl

@@ -4,7 +4,7 @@
  *
  * Scaffold written by `basalt-ui init`. This file is yours — `basalt-ui sync` will not overwrite it.
  */
-import { createBasaltQueryClient } from 'basalt-ui/query'
+import { createBasaltQueryClient } from 'basalt-ui'
 
 export const queryClient = createBasaltQueryClient({
   // staleTime: 60_000,   // optional: global cache freshness window (ms)