basalt-ui 1.19.1 → 1.21.0

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

@@ -53,6 +53,28 @@ own the files.
 - `.basalt/manifest.json` — a sha256 per managed file + the basalt-ui version that wrote it, so
   `sync` can three-way diff and `doctor` can spot a stale install.
 
+It also patches `package.json`: **`basalt.roots`** inferred from the real layout (workspace packages
+depending on basalt or Mantine, else every workspace `src/`, else `src`) and a **`lint:basalt`**
+script (`oxlint . && basalt-ui check-theme`). Everything derives from `roots` — the guard's scan, the
+seeded CI `oxfmt` globs, the default exemption — so a workspace repo without it scaffolds a guard
+that scans zero files while every gate reports green. Correct it if your sources live elsewhere. A
+Mantine-free consumer adds `"basalt": { "profile": "tokens-only" }` by hand; `check-theme` never
+infers that, because inferring it from a missing `@mantine/core` would silence 17 kinds on a repo
+that simply keeps Mantine in another workspace package.
+
+**`init` on an EXISTING app is a lint-debt event, not a no-op.** Adopting the shipped preset turns
+on whole oxlint plugins the repo was never linted against, so previously-clean code lands with real
+findings on the first run. `init` names the plugins and every file it kept — plus what keeping it
+costs (an existing `.oxlintrc.json` that does not `extends` the preset means the entire basalt lint
+half is off, and nothing else says so; `--merge-lint` splices it in). Run `oxlint .` and triage
+before the next commit; turn a rule off with a written reason rather than disabling a plugin.
+
+Then `basalt-ui doctor`. `SKIPPED` is a third outcome beside pass/warn/fail and exits non-zero on
+its own — a check that could not run is not a check that passed — and the hard checks now include
+`basalt-resolves`, `guard-scan` (would `check-theme` cover more than zero files?) and
+`oxlint-preset` (does `.oxlintrc.json` really extend the preset? JSONC is parsed, not rejected).
+Expect doctor to go red where it was green on an older basalt; that is the point.
+
 After `init`, do the runtime wiring (the CLI scaffolds files, not your app's composition):
 
 ```tsx
@@ -94,10 +116,18 @@ ordering (e.g. alongside `@content-collections/vite`) and the full head/PWA/mani
 import 'basalt-ui/styles.css' // @layer basalt base styles, iOS input safety net, font stack
 ```
 
-Lint wires as `oxlint . && basalt-ui check-theme` — the theme guard is the teeth behind the token
-doctrine. The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts`
-on a plain app, `apps/web/src/lib/series.ts` on a monorepo; override via `basalt.seriesModulePath`) is the
-single guard-exempt palette source — see `/basalt-charts`.
+Lint wires as `oxlint . && basalt-ui check-theme` (seeded as the `lint:basalt` script) — the theme
+guard is the teeth behind the token doctrine. Before writing any composite, check whether basalt
+already ships it: round 4 found ~15 forked copies of shipped components across seven repos, all
+passing every gate, because a fork by a token-fluent author uses exactly the right tokens.
+`basalt/shadow-basalt-export` reads all nine published barrels since 1.20.1 (the charts layer
+included), but it warns only on an **exact** name collision — round 5 found the renamed forks
+(`Cell`, `Box`, `Stat`) sail straight past it. It is a tripwire, not coverage; nothing catches the
+rest. Ask before you build; do not wait to be told.
+
+The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts` on
+a plain app, `apps/web/src/lib/series.ts` on a monorepo; override via `basalt.seriesModulePath`) is
+the single guard-exempt palette source — see `/basalt-charts`.
 
 ## Refresh: `bunx basalt-ui sync`
 
@@ -140,13 +170,22 @@ both.
 - A thin `DESIGN.md` (deltas) + the thirteen `basalt-*` rules + the managed CLAUDE block are present.
 - `<first basalt.root>/lib/series.ts` exists as the one guard-exempt series source (for any app metric colors).
 - `basalt-ui sync --check` wired in CI (recommended) to catch drift on future upgrades.
