@recursica/adapter-mantine-v8 1.2.2 → 1.3.1

package/src/components/Checkbox/Checkbox.module.css

@@ -21,7 +21,7 @@
 /* SideBySide Variant */
 .groupRoot[data-layout="side-by-side"] {
   flex-direction: column;
-  flex-wrap: wrap;
+  flex-wrap: nowrap;
   padding-top: var(
     --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_vertical-padding
   );
@@ -259,8 +259,6 @@
   );
 }
 .groupRoot[data-layout="side-by-side"] {
-  flex-direction: row;
-  flex-wrap: wrap;
   gap: var(
     --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_gutter
   );

package/src/components/Container/USAGE.md

@@ -35,7 +35,6 @@ All Recursica components in the `@recursica/adapter-mantine-v8` package adhere s
 
 > [!IMPORTANT]
 >
-> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
 

package/src/components/FileInput/FileInput.module.css

@@ -58,6 +58,14 @@
   min-height: var(
     --recursica_ui-kit_components_file-input_properties_min-height
   );
+  /* Fixed height (icon + padding + border) so the nested clear Button overflows the row instead of growing the control. */
+  height: calc(
+    var(--recursica_ui-kit_components_file-input_properties_icon-size) + 2 *
+      var(
+        --recursica_ui-kit_components_file-input_properties_vertical-padding
+      ) +
+      2 * var(--recursica_ui-kit_components_file-input_properties_border-size)
+  );
   gap: var(--recursica_ui-kit_components_file-input_properties_icon-text-gap);
   padding-top: var(
     --recursica_ui-kit_components_file-input_properties_vertical-padding

package/src/components/FileUpload/FileUpload.module.css

@@ -35,6 +35,7 @@
   display: flex;
   flex-direction: column;
   width: 100%;
+  max-width: var(--recursica_ui-kit_globals_form_field_size_max-width);
   gap: var(--recursica_ui-kit_components_file-upload_properties_list-spacing);
 }
 

package/src/components/FileUpload/FileUpload.tsx

@@ -265,6 +265,7 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
         required={required}
         withAsterisk={withAsterisk}
         id={id}
+        controlMaxWidth="var(--recursica_ui-kit_globals_form_field_size_max-width)"
       >
         <div
           ref={ref}

package/src/components/Flex/USAGE.md

@@ -36,10 +36,11 @@ All Recursica components in the `@recursica/adapter-mantine-v8` package adhere s
 
 > [!IMPORTANT]
 >
-> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
 
+> [!NOTE] > **Responsive props use your Mantine theme's breakpoints, not Forge's.** Keys such as `{ base, sm, md }` come from `theme.breakpoints`; Forge's layout grids switch via plain CSS `@media` and never edit the Mantine theme. Build your theme with `breakpointsFromRecManifest` so the two agree (see [LayoutGrid](../LayoutGrid/USAGE.md)).
+
 ---
 
 ## 4. Key Integration Features & Constraints

package/src/components/Group/USAGE.md

@@ -36,10 +36,11 @@ All Recursica components in the `@recursica/adapter-mantine-v8` package adhere s
 
 > [!IMPORTANT]
 >
-> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
 
+> [!NOTE] > **Responsive props use your Mantine theme's breakpoints, not Forge's.** Keys such as `{ base, sm, md }` come from `theme.breakpoints`; Forge's layout grids switch via plain CSS `@media` and never edit the Mantine theme. Build your theme with `breakpointsFromRecManifest` so the two agree (see [LayoutGrid](../LayoutGrid/USAGE.md)).
+
 ---
 
 ## 4. Key Integration Features & Constraints

package/src/components/LayoutGrid/LAYOUT_GRID_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,88 @@
+# LayoutGrid Implementation Notes
+
+`LayoutGrid` is the Recursica layout grid. It wraps Mantine's `Grid`/`Grid.Col`, but unlike the other
+primitive layout components (`Flex`, `Stack`, `Group`, `Container`) it has a formal Recursica prop
+contract (`RecursicaLayoutGridProps` in `adapter-common`) and wires the design system's
+`layout-grids` tokens. It was named `Grid` before 2026-10-02.
+
+## Forge contract
+
+Forge always emits a default grid with columns (default 6, editable), column-gutter, row-gutter and
+side margin, in the CSS and in `recursica_manifest.json`. Additional breakpoints are overrides.
+Because the variables are always defined, nothing here has a fallback value.
+
+## No integrator-facing layout props
+
+Columns, column-gutter, row-gutter and margin are design-system-managed, not per-instance settings.
+`columns` was removed 2026-10-01 because Forge defines `layout-grids` per breakpoint, so no fixed
+number is right at every viewport. For an arbitrary N-column grid, use Mantine's `Grid` directly.
+
+## Breakpoints
+
+Forge emits a responsive alias per grid var (`--recursica_brand_layout-grids_{columns,row-gutter,column-gutter,margin}`),
+set from `_default_*` at `:root` and redefined inside Forge's `@media` blocks per non-default grid.
+`LayoutGrid` reads only the alias, so tokens follow breakpoints with no JS. Overlapping ranges are
+not guarded by Forge; the later `@media` block wins.
+
+Responsive props (`span={{ base, md }}`, `visibleFrom`, and Flex/Stack/Group props) switch at the
+Mantine theme's breakpoints, which Forge never edits. Integrators should build `theme.breakpoints`
+with `breakpointsFromRecManifest` so both switch at the same widths. `RecursicaThemeProvider` is UI-kit agnostic and does not
+compare the manifest against the theme.
+
+## Why it is more than a thin wrapper
+
+Mantine's Grid divides widths by a JS number; Forge's column count is a CSS variable redefined in
+`@media` blocks, so Mantine's math can't follow it. All of `LayoutGrid.Col`'s span/offset handling
+(`ColLayoutStyles`) exists to bridge that gap. Alternatives considered and rejected (2026-10-02):
+
+- **Read the manifest in JS and pass Mantine the active column count.** Removes the per-column
+  styles, but makes the manifest required, flips the layout after hydration (flash with SSR),
+  creates a second source of truth next to the CSS variable, and loses span clamping.
+- **Rewrite on native CSS grid.** Numeric spans get trivial, but breakpoint-map spans still need
+  per-breakpoint rules, and Mantine's `grow`, `justify`, `align` and `type="container"` are lost.
+- **Drop breakpoint-map spans.** Removes most of the code but is a real feature loss.
+
+## How each token is applied
+
+- **Columns**: Mantine computes widths from a JS number, which can't follow a CSS var.
+  `LayoutGrid.Col` emits its own `<style>` rule (via Mantine's `InlineStyles`; inline styles would
+  beat the breakpoint rules) setting `--rec-col-basis`, `--rec-col-max-width` and `--rec-col-offset`
+  to `calc(min(span, columns) / columns * 100%)`, for the base value and every key of a
+  breakpoint-map `span`/`offset`. It uses the theme's breakpoints, or the grid's `breakpoints` with
+  `type="container"`. `.col.col` in `LayoutGrid.module.css` applies them in place of Mantine's
+  `--col-flex-basis`/`--col-max-width`/`--col-offset`. An omitted span is 12, like Mantine.
+  `"auto"` and `"content"` point the hooks back at Mantine's own variables, since they don't depend
+  on the column count. Mantine still needs a `columns` number but it never decides a width
+  (`MANTINE_UNUSED_COLUMNS`). `grow` is surfaced as `data-recursica-grow` on the root so CSS can keep
+  Mantine's `max-width: 100%` for grown columns.
+- **Column gutter**: passed to Mantine's `gutter` as `var(--recursica_brand_layout-grids_column-gutter)`.
+- **Row gutter / margin**: no Mantine equivalent; `LayoutGrid.module.css` reads them directly.
+  `.root.root` applies the margin, `.inner.inner` overrides `margin-block`, `.col.col` overrides
+  `padding-block`. The doubled-class selectors beat Mantine's single-class specificity.
+- Internal override hooks use the `--rec-*` prefix, never `--recursica*` (the build treats that as a
+  real token) and never a name Mantine uses itself.
+
+## `LayoutGrid.Col` contract is scaffolded
+
+`RecursicaLayoutGridColProps` currently only contributes `children`. `span`, `order`, `visibleFrom`
+and `hiddenFrom` were drafted and commented out (2026-09-22), so `LayoutGrid.Col` types them straight
+off Mantine's `GridColProps`. No runtime effect. Queued in
+`adapter-common/src/components/LayoutGrid/RecursicaLayoutGridColProps.ts`:
+
+- `span`/`order`: mantine-v8 and mui-v7 independently built matching versions, worth formalizing.
+  Mantine's name `span` was chosen over mui-v7's `size` (2026-09-22), so mui-v7 renames when this lands.
+- `visibleFrom`/`hiddenFrom` and per-breakpoint maps: blocked on a Recursica breakpoint naming
+  convention; `xs`/`sm`/`md`/`lg`/`xl` are Mantine's names. Don't copy them in.
+- `offset`: never added, still undiffed between the adapters.
+
+## Brand-layer exemption
+
+`layout-grids` tokens have no `ui-kit` layer in Forge's model (a grid is a page-layout primitive, not
+a component), so `LayoutGrid.module.css` reads `brand_layout-grids_*` directly, with
+`recursica-allow-brand:` headers (see `packages/recursica-token-analyzer/README.md` in the monorepo).
+
+## Stories
+
+A single `Default` story reads `brand.layout-grids.default.columns` from the manifest (via `useRecursicaManifest()`) and fills two rows of that many single-column cells. Stories only use what the
+`adapter-common` contract defines plus `span`, so they stay valid for every adapter; Mantine-only
+props (`offset`, `grow`, `visibleFrom`/`hiddenFrom`, breakpoint-map spans) are not demonstrated.

