basalt-ui 1.25.0 → 1.26.0

package/agent/rules/basalt-tokens.md

@@ -1,322 +1,160 @@
 ---
 source: basalt-ui
-description: Color, spacing, radius, and type discipline — route every value through the basalt-ui token system. Enforced by `basalt-ui check-theme`.
+description: Color, spacing, radius and type discipline — route every value through the basalt-ui token system. Enforced by `basalt-ui check-theme` plus the oxlint type-scale rules.
 paths:
   - 'src/**'
   - 'apps/**/src/**'
   - 'packages/**/src/**'
 ---
 
-# Basalt Tokens — Color, Spacing, Radius, Type
+<!-- basalt:coverage -->
+<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --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 -->
 
-basalt-ui ships one color/type/spacing/radius identity shared by the Mantine chrome and the visx
-charts. The **identity is modern zinc** (long form: <https://github.com/jkrumm/basalt-ui/blob/master/docs/DESIGN-SPEC.md>, which does not ship in the
-package) —
-**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` 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
-surface (60/30/10, pushed toward 90/10); the accent only points — primary CTA, focus, links, small
-status pops — never floods. (Blueprint/Basalt zinc-charcoal are the historical hue-tuning
-ancestors; DESIGN-SPEC supersedes both — see its "Doctrine inversions" section.) This
-rule is the operational checklist; it is enforced mechanically by **`basalt-ui check-theme`**
-(wire it into `lint`: `oxlint . && basalt-ui check-theme`; `init` seeds that as `lint:basalt`). A
-violation fails the build. Escape hatch: a scoped `theme-allow <rule-id> — <reason>` comment
-(diff-visible, deliberate) — see the contract below.
+# Basalt Tokens — color, spacing, radius, type
 
-`check-theme` reads its config from your `package.json` `"basalt"` key
-(`{ roots?, exempt?, include?, profile?, severity?, spacingSteps?, forbiddenAccents? }`); set `roots`
-to your source dirs and `exempt` to the files that legitimately define palette values.
+## The identity (stated once, here)
 
-**`roots` is not optional in practice.** Omitted it falls back to `src` relative to the cwd — fine
-for a single-app repo, zero files for anything under `apps/*/src`, and `check-theme` then exits 1
-with `0 files scanned`. Since 1.20.0 `init` writes a real `roots` from the detected layout and
-`doctor`'s `guard-scan` check fails when the configured roots resolve to nothing; before that a repo
-could look fully wired while the gate scanned nothing.
+basalt-ui ships ONE identity shared by the Mantine chrome and the visx charts: **cool-neutral zinc
+surfaces on both schemes**, a page slightly darker than its panels, depth from a whisper shadow with
+a 1px ring baked in rather than a hairline border, and **one saturated sky-blue accent** that only
+points. Neutrals carry ~90% of the surface.
 
-The scan reaches slightly beyond `roots`: each root's PARENT contributes its `index.html` and its
-`public/` tree (the Vite layout basalt's own preset assumes), because that is where a `theme-color`
-meta and a webmanifest's `background_color` actually live. `.json` is never blanket-scanned — name a
-design-surface JSON in `basalt.include`, the only route to one.
+The accent is **split by ROLE**, and this is the one thing an author gets wrong:
 
-## `theme-allow` — the 1.21.0 contract
+- **As ink** — links, active-nav icon, chart lines, focus ring — it is read against the page, so it
+  inverts across schemes. `VX.accent`.
+- **As a filled surface** — a control carrying a white label — it cannot invert: it is squeezed
+  between the label's contrast and the page's, which leaves one narrow luminance band. `VX.accentFill`,
+  labelled with `VX.onAccent`. Every Mantine family's fill sits in that same band, so a filled
+  control always reads white on either page. **Never fill with `VX.accent`.**
 
-The full grammar, in both engines:
-
-```text
-theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
-theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules  (unscoped without a why)
-theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those rules; a bare one waives NOTHING
-"basalt:theme-allow[-file]": "<id>… — <why>" → the same two, for JSON / .webmanifest
-```
-
-An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin rule
-(`hand-rolled-plot`, `raw-scroll-container`, …), with or without the `basalt/` prefix.
-
-```tsx
-// theme-allow raw-surface — third-party widget needs a literal corner
-<Widget style={{ borderRadius: 3 }} />
-```
-
-- **An annotation must START its comment** — after `//`, `/*`, `<!--`, a block-comment gutter `*`,
-  or nothing but whitespace. Before 1.21.0 any comment that merely _mentioned_ the token parsed as
-  the bare blanket form and switched every rule off on the line below: linewatch documented its own
-  waivers in a docblock and thereby disarmed the file. Prose about the escape hatch no longer waives
-  anything; everything a consumer actually writes still qualifies.
-- **File scope is spelled, not inferred.** `theme-allow-file <id>… — <why>`, anywhere in the file.
-  Plain `theme-allow` is the node/line waiver in both engines. At 1.20.0 the two halves of the
-  contract intersected at exactly one legal shape and that shape was whole-file — naming a rule and
-  giving a reason was read as a file declaration, which is why per-node scoping did not actually
-  ship. **This is the consumer break in 1.21.0**: move each existing file declaration one word.
-- **A bare `theme-allow` still waives everything on its placement** but reports
-  `theme-allow-unscoped` (`warn` for one minor, then `error`). A bare `theme-allow-file` waives
-  nothing at all — whole-file blanket immunity off one unnamed comment is the thing this contract
-  exists to price.
-- **Spell the id right — a typo waives nothing.** A word in the id slot that names no rule is
-  recorded as unknown and suppresses nothing; the annotation covers exactly the ids it got right.
-  Because the id slot is read strictly, a prose reason has to be introduced by a separator:
-  `theme-allow: <why>` or `theme-allow <id> — <why>`, never `theme-allow <why>`.
-- **JSON and `.webmanifest` get a member key**, since they have been scanned since 1.20.0 and cannot
-  hold a comment — their findings were unwaivable and the printed remedy prescribed something
-  impossible. `"basalt:theme-allow-file": "raw-hex — a PWA manifest theme_color must be a literal"`
-  carries the same grammar. For a manifest the first remedy is `basaltAppPlugin`, not a waiver: a
-  hand-copied hex drifts from the palette.
-- **Three placements work and both engines agree on all three**: the reported line, a comment-ONLY
-  line directly above it (the only form JSX can express — the reported line is usually a multi-line
-  opening tag or a `{expr}` child), and in CSS a trailing annotation reaching back over the
-  declaration it terminates. The third is what survives the shipped `oxfmt` reflowing a long
-  `background-color` so the hex lands ABOVE the comment.
-- **A comment-only annotation reaches the first CODE line below it**, walking through the rest of
-  its own comment block. A wrapped reason, or a docblock's `*/`, used to absorb the waiver so the
-  natural shape silently waived nothing — argo hit that three times in one upgrade. A blank line
-  still ends the block; that is how you say "this comment is not about the next statement".
-- **`basalt/hand-rolled-plot` grants whole-file immunity only through `theme-allow-file`.** Every
-  assembly node is otherwise waived on its own.
-- **Eight shapes are asserted NOT to waive, in both halves.** They are pinned as unsupported rather
-  than merely left out, so "unsupported" and "silently broken" stop reading the same. Don't write
-  them:
-
-  | Shape                                                                                                                              | Why it does not waive                                                                                               |
-  | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-  | a blank line between the annotation and the code — after `//`, after `{/* */}`, or after a `{/*` whose closer sits on its own line | a blank line is how you say "this comment is not about the next statement"                                          |
-  | the token mid-sentence in a line comment, a docblock gutter, or a JSX expression comment                                           | prose that MENTIONS the token is not an annotation — the reason it must START its comment                           |
-  | the token inside a string literal                                                                                                  | same                                                                                                                |
-  | above a multi-line OPENING tag, when the finding sits on a later attribute line                                                    | a waiver reaches the first line below its comment, not an arbitrary line further down — put it beside the attribute |
-
-  The whole grid — four axes, comment style × token position × where the closer falls × what
-  follows — is pinned row for row in `src/guard/check-source.test.ts` (37 supported + these 8) and
-  `configs/oxlint-plugin.test.ts` (32 + 8; five of the guard's rows are CSS/HTML/JSON dialects
-  oxlint never sees). Zero disagreements between the two, and no waiver tally moved in any of the
-  seven consumer repos.
-
-### Audit them: `basalt-ui check-theme --audit-allows`
-
-Reports instead of scanning. For every annotation and every `basalt.exemptRules` entry it re-runs
-the guard with that one occurrence neutralized, so the verdict comes from the scan rather than from
-parsing the waiver's text:
-
-```text
-theme-allow annotations (3):
-src/shell/x.tsx:42    suppresses raw-surface@43
-src/theme/y.ts:18     SUPPRESSES NOTHING — dead, delete it
-src/charts/z.tsx:7    suppresses hand-rolled-plot@8 (oxlint)
-
-basalt.exemptRules entries (1):
-raw-hex: "site.webmanifest"  suppresses findings in public/site.webmanifest — <the recorded reason>
-
-3 live, 1 dead, 0 unjudgeable, 0 unaccountable (reported as theme-allow-unscoped by a normal run).
-Scope: the N file(s) check-theme scans — everything under basalt.roots (…), plus each root's
-sibling index.html and public/ tree, plus anything named in basalt.include (none). …
-```
-
-**Two sections, not one list** — annotations first, then `basalt.exemptRules`, each with its own
-count. A plugin-rule annotation is judged too (since 1.22.0, by re-running oxlint over one
-neutralized sibling file), so `unjudgeable` now means only "names no rule at all" or "oxlint could
-not be run here" — never "not a check-theme kind". The scope line is part of the report: `0 dead`
-is not `0 dead anywhere`.
-
-It closes with a `live / dead / unjudgeable / unaccountable` tally and **exits 1 on a dead
-waiver**, so it wires into CI. A waiver that stopped covering anything is not harmless: it silently
-covers the next real finding on that line. Basalt's own source had one; it is deleted.
-
-### New in 1.20.0 — five guard kinds, all `warn` for one minor
-
-| Kind                      | Fires on                                                                                                            |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `theme-allow-unscoped`    | a `theme-allow` with no rule id, no reason, or an id that names no rule                                             |
-| `surface-shadow-override` | a `boxShadow` built FROM tokens that REPLACES `--vx-shadow-card` instead of composing with it                       |
-| `css-raw-surface`         | the kebab dialect of the surface kinds in CSS (`border-radius: 6px`); sub-scale corners and circle/pill values pass |
-| `inline-font-size`        | `style={{ fontSize: 11 }}` — the `check-theme` half of `basalt/no-raw-font-size`, for a CI that runs only the guard |
-| `hidden-inline-style`     | a multi-line opening tag, or a style object hoisted to a const — `raw-html-layout`'s formatting-independent half    |
-
-Two new oxlint rules ship at `warn` alongside them: **`basalt/shadow-basalt-export`** (below) and
-**`basalt/hand-rolled-shell`** (`AppShell` parts or `Burger` in a file that does not render
-`BasaltShell`). **`basalt/raw-size-literal` is now `error`** — CSS-length strings on
-`size`/`fz`/`fontSize`. Every kind keeps its own boolean, `basalt.severity` and `exemptRules`.
-
-## The guard sees palette, not vocabulary
-
-Round 4 swept seven consumer repos: every gate green, and ~15 independently re-rolled copies of
-components basalt already ships (`StatCard` in 4 of 4 apps, `EmptyState`, a 266-line hand-rolled
-`AppShell`). A fork written by a token-fluent author uses exactly the right tokens, so no palette
-guard can ever see it. **`basalt/shadow-basalt-export` is a cheap detector, not a safety net** — the
-rule says so in its own message: it is a **tripwire, not coverage**, and silence is not evidence that
-nothing is forked.
-
-- **Exact name match only** — the one limit that is structural. Round 5 confirmed the miss rate:
-  linewatch's forks are named `Cell` and `Box`, rb's is `Stat`. Rename the fork and the rule goes
-  quiet, which is what a fork's author naturally does.
-- **Scope: basalt consumers only, and component-shaped declarations only.** Since 1.22.0 the rule
-  gates on `isBasaltScopedFile` like every other rule in the file, and needs a function, an arrow, a
-  `memo`/`forwardRef` wrapper or a class extending one. A plain data class sharing a name with a
-  shipped export is a collision, not a fork — it fired on a `SlugTracker` class in a React-free
-  package that cannot import basalt-ui.
-- **Scope: everything importable.** Since 1.21.0 it reads all nine published barrels, not just
-  `dist/index.d.ts` — so the `basalt-ui/charts` layer, which is where forks actually live, is finally
-  covered. Names a barrel merely re-exports from a third party are skipped: `./charts` passes
-  `Bar` / `Line` / `Pie` straight through from `@visx/shape`, and a local `Bar` is not a fork of
-  anything basalt wrote.
-
-So the renamed majority goes unreported. **Detection does not substitute for expressiveness**: a
-composite that cannot express a common case gets routed around by compliant-looking code, and a
-name-collision rule only catches the authors who did not bother to rename. The habit it stands in
-for is the actual control: check whether basalt already ships the thing before building it.
-
-## Filled surfaces — the fill band
-
-A filled control is a SURFACE, not ink, and it does not invert across schemes. It is squeezed from
-both sides at once: a **white label** needs ≥4.5:1 against the fill, and the control needs ≥3:1
-against the page behind it — on BOTH pages. That leaves one narrow luminance band, so:
-
-- **Every family's fill sits in that band** (`FILL` / `ACCENT` in the palette): the hue varies, the
-  luminance does not. Every filled surface therefore reads WHITE, on either page, at ~4.9:1.
-- **Never fill with the ink accent.** `--vx-accent` is light on dark by design (it is read against
-  the page) — filling with it puts a white label on a light blue button. Fill with
-  `--vx-accent-fill` / `--vx-fill-{family}`; label with `--vx-on-accent` / `--vx-on-{family}`.
-- **Never decide a foreground yourself**, and do not trust Mantine's `autoContrast`: it resolves the
-  color once in JS, scheme-blindly, using a brightness heuristic that does not track WCAG contrast.
-  The theme emits `--vx-on-*` per scheme instead, and every filled control is bound to it.
-- Hover is **derived** from the fill in CSS, so retuning a fill carries its hover along.
-
-Retuning a fill OUTSIDE the band breaks its label. `theme/contrast.test.ts` fails the build on it.
+**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`.
 
 ## Color — never a raw literal
 
-- **No raw `#hex` / `rgb()` / `rgba()` / `hsl()`** in scanned source. Route every color through the
-  palette: `VX.*` tokens (from `basalt-ui/tokens` or `basalt-ui/charts` — they are CSS vars, so they
-  work in components AND non-component files), or the Mantine theme (`color`/`c`/`bg` props, `theme.colors`).
-  Opacity via `alpha(token, a)` — never `rgba()` — so the hue keeps resolving per color scheme.
-- **No off-identity Mantine accents.** `color`/`c`/`bg`/`backgroundColor` must not be
-  `teal`/`violet`/`grape`/`indigo`/`pink`. `createBasaltTheme` reskins _every_ Mantine accent to the
-  Basalt identity, so those names still render on-palette — but the guard rejects them because they
-  signal off-identity intent. Allowed accents: **`blue`** (the one earned identity hue — the
-  saturated sky accent), **`gray`** (neutral), and the status hues **`red`/`green`/`orange`/`yellow`**
-  (muted/forest, never raw Material/AntD). Categorical/series color goes through series tokens
-  (`defineSeries` → `seriesTokens`/`groupTokens`), never a Mantine accent prop. Success-button flips
-  and positive deltas use `color="green"` (forest green), not `teal` (vivid turquoise).
-- **"Ink earns its color"** — default to neutral. A hue is justified only for trend, signal/status,
-  or genuine multi-series separation. A count badge is a signal → it may carry blue; a nav active-state
-  is UI chrome → it stays neutral (`NavCountBadge` already encodes this). Active nav renders a
-  **neutral surface fill** + plain text + a weight bump, never the accent — baked into the theme's
-  NavLink `--nl-*` defaults across every render path (including a router `<Link>` hosted through
-  `SidebarItem.Anchor`).
-- **Accent restraint, mechanically.** The accent lands on exactly the single primary CTA per view
-  (`variant="filled"`), focus rings, links, and small status pops — nowhere else. Routine/secondary
-  buttons use `variant="default"` (neutral); don't reach for a colored `variant="light"` (it reads
-  washed-out on the warm light canvas). Neutrals carry borders, large fills, and routine icons.
+- **No raw `#hex` / `rgb()` / `rgba()` / `hsl()` in scanned source.** Route color through `VX.*`
+  (from `basalt-ui/tokens` or `basalt-ui/charts` — they are CSS vars, so they work in components AND
+  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.
+- **"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.
 
 ## Surfaces — one collapsed token set
 
-The surface token set is **`bg` · `panel` · `elevated` · `subtle` · `border`**:
+`VX.surface` is exactly: `bg` · `panel` · `panelHover` · `elevated` · `subtle` · `overlay` ·
+`field` · `border` · `hairline`. Plus `VX.divider` for layout separators, which is NOT a surface.
 
-- `--vx-surface-bg` (`VX.surface.bg`) — the page background.
-- `--vx-surface-panel` (`VX.surface.panel`) — the card/`Paper` background.
-- `--vx-surface-elevated` (`VX.surface.elevated`) — a lifted surface (chart areas, tooltips).
-- `--vx-surface-subtle` (`VX.surface.subtle`) — a faint hover/striped/track surface: a step
-  **below white on light** (`#f2f2f1`), **above panel on dark** (`#323239`). Used for Table
-  hover/striped rows, `Code`, the `SegmentedControl` track, and Tabs/Accordion/Menu hover.
-- `--vx-surface-border` (`VX.surface.border`) — the single hairline border token.
-
-The theme **collapses Mantine's raw ramp steps onto these tokens** (`cssVariablesResolver` plus
-theme `styles`): light/dark border ramp steps → `--vx-surface-border`, light hover steps →
-`--vx-surface-subtle`, card bg → `--vx-surface-panel`, `--app-shell-border-color` →
-`--vx-surface-border`. So **every** Mantine component (AppShell, Table, Input, Divider, Tabs,
-Popover, Accordion, cards) renders one border shade, one card background, and one radius
-(`--vx-radius-card`). Never inline a surface color or reach for a raw ramp-step var
-(`var(--mantine-color-gray-N)`) — the `off-system-surface-var` guard rejects it.
+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,
+Card — renders one border shade, one card background and one radius. Never inline a surface color
+and never reach for a raw ramp-step var (`var(--mantine-color-gray-N)`).
 
 ## Spacing & radius — prefer the scale token
 