+- `basalt-ui doctor` run after `init` and read to the last line — a `SKIPPED` check exits non-zero
+  and is not a pass.
 
 ## Notes
 
 - `init`, `sync`, and `check-theme` are all **real**. `sync` reconciles via a sha256 three-way diff
   (`--check` is a CI drift gate, `--force` overwrites local edits); `check-theme` is the palette
-  guard; `doctor` verifies the installed basalt-ui version against the manifest. All via
-  `bunx basalt-ui …`.
+  guard; `doctor` checks resolution, version, guard scan, oxlint preset, spacing-scale drift and
+  cross-package `ai` major parity. All via `bunx basalt-ui …`.
+- **Not a React app?** `bunx basalt-ui tokens:css --out src/tokens.css` emits the `--vx-*` layer with
+  no package in your dependency tree, `--selector-class dark` for the Tailwind `<html class="dark">`
+  convention, and `fonts:css` emits the shipped `--basalt-font-*` stacks. Both carry the two-line
+  `@generated basalt-ui` header the guard skips on — that header verbatim, and then only the LINES
+  that are basalt custom properties, selectors, `}` or self-closing comments, so the marker pasted
+  into a `.tsx` suppresses nothing and a declaration added to such a file is still reported — and
+  both take `--check` as a CI drift gate. See `docs/FRAMEWORK-FREE.md` in the basalt-ui repo.
 - The framework ships **no** icon or notification dep — pass icons as `ReactNode` and wire toasts
   yourself (e.g. `ThemeLabControls`' `copyIcon` / `onCopy`).
 - The framework DOES ship `motion` (motion.dev, formerly framer-motion) as a bundled dependency —

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

@@ -210,9 +210,11 @@ import { ChartCursorScope } from 'basalt-ui/charts'
   `AxisLeftNumeric` / `AxisRightNumeric` / `AxisBottomDate` (escape via `theme-allow`).
 - **No hand-rolled plot assembly.** `basalt/hand-rolled-plot` fails the build on a chart-assembly
   primitive (`AxisLeftNumeric`, `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`)
-  rendered in a file that doesn't compose `CartesianChart`. Escape: a `theme-allow` comment on the
-  first such site — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`, `Donut`) declares
-  itself. The file that defines `CartesianChart` is exempt definitionally.
+  rendered in a file that doesn't compose `CartesianChart`, per NODE. Escape:
+  `theme-allow hand-rolled-plot — <why>` on the one node, or `theme-allow-file hand-rolled-plot —
+<why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`,
+  `Donut`) declares itself. `-file` is the 1.20.1 spelling and it is required. The file that defines
+  `CartesianChart` is exempt definitionally.
 - **No hand-authored legends.** `basalt/chart-legend-literal` fails the build on a hand-written
   array literal passed to `ChartLegend`'s `items` — derive it from the same `series` the chart draws
   (`deriveLegend`, or let `ChartFrame`/`CartesianChart` do it) so it can't name a series the plot no

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

@@ -2,8 +2,9 @@
 
 ## basalt-ui (managed — do not hand-edit)
 
-Scaffolded by `bunx basalt-ui init` and refreshed by `bunx basalt-ui sync` (run it after a basalt-ui
-upgrade; `basalt-ui sync --check` gates drift in CI). This block is framework-owned — edit `DESIGN.md`
+Scaffolded by `bunx basalt-ui init` (the one command that legitimately predates the install) and
+refreshed by the locally installed `basalt-ui sync` after every upgrade; `basalt-ui sync --check`
+gates drift in CI. This block is framework-owned — edit `DESIGN.md`
 or the `basalt-*` rules instead; manual changes here are overwritten on the next sync.
 
 **Stack:** React 19 + Mantine v9, themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`).