package/src/components/LayoutGrid/LayoutGrid.columns.dom.test.tsx

@@ -0,0 +1,66 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { MantineProvider, createTheme } from "@mantine/core";
+import { LayoutGrid } from "./LayoutGrid";
+
+const COLUMNS = "var(--recursica_brand_layout-grids_columns)";
+const basis = (n: number) => `calc(min(${n}, ${COLUMNS}) / ${COLUMNS} * 100%)`;
+
+function renderStyles(node: React.ReactElement, theme = createTheme({})) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  flushSync(() =>
+    root.render(<MantineProvider theme={theme}>{node}</MantineProvider>),
+  );
+  const css = [...container.querySelectorAll("style")]
+    .map((el) => el.innerHTML)
+    .join("\n");
+  root.unmount();
+  container.remove();
+  return css;
+}
+
+describe("Grid.Col column widths", () => {
+  it("derives breakpoint-map spans from the Forge column count", () => {
+    const css = renderStyles(
+      <LayoutGrid>
+        <LayoutGrid.Col span={{ base: 12, md: 6 }}>a</LayoutGrid.Col>
+      </LayoutGrid>,
+    );
+    expect(css).toContain(`--rec-col-basis:${basis(12)}`);
+    expect(css).toContain(`--rec-col-basis:${basis(6)}`);
+    expect(css).toMatch(/@media\(min-width: 62em\)/);
+  });
+
+  it("defaults an omitted span to 12 columns", () => {
+    const css = renderStyles(
+      <LayoutGrid>
+        <LayoutGrid.Col>a</LayoutGrid.Col>
+      </LayoutGrid>,
+    );
+    expect(css).toContain(`--rec-col-basis:${basis(12)}`);
+  });
+
+  it("hands auto and content back to Mantine's values", () => {
+    const css = renderStyles(
+      <LayoutGrid>
+        <LayoutGrid.Col span={{ base: 4, md: "auto" }}>a</LayoutGrid.Col>
+      </LayoutGrid>,
+    );
+    expect(css).toContain("--rec-col-basis:var(--col-flex-basis)");
+  });
+
+  it("uses custom breakpoint names from the theme", () => {
+    const css = renderStyles(
+      <LayoutGrid>
+        <LayoutGrid.Col span={{ base: 12, tablet: 4 }}>a</LayoutGrid.Col>
+      </LayoutGrid>,
+      createTheme({ breakpoints: { mobile: "0px", tablet: "481px" } }),
+    );
+    expect(css).toContain("(min-width: 481px)");
+    expect(css).toContain(`--rec-col-basis:${basis(4)}`);
+  });
+});

