basalt-ui 1.25.0 → 1.27.0

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

@@ -1,268 +1,76 @@
 ---
 name: basalt-design
-description: Design and restyle data visualizations and analytics UIs in a basalt-ui app (Mantine v9 + visx). The dataviz successor — restraint doctrine plus the live theme-lab tuning loop and the centralized, lint-enforced --vx-* token system. Use when building or restyling charts/dashboards, choosing a palette, tuning dark/light, or when charts look childish / inconsistent / over-colored.
-when_to_use: User is building or restyling charts, dashboards, or metric UIs in a basalt-ui consumer; picking or tuning a palette; deciding on dark/light shades; or complaining that charts look "AI default", inconsistent across tabs, or over-saturated. Also the entry point for any "make this look professional" dataviz request in a Mantine + visx app.
+description: Design and restyle dashboards, charts and metric UIs in a basalt-ui app (Mantine v9 + visx) — the procedure: read the law, decide before coding, tune by eye in the theme lab, bake the values back into the palette. Use when building or restyling charts/dashboards, choosing or tuning a palette, or when a UI looks childish / inconsistent / over-colored.
+when_to_use: User is building or restyling charts, dashboards or metric UIs in a basalt-ui consumer; picking or tuning a palette; deciding dark/light shades; or complaining that a UI looks "AI default", inconsistent across tabs or over-saturated. Also the entry point for any "make this look professional" request in a Mantine + visx app.
 ---
 
-`/basalt-design` is the design authority for a basalt-ui app. It is the **method**; the project's
-doctrine is the **law**. Professional dataviz is restraint, not decoration — this skill encodes
-that restraint and the concrete, lint-enforced way basalt-ui makes it impossible to bypass.
+`/basalt-design` is the METHOD. The law is the `basalt-*` rules plus this app's `DESIGN.md`, and the
+managed `CLAUDE.md` block states which wins — read them, do not re-derive them here. This skill is
+the sequence to follow and the loop to run.
 
-## Read the law first (strict precedence)
+## 1. Load the law before touching code
 
-Before applying any generic guidance, load the doctrine in this exact order and obey the highest
-one that exists. Lower layers fill gaps; they never override a higher layer.
+- `.claude/rules/basalt-tokens.md` — the identity, the color/spacing/type law, `theme-allow`.
+- `.claude/rules/basalt-mantine.md` — provider, shell, surfaces, depth, motion.
+- `.claude/rules/basalt-controls.md` — where a control lives and what sizes it.
+- `.claude/rules/basalt-charts.md` — the chart contract. `/basalt-charts` is the how-to.
+- `./DESIGN.md` — this app's deltas: identity confirmation, series dictionary, deviations.
 
-1. **Consumer `DESIGN.md`** (repo root) — the thin, app-specific instantiation. Identity
-   confirmation, the series dictionary, app deviations. **This wins on every conflict.** It is the
-   Google-spec convention (YAML token front matter + Markdown prose, sibling to `CLAUDE.md`).
-2. **Shipped `basalt-*` rules** (`.claude/rules/basalt-{tokens,charts,mantine,state}.md`) — the
-   universal law AND its enforcement: the Basalt modern-zinc palette + saturated sky accent,
-   one-hue-per-metric, neutral structure, gradient defaults, the three-tier token contract, the
-   elevation/density doctrine.
-3. **This skill** — only the loop and the judgment, where the above are silent.
+**No `DESIGN.md` means the app was never scaffolded** — run `/basalt-app` first. Never invent a
+palette ad hoc.
 
-If a consumer `DESIGN.md` does not exist yet, the app has not been scaffolded — run `/basalt-app`
-(it wraps `basalt-ui init`, which writes the thin `DESIGN.md` and the `basalt-*` rules). Do not invent
-a palette ad hoc.
+## 2. Decide before coding
 
-## Restraint doctrine (decide before touching code)
+Answer these four in one pass; each one is a decision, not a preference:
 