@@ -18,9 +19,14 @@ code must follow) — never import `@visx/*` outside a `charts/` directory (oxli
 Toolchain is oxlint + oxfmt (no ESLint/Biome/Prettier) and `basalt-ui check-theme` guards the
 palette. Runtime is Bun.
 
-**Before guessing an import, check the installed package's machine docs**:
-`node_modules/basalt-ui/llms.txt` (per-subpath import map), `node_modules/basalt-ui/AGENTS.md`, or
-run `bunx basalt-ui info --json`.
+**Before guessing an import, read the installed package's machine docs — `llms.txt` (per-subpath
+import map) and `AGENTS.md`, at the install directory.** That is `./node_modules/basalt-ui` only on
+a single-package app. In a workspace, basalt resolves under the package that depends on it
+(`packages/<name>/node_modules/basalt-ui`), and the repo root may have no copy at all. Run
+`basalt-ui doctor` — its `basalt-resolves` line prints the resolved install dir and version; read
+the two files there. Invoke the CLI through the **locally installed** bin (the `lint:basalt` script
+seeded by `init` shows the path); `bunx basalt-ui` fetches a second copy from npm and can answer
+for a different version than the one you are building against.
 
 **DESIGN.md is law.** `./DESIGN.md` (imported below) records this app's palette identity and series
 dictionary. Precedence: **DESIGN.md > `basalt-*` rules > skills.** When building or restyling any

package/configs/check.yml

@@ -5,8 +5,14 @@
 # color literals / off-identity accents that bypass the --vx-* token system).
 # `basalt-ui sync --check` fails when the basalt-managed files (rules, skills, the
 # CLAUDE block) have drifted from the installed basalt-ui version.
-# The oxfmt globs below are rendered from `basalt.roots` at init time — this file is a
-# template, not a raw copy, so a monorepo doesn't seed a `src/**` that matches nothing.
+# The oxfmt globs below are rendered from `basalt.roots` at init time — `init` writes that
+# key from the repo's real layout (workspace packages included), so a monorepo does not
+# seed a `src/**` that matches nothing.
+# The basalt-ui command below is the LOCAL bin, rendered from where basalt actually
+# installed. `bunx basalt-ui` is deliberately not used: when the package is not resolvable
+# from the working directory (bun's isolated linker puts it beside the package that depends
+# on it, not at the root) bunx silently downloads a DIFFERENT copy from npm and the gate
+# runs a version nobody pinned.
 name: check
 on:
   pull_request:
@@ -23,8 +29,9 @@ jobs:
           bun-version: latest
       - run: bun install --frozen-lockfile
       - run: bunx oxlint .
-      - run: bunx basalt-ui check-theme
-      - run: bunx basalt-ui sync --check
+      - run: '{{BASALT_BIN}} doctor'
+      - run: '{{BASALT_BIN}} check-theme'
+      - run: '{{BASALT_BIN}} sync --check'
       - run: bunx oxfmt {{ROOTS_GLOBS}} '!**/dist/**' --check
       # Enable once your app defines these package.json scripts:
       # - run: bun run typecheck

package/configs/lefthook.yml

@@ -2,10 +2,32 @@
 # `basalt-ui init` seeds a lefthook.yml that references this file:
 #   extends:
 #     - node_modules/basalt-ui/configs/lefthook.yml
-# lefthook merges these commands with the consumer's own, so this preset auto-updates
-# with the package. Runs oxlint + oxfmt on staged files and the theme guard on the whole
-# tree, pre-commit. Assumes oxlint/oxfmt are installed and your .oxlintrc.json extends
-# ./node_modules/basalt-ui/configs/oxlint.json.
+# so this preset auto-updates with the package. Runs oxlint + oxfmt on staged files and the theme
+# guard on the whole tree, pre-commit. Assumes oxlint/oxfmt are installed.
+#
+# ── HOW OVERRIDING ACTUALLY WORKS (read before trying) ───────────────────────────────────────────
+# An `extends` target WINS over your own lefthook.yml on a colliding key. Verified with
+# `lefthook dump`: declare `pre-commit.commands.oxfmt.run` (or `glob:`) in your file and the
+# preset's value is what runs — yours is discarded silently, with no warning. Only keys this preset
+# does NOT define merge in from yours. So:
+#   • `env:`, `exclude:`, `skip:` and any command name not used here — yours, they merge.
+#   • `run:` and `glob:` on a command below — NOT overridable. Do not try.
+# The sanctioned seams are therefore:
+#   • `BASALT_BIN` (below) — set it via `env:` to point the guard at a specific CLI.
+#   • `exclude:` — carve files out of a glob you cannot narrow.
+#   • a differently-named command of your own, plus `skip: true` on the one here you are replacing.
+#
+# It does NOT assume your `.oxlintrc.json` extends the shipped preset — that assumption was
+# false for exactly the repos this seed exists for, since `init` KEEPS an existing oxlint
+# config. `basalt-ui doctor` now checks the extends and hard-fails when it is missing OR when it
+# points at a path that does not resolve; run it in CI (the seeded check.yml does) rather than
+# trusting a comment nobody reads.
+#
+# `init` seeds the path RESOLVED from where basalt actually installed. Under bun's isolated
+# linker basalt lives beside the package that depends on it, not at the repo root, and a
+# root-relative `extends` there resolves to nothing — silently, because lefthook merges a missing
+# file into ZERO commands and exits 0. `basalt-ui doctor`'s `lefthook-preset` check is the only
+# thing that can see that state; nothing else errors.
 pre-commit:
   parallel: true
   commands:
