basalt-ui 1.5.0 → 1.7.0

package/src/theme/index.ts

@@ -342,6 +342,24 @@ const basaltVariantColorResolver: VariantColorsResolver = (input) => {
     return autoContrast ? { ...resolved, color: on } : resolved
   }
 
+  // `subtle`: hover is a NEUTRAL ink tint, not Mantine's accent tint
+  // (`--mantine-color-{c}-light`). `docs/DESIGN-SPEC.md` §5 specifies the ghost idiom as "hover
+  // ink-6% + ink icon", and a subtle Button had never followed it — it hovered into a saturated
+  // accent block that read as a filled control appearing under the cursor. Fixing it HERE rather
+  // than in controls.module.css is what makes Button and ActionIcon agree: both resolve `subtle`
+  // through this one function, and §5's ghost icon button and a `variant="subtle"` Button are meant
+  // to be the same idiom at two sizes.
+  //
+  // Scoped to the DEFAULT color on purpose. An explicitly-colored subtle control (`color="red"` on a
+  // destructive text action) carries its hue as the whole signal, so neutralizing its hover would
+  // erase the one thing that marks it dangerous — those keep Mantine's own tinted hover.
+  if (input.variant === 'subtle') {
+    const isDefaultColor = input.color === undefined || input.color === input.theme.primaryColor
+    return isDefaultColor
+      ? { ...resolved, hover: `color-mix(in srgb, var(--vx-ink) 6%, transparent)` }
+      : resolved
+  }
+
   if (input.variant !== 'light') return resolved
   const ink = `var(--mantine-color-${colorName}-light-color)`
   return {
@@ -526,17 +544,26 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
         },
       }),
       // "Ink earns its color" — a nav selection is UI state, not the identity accent on the LABEL.
-      // The active item is panel bg + `shadow-card` (forced here at the THEME level via NavLink's
-      // `--nl-*` vars, so it holds for every render path — including a consumer's router `<Link>`
-      // via `renderNavLink`, which never sees the shell CSS module); the active ICON is
-      // accent-colored via `nav-link.module.css` (targets the `[data-position='left']` leftSection,
-      // which the flat `vars`/`styles` API can't express conditionally on `[data-active]`).
+      // The active item is a SELECTED ROW, not a raised control: the same ink-tint idiom as the
+      // hover state (one step stronger, ink-9%), no panel fill and no `shadow-card` — a raised,
+      // panel-filled row read as a button sitting in the nav rather than as the current location.
+      // Selection is carried by the tint + ink text + weight 600 + the accent icon instead. Forced
+      // here at the THEME level via NavLink's `--nl-*` vars so it holds for every render path —
+      // including a consumer's router `<Link>` via `renderNavLink`, which never sees the shell CSS
+      // module; the active ICON is accent-colored via `nav-link.module.css` (targets the
+      // `[data-position='left']` leftSection, which the flat `vars`/`styles` API can't express
+      // conditionally on `[data-active]`).
+      //
+      // `--nl-hover` (ink-13%) only ever reaches an ACTIVE row in practice — the inactive hover is
+      // set at ink-6% by higher-specificity `:not([data-active])` rules in `nav-link.module.css` /
+      // `app-sidebar.module.css` — so it exists to keep the active row responding to the pointer
+      // now that its rest state sits in the same tint family as an inactive hover.
       NavLink: NavLink.extend({
         vars: () => ({
           root: {
-            '--nl-bg': 'var(--vx-surface-panel)',
+            '--nl-bg': 'color-mix(in srgb, var(--vx-ink) 9%, transparent)',
             '--nl-color': 'var(--vx-ink)',
-            '--nl-hover': 'color-mix(in srgb, var(--vx-ink) 6%, transparent)',
+            '--nl-hover': 'color-mix(in srgb, var(--vx-ink) 13%, transparent)',
           },
           children: {},
         }),
@@ -570,7 +597,7 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
           label: { fontSize: VX.text.md, lineHeight: 'var(--vx-space-row-line-height)' },
         },
       }),