package/src/components/LayoutGrid/LayoutGrid.module.css

@@ -0,0 +1,48 @@
+/* HARDCODED VALUES:
+ * None. (--rec-col-basis / --rec-col-offset are internal hooks set by LayoutGrid.Col, not tokens.)
+ */
+
+/* Brand-layer exemptions (recursica-allow-brand) — layout-grid tokens have no ui-kit-layer
+ * representation in Forge's model (a grid is a page-layout primitive, not a "component"), so
+ * LayoutGrid is the one component that reads brand_layout-grids_* directly (the responsive alias, which Forge
+ * redefines per breakpoint inside @media). See
+ * LAYOUT_GRID_IMPLEMENTATION_NOTES.md.
+ *   recursica-allow-brand: --recursica_brand_layout-grids_column-gutter
+ *   recursica-allow-brand: --recursica_brand_layout-grids_row-gutter
+ *   recursica-allow-brand: --recursica_brand_layout-grids_columns
+ *   recursica-allow-brand: --recursica_brand_layout-grids_margin
+ */
+
+.root.root {
+  /* Mantine handles column geometry (span, gutter width/margin-inline math) natively — the
+     column-gutter design token is applied via LayoutGrid.tsx's `gutter` prop, not here. `margin` has no
+     Mantine equivalent at all, so it's applied directly on the root element, always from the
+     design token — margin is design-system-managed, not an integrator-facing override. Doubled
+     selector beats Mantine's own single-class specificity regardless of stylesheet load order
+     (same idiom as Chip/other components). */
+  margin: var(--recursica_brand_layout-grids_margin);
+}
+
+.inner.inner {
+  /* Mantine's own `.inner` margin is uniform on both axes, computed from `gutter`. Overriding just
+     the block (vertical) component here lets row spacing differ from column spacing without
+     touching Mantine's horizontal width/margin-inline math, which stays driven by `gutter`. Always
+     the design token — row-gutter is design-system-managed, not an integrator-facing override. */
+  margin-block: calc(var(--recursica_brand_layout-grids_row-gutter) / -2);
+}
+
+.col.col {
+  /* Column width/offset for numeric `span`/`offset`, from Forge's breakpoint-aware column count
+     (set by LayoutGrid.Col as --rec-col-basis / --rec-col-offset). LayoutGrid.Col sets the hooks at
+     every breakpoint a span/offset is given; "auto"/"content" point them back at Mantine's own
+     values. */
+  flex-basis: var(--rec-col-basis, var(--col-flex-basis));
+  max-width: var(--rec-col-max-width, var(--col-max-width));
+  margin-inline-start: var(--rec-col-offset, var(--col-offset));
+  /* Row-gutter design token, independent of column-gutter; padding-inline stays Mantine's own. */
+  padding-block: calc(var(--recursica_brand_layout-grids_row-gutter) / 2);
+}
+
+.root[data-recursica-grow] .col.col {
+  max-width: 100%;
+}