-This is the same restraint `frontend-design` calls for, applied to data: intentionality over
-intensity. The `basalt-ui init` CLAUDE block sets a restraint override for exactly this reason — in a
-dashboard the bold move is calm.
+1. **What earns a hue here?** Trend, signal/status, or genuine categorical separation. Everything
+   else is neutral. One hue per metric, stable across every view.
+2. **Where does each control live?** One home per control, and the home sets its size (law C1/C5).
+3. **What is the one primary action on this view?** Exactly one filled accent; everything else
+   neutral.
+4. **What does this surface reuse?** Check the shipped composite FIRST — `StatCard`, `ChartCard`,
+   `Section`, `BasaltDataTable`, `QueryState`, `EmptyState`. A fork by a token-fluent author passes
+   every gate, so no guard will tell you; asking is the control. If a composite genuinely cannot
+   express the case, that is a gap to REPORT, not to route around.
 
-- **One muted hue family, reused everywhere.** The Basalt modern-zinc identity (below), never raw
-  Material / AntD / Tailwind primaries (they read childish and clash). A small harmonious subset
-  across every page so tabs feel like one app.
-- **Single hue per metric.** Each metric owns ONE color, stable across all views (HRV always
-  violet, bench always amber). Series colors are app-side and distinct from the UI accent — don't
-  reuse the sky accent as a metric hue. Multiple colors only for genuinely categorical data
-  (sleep stages, source breakdown). A line chart almost never needs more than one hue plus neutrals.
-- **Neutral structure, colored signal.** Lines/axes/grids in muted neutrals; color is the data and
-  status (good/warn/bad). A single neutral line with a soft tinted area reads more premium than a
-  rainbow.
-- **Gradients on areas, not everything.** A soft single-hue vertical gradient under a line is the
-  canonical "modern" move (`AreaGradient`). Keep stacked-area bands opaque — transparency leaks
-  lower bands.
-- **Quiet chrome.** Hairline grids (~6–8% neutral), thin crosshairs, restrained tooltips with a
-  card surface and one accent swatch per row. Generous whitespace.
-- **Motion restraint (same doctrine, applied to animation).** Subtle and purposeful, never
-  decorative — a state change earns a transition, idle chrome does not. Reach for the shared
-  `MOTION_DURATION` / `MOTION_SPRING` tokens (`basalt-ui`'s `src/motion`) instead of inventing
-  per-component durations/easings, so animated chrome feels like one identity the same way the
-  `--vx-*` palette does for color. Never a looping/pulsing idle animation. Always respect
-  `useReducedMotion` (`@mantine/hooks`) — an animated component needs a real unanimated code path,
-  not just `duration: 0`.
+## 3. Build it
 
-## Color identity & accent restraint (the #1 lever)
+Compose Mantine primitives and shipped composites; pull every color from `VX.*` / a series token.
+Let the theme carry size, radius, depth and font — a prop you did not have to pass is the point.
 
-The Basalt identity is **modern zinc + a saturated sky accent** — cool-neutral zinc surfaces
-(Tailwind zinc family) on both schemes, a slightly darker page with panels lifting off it via depth
-(a whisper shadow + 1px ring, `shadow-card` — never a bare border), and one saturated sky-blue
-accent. Restraint is now about _placement_, not _saturation_ — the accent is louder than the old
-muted-slate identity, so the discipline below (where it appears / where it never appears) carries
-more of the weight.
+## 4. Tune by eye, then bake
 
-**Neutrals carry the surface — cool zinc on both schemes**, never warm-neutral/off-white, never
-steel-blue, never pure black/white:
-
-- **Dark:** bg `color-mix(in srgb, #27272a 70%, #18181b)` (#232326), panel `#27272a`, panel-hover
-  `color-mix(in srgb, #3f3f46 50%, #27272a)` (#333338), hairline (card ring)
-  `color-mix(in srgb, #52525c 50%, #3f3f46)` (#494951), line (strong border) `#3f3f46`. Ink
-  `#e5e5e5`, muted `#d4d4d4`, faint `#a1a1a1`.
-- **Light:** bg `color-mix(in srgb, #f4f4f5 50%, #e4e4e7)` (#ececee), panel `#f4f4f5`, panel-hover
-  `#fafafa`, hairline `#e5e5e5`, line (strong border) `color-mix(in srgb, #e4e4e7 50%, #d4d4d8)`
-  (#dcdce0). Ink `#262626`, muted `#525252`, faint `#737373`.
-
-The surface token set is `bg` (page) · `panel` (cards, controls) · `panel-hover` · `line` (strong
-border) · `hairline` (card ring, lives inside `shadow-card`, never rendered as a bare `border`) ·
-`divider` (layout separators).
-
-**One accent, saturated sky-blue — split by ROLE.** As **ink** (links, active-nav icon, chart lines,
-focus ring) it is read against the page, so it inverts: `#0077bd` light / `#8ec5ff` dark. As a
-**filled surface** it carries a label, so it is squeezed between that label (≥4.5:1) and the page
-behind it (≥3:1) — which leaves one luminance band, the same on both pages: `#0077bd` with a WHITE
-label, in BOTH schemes. Fill with `--vx-accent-fill` / `--vx-fill-{family}`, never with `--vx-accent`
-(a light fill cannot carry white text). Every Mantine family's fill sits in that same band, so a
-filled surface always reads white. With `accent-hover` (derived from the fill) and `on-accent`
-companions (NOT the old ~50%-saturation muted slate).
-
-The accent appears on: the primary data series, active-nav **icons** and active **child** labels,
-links, primary buttons, focus rings, and the leader bar in meters. It stays off: general chrome,
-borders, large fills, every icon, secondary buttons. "Ink earns its color" — neutral does the
-structure, the accent only points.
-
-- **Active nav = an ink-9% tint + accent-colored icon + weight-600 ink text** — no panel fill, no
-  shadow, and never a full accent fill. It's a selected row, not a raised control. The theme bakes
-  this into `NavLink` for every render path — don't re-color it.
-- **Buttons:** exactly one filled-accent primary CTA per view; every other action is
-  `variant="default"` (neutral). Avoid colored `variant="light"` for routine actions.
-- **Status:** positive deltas `color="green"` (forest), never `teal`/turquoise/saturated emerald.
-- **Dark done right:** cool zinc, neutral/faint-cool, never steel-blue, never pure black; the
-  dark-scheme accent (`#8ec5ff`) is lighter/less saturated than its light counterpart so it doesn't
-  glow/bleed.
-- **Light done right:** cool zinc page + panel lift (never warm/off-white); depth comes from
-  `shadow-card`, not a bare hairline border.
-
-### Density & surface consistency
-
-- **Dense by default** (Linear/Notion): compact nav rows, `sm` (12px) gaps and card padding, a
-  48px shell header. Separate by surface + `shadow-card`, not by large air — default to the
-  tighter step.
-- **All cards render identically:** Mantine `Card`/`Paper` **and** the Mantine-free `ChartCard`
-  resolve to **one radius token** (`--vx-radius-card` = 7px) and **`shadow-card`** — a whisper
-  shadow with the 1px ring baked into the shadow itself, **no `border` property**. Never
-  inline-override a surface's `border`/`borderRadius`/`boxShadow`/`backgroundColor` — use the
-  radius token + `VX.surface.*` / the shadow-card token. Mechanically enforced by
-  `basalt-ui check-theme`'s `raw-surface` guard.
-- **Depth splits control-vs-panel-vs-floating** — three tokens, not one. Panels holding content
-  (Card/Paper/Notification/ChartCard) take `shadow-card`; anything you click or type into (Button,
-  ActionIcon, inputs, chips, the search trigger) takes `shadow-raised`, whose ring is INSET so one
-  value rides a fill, a tint and a panel alike; detached floating surfaces (Tooltip/Popover/Menu/
-  Modal/Drawer) take `shadow-overlay`. Depth is static — nothing lifts or gains a shadow on hover,
-  and emphasis is carried by fill weight, never z-height. Full doctrine in the `basalt-mantine`
-  rule.
-- **Strict surfaces & primitives.** The theme runs a strict surface system: Mantine components read
-  raw ramp steps directly, so `cssVariablesResolver` **collapses the ramp steps onto the
-  `--vx-surface-*` tokens** — one depth token per tier, one card bg, one radius across every
-  component (AppShell, Table, Input, Divider, Tabs, Popover, Accordion, cards). Consumer code must
-  **use Mantine layout primitives** (`Box`/`Flex`/`Grid`/`SimpleGrid`/`Stack`/`Group`/`Paper`/`Card`),
-  not raw `<div>`/`<span>` with inline `style`. `check-theme` adds five guard kinds to enforce this
-  (default ON, `theme-allow` escape): `off-system-surface-var` (raw ramp-step vars),
-  `mantine-shade-index` (a shade-pinned color — `c="yellow.7"` is one fixed swatch in both schemes;
-  use `VX.status.*` or the bare hue name), `raw-html-layout`, `inline-spacing`, `inline-display`.
-  Only the Mantine-free `src/charts/**` may use raw `<div>` (still with `VX.*` tokens).
-- **Reach for the shipped composite before wrapping one.** A `StatCard` carrying a threshold verdict
-  takes `tone="good" | "warn" | "bad"` (an accent rail down its leading edge). Omitting `tone` is not
-  the same as `"good"` — omitted means "fine, or nothing measured" and stays untinted, so `"good"` is
-  a positive assertion you opt into for a value that earned it (`0 min` downtime), never a default.
-  A chart goes in `ChartCard`. Wrapping
-  a shipped card in a hand-positioned `Box` to add a mark it already has is how an app grows a second
-  card idiom — one the guard cannot recognize as a card, and therefore cannot police. If a composite
-  genuinely can't express what you need, that is a gap to report, not to route around.
-
-**Anti-slop checklist:** no pure `#000`/`#fff`; one accent locked page-wide; neutral does the
-structure, accent only points; don't flood blue; hierarchy via scale/weight/contrast/space, not
-color; depth = `shadow-card` (whisper shadow + ring), never a bare hairline border on cards.
-
-## The three-tier token system (centralize + enforce)
-
-Aesthetics only survive if they cannot be bypassed. basalt-ui ships this as the `./tokens` and
-`./charts` surfaces:
-
-1. **Palette data** — the Basalt modern-zinc ramps + the saturated sky accent family, plus
-   every semantic/status/neutral/surface entry as a per-theme `{ light, dark }` pair. Pure data: no
-   React, no `@mantine/*`, no browser API.
-2. **CSS variables** — `buildPaletteCss(opts)` emits the pairs as `--vx-*` custom properties under
-   the light/dark color-scheme selector. Theme resolution is **pure CSS** — no JS branching, works
-   in non-component files.
-3. **Token refs** — `VX.*` are just `var(--vx-*)` strings (colors) plus non-color sizing constants.
-   Opacity via `alpha(token, a)` (= `color-mix`), **never** `rgba()` — the hue must keep resolving
-   per scheme.
-
-Hard rules (the guard enforces these, not just prose):
-
-- **Never a raw hex / `rgb()` / `hsl()` in chart or app source.** Route every color through
-  `VX.*` / the palette. `basalt-ui check-theme` fails the build on a literal; a `theme-allow` comment
-  is the only deliberate exception.
-- **Never `localStorage.getItem('theme')`.** The scheme resolves via Mantine's color scheme + the
-  `--vx-*` vars. The guard bans this read.
-- New colors go into the palette as `{ light, dark }` pairs — never inline, never two
-  `fooLight`/`fooDark` keys.
-
-```ts
-import { VX, alpha } from 'basalt-ui/tokens'
-import { SERIES } from '../lib/series' // consumer-owned — see /basalt-charts
-
-const stroke = SERIES.hrv // app-side series ref (consumer-defined — see /basalt-charts)
-const fill = alpha(SERIES.hrv, 0.12) // theme-aware soft area, NOT rgba()
-const grid = VX.grid // framework neutral
-```
-
-## Drive the theme-lab loop (tune by eye, then bake)
-
-Static HTML POCs do not translate 1:1 to visx/Mantine. Tune in the **real app** with the shipped
-theme lab (`basalt-ui/theme-lab`), then bake the values into the palette. The lab writes overrides
-as inline `--vx-*` styles on `<html>`, which beat the stylesheet's per-scheme rules — so everything
-restyles **instantly with no React re-render**.
-
-Wire it (DEV-only) inside a dev dock popover:
+A static POC never translates 1:1 to visx + Mantine. Tune in the REAL app with the shipped lab
+(`basalt-ui/theme-lab`), which writes inline `--vx-*` overrides on `<html>` — they beat the
+stylesheet, so everything restyles instantly with no React re-render.
 
 ```tsx
 import { ThemeLabControls, applyOverrides, loadOverrides } from 'basalt-ui/theme-lab'
 
-// At boot — re-apply a persisted tuning session (the control body does NOT do the initial apply):
-applyOverrides(loadOverrides())
-
-// In the dev dock — pass the consumer's own series groups so they're tunable too:
-<ThemeLabControls
-  groups={[
-    ...COLOR_GROUPS,                       // framework: Semantic / Status / Neutral / Surface
-    { title: 'Health', items: [{ var: '--vx-hrv', label: 'HRV' }, /* ... */] },
-  ]}
-  onCopy={(json) => notifications.show({ message: 'Overrides copied' })}
-  copyIcon={<IconCopy size={16} />}        // framework ships no icon/notification dep
-  resetIcon={<IconRefresh size={16} />}
-/>
+applyOverrides(loadOverrides()) // at boot — the control body does NOT do the initial apply
+;<ThemeLabControls groups={[...COLOR_GROUPS, appSeriesGroup]} onCopy={notifyCopied} />
 ```
 
-The loop:
-
-1. Open the lab, adjust `--vx-*` colors and the area-gradient strength (`--vx-area-top` /
-   `--vx-area-bottom`) by eye, in both schemes.
-2. Toggle the Mantine color scheme and re-check: saturated mid-tones **glow/bleed on dark** — step
-   one shade lighter and slightly desaturated; on light go one shade deeper for contrast. Same hue,
-   different shade — **never the same hex in both**.
-3. **Copy JSON** → hand the values back into the palette data as `{ light, dark }` pairs.
-4. Remove the override (or "Reset to palette defaults") and confirm the baked palette matches.
-
-The lab is a tuning sandbox, not a prod theme editor: inline overrides apply to whatever scheme is
-on screen and win over both light and dark rules. It is the closing step of design, not a shipped
-feature.
-
-## Primitives + kind discipline (don't loosen, extend)
-
-Every chart composes the shipped primitives — never hand-rolled equivalents:
-
-- **`ChartCard`** wrapper (title + info-tooltip + extra slot, consistent margin).
-- **`ChartLegend`** (`line | bar | split | splitLine` shapes) — never hand-rolled legend markup.
-- **`ChartTooltipFloat`** + `TooltipHeader` / `TooltipRow` / `TooltipBody` — never import `@visx/tooltip`
-  directly (oxlint bans it in chart files).
-- **`AxisBottomDate`** / **`AxisLeftNumeric`** / **`AxisRightNumeric`** — never raw
-  `<AxisLeft>`/`<AxisBottom>` (they miss theme tokens + smart ticks). Now lint-enforced:
-  `basalt-ui check-theme`'s `raw-visx-axis` guard fails the build on a raw axis inside a `/charts/`
-  file (escape via `theme-allow`).
-- **The cursor is shared by default** — `CartesianChart` wires the hover overlay, crosshair, dots
-  and tooltip itself, and every chart on the page tracks one cursor through a module-level store
-  with no provider. Reach for `useChartCursor` only in a hand-composed non-single-plot shape, and
-  for **`ChartCursorScope`** only to opt a subtree OUT of sharing.
-- **`AreaGradient`** / `areaFillUrl` for the soft single-hue fill.
-
-Shipped kinds beyond `ZonedLine` / `Bars` / `StackedArea` / `Donut`: **`MultiLine`** (N series on a
-shared y-axis, legend-hover dimming, dashed MA companions, per-point markers, zones/refLines, fixed
-or auto domain — also z-score/σ via a symmetric domain + zero refLine), **`DualPanel`** (line pane
-
-- signed-histogram pane on one x-scale and cursor, optional fill-between), **`Heatmap`**
-  (category×category intensity grid with per-cell tooltip + optional gradient legend strip).
-
-> If the new chart does not fit the primitives, **add a kind — don't loosen the primitives.**
-> Recurring shape → extract a kind via the Rule of Three. Genuinely unique → stay bespoke,
-> composing primitives directly. New color → a `{ light, dark }` pair in the palette, wired through
-> `--vx-*`, exposed as a `VX.*` ref — never an inline hex. The mechanics of all three live in
-> **`/basalt-charts`** — defer to it for the "how".
-
-The Mantine-free boundary holds here too: `./charts` and `./tokens` import zero `@mantine/*` (an
-internal invariant keeping the token layer upstream of Mantine, and letting those two subpaths
-resolve/render with no `@mantine/*` installed — CI-tested, repo-local only, not shipped), and
-`@visx/*` is only allowed under chart files (oxlint-enforced in the shipped consumer preset too).
-
-## Checklist before declaring a chart "done"
-
-- Every color comes from a token (`VX.*` / palette) — `basalt-ui check-theme` green, zero raw hex.
-- One hue per metric; categorical multi-color only where the data is genuinely categorical.
-- Neutral line/axis/grid; soft `AreaGradient` on plain metric lines, opaque stacked-area bands.
-- Tooltip = `ChartCard` / `ChartTooltipFloat` primitives, one swatch per row — no hand-rolled markup.
-- Looks right in BOTH schemes (toggled and checked: glow on dark, contrast on light).
-- New colors landed as `{ light, dark }` pairs in the palette, not inline.
-- Nothing reads `localStorage.getItem('theme')`.
+1. Adjust colors and the area-gradient strength by eye — in BOTH schemes.
+2. Toggle the scheme and re-check: a saturated mid-tone glows on dark (step lighter, slightly
+   desaturated) and washes out on light (step deeper). Same hue, different shade, **never the same
+   value in both**.
+3. Copy the JSON and hand the values back into the palette as `{ light, dark }` pairs — or, for the
+   identity itself, into the derive config's knobs rather than a hand-picked hex.
+4. Remove the override and confirm the baked palette matches.
+
+`DeriveControls` is the identity/colour knobs (seed + the bounded levels + radius + density) and is
+faithful to `createBasaltTheme`; `ThemeLabControls` is the low-level inspector for the non-derived
+structural tokens. Both are DEV tools and inert in a production build — run the dev server.
+
+## 5. Verify before calling it done
+
+- `basalt-ui check-theme` green: zero raw hex, zero `rgba()`, nothing reading `localStorage['theme']`.
+- `oxlint .` green on the `basalt/*` rules — no hand-rolled filter (in a slot) and no in-body
+  `<Title order={1|2}>`. Hand-rolled section headings are NOT lint-visible (see the `not guarded`
+  line in `basalt-controls.md`'s coverage header): grep the diff for `fw={600}` / `<Title order={3`
+  headings by hand and replace them with `WidgetHeader` / `Section`.
+- One hue per metric; neutral structure; the accent only points.
+- Checked in BOTH schemes, and below `sm` as well as on a wide viewport.
+- Any new color landed as a `{ light, dark }` pair in the consumer series file, never inline.
+- Nothing you built duplicates a shipped composite.

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

@@ -2,48 +2,39 @@
 
 ## basalt-ui (managed — do not hand-edit)
 
-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`).
-Colors come from the three-tier `--vx-*` token system — read `VX.*` / a `defineSeries` token,
-never a raw hex/`rgb()`/`hsl()`. Charts are visx via `basalt-ui/charts`: every single-plot chart
-composes `CartesianChart` (owns margins, scales, axes, grid, cursor, tooltip — draw only marks);
-legends/tooltip rows are DERIVED from `series`, never hand-authored (`basalt/hand-rolled-plot` +
-`basalt/chart-legend-literal` enforce both); `DualPanel`/`BandStrip`/`MirroredBars` declare
-themselves exceptions, and `Donut`/`Heatmap` render no plot-assembly element so the rule never
-fires on them. Add a kind on the third repeat, don't loosen the primitives. `basalt-ui/charts` and
-`basalt-ui/tokens` are Mantine-free internally (a framework invariant, not something your own app
-code must follow) — never import `@visx/*` outside a `charts/` directory (oxlint-enforced).
-Toolchain is oxlint + oxfmt (no ESLint/Biome/Prettier) and `basalt-ui check-theme` guards the
-palette. Runtime is Bun.
-
-**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
-UI, that law wins over habit, over library defaults, and over a skill's instinct. The design/charts
-workflows are the managed skills in `.claude/skills/` (`/basalt-design`, `/basalt-charts`) — they
-defer to DESIGN.md.
+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.
+
+**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.
+
+**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.
+
+**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.
 
 @./DESIGN.md
 
-**Restraint override (supersedes `/frontend-design`).** This app is a calm, data-dense,
-dark-first professional surface — not a showcase. Ignore `/frontend-design`'s push toward a "BOLD
-aesthetic direction", gradient meshes, noise/grain, and dramatic motion. Here: the shipped
-three-font system (Nunito Sans body, Hubot Sans condensed headings, JetBrains Mono for every
-numeral/micro-label), depth via a whisper shadow + 1px ring (`shadow-card` on panels,
-`shadow-raised` on controls — never a decorative drop shadow, never a hover lift), neutral
-zinc-by-default with the single saturated accent spent only when earned (trend /
-signal / categorical separation). Restraint **is** the identity.
+**Restraint override (supersedes `/frontend-design`).** This app is a calm, data-dense professional
+surface, not a showcase. Ignore the push toward a "BOLD aesthetic direction", gradient meshes,
+noise/grain and dramatic motion. Here: the shipped three-font system, depth from a whisper shadow
+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.
 
 <!-- basalt:end -->

package/agent/templates/DESIGN.md.tpl

@@ -1,74 +1,45 @@
 # {{APP_NAME}} — Design
 
-> Managed by basalt-ui — run `basalt-ui doctor` for the version, never trust a number written into
-> a file (this one is a seed: written once at `init`, then owned by you, so any version stamped
-> here would be frozen at scaffold time). This is a **thin** instantiation — it records this
-> app's **deltas only** on top of the shipped `basalt-*` rules. The universal law (earned color,
-> neutral-by-default, three-tier `--vx-*` tokens, theme-is-data, the chart primitive contract, the
-> elevation/density/shape doctrine) lives in those rules and the `/basalt:design` skill, and is
-> **not** repeated here. Touch this file only to confirm identity, register the app's series, or
-> record a genuine deviation.
-
-## Precedence (when guidance conflicts)
-
-This file's deltas win, then the shipped rules, then any skill:
-
-1. **This file** (`{{APP_NAME}}` DESIGN.md) — app-specific deltas. Highest authority.
-2. **`basalt-*` rules** (`.claude/rules/basalt-*.md`) — the shipped law and its enforcement.
-3. **Skills** (`/basalt:design`, `/basalt:charts`, `/frontend-design`, …) — generic method, lowest.
-
-A skill never overrides this file or the `basalt-*` rules. When a skill's instinct collides with the
-law, the law wins.
+> Seeded by basalt-ui `init`, then owned by you — `sync` never touches it again, and no version is
+> stamped here (run `basalt-ui doctor` for the version; a number written into a file is frozen at
+> scaffold time). It records this app's **deltas only**: the law lives in `.claude/rules/basalt-*.md`,
+> and the precedence between this file, those rules and the skills is stated once in `CLAUDE.md`.
 
 ## Identity
 
-{{APP_NAME}} inherits the basalt-ui identity verbatim: modern zinc surfaces, one earned saturated
-sky-blue accent, the `shadow-card` / `shadow-raised` / `shadow-overlay` depth split,
-dense-by-default spacing, and the three-font system. The
-law itself — every hex, role split, and enforcement rule — lives in the `basalt-tokens` and
-`basalt-mantine` rules (`.claude/rules/basalt-{tokens,mantine}.md`) and `docs/DESIGN-SPEC.md` in
-the basalt-ui repo; it is **not** restated here. Confirm or restate any intentional identity shift
-below; **silence means "inherits the basalt-ui defaults unchanged."**
+{{APP_NAME}} inherits the basalt-ui identity verbatim, and every value behind it is DERIVED from the
+theme's config knobs (see the `basalt-tokens` rule) — so nothing here restates one. **Silence means
+"inherits the basalt-ui defaults unchanged."**
 
-- **Accent hue:** {{ACCENT_HUE}} (default: the saturated sky accent — `var(--vx-line)` neutral is
-  still the default for single-series marks)
-- **Tone deltas:** _(none — inherits)_
+- **Accent hue:** {{ACCENT_HUE}} (default: the shipped seed; a single-series mark stays neutral)
+- **Theme knobs:** _(none — `createBasaltTheme()` bare)_ · record any non-zero `derive`/`fonts`/
+  `radius`/`density` level here, with its reason.
 
 ## Series dictionary
 
-The framework owns the **roles** and the **available hues** (see the `basalt-tokens` rule). This
-table is the app's **data dictionary** — which metric maps to which hue, as `{light,dark}` pairs,
-wired through `defineSeries()`. This is the one design artifact that legitimately lives in the
-consumer; keep it the single source of truth and never inline a hex elsewhere.
+The framework owns the roles and the available hues; this table is the app's **data dictionary** —
+which metric maps to which hue, as `{ light, dark }` pairs wired through `defineSeries()`. It is the
+one design artifact that legitimately lives in the consumer; never inline a color elsewhere.
 
-| Series name | Light hex | Dark hex | `defineSeries` key | Role / earned reason |
-|-|-|-|-|-|
-| _e.g. requests_ | `#4f78a4` | `#7099c4` | `requests` | Primary metric (earned accent hue) |
-| | | | | |
+| Series name      | `defineSeries` key | Role / earned reason               |
+| ---------------- | ------------------ | ---------------------------------- |
+| _e.g. requests_  | `requests`         | Primary metric (earned trend hue)  |
 
 ```ts
 // {{SERIES_MODULE_PATH}} — the app's guard-exempt series file
 import { defineSeries, groupTokens } from 'basalt-ui/tokens'
-
 const SERIES_MAP = defineSeries({
-  // requests: { light: '#4f78a4', dark: '#7099c4' },
+  // requests: { light: '…', dark: '…' },   // deeper on light, lighter on dark — never one value
 })
-
-export const series = groupTokens('app', SERIES_MAP) // { requests: 'var(--vx-app-requests)', ... }
-export const paletteGroups = { 'app-': SERIES_MAP }
-// wire into the provider: <BasaltProvider paletteOptions={{ groups: paletteGroups }} .../>
-// (paletteOptions takes the group map directly — not a CSS string; read `series.requests` in charts)
+export const series = groupTokens('app', SERIES_MAP) // { requests: 'var(--vx-app-requests)', … }
+export const paletteGroups = { 'app-': SERIES_MAP } // the trailing dash is a CSS-var prefix
+// <BasaltProvider paletteOptions={{ groups: paletteGroups }} …/> — then charts read `series.requests`
 ```
 
-Rules for this table (from the `basalt-tokens` / `basalt-charts` rules — do not relax):
-- One hue per series, drawn from the identity families only. Never raw Material/AntD/Tailwind.
-- A series earns a color only for **trend**, **signal/status**, or **categorical separation**.
-  A lone single-series metric stays neutral (`var(--vx-line)`).
-- Light is one shade **deeper**, dark one shade **lighter** — same hue, never the same hex.
+A series earns a color only for trend, signal/status or categorical separation. `/basalt-design` is the tuning loop; `/basalt-charts` is the wiring.
 
 ## App deviations
 
-Genuine, intentional departures from the basalt-ui defaults — each with a one-line justification. An
-empty section is the correct default; do not invent deviations to fill it.
+Intentional departures from the defaults, each with a one-line justification. Empty is correct.
 
 - _(none yet)_