-- `baseTheme` owns the scales: `spacing` 11/13/18/20/26 → `xs…xl`, `radius` 2/4/6/16/32 → `xs…xl`.
-  Both are DERIVED — `deriveSpacing(level)` / `deriveRadius(level)` in `tokens/palette.ts` move them
-  with `createBasaltTheme`'s `density` / `radius` knobs, so read the numbers as level-0 values, not
-  as constants. **Use the token**, not the raw number, when a value equals a step: `p="md"` not
-  `p={18}`, `gap="sm"` not `gap={13}`, `radius="sm"` not `radius={4}`. The guard flags exact
-  token-equals (`p={18}`, any numeric `radius`).
-- **Card radius has one source: `--vx-radius-card` (7px) = `VX.radiusCard`.** Every
-  card corner — the Mantine chrome (`Card`/`Paper`, `radius="md"`) and the Mantine-free `ChartCard`
-  (`var(--vx-radius-card)`) — resolves to this single token; cards must never diverge. Don't inline
-  a `borderRadius` on a surface (the `raw-surface` guard rejects it).
-- **Dense by default.** The framework targets compact (Linear/Notion) surfaces — prefer the tighter
-  spacing step (`sm`/`xs`) for shell, nav, and card padding rather than `md`/`lg` air (see
-  basalt-mantine.md for the shipped dense defaults).
-- **Sub-scale micro-spacing is legitimate and allowed raw** — `gap={2}`, `pl={4}`, `mt={6}` have no
-  token equivalent (the scale starts at 11). Use them freely for tight clusters; don't invent
-  micro-tokens or pepper `theme-allow`. One-off layout dims (`h={36}`, `w={64}`) are also fine raw.
-  **The same permission holds in CSS modules**, where it has to be enforced differently: there is no
-  prop form to prefer, so `inline-spacing` simply does not fire on a declaration whose every literal
-  is ≤ 10px (`gap: 2px`, `padding: 4px 8px`). It reads longhands and logical properties too
-  (`padding-top`, `margin-inline`, `row-gap`, `padding-inline-start`), not just the shorthands.
-  `rem` resolves against the 16px root, so `0.25rem` and `4px` get the same answer; units that need
-  layout context (`em`, `%`, `ch`, `vw`) are not micro-spacing claims and flag. A `var()` component
-  is dropped before that judgement; one non-micro value makes the whole declaration a finding
-  (`padding: 4px 16px` flags). An inline style OBJECT in TSX (`style={{ padding: 4 }}`) also still
-  flags: there the Mantine prop exists and should have been used.
-- **Icons** size via the icon's own `size` prop (`size={16}`), not spacing tokens — that's not spacing.
+- `baseTheme` owns both scales and both are DERIVED (`deriveSpacing(level)` / `deriveRadius(level)`
+  move them with the `density` / `radius` knobs). **Use the token, not the number**: `p="md"`, not
+  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.
 
 ## Type
 
