@recursica/mantine-adapter 0.50.1 → 0.50.4

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.50.1",
+  "version": "0.50.4",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -55,10 +55,11 @@
     "lint": "eslint .",
     "storybook": "storybook dev -p 6011",
     "analyze-tokens": "analyze-tokens --css @recursica/official-release/recursica_variables_scoped.css --dir src/components --output token-analysis.json",
-    "prebuild": "npm run analyze-tokens"
+    "prebuild": "npm run analyze-tokens",
+    "test": "vitest run --project unit",
+    "test:dom": "vitest run --project dom"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^5.1.1",
     "@eslint/js": "^9.25.0",
     "@recursica/recursica-postcss-vars": "*",
     "@recursica/storybook-template": "*",
@@ -94,7 +95,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.25.0",
+    "@recursica/adapter-common": "^0.25.1",
     "@recursica/official-release": "^2.8.0"
   },
   "peerDependencies": {

package/src/components/Accordion/Accordion.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Accordion component tests. Add tests here if/when needed.

package/src/components/AssistiveElement/AssistiveElement.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future AssistiveElement component tests. Add tests here if/when needed.

package/src/components/AutoComplete/AutoComplete.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future AutoComplete component tests. Add tests here if/when needed.

package/src/components/Avatar/Avatar.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Avatar component tests. Add tests here if/when needed.

package/src/components/Badge/Badge.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Badge component tests. Add tests here if/when needed.

package/src/components/Breadcrumb/Breadcrumb.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Breadcrumb component tests. Add tests here if/when needed.

package/src/components/Button/Button.module.css

@@ -24,6 +24,7 @@
   position: relative;
   transition: all 0.2s ease;
   width: fit-content; /* Prevent stretching in flex columns */
+  max-width: 100%; /* Let a constraining parent (e.g. max-width container) actually shrink the button; fit-content alone ignores it */
 
   /* Shared Defaults */
   font-family: var(

package/src/components/Button/Button.styleIsolation.dom.test.tsx

@@ -0,0 +1,98 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { MantineProvider, Button as MantineButton } from "@mantine/core";
+import { Button as RecursicaButton } from "./Button";
+
+function mount(node: React.ReactElement): {
+  container: HTMLElement;
+  root: Root;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  flushSync(() => root.render(node));
+  return { container, root };
+}
+
+function unmount({ container, root }: { container: HTMLElement; root: Root }) {
+  root.unmount();
+  container.remove();
+}
+
+function withProvider(node: React.ReactElement) {
+  return <MantineProvider defaultColorScheme="light">{node}</MantineProvider>;
+}
+
+/**
+ * Guards against Recursica's Button CSS bleeding onto (or being bled onto by) a plain,
+ * unwrapped Mantine Button rendered in the same document. The two must be visibly different
+ * (Recursica's own classes/data-attributes), but the plain kit button must render identically
+ * whether or not a Recursica Button exists alongside it.
+ */
+describe("Button style isolation from the underlying Mantine kit", () => {
+  it("adds Recursica-only classes/attributes without leaking them onto a plain Mantine Button", () => {
+    const recursica = mount(
+      withProvider(<RecursicaButton>Recursica</RecursicaButton>),
+    );
+    const kit = mount(withProvider(<MantineButton>Plain</MantineButton>));
+
+    try {
+      const recursicaButton = recursica.container.querySelector("button")!;
+      const kitButton = kit.container.querySelector("button")!;
+
+      const recursicaClasses = Array.from(recursicaButton.classList);
+      const kitClasses = new Set(kitButton.classList);
+      const recursicaOnlyClasses = recursicaClasses.filter(
+        (cls) => !kitClasses.has(cls),
+      );
+
+      // Recursica's Button.module.css classes must exist...
+      expect(recursicaOnlyClasses.length).toBeGreaterThan(0);
+      // ...and none of them are present on the plain kit button.
+      for (const cls of recursicaOnlyClasses) {
+        expect(kitButton.classList.contains(cls)).toBe(false);
+      }
+
+      // Recursica-only markers confirm the two are meaningfully different components.
+      expect(recursicaButton.getAttribute("data-variant")).toBe("solid");
+      expect(kitButton.getAttribute("data-variant")).toBeNull();
+    } finally {
+      unmount(recursica);
+      unmount(kit);
+    }
+  });
+
+  it("renders a plain Mantine Button identically whether or not Recursica's Button is mounted alongside it", () => {
+    const recursica = mount(
+      withProvider(<RecursicaButton>Recursica</RecursicaButton>),
+    );
+    const kitAlongsideRecursica = mount(
+      withProvider(<MantineButton>Plain</MantineButton>),
+    );
+    const kitIsolated = mount(
+      withProvider(<MantineButton>Plain</MantineButton>),
+    );
+
+    try {
+      const kitButton =
+        kitAlongsideRecursica.container.querySelector("button")!;
+      const isolatedButton = kitIsolated.container.querySelector("button")!;
+
+      expect(Array.from(kitButton.classList).sort()).toEqual(
+        Array.from(isolatedButton.classList).sort(),
+      );
+
+      const kitStyle = getComputedStyle(kitButton);
+      const isolatedStyle = getComputedStyle(isolatedButton);
+      expect(kitStyle.borderRadius).toBe(isolatedStyle.borderRadius);
+      expect(kitStyle.backgroundColor).toBe(isolatedStyle.backgroundColor);
+      expect(kitStyle.fontFamily).toBe(isolatedStyle.fontFamily);
+    } finally {
+      unmount(recursica);
+      unmount(kitAlongsideRecursica);
+      unmount(kitIsolated);
+    }
+  });
+});

package/src/components/Button/IMPLEMENTATION_NOTES.md

@@ -38,6 +38,8 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 - The structural children wrap into `<span className={styles.labelText}>`.
 - **`.labelText`** binds `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;` creating flawless string cutoffs strictly at exact UI constraints.
 
+**Bug found (2026-08-27):** none of the above clips the button itself against a _constraining ancestor_ (e.g. `<div style={{ maxWidth: 250 }}>` — see the `TruncatedLabel` story). `.root` uses `width: fit-content` so it hugs its own content when unconstrained, but `fit-content` on this box doesn't reliably resize down against a narrower parent's resolved width — verified via Playwright: the button rendered at its full 534px `max-content` width and visually overflowed the 250px wrapper, even though the wrapper itself measured 250px. `max-width: 100%` on `.root` (percentage of the actual containing block) fixes it — it doesn't fight `width: fit-content` for the normal unconstrained case, it only kicks in when the parent is narrower than the content's intrinsic width.
+
 ---
 
 ## Disabled state: brand theme opacity (implicit)

package/src/components/Card/Card.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Card component tests. Add tests here if/when needed.

package/src/components/Checkbox/Checkbox.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Checkbox component tests. Add tests here if/when needed.

package/src/components/Chip/Chip.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Chip component tests. Add tests here if/when needed.

package/src/components/Container/Container.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Container component tests. Add tests here if/when needed.

package/src/components/DatePicker/DatePicker.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future DatePicker component tests. Add tests here if/when needed.

package/src/components/Dropdown/Dropdown.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Dropdown component tests. Add tests here if/when needed.

package/src/components/FileInput/FileInput.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FileInput component tests. Add tests here if/when needed.

package/src/components/FileUpload/FileUpload.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FileUpload component tests. Add tests here if/when needed.

package/src/components/Flex/Flex.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Flex component tests. Add tests here if/when needed.

package/src/components/Flex/Flex.tsx

@@ -10,18 +10,18 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Flex.module.css";
 
-import { type RecursicaFlexProps } from "@recursica/adapter-common";
-
 /**
  * Flex layout wrapper.
  *
  * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container)
  * DO NOT use the `RecursicaOverStyled` gatekeeper. Developers must be able to freely pass
  * width, height, padding, margins, and flexbox alignment props to construct structural layouts.
+ *
+ * No formal Recursica prop contract here: this simply passes through Mantine's own
+ * `FlexProps` (gap/rowGap/columnGap/direction/align/justify/wrap are all native to Mantine),
+ * layered only with rec- spacing token support via `WithRecursicaSpacing`.
  */
-export type FlexProps = WithRecursicaSpacing<
-  MantineFlexProps & RecursicaFlexProps
->;
+export type FlexProps = WithRecursicaSpacing<MantineFlexProps>;
 
 const _Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
   { children, gap = "rec-default", rowGap, columnGap, ...rest },

package/src/components/FormControlLayout/FormControlLayout.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FormControlLayout component tests. Add tests here if/when needed.

package/src/components/FormControlWrapper/FormControlWrapper.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future FormControlWrapper component tests. Add tests here if/when needed.

package/src/components/Grid/GRID_IMPLEMENTATION_NOTES.md

@@ -2,8 +2,8 @@
 
 The `Grid` component is a generic 12-column (by default) layout wrapper mapped directly to Mantine's `Grid`/`Grid.Col`. It requires no custom logical layouts or CSS workarounds — Mantine handles column geometry, breakpoints, and wrapping natively.
 
-The one deliberate divergence from Mantine's native API: the public `gap` prop replaces Mantine's `gutter`, for naming consistency with the other primitive layout components (`Flex`, `Stack`, `Group`). `gap` is translated to Mantine's `gutter` prop internally via `mapLayoutProps`, the same utility used to resolve `rec-*` spacing tokens elsewhere.
+Per the layout-components rule (no formal Recursica common props definition — these simply pass through the underlying kit's own props), `Grid` and `Grid.Col` are typed directly off Mantine's own `GridProps`/`GridColProps` with no Recursica-specific prop renaming. The public prop for spacing between columns is Mantine's own `gutter` (previously renamed to `gap` for cross-component consistency — that rename has been reverted since it wasn't a real Mantine prop). `gutter` still accepts `rec-*` spacing tokens, resolved via `mapLayoutProps`, the same utility used elsewhere.
 
-`Grid.Col`'s `span`, `offset`, `order`, `visibleFrom`, and `hiddenFrom` props are passed straight through to Mantine's `Grid.Col` unchanged — Mantine already uses generic, portable naming for these.
+`Grid.Col`'s `span`, `offset`, `order`, `visibleFrom`, and `hiddenFrom` props are passed straight through to Mantine's `Grid.Col` unchanged, using Mantine's own breakpoint scale (`xs`/`sm`/`md`/`lg`/`xl` — there is no `base` breakpoint in Mantine; `xs` is the smallest).
 
 Like the other primitive layout components, `Grid` and `Grid.Col` use `WithRecursicaSpacing<T>` rather than `RecursicaOverStyled<T>` and are listed in the "Primitive Layout Components Exemption" section of `OVERSTYLING.md`.

package/src/components/Grid/Grid.stories.tsx

@@ -19,12 +19,12 @@ const meta: Meta<GridStoryProps> = {
     },
   },
   args: {
-    gap: "rec-default",
+    gutter: "rec-default",
     columns: 12,
     grow: false,
   },
   argTypes: {
-    gap: {
+    gutter: {
       control: "select",
       options: [
         "rec-none",
@@ -35,7 +35,7 @@ const meta: Meta<GridStoryProps> = {
         "rec-xl",
         "rec-2xl",
       ],
-      description: "Gap between columns",
+      description: "Gutter between columns",
     },
     columns: {
       control: "number",
@@ -97,17 +97,17 @@ export const ResponsiveSpans: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
     <Grid {...args}>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>
-        <Swatch>base 12 / sm 6 / md 3</Swatch>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
       </Grid.Col>
     </Grid>
   ),

package/src/components/Grid/Grid.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Grid component tests. Add tests here if/when needed.

package/src/components/Grid/Grid.tsx

@@ -11,24 +11,21 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Grid.module.css";
 
-import {
-  type RecursicaGridProps,
-  type RecursicaGridColProps,
-} from "@recursica/adapter-common";
-
 /**
  * Grid layout wrapper.
  *
  * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container, Grid)
  * DO NOT use the `RecursicaOverStyled` gatekeeper. Developers must be able to freely pass
  * width, height, padding, margins, and flexbox alignment props to construct structural layouts.
+ *
+ * No formal Recursica prop contract here: this simply passes through Mantine's own
+ * `GridProps` (gutter/grow/columns/justify/align are all native to Mantine), layered only
+ * with rec- spacing token support via `WithRecursicaSpacing`.
  */
-export type GridProps = WithRecursicaSpacing<
-  Omit<MantineGridProps, "gutter"> & RecursicaGridProps
->;
+export type GridProps = WithRecursicaSpacing<MantineGridProps>;
 
 const _Grid = forwardRef<HTMLDivElement, GridProps>(function Grid(
-  { children, gap = "rec-default", ...rest },
+  { children, gutter = "rec-default", ...rest },
   ref,
 ) {
   const mergedClassNames: Partial<Record<string, string>> = {
@@ -50,15 +47,15 @@ const _Grid = forwardRef<HTMLDivElement, GridProps>(function Grid(
     ? `${styles.root} ${classNameProp}`
     : styles.root;
 
-  const { gap: gutter, ...mappedRest } = mapLayoutProps({
-    gap,
+  const { gutter: mappedGutter, ...mappedRest } = mapLayoutProps({
+    gutter,
     ...rest,
   } as Record<string, unknown>);
 
   return (
     <MantineGrid
       ref={ref}
-      gutter={gutter as MantineGridProps["gutter"]}
+      gutter={mappedGutter as MantineGridProps["gutter"]}
       className={finalClass}
       classNames={mergedClassNames}
       {...(mappedRest as unknown as Omit<MantineGridProps, "gutter">)}
@@ -87,9 +84,7 @@ const GridBase = createPolymorphicComponent<"div", GridProps>(_Grid);
 // GRID.COL
 // ============================================================
 
-export type GridColProps = WithRecursicaSpacing<
-  MantineGridColProps & RecursicaGridColProps
->;
+export type GridColProps = WithRecursicaSpacing<MantineGridColProps>;
 
 const _GridCol = forwardRef<HTMLDivElement, GridColProps>(function GridCol(
   { children, ...rest },

package/src/components/Grid/USAGE.md

@@ -20,9 +20,9 @@ import { Grid } from "@recursica/mantine-adapter";
 
 export default function Demo() {
   return (
-    <Grid gap="rec-default">
+    <Grid gutter="rec-default">
       <Grid.Col span={6}>Half width</Grid.Col>
-      <Grid.Col span={{ base: 12, sm: 6, md: 3 }}>Responsive width</Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>Responsive width</Grid.Col>
     </Grid>
   );
 }
@@ -44,4 +44,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-The `Grid` component maps directly to Mantine's `Grid`/`Grid.Col`. The one deviation from Mantine's native API: the prop for spacing between columns is named `gap` (not Mantine's `gutter`), for consistency with `Flex`, `Stack`, and `Group`. Everything else — `columns`, `grow`, `justify`, `align` on `Grid`, and `span`, `offset`, `order`, `visibleFrom`, `hiddenFrom` on `Grid.Col` — matches Mantine's own naming and accepts the same shapes, including per-breakpoint objects (`{ base, xs, sm, md, lg, xl }`).
+The `Grid` component maps directly to Mantine's `Grid`/`Grid.Col` with no Recursica-specific prop renaming — `gutter`, `columns`, `grow`, `justify`, `align` on `Grid`, and `span`, `offset`, `order`, `visibleFrom`, `hiddenFrom` on `Grid.Col` all match Mantine's own naming and accept the same shapes, including per-breakpoint objects (`{ xs, sm, md, lg, xl }`). `gutter` additionally accepts `rec-*` spacing tokens.

package/src/components/Group/Group.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Group component tests. Add tests here if/when needed.

package/src/components/Group/Group.tsx

@@ -9,18 +9,18 @@ import {
 } from "../../utils/filterStylingProps";
 import styles from "./Group.module.css";
 
-import { type RecursicaGroupProps } from "@recursica/adapter-common";
-
 /**
  * Group flex layout wrapper.
  *
  * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container)
  * DO NOT use the `RecursicaOverStyled` gatekeeper. Developers must be able to freely pass
  * width, height, padding, margins, and flexbox alignment props to construct structural layouts.
+ *
+ * No formal Recursica prop contract here: this simply passes through Mantine's own
+ * `GroupProps` (gap/rowGap/columnGap/justify/align/wrap are all native to Mantine),
+ * layered only with rec- spacing token support via `WithRecursicaSpacing`.
  */
-export type GroupProps = WithRecursicaSpacing<
-  MantineGroupProps & RecursicaGroupProps
->;
+export type GroupProps = WithRecursicaSpacing<MantineGroupProps>;
 
 export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
   { children, gap = "rec-default", ...rest },

package/src/components/HoverCard/HoverCard.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future HoverCard component tests. Add tests here if/when needed.

package/src/components/Label/Label.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Label component tests. Add tests here if/when needed.

package/src/components/Link/Link.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Link component tests. Add tests here if/when needed.

package/src/components/Loader/Loader.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Loader component tests. Add tests here if/when needed.

package/src/components/Menu/Menu.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Menu component tests. Add tests here if/when needed.

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -13,3 +13,15 @@ Mantine natively exposes an abstract `size` prop (`"sm" | "md" | "lg" | "xl"`) t
 ### 2. Scroll Dividers behavior
 
 Mantine internally handles scroll state natively, dynamically showing/hiding a divider line when content overflows in `.body`. This logic is tightly coupled to React DOM measurements internally. Our component inherits this dynamic behavior rather than statically rendering a permanent divider, matching Mantine's robust overflow UX. However, we aggressively override the generated `border-bottom` via CSS modules to ensure that when it _does_ appear, it correctly utilizes the `--recursica_ui-kit_components_modal_colors_scroll-divider` variable and `--recursica_ui-kit_components_modal_properties_scroll-divider-thickness` token.
+
+### 3. Title truncation
+
+`.title` truncates with an ellipsis (`overflow: hidden`, `white-space: nowrap`, `text-overflow: ellipsis`) rather than wrapping. It also needs `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside the close button — without `min-width: 0`, a flex item won't shrink below its content's intrinsic width, so ellipsis never engages. `.header`'s `display: flex` is likewise explicit rather than relied upon from Mantine's own header class, so the mui-adapter's plain-`<div>` header gets identical layout.
+
+### 4. Width was pinned to Mantine's `md` size, not content-driven
+
+Despite §1 above, `.content` never actually scaled fluidly: Mantine's own CSS sets `flex: 0 0 var(--modal-size)` (defaulting to 440px) on the Content element, and our module only added `min-width`/`max-width` without touching `flex`. A fixed flex-basis with `flex-shrink: 0` pins the box at exactly 440px regardless of those bounds, so they were unreachable dead code — e.g. "Authentication Required" (the `Default` story's title) didn't fit at 440px and silently wrapped to two lines. Overriding to `flex: 0 1 auto` makes the width shrink-to-fit the content within `min-width`/`max-width`, which is what makes title truncation (§3) only kick in once a title would exceed `max-width` rather than truncating titles that would otherwise fit. `.content[data-full-screen]` restores Mantine's own `flex: 0 0 100%` since the shrink-to-fit override would otherwise stop `fullScreen` from filling the viewport.
+
+### 5. Close button restyled to match Button
+
+`.close` reuses Button's text-variant/icon-only/small tokens (radius, padding, background/icon color, hover overlay, focus ring) instead of Mantine's native CloseButton look. Two overrides need `!important`/an explicit reset to win: Mantine's `CloseIcon` sizes itself via an inline `style` (`--cb-icon-size`, default `70%`), which beats any plain class rule — same category as Tree's `--level-offset` override; and Mantine's own subtle-variant `:hover` background (from `CloseButton.css`) is pinned back to the Button background token so only our `::after` overlay renders hover feedback.

package/src/components/Modal/Modal.module.css

@@ -1,3 +1,14 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Close button is styled to match the Button component's text/icon-only variant, so it reuses
+ * the same global hover/focus state tokens Button.module.css exempts.
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 .root {
 }
 
@@ -6,6 +17,12 @@
 }
 
 .content {
+  /* HARDCODE: Mantine pins content to a fixed flex-basis from its own size scale
+     (`flex: 0 0 var(--modal-size)`, defaulting to 440px). Overriding to `0 1 auto` makes width
+     content-driven (shrink-to-fit) instead of fixed, so min-width/max-width below actually bound
+     it rather than being unreachable dead code. */
+  flex: 0 1 auto;
+
   /* Geometric Bounds */
   min-width: var(--recursica_ui-kit_components_modal_properties_min-width);
   max-width: var(--recursica_ui-kit_components_modal_properties_max-width);
@@ -39,7 +56,16 @@
   flex-direction: column;
 }
 
+.content[data-full-screen] {
+  /* HARDCODE: preserve Mantine's native full-screen sizing — the shrink-to-fit override above
+     would otherwise apply here too and stop `fullScreen` from filling the viewport. */
+  flex: 0 0 100%;
+}
+
 .header {
+  display: flex; /* HARDCODE: puts the title and close button side-by-side so the title has a bounded width to truncate against */
+  align-items: center;
+  justify-content: space-between;
   padding: var(
       --recursica_ui-kit_components_modal_properties_header-footer-vertical-padding
     )
@@ -50,6 +76,12 @@
 }
 
 .title {
+  flex: 1 1 auto; /* HARDCODE: let the title claim the space between the header edge and the close button */
+  min-width: 0; /* HARDCODE: required for text-overflow ellipsis to take effect on a flex child */
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+
   color: var(--recursica_ui-kit_components_modal_properties_colors_title);
 
   /* Direct Figma Typography Mapping */
@@ -173,5 +205,91 @@
 }
 
 .close {
-  /* Inherits standard icon button tokens natively, but we can override if required */
+  /* Matches the Button component's text-variant, icon-only, small-size visual treatment
+     (see Button.module.css) so the modal close control looks like a Recursica Button
+     rather than Mantine's native CloseButton. */
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  overflow: hidden;
+  transition: all 0.2s ease;
+
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+  );
+
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+  );
+}
+
+/* Mantine's CloseIcon sets width/height via an inline `style` attribute
+   (`--cb-icon-size`, default 70%), which beats any plain class rule regardless of specificity —
+   same category of override as Tree's `--level-offset` (see Tree/IMPLEMENTATION_NOTES.md).
+   `!important` is required here to land the Button's small icon-size token instead. */
+.close svg {
+  position: relative;
+  z-index: 1;
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  ) !important;
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  ) !important;
+}
+
+.close::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  transition: opacity 150ms ease;
+  opacity: 0;
+  background-color: var(--recursica_brand_states_hover_color);
+}
+.close:hover:not(:disabled)::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* Mantine's own subtle-variant hover background (CloseButton.css) would otherwise show through
+   underneath the overlay above — pin it back to the Button's own background token so only the
+   `::after` overlay renders the hover feedback, matching Button's single-overlay treatment. */
+.close:hover {
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
+  );
+}
+
+.close:focus-visible {
+  outline: none;
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
 }

package/src/components/Modal/Modal.stories.tsx

@@ -19,7 +19,8 @@ export default meta;
 type Story = StoryObj<typeof Modal>;
 
 const DefaultWrapper = (args: ModalProps) => {
-  const [opened, setOpened] = useState(false);
+  // Starts opened so the modal is visible without pressing a button first.
+  const [opened, setOpened] = useState(true);
   return (
     <>
       <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
@@ -43,8 +44,33 @@ export const Default: Story = {
   render: (args) => <DefaultWrapper {...args} />,
 };
 
+const LongTitleWrapper = (args: ModalProps) => {
+  const [opened, setOpened] = useState(true);
+  return (
+    <>
+      <Modal {...args} opened={opened} onClose={() => setOpened(false)}>
+        The title above is longer than the header can display, so it truncates
+        with an ellipsis instead of wrapping onto a second line.
+        <Modal.Footer>
+          <Button onClick={() => setOpened(false)}>Got it</Button>
+        </Modal.Footer>
+      </Modal>
+      <Button onClick={() => setOpened(true)}>Open Modal</Button>
+    </>
+  );
+};
+
+export const LongTitle: Story = {
+  args: {
+    title:
+      "This Modal Title Is Deliberately Long Enough To Exceed The Available Header Width",
+  },
+  render: (args) => <LongTitleWrapper {...args} />,
+};
+
 const ScrollingWrapper = (args: ModalProps) => {
-  const [opened, setOpened] = useState(false);
+  // Starts opened so the modal is visible without pressing a button first.
+  const [opened, setOpened] = useState(true);
   return (
     <>
       <Modal {...args} opened={opened} onClose={() => setOpened(false)}>

package/src/components/Modal/Modal.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Modal component tests. Add tests here if/when needed.