-      // Field idiom (docs/DESIGN-SPEC.md §5): field surface + `shadow-card` depth + faint placeholder,
+      // Field idiom (docs/DESIGN-SPEC.md §5): field surface + `shadow-raised` depth + faint placeholder,
       // accent border + subtle accent ring on focus — see controls.module.css. The two slots carry
       // different halves of it: the `wrapper` is where Mantine declares the `--input-*` vars, the
       // `input` is the box that actually paints the surface (bg + radius) and therefore the only
@@ -625,16 +652,19 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       PillsInput: PillsInput.extend({
         classNames: { wrapper: controlsClasses.inputWrapper, input: controlsClasses.input },
       }),
-      // Button / ActionIcon (`default` variant): same `shadow-card` depth as every other control
-      // surface (docs/DESIGN-SPEC.md §5: "search trigger … panel + shadow-card", "icon button …
-      // panel + shadow-card"; doctrine inversion #1). Background already resolves through the shared
+      // Button / ActionIcon: depth for EVERY variant that owns a box (docs/DESIGN-SPEC.md §5's
+      // Button idiom; doctrine inversion #1) — `default`/`filled`/`light` on the shared
+      // `shadow-raised`, `outline` on ring-free `shadow-ctrl`, `subtle` flat at rest. Emphasis stays
+      // in fill weight,
+      // never in z-height. Background for `default` already resolves through the shared
       // `--mantine-color-default` var (→ `--vx-surface-panel`, see cssVariablesResolver below) and
-      // the border through `--mantine-color-default-border` (→ transparent, same resolver) — neither
+      // its border through `--mantine-color-default-border` (→ transparent, same resolver) — neither
       // component had a `.extend()` block at all before this, which is why they never picked up
-      // either. Only the shadow needs adding here, in controls.module.css: Mantine's own
-      // `[data-variant='default']` rule never declares a `box-shadow`, so no specificity fight is
-      // needed to win one. `filled`/`subtle`/`light` variants are untouched — scoped by attribute
-      // selector in the CSS, not here.
+      // either. Everything else — the per-variant depth and the disabled/reduced-motion grounding —
+      // lives in controls.module.css, where the variant scoping
+      // is an attribute selector: Mantine declares no `box-shadow` on either component at any
+      // specificity, so none of it needs a specificity fight. Nothing about depth is expressible in
+      // the flat `styles` objects here, which is the whole reason that file exists.
       //
       // Density coupling: mirrors Input's `--input-height` override above — Mantine's OWN
       // `--button-height-md`/`--ai-size` (via `--ai-size-md`) are global, non-retunable statics
@@ -679,7 +709,8 @@ function buildTheme(data: PaletteData, options: BuildThemeOptions = {}): Mantine
       // real attribute selectors ((0,2,0)) — Mantine's own rule wraps the same attribute in `:where()`
       // (0 specificity, landing at (0,1,0) total), so no `html[…]` prefix fight is needed here either.
       // Neither component sets a background of its own, so panel bg is added alongside the shadow —
-      // the same panel-bg + shadow-card + no-border triad as Card/Paper.
+      // the same panel-bg + depth + no-border triad as Card/Paper — on `shadow-raised`, the shared
+      // CONTROL depth, not Card/Paper's `shadow-card`: a selection card is something you click.
       CheckboxCard: CheckboxCard.extend({
         classNames: { card: controlsClasses.checkboxCardRoot },
       }),