package/src/components/LayoutGrid/LayoutGrid.stories.tsx

@@ -0,0 +1,61 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { useRecursicaManifest } from "@recursica/adapter-common";
+import { LayoutGrid } from "./LayoutGrid";
+
+type LayoutGridStoryProps = React.ComponentProps<typeof LayoutGrid>;
+
+const meta: Meta<LayoutGridStoryProps> = {
+  title: "UI-Kit/LayoutGrid",
+  component: LayoutGrid,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "LayoutGrid is the Recursica layout grid. Its column count, column-gutter, row-gutter and margin come from the design system's layout-grid tokens, which Forge defines per breakpoint, so they respond to the viewport and are not integrator-configurable.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<LayoutGridStoryProps>;
+
+// Plain bordered cell: Card has a token min-width wider than one column, which would overflow it.
+const Swatch = ({ children }: { children: React.ReactNode }) => (
+  <div
+    style={{
+      border: "1px dashed currentColor",
+      padding: "8px",
+      textAlign: "center",
+    }}
+  >
+    {children}
+  </div>
+);
+
+// Reads the default layout grid from the manifest (brand.layout-grids.default) and fills two full
+// rows of single-column cells, so the story shows exactly the design system's column count.
+const DefaultGrid = () => {
+  const manifest = useRecursicaManifest() as {
+    brand: {
+      "layout-grids": { default: { columns: { $value: number } } };
+    };
+  };
+  const columns = manifest.brand["layout-grids"].default.columns.$value;
+  return (
+    <LayoutGrid>
+      {Array.from({ length: columns * 2 }, (_, i) => (
+        <LayoutGrid.Col key={i} span={1}>
+          <Swatch>{(i % columns) + 1}</Swatch>
+        </LayoutGrid.Col>
+      ))}
+    </LayoutGrid>
+  );
+};
+
+export const Default: Story = {
+  render: () => <DefaultGrid />,
+};

package/src/components/LayoutGrid/LayoutGrid.test.tsx

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

package/src/components/LayoutGrid/LayoutGrid.tsx

@@ -0,0 +1,309 @@
+import { createContext, forwardRef, useContext } from "react";
+import {
+  Grid as MantineGrid,
+  InlineStyles,
+  getSortedBreakpoints,
+  useMantineTheme,
+  useRandomClassName,
+  type GridProps as MantineGridProps,
+  type GridColProps as MantineGridColProps,
+  createPolymorphicComponent,
+} from "@mantine/core";
+import {
+  mapLayoutProps,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import {
+  type RecursicaLayoutGridColProps,
+  type RecursicaLayoutGridProps,
+} from "@recursica/adapter-common";
+import styles from "./LayoutGrid.module.css";
+
+// HOW THIS WORKS (why it is more than a thin Mantine wrapper)
+// Mantine's Grid divides column widths by a JS number, but Forge's column count is a CSS variable
+// (--recursica_brand_layout-grids_columns) that Forge redefines inside @media blocks, so Mantine's
+// math can never follow it. Everything below the root component exists to bridge that:
+//   1. LayoutGrid passes Mantine a dummy `columns` (it never decides a width) and the token-driven
+//      column gutter. Row-gutter and margin come from LayoutGrid.module.css.
+//   2. LayoutGrid.Col emits its own <style> rule (ColLayoutStyles) that sets --rec-col-basis,
+//      --rec-col-max-width and --rec-col-offset to calc(min(span, columns) / columns * 100%), once
+//      for the base value and once per key of a breakpoint-map span/offset (switching at the
+//      Mantine theme's breakpoints). LayoutGrid.module.css applies them in place of Mantine's own.
+//   3. "auto" and "content" don't depend on the column count, so they hand back to Mantine's vars.
+// Alternatives considered and rejected (2026-10-02): reading the manifest in JS to pass Mantine the
+// current column count (makes the manifest required, flips layout after hydration, no clamping),
+// and a native CSS-grid rewrite (loses Mantine's Grid API). See LAYOUT_GRID_IMPLEMENTATION_NOTES.md.
+
+// Mantine's Grid requires a column count for its own span math. Every width this component sets
+// is re-derived from Forge's --recursica_brand_layout-grids_columns (see colVars below), so this
+// number never determines a rendered width; it only has to be a valid value for Mantine.
+const MANTINE_UNUSED_COLUMNS = 1;
+
+interface LayoutGridContext {
+  type?: "media" | "container";
+  breakpoints?: Record<string, string>;
+}
+const LayoutGridContext = createContext<LayoutGridContext>({});
+
+/**
+ * LayoutGrid: the Recursica layout grid.
+ *
+ * Note: Unlike complex UI components, primitive layout components (Flex, Stack, Group, Container, LayoutGrid)
+ * 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.
+ *
+ * Recursica's `layout-grids` tokens (columns, column-gutter, row-gutter, margin) are
+ * design-system-managed and breakpoint-aware (Forge redefines them inside `@media` blocks), so
+ * LayoutGrid applies them itself via CSS variables. Neither Mantine's `gutter` nor `columns` is
+ * accepted; use Mantine's Grid directly for a fixed N-column grid. See
+ * `LAYOUT_GRID_IMPLEMENTATION_NOTES.md`.
+ */
+export type LayoutGridProps = WithRecursicaSpacing<
+  Omit<MantineGridProps, "gutter" | "columns"> &
+    Omit<RecursicaLayoutGridProps, "columns">
+>;
+
+const _LayoutGrid = forwardRef<HTMLDivElement, LayoutGridProps>(
+  function LayoutGrid({ children, ...rest }, ref) {
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+      inner: styles.inner,
+      col: styles.col,
+    };
+
+    const classNamesProp = rest.classNames;
+    if (
+      classNamesProp &&
+      typeof classNamesProp === "object" &&
+      !Array.isArray(classNamesProp)
+    ) {
+      const o = classNamesProp as Partial<Record<string, string>>;
+      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+      mergedClassNames.inner = o.inner
+        ? `${styles.inner} ${o.inner}`
+        : styles.inner;
+      mergedClassNames.col = o.col ? `${styles.col} ${o.col}` : styles.col;
+    }
+
+    const classNameProp = rest.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    // `gutter` is no longer a supported prop — column-gutter is design-system-managed (see below),
+    // dropped defensively here so a caller still passing the old prop name at runtime can't shadow
+    // the token-driven value passed to Mantine below via the `{...mappedRest}` spread.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { gutter: _legacyGutter, ...restWithoutGutter } = rest as Record<
+      string,
+      unknown
+    >;
+
+    const mappedRest = mapLayoutProps(
+      restWithoutGutter as Record<string, unknown>,
+    );
+
+    // Mantine computes column widths from a plain number, which can't follow Forge's per-breakpoint
+    // column count. Numeric and breakpoint-map `span`/`offset` are therefore re-derived from
+    // --recursica_brand_layout-grids_columns in LayoutGrid.Col (see colVars). Only "auto" and "content"
+    // spans still come from Mantine, and those don't depend on the column count.
+    return (
+      <LayoutGridContext.Provider
+        value={{
+          type: rest.type,
+          breakpoints: rest.breakpoints as Record<string, string> | undefined,
+        }}
+      >
+        <MantineGrid
+          ref={ref}
+          columns={MANTINE_UNUSED_COLUMNS}
+          gutter="var(--recursica_brand_layout-grids_column-gutter)"
+          data-recursica-grow={rest.grow ? "" : undefined}
+          className={finalClass}
+          classNames={mergedClassNames}
+          {...(mappedRest as unknown as Omit<
+            MantineGridProps,
+            "gutter" | "columns"
+          >)}
+        >
+          {children}
+        </MantineGrid>
+      </LayoutGridContext.Provider>
+    );
+  },
+);
+_LayoutGrid.displayName = "LayoutGrid";
+
+/**
+ * Recursica LayoutGrid layout wrapper.
+ *
+ * Supports polymorphism via the `component` prop for custom element rendering.
+ * @example
+ * ```tsx
+ * <LayoutGrid>
+ *   <LayoutGrid.Col span={3}>Half width at 6 columns (full width at 3)</LayoutGrid.Col>
+ *   <LayoutGrid.Col span={3}>Half width at 6 columns</LayoutGrid.Col>
+ * </LayoutGrid>
+ * ```
+ */
+const LayoutGridBase = createPolymorphicComponent<"div", LayoutGridProps>(
+  _LayoutGrid,
+);
+
+// ============================================================
+// GRID.COL
+// ============================================================
+
+// TODO(grid-col-contract): `RecursicaLayoutGridColProps` currently only contributes `children` here —
+// `span`, `order`, `visibleFrom`, and `hiddenFrom` are all drafted in that type (adapter-common)
+// but commented out for now (2026-09-22, Matt — paused to get Grid merged). Until they're
+// restored there, this stays a plain pass-through of Mantine's own `GridColProps`; no Omit needed
+// since nothing here is contract-backed yet. Re-add the intersection/Omit once
+// `RecursicaLayoutGridColProps` picks these back up. See `LAYOUT_GRID_IMPLEMENTATION_NOTES.md`.
+export type LayoutGridColProps = WithRecursicaSpacing<
+  MantineGridColProps & RecursicaLayoutGridColProps
+>;
+
+const COLUMNS_VAR = "var(--recursica_brand_layout-grids_columns)";
+
+// Numeric span/offset are expressed against Forge's (breakpoint-aware) column count. Span is
+// clamped to the current column count so e.g. span 6 fills the row at 3 columns instead of
+// overflowing. "auto" and "content" don't depend on the column count, so those hand back to
+// Mantine's own per-breakpoint values.
+const basisOf = (span: unknown): Record<string, string> => {
+  if (typeof span === "number") {
+    const basis = `calc(min(${span}, ${COLUMNS_VAR}) / ${COLUMNS_VAR} * 100%)`;
+    return { "--rec-col-basis": basis, "--rec-col-max-width": basis };
+  }
+  return {
+    "--rec-col-basis": "var(--col-flex-basis)",
+    "--rec-col-max-width": "var(--col-max-width)",
+  };
+};
+
+const offsetOf = (offset: unknown): Record<string, string> => ({
+  "--rec-col-offset":
+    typeof offset === "number"
+      ? `calc(${offset} / ${COLUMNS_VAR} * 100%)`
+      : "var(--col-offset)",
+});
+
+type ResponsiveValue = Record<string, unknown>;
+const isResponsive = (value: unknown): value is ResponsiveValue =>
+  typeof value === "object" && value !== null;
+const valueAt = (value: unknown, breakpoint: string) =>
+  isResponsive(value)
+    ? value[breakpoint]
+    : breakpoint === "base"
+      ? value
+      : undefined;
+
+const varsAt = (span: unknown, offset: unknown, breakpoint: string) => ({
+  ...(valueAt(span, breakpoint) === undefined
+    ? {}
+    : basisOf(valueAt(span, breakpoint))),
+  ...(valueAt(offset, breakpoint) === undefined
+    ? {}
+    : offsetOf(valueAt(offset, breakpoint))),
+});
+
+// Emitted as a <style> rule (like Mantine's own column styles) and not as inline style, because
+// an inline custom property would beat the breakpoint rules. `span` defaults to 12 columns, like
+// Mantine's Grid.Col.
+function ColLayoutStyles({
+  selector,
+  span,
+  offset,
+}: {
+  selector: string;
+  span: unknown;
+  offset: unknown;
+}) {
+  const theme = useMantineTheme();
+  const { type, breakpoints: gridBreakpoints } = useContext(LayoutGridContext);
+  const breakpoints = gridBreakpoints ?? theme.breakpoints;
+  const names = Object.keys(breakpoints).filter(
+    (name) =>
+      valueAt(span, name) !== undefined || valueAt(offset, name) !== undefined,
+  );
+  const media = getSortedBreakpoints(
+    names,
+    breakpoints as Parameters<typeof getSortedBreakpoints>[1],
+  ).map(({ value }) => ({
+    query:
+      type === "container"
+        ? `mantine-grid (min-width: ${breakpoints[value]})`
+        : `(min-width: ${breakpoints[value]})`,
+    styles: varsAt(span, offset, value),
+  }));
+  return (
+    <InlineStyles
+      selector={selector}
+      styles={varsAt(span ?? 12, offset, "base")}
+      media={type === "container" ? undefined : media}
+      container={type === "container" ? media : undefined}
+    />
+  );
+}
+
+const _LayoutGridCol = forwardRef<HTMLDivElement, LayoutGridColProps>(
+  function LayoutGridCol({ children, ...rest }, ref) {
+    const mergedClassNames: Partial<Record<string, string>> = {
+      col: styles.col,
+    };
+
+    const classNamesProp = rest.classNames;
+    if (
+      classNamesProp &&
+      typeof classNamesProp === "object" &&
+      !Array.isArray(classNamesProp)
+    ) {
+      const o = classNamesProp as Partial<Record<string, string>>;
+      mergedClassNames.col = o.col ? `${styles.col} ${o.col}` : styles.col;
+    }
+
+    const classNameProp = rest.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.col} ${classNameProp}`
+      : styles.col;
+
+    const layoutClassName = useRandomClassName();
+
+    return (
+      <>
+        <ColLayoutStyles
+          selector={`.${layoutClassName}`}
+          span={rest.span}
+          offset={rest.offset}
+        />
+        <MantineGrid.Col
+          ref={ref}
+          className={`${finalClass} ${layoutClassName}`}
+          classNames={mergedClassNames}
+          {...(mapLayoutProps(
+            rest as Record<string, unknown>,
+          ) as unknown as MantineGridColProps)}
+        >
+          {children}
+        </MantineGrid.Col>
+      </>
+    );
+  },
+);
+_LayoutGridCol.displayName = "LayoutGridCol";
+
+export const LayoutGridCol = createPolymorphicComponent<
+  "div",
+  LayoutGridColProps
+>(_LayoutGridCol);
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type LayoutGridComponent = typeof LayoutGridBase & {
+  Col: typeof LayoutGridCol;
+};
+
+export const LayoutGrid = LayoutGridBase as LayoutGridComponent;
+LayoutGrid.Col = LayoutGridCol;