@@ -15,9 +37,20 @@ pre-commit:
     # `css` is load-bearing, not tidiness: oxfmt formats stylesheets, so without it a CSS-only
     # commit passes the hook and then fails the same check in CI. `oxlint` above deliberately
     # stops at JS — it has nothing to say about CSS.
+    #
+    # SOURCE EXTENSIONS ONLY, deliberately. This glob used to include `json,md,yml,yaml`, which
+    # reached every staged file at the repo ROOT — and oxfmt pads markdown table separators, so it
+    # blocked commits on a consumer's CLAUDE.md and docs/ over a house style basalt has no opinion
+    # about, in files their own `format` script does not own. Since you cannot narrow this glob
+    # (see the override note above), the preset has to be the one that is narrow. Markdown, YAML
+    # and JSON stay yours: add them to your own `format` script if you want them formatted.
+    #
+    # `--no-error-on-unmatched-pattern` covers the case where every staged file is excluded by an
+    # ignore file: oxfmt exits 2 on "Expected at least one target file", which failed a docs-only
+    # commit for any consumer carrying a .prettierignore — and, again, they could not add the flag.
     oxfmt:
-      glob: '*.{ts,tsx,js,jsx,css,json,md,yml,yaml}'
-      run: bunx oxfmt --check {staged_files}
+      glob: '*.{ts,tsx,js,jsx,css}'
+      run: bunx oxfmt --check --no-error-on-unmatched-pattern {staged_files}
 
     # NO glob, deliberately. This command scans the configured `basalt.roots` — it never reads
     # {staged_files} — so any glob here is a gate on WHETHER the guard runs, decided by the file
@@ -28,5 +61,24 @@ pre-commit:
     # was written against: a guard that only runs when someone remembers to run it is not a guard.
     # Without this, a consumer accumulates violations indefinitely while `check-theme` is never
     # invoked, and the kinds it never ran are indistinguishable from the kinds that found nothing.
+    #
+    # `$BASALT_BIN` is the one sanctioned override seam here, because `run:` itself is not
+    # overridable (see the note at the top). It defaults to `bunx --no-install basalt-ui`:
+    #   • `--no-install` because a plain `bunx basalt-ui` in a repo where basalt is not resolvable
+    #     from the ROOT (bun's isolated linker puts it beside the package that depends on it)
+    #     silently downloads a DIFFERENT copy from npm and gates the commit with a version nobody
+    #     pinned. With the flag it fails loudly instead, which is the answer you can act on.
+    #   • point it at the local bin to fix that, exactly as the seeded check.yml does:
+    #       pre-commit:
+    #         commands:
+    #           check-theme:
+    #             env: { BASALT_BIN: ./packages/web/node_modules/.bin/basalt-ui }
+    #
+    # Lefthook runs commands at the REPO ROOT, while in a monorepo the `basalt` config and the
+    # manifest live in a package below it — verified to produce `0 files scanned`, i.e. following
+    # this preset installed a gate that never gated. `check-theme` now relocates to the single
+    # workspace package carrying a basalt config and says so; with more than one, set BASALT_CWD
+    # in the same `env:` block to name the package:
+    #   env: { BASALT_CWD: apps/web }
     check-theme:
-      run: bunx basalt-ui check-theme
+      run: ${BASALT_BIN:-bunx --no-install basalt-ui} check-theme