@@ -1099,8 +1130,8 @@ function buildCssVariablesResolver(data: PaletteData): CSSVariablesResolver {
       '--mantine-color-body': `var(--vx-surface-bg, ${SURFACE.bg.light})`, // page background
       '--mantine-color-default': `var(--vx-surface-panel, ${SURFACE.panel.light})`, // cards / default controls
       '--mantine-color-default-hover': `var(--vx-surface-elevated, ${SURFACE.elevated.light})`,
-      // THE central lever for doctrine inversion #1 on CONTROLS (docs/DESIGN-SPEC.md §8): depth is
-      // `shadow-card`, never a hairline, for every `variant="default"` control — not just Card/Paper.
+      // THE central lever for doctrine inversion #1 on CONTROLS (docs/DESIGN-SPEC.md §8): depth is a
+      // shadow, never a hairline, for every `variant="default"` control — not just Card/Paper.
       // `defaultVariantColorsResolver`'s `variant === 'default'` branch reads this ONE var for every
       // component that uses it (Button, ActionIcon, Chip, CheckboxCard, RadioCard, …), so pointing it
       // at `transparent` kills the stock 1px hairline everywhere at once. `transparent`, not `border:

package/src/theme/nav-link.module.css

@@ -1,19 +1,19 @@
 /*
- * Active nav row = heavier weight + card depth, applied at the THEME level via `classNames` so it
- * reaches EVERY NavLink render path — including a consumer's router `<Link>` mounted through
- * `renderNavLink`, which a shell-scoped CSS module never sees. Mantine's `styles` prop only takes
- * flat inline properties (a nested `&[data-active]` there throws a React warning), so the state
- * selectors live here. React Router's NavLink marks the active item via `aria-current` rather than
- * the `active` prop's `data-active`, so both states are matched.
+ * Active nav row = heavier weight over the ink tint `--nl-bg` carries (set in theme/index.ts,
+ * applied unconditionally by Mantine's own `[data-active]` CSS). NO depth: an active row is a
+ * SELECTED ROW, not a raised control — it deliberately reads as a stronger version of the hover
+ * tint rather than as a button, so the row never competes with the real filled controls around it.
  *
- * The row's background comes from `--nl-bg` (set in theme/index.ts, applies unconditionally via
- * Mantine's own `[data-active]` CSS) — `shadow-card` is added here because there's no `--nl-*` var
- * for depth.
+ * Applied at the THEME level via `classNames` so it reaches EVERY NavLink render path — including a
+ * consumer's router `<Link>` mounted through `renderNavLink`, which a shell-scoped CSS module never
+ * sees. Mantine's `styles` prop only takes flat inline properties (a nested `&[data-active]` there
+ * throws a React warning), so the state selectors live here. React Router's NavLink marks the
+ * active item via `aria-current` rather than the `active` prop's `data-active`, so both states are
+ * matched.
  */
 .root[data-active],
 .root[aria-current='page'] {
   font-weight: 600;
-  box-shadow: var(--vx-shadow-card);
 }
 
 /*

package/src/theme/shadow-surfaces.test.ts

@@ -2,7 +2,8 @@
  * Shadow-surface coverage — closes a class of bug `check-theme`'s regex scans cannot see: applying
  * the depth token to the WRONG box.
  *
- * `--vx-shadow-card` (and `--vx-shadow-ctrl`) bakes a 1px ring into the shadow value itself (see
+ * `--vx-shadow-card` (and `--vx-shadow-ctrl`/`--vx-shadow-raised`) bakes a 1px ring into the shadow
+ * value itself (see
  * `tokens/palette.ts`'s `SHADOW`). THE INVARIANT: an element applying the token must carry the
  * surface's OWN `border-radius` — the ring is drawn by the shadow's rendering box and follows THAT
  * box's own corners, not any other element's. We shipped a bug where `box-shadow: var(--vx-shadow-
@@ -16,10 +17,16 @@
  * mechanical inventory of every site that APPLIES the token would have caught it: a source-level
  * guard can only flag a bad value, never a bad ELEMENT.
  *
+ * `--vx-shadow-raised`'s ring is INSET rather than outset, which changes nothing about the
+ * invariant: an inset ring is still drawn by the shadow's rendering box and still follows that
+ * box's own corners, so a radius mismatch leaks the same way (nubs on the inside of the corner
+ * instead of the outside). It is registered here for exactly the same reason as the other two.
+ *
  * This test IS that inventory: it scans basalt-ui's own source for every place that applies
- * `--vx-shadow-card`/`--vx-shadow-ctrl` (a `box-shadow`/CSS-custom-property declaration in
- * `*.module.css`, or a `boxShadow` object property — literal, `VX.shadowCard`/`VX.shadowCtrl`, or a
- * template-literal composite of either — in `*.ts`/`*.tsx`) and asserts every one is registered in
+ * `--vx-shadow-card`/`--vx-shadow-ctrl`/`--vx-shadow-raised` (a `box-shadow`/CSS-custom-property
+ * declaration in `*.module.css`, or a `boxShadow` object property — literal, `VX.shadowCard`/
+ * `VX.shadowCtrl`/`VX.shadowRaised`, or a template-literal composite of any — in `*.ts`/`*.tsx`)
+ * and asserts every one is registered in
  * `SHADOW_SURFACES` below with a written `roundedBy` reason naming exactly where that box's
  * `border-radius` comes from. Mere mentions in comments/docstrings and the token DEFINITION itself
  * (`tokens/index.ts`, `tokens/palette.ts`) are excluded — this test only cares about APPLICATION.
@@ -34,8 +41,12 @@
  * so plainly; a square ring on a square surface is correct, not a gap.
  *
  * THIS TEST IS DELIBERATELY COUPLED TO OUR OWN SOURCE. Adding a new `box-shadow: var(--vx-shadow-
- * card)` (or `-ctrl`) anywhere SHOULD fail this test until it's registered — that failure IS the
- * point. Do NOT "fix" a future failure by loosening the scan or bulk-registering with a placeholder
+ * card)` (or `-ctrl`/`-raised`) anywhere SHOULD fail this test until it's registered — that failure
+ * IS the point. A NEW depth token is the one case the scan cannot fail loudly on: the two regexes
+ * below name their tokens explicitly, so an unlisted `--vx-shadow-*` slips through silently and
+ * vacuously. Adding a token to `SHADOW` therefore means adding it to BOTH regexes in the same
+ * commit — `raised` is the precedent.
+ * Do NOT "fix" a future failure by loosening the scan or bulk-registering with a placeholder
  * reason; open the file, find the element the shadow is declared on, prove (or fix) that IT carries
  * the surface's own border-radius, and write down where that radius comes from.
  *
@@ -95,7 +106,7 @@ function stripTsComments(text: string): string {
 // bare mention of `--vx-shadow-card` in a comment never matches — comments are stripped first, and
 // this requires an actual `property:` declaration.
 const CSS_SHADOW_TOKEN =
-  /(?<![\w-])(?:box-shadow|--[\w-]+)\s*:\s*[^;]*var\(--vx-shadow-(?:card|ctrl)\)/
+  /(?<![\w-])(?:box-shadow|--[\w-]+)\s*:\s*[^;]*var\(--vx-shadow-(?:card|ctrl|raised)\)/
 
 // A real application in TS/TSX: a `boxShadow` object property whose value is the literal CSS var
 // string, `VX.shadowCard`/`VX.shadowCtrl`, or a template literal compositing either (e.g. the
@@ -103,7 +114,7 @@ const CSS_SHADOW_TOKEN =
 // `--vx-shadow-overlay` (a different, unrelated token) or a `boxShadow` string literal that doesn't
 // reference either token (data-table's scroll-shadow, guard/index.ts's own regex source, etc.).
 const TS_SHADOW_TOKEN =
-  /\bboxShadow\s*:\s*(?:'[^']*var\(--vx-shadow-(?:card|ctrl)\)[^']*'|`[^`]*(?:var\(--vx-shadow-(?:card|ctrl)\)|VX\.shadow(?:Card|Ctrl))[^`]*`|VX\.shadow(?:Card|Ctrl))/
+  /\bboxShadow\s*:\s*(?:'[^']*var\(--vx-shadow-(?:card|ctrl|raised)\)[^']*'|`[^`]*(?:var\(--vx-shadow-(?:card|ctrl|raised)\)|VX\.shadow(?:Card|Ctrl|Raised))[^`]*`|VX\.shadow(?:Card|Ctrl|Raised))/
 
 type ShadowSite = {
   /** Path relative to `src/`, e.g. `theme/controls.module.css`. */
@@ -116,8 +127,13 @@ type ShadowSite = {
 
 /** Every rule in a CSS module whose declarations apply the token, keyed by the rule's own selector
  * (multi-line selectors are collapsed to one line). Assumes flat, non-nested CSS (no native
- * nesting) — the one `@media` block in this codebase sits after every shadow site, so a naive
- * brace-pair scan never needs to understand at-rule nesting to find them. */
+ * nesting). A rule nested one level inside an at-rule IS still found — the brace-pair regex matches
+ * INNERMOST pairs, so `@media (hover: hover) { .x:hover { … } }` resolves as the inner `.x:hover`
+ * rule. (No such site exists today — depth is static — but the scan must keep finding one if a
+ * future state-scoped depth rule lands inside an at-rule.) What the
+ * naive scan does NOT do is carry the at-rule condition into the site label: such a site registers
+ * under its bare inner selector, with the `@media` context stated in its `roundedBy` reason
+ * instead. That is a labeling limitation, never a coverage one. */
 function cssShadowSites(relPath: string, text: string): ShadowSite[] {
   const clean = stripCssComments(text)
   const sites: ShadowSite[] = []
@@ -173,7 +189,7 @@ function tsShadowSites(relPath: string, text: string): ShadowSite[] {
   return sites
 }
 
-/** Every application of `--vx-shadow-card`/`--vx-shadow-ctrl` across `src/**`. */
+/** Every application of `--vx-shadow-card`/`--vx-shadow-ctrl`/`--vx-shadow-raised` across `src/**`. */
 function scanShadowSites(): ShadowSite[] {
   const files: string[] = []
   collectSourceFiles(SRC_DIR, files)
@@ -221,21 +237,55 @@ export const SHADOW_SURFACES: readonly ShadowSurfaceEntry[] = [
       '<input> element itself — the custom property inherits from wrapper to input, landing on the ' +
       'exact element the shadow lands on).',
   },
+  // The five Button/ActionIcon entries below all resolve their radius the same way, and all set the
+  // token on `--ctrl-depth` rather than on `box-shadow` directly — the single `box-shadow:
+  // var(--ctrl-depth)` declaration lives on the shared `.buttonRoot, .actionIconRoot` base rule
+  // (which is therefore NOT a token-application site itself and correctly goes unregistered). The
+  // indirection changes nothing about this invariant: the variable is consumed on the very same
+  // element these selectors target, so the ring is still drawn by a box carrying the control's own
+  // `--button-radius`/`--ai-radius`.
   {
     file: 'theme/controls.module.css',
-    site: ".buttonRoot[data-variant='default']",
+    site:
+      ".buttonRoot[data-variant='default'], .buttonRoot[data-variant='filled'], " +
+      ".buttonRoot[data-variant='light']",
     roundedBy:
       "--button-radius (Mantine's own Button.css declares `border-radius: var(--button-radius, " +
       'var(--mantine-radius-default))` directly on the button root — the same element `.buttonRoot` ' +
-      'targets).',
+      'targets). This is the raised family on the shared `shadow-raised`, and its ring is INSET — a ' +
+      'radius mismatch would leak nubs on the INSIDE of each corner rather than the outside, so the ' +
+      'invariant bites exactly as hard here as on an outset ring.',
   },
   {
     file: 'theme/controls.module.css',
-    site: ".actionIconRoot[data-variant='default']",
+    site: ".buttonRoot[data-variant='outline']",
+    roundedBy:
+      '--button-radius (same chain as the raised-family entry above — Button.css declares ' +
+      '`border-radius: var(--button-radius, var(--mantine-radius-default))` on the button root; the ' +
+      'variant changes only which depth token lands, never which element carries it). `outline` is ' +
+      'the one raised variant on ring-FREE `shadow-ctrl`, because its real 1px accent border already ' +
+      'IS its edge and an inset ring tucked just inside a border is muddy — so no ring is at risk ' +
+      'here at all, and the registration exists to keep the inventory exhaustive.',
+  },
+  {
+    file: 'theme/controls.module.css',
+    site:
+      ".actionIconRoot[data-variant='default'], .actionIconRoot[data-variant='filled'], " +
+      ".actionIconRoot[data-variant='light']",
     roundedBy:
       "--ai-radius (Mantine's own ActionIcon.css declares `border-radius: var(--ai-radius, " +
       'var(--mantine-radius-default))` directly on the root — the same element `.actionIconRoot` ' +
-      'targets).',
+      'targets). Same inset-ring reasoning as the Button raised-family entry above.',
+  },
+  {
+    file: 'theme/controls.module.css',
+    site: ".actionIconRoot[data-variant='outline']",
+    roundedBy:
+      '--ai-radius (same chain as the entry above — ActionIcon.css declares `border-radius: ' +
+      'var(--ai-radius, var(--mantine-radius-default))` on the root). Ring-free `shadow-ctrl`, same ' +
+      "reason as Button's `outline`. ActionIcon has no `subtle` counterpart to Button's " +
+      "hover-materialized entry by design: its `subtle` IS the spec's separate ghost-icon-button " +
+      'idiom (DESIGN-SPEC §5), whose hover state is an ink tint, not a raise.',
   },
   {
     file: 'theme/controls.module.css',
@@ -251,17 +301,8 @@ export const SHADOW_SURFACES: readonly ShadowSurfaceEntry[] = [
       "--chip-radius (Mantine's own Chip.css declares `border-radius: var(--chip-radius, 1000rem)` " +
       'directly on the label part — the same element `.chipLabel` targets).',
   },
-  // ── theme/nav-link.module.css ────────────────────────────────────────────────────────────────
-  {
-    file: 'theme/nav-link.module.css',
-    site: ".root[data-active], .root[aria-current='page']",
-    roundedBy:
-      "borderRadius: 6 (theme/index.ts's NavLink.extend styles.root — Mantine renders this as an " +
-      'inline style on the root part, wired via `classNames: { root: navLinkClasses.root }` to the ' +
-      "exact `.root` element this rule's box-shadow lands on). Verified NOT a square surface: " +
-      "Mantine's own NavLink.css declares no border-radius at all for .root — the 6px comes only " +
-      'from our own theme override.',
-  },
+  // theme/nav-link.module.css applies no shadow token: the active nav row is a selected row (ink
+  // tint), never a raised control — see that file's header comment.
   // ── shell/app-mobile-nav.module.css ──────────────────────────────────────────────────────────
   {
     file: 'shell/app-mobile-nav.module.css',
@@ -326,11 +367,9 @@ export const SHADOW_SURFACES: readonly ShadowSurfaceEntry[] = [
     roundedBy: 'borderRadius: 8 (co-declared in the same TOOLTIP_STYLES object).',
   },
   // ── agent-chat ───────────────────────────────────────────────────────────────────────────────
-  {
-    file: 'agent-chat/composer.tsx',
-    site: 'input',
-    roundedBy: 'borderRadius: 8 (co-declared in the same styles.input object).',
-  },
+  // agent-chat/composer.tsx applies no shadow token of its own: it takes the themed `.input` depth
+  // (theme/controls.module.css) so it also inherits that class's disabled grounding — an inline
+  // `boxShadow` in its `styles` object used to beat the class and leave a disabled composer raised.
   {
     file: 'agent-chat/thread-outcome-card.tsx',
     site: 'default',
@@ -380,7 +419,7 @@ describe('SHADOW_SURFACES is well-formed', () => {
   })
 })
 
-describe('every applied --vx-shadow-card / --vx-shadow-ctrl site is registered', () => {
+describe('every applied --vx-shadow-card / -ctrl / -raised site is registered', () => {
   // The coverage assertion below is `expect(gaps).toEqual([])`, which passes VACUOUSLY if the scan
   // finds nothing. That is exactly the failure mode `border-coverage.test.ts` already had to guard
   // against once — this is the same tripwire: fail loudly here if the scan stops resolving real
@@ -408,7 +447,7 @@ describe('every applied --vx-shadow-card / --vx-shadow-ctrl site is registered',
       .filter((site) => !registered.has(siteKey(site)))
       .map(
         (site) =>
-          `${site.file} (${site.site}): applies --vx-shadow-card/--vx-shadow-ctrl but has no ` +
+          `${site.file} (${site.site}): applies --vx-shadow-card/-ctrl/-raised but has no ` +
           'entry in SHADOW_SURFACES (src/theme/shadow-surfaces.test.ts). The ring baked into the ' +
           "token follows THIS box's own border-radius — find where this box's radius comes from " +
           '(a co-declared border-radius, or a Mantine CSS var/prop, verified against the shipped ' +

package/src/tokens/index.ts

@@ -202,6 +202,9 @@ export const VX = {
   // Depth shadows — a whisper shadow + a 1px ring baked into the value (never a `border` prop).
   shadowCard: 'var(--vx-shadow-card)',
   shadowCtrl: 'var(--vx-shadow-ctrl)',
+  // Raised interactive controls — drop + a 1px INSET edge, the one depth every raised Button/
+  // ActionIcon variant shares (works over a fill, a tint or a panel alike; see SHADOW.raised).
+  shadowRaised: 'var(--vx-shadow-raised)',
   // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a real drop shadow.
   shadowOverlay: 'var(--vx-shadow-overlay)',
 
@@ -333,6 +336,7 @@ function frameworkPrimitives(side: Side, data: PaletteData, legacyAliases: boole
     decl('divider', su.divider[side]),
     decl('shadow-card', SHADOW.card[side]),
     decl('shadow-ctrl', SHADOW.ctrl[side]),
+    decl('shadow-raised', SHADOW.raised[side]),
     decl('shadow-overlay', SHADOW.overlay[side]),
     decl('surface-bg', su.bg[side]),
     decl('surface-panel', su.panel[side]),

package/src/tokens/palette.ts

@@ -104,6 +104,37 @@ export const SHADOW = {
     light: '0 1px 2px rgba(28,25,23,0.12)',
     dark: '0 1px 2px rgba(0,0,0,0.35)',
   },
+  /**
+   * Interactive-control depth — the ONE value every raised Button/ActionIcon/Input variant shares
+   * (`docs/DESIGN-SPEC.md` §5's Button idiom). Exists rather than reusing `card` because `card`'s
+   * ring is OUTSET, and an outset ring paints in the color of whatever it is drawn over: fine
+   * between neutral panels, but on light scheme it resolves to `--vx-surface-hairline` and draws a
+   * pale grey outline around a saturated `filled` button, which reads as a rendering defect.
+   *
+   * THE TWO SCHEMES ARE SHAPED DIFFERENTLY, and the asymmetry is the whole design — do NOT "tidy"
+   * them into one shape. Both were arrived at by elimination, on screen:
+   *
+   *   - DARK = drop + a full inset rim. Its edge is a LIGHTENING, so it cannot collide with the
+   *     dark drop below the box; a uniform lightening on a dark surface reads as rim light wrapping
+   *     a raised object, which is exactly right.
+   *
+   *   - LIGHT = drop ONLY, no edge at all. A light-mode edge would have to be a DARKENING (there is
+   *     nothing lighter than a near-white control to lighten with), and every position for one
+   *     fails: a uniform dark ring does not read as depth, it reads as a BORDER — it made `default`
+   *     and `light` look like outlined buttons and every form field look boxed. Moving it to the
+   *     bottom edge alone then put a dark inner line directly above the dark drop, i.e. a visible
+   *     DOUBLE BOTTOM BORDER. There is no third position, because a light-mode raised object's only
+   *     honest cue is the shadow it casts. So light casts one and draws nothing.
+   *
+   * Consequence to know, on light only: a `default` control nested in a Card shares
+   * `--vx-surface-panel` with it and has no boundary but the drop. That is accepted — a wrong-
+   * looking border on every control in the app is worse than a soft edge in one nesting case. If it
+   * ever needs more, raise the DROP. Do not reintroduce an edge; both shapes have been tried.
+   */
+  raised: {
+    light: '0 1px 2px rgba(28,25,23,0.10)',
+    dark: '0 1px 2px rgba(0,0,0,0.35), inset 0 0 0 1px color-mix(in srgb, #ffffff 8%, transparent)',
+  },
   // Floating-layer elevation (menus, popovers, tooltips, modals, drawers) — a REAL drop shadow, a
   // step above `card`, so detached surfaces read as lifted off the page (`docs/DESIGN-SPEC.md` §5).
   // Unlike `card`, no embedded ring: floating surfaces carry a real 1px `--vx-surface-border` so

package/src/vite.ts

@@ -13,8 +13,13 @@
  *
  * NEVER reference `import.meta.env` here — this file is invoked inside the consumer's vite config
  * at config-evaluation time (plain Node), where only `process.env` exists.
+ *
+ * It also carries the enforcement notice (`warnIfUnenforced`): this is the one basalt seam that runs
+ * on every dev start and every build of a consumer app, so it is the only place that can tell an app
+ * it installed the components and skipped `basalt-ui init`.
  */
-import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
 import { searchForWorkspaceRoot } from 'vite'
 import type { HtmlTagDescriptor, Plugin, PluginOption, UserConfig } from 'vite'
 import { SURFACE } from './tokens/palette'
@@ -46,6 +51,55 @@ export type BasaltViteOptions = {
   basaltSrc?: string
   /** App version surfaced via the `__APP_VERSION__` define. Defaults to `0.0.0`. */
   version?: string
+  /**
+   * Print a one-time notice when `basalt-ui init` has never been run in this project (no
+   * `.basalt/manifest.json` found at or above the cwd) — see `warnIfUnenforced`. Default `true`.
+   * Set `false` to adopt the components without the toolchain and stop being told about it.
+   */
+  enforcementNotice?: boolean
+}
+
+/** How many directories up from `cwd` to look for `.basalt/manifest.json`. Three covers the common
+ * shapes: config at the app root, an app in `web/` or `apps/<name>/` under a repo root. */
+const UNENFORCED_SEARCH_DEPTH = 3
+
+/** Set once the notice has been printed, so a watch-mode restart doesn't reprint it every reload. */
+let unenforcedNoticePrinted = false
+
+/**
+ * Print one notice when basalt-ui is installed as a component library and nothing else.
+ *
+ * `basalt-ui init` is what places the oxlint preset, the theme-guard wiring, the lefthook stub and
+ * the agent rules. Skipping it leaves a consumer with the components and NONE of the enforcement —
+ * and, critically, no signal that this is the case. The failure is silent and cumulative: every
+ * hand-rolled `<Card withBorder radius="md" padding="lg">` renders perfectly, so the app drifts a
+ * card idiom at a time until someone looks at a screenshot and asks why the design system did
+ * nothing. The first real consumer reached seven such cards across six files that way.
+ *
+ * This is the only seam basalt owns that runs on every dev start and every build, which makes it
+ * the only place that can say so at the time it is still cheap to fix. It stays a notice, never an
+ * error: declining to adopt the toolchain is a legitimate choice, and a build that fails because a
+ * lint preset is absent would be a worse bug than the one this prevents.
+ */
+function warnIfUnenforced(cwd: string): void {
+  if (unenforcedNoticePrinted) return
+
+  let dir = cwd
+  for (let i = 0; i <= UNENFORCED_SEARCH_DEPTH; i++) {
+    if (existsSync(resolve(dir, '.basalt/manifest.json'))) return
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+
+  unenforcedNoticePrinted = true
+  // oxlint-disable-next-line no-console -- a build-time notice has no other channel
+  console.warn(
+    '\n[basalt-ui] Installed, but `basalt-ui init` has never run here — no oxlint preset, no theme\n' +
+      '            guard, no agent rules. You have the components and none of the enforcement.\n' +
+      '            Fix: `bunx basalt-ui init`, then add `oxlint . && basalt-ui check-theme` as your\n' +
+      '            lint script. Silence: pass `enforcementNotice: false` to basaltViteConfig().\n',
+  )
 }
 
 export function basaltViteConfig(opts: BasaltViteOptions): UserConfig {
@@ -55,6 +109,13 @@ export function basaltViteConfig(opts: BasaltViteOptions): UserConfig {
   // on without editing its vite config. process.env (not import.meta.env) — this runs in Node.
   const basaltSrc = opts.basaltSrc ?? process.env['BASALT_LOCAL']
 
+  // Skipped under basaltSrc/BASALT_LOCAL: that path means basalt-ui itself is being developed from
+  // a sibling checkout (the playground, or a consumer debugging against local source), where the
+  // enforcement config lives in basalt's own repo and a manifest is not expected.
+  if (opts.enforcementNotice !== false && basaltSrc === undefined) {
+    warnIfUnenforced(process.cwd())
+  }
+
   const config: UserConfig = {
     define: {
       __APP_VERSION__: JSON.stringify(process.env['BUILD_VERSION'] ?? version),