-- A shipped **three-font system**: `Nunito Sans Variable` (body), `Hubot Sans Variable` (headings,
-  brand, card titles — always `font-stretch: 88%`), `JetBrains Mono Variable` (all numerals,
-  micro-labels, kbd/badges, axis ticks). Fonts ship as exact-pinned `@fontsource-variable/*` deps,
-  `@import`ed in `styles.css`; the `--basalt-font-{sans,head,mono}` vars stay the override seam
-  (system-font fallback chains preserved). Type is carried by Mantine's `fontSizes` + `headings` +
-  the named `fontWeights` ladder (`fw="semibold"`, `fw="medium"`, …) and `fontFamilyMonospace` for
-  numbers. Don't hard-code `fontSize` in px on chrome; use `size`/`fz` tokens.
-
-## `groupTokens` ↔ `paletteOptions.groups` — the prefix lockstep
+Three fonts: sans (body), a condensed head font (headings, brand, card titles), mono (every numeral,
+micro-label, kbd, axis tick). They ship as exact-pinned `@fontsource-variable/*` peers imported by
+`basalt-ui/styles.css`; `createBasaltTheme(_, { fonts })` is the ONE override seam, writing the
+`--basalt-font-*` vars. Size and weight come from the theme's `fontSizes` / `headings` / named
+`fontWeights` ladder (`fw="semibold"`) — never a hardcoded `fontSize`, and never a CSS-length string
+on `size`/`fz`.
 
-`groupTokens(GROUP, MAP)` (from `basalt-ui/tokens` or `basalt-ui/charts`) generates `var(--vx-GROUP-key)`
-refs assuming the same map is also handed to `BasaltProvider`'s `paletteOptions.groups` under the key
-`` `${GROUP}-` `` (**with the trailing dash** — `paletteOptions.groups` is keyed by CSS-var _prefix_,
-not by group name). Drift between the two — e.g. calling `groupTokens('activity', MAP)` but wiring
-`paletteOptions={{ groups: { activity: MAP } }}` (missing the dash) — emits token refs that point at
-CSS variables the palette stylesheet never declares: no tsc error, silent unstyled/transparent charts
-at runtime. Derive both from one `GROUP` constant so they can't drift:
+## `theme-allow` — the escape hatch and its grammar (stated once, here)
 
-```ts
-// theme/series.ts
-export const GROUP = 'activity'
-export const colors = groupTokens(GROUP, SERIES) // -> var(--vx-activity-key)
-export const paletteGroups = { [`${GROUP}-`]: SERIES } // -> { 'activity-': SERIES }
+```text
+theme-allow                                  → this node/line, EVERY rule   (reports theme-allow-unscoped)
+theme-allow <id>[, <id>…] [— <why>]          → this node/line, those rules  (unscoped without a why)
+theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those rules; a bare one waives NOTHING
+"basalt:theme-allow[-file]": "<id>… — <why>" → the same two, for JSON / .webmanifest
 ```
 
+An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin rule
+(`hand-rolled-plot`, `hand-rolled-filter`, …), with or without the `basalt/` prefix.
+
 ```tsx
-// main.tsx
-<BasaltProvider paletteOptions={{ groups: paletteGroups }}>{/* app */}</BasaltProvider>
+// theme-allow raw-surface — third-party widget needs a literal corner
+<Widget style={{ borderRadius: 3 }} />
 ```
 
-## When the guard fires
-
-Fix the source, don't silence it — reach for the right token first. Only add `theme-allow` for a
-genuine, documented exception (a third-party widget needing a literal), scoped to the rule id, with
-a reason: a bare `// theme-allow` passes the check, tells the next reader nothing, and now reports
-`theme-allow-unscoped` besides. The palette-definition files are listed in your `exempt` set so they
-don't self-trip. A stylesheet emitted by `basalt-ui tokens:css` needs no entry — in a `.css` file
-carrying that exact two-line `@generated basalt-ui` header, the guard skips the LINES that are
-basalt custom properties, selectors, `}` or self-closing comments. Pasting the marker anywhere else
-suppresses nothing, and an ordinary declaration added to such a file is still reported.
+- **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`.
+
+## 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.**