@recursica/adapter-mantine-v8 1.2.2 → 1.3.0

package/src/utils/breakpointsFromRecManifest.ts

@@ -0,0 +1,75 @@
+interface ManifestNumber {
+  $value?: unknown;
+}
+
+interface ManifestLayoutGrid {
+  "min-width"?: ManifestNumber;
+  "max-width"?: ManifestNumber;
+}
+
+interface ManifestWithLayoutGrids {
+  brand?: { "layout-grids"?: Record<string, unknown> };
+}
+
+function width(grid: ManifestLayoutGrid, key: "min-width" | "max-width") {
+  const value = grid[key]?.$value;
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(
+      `layout-grid ${key} must be a non-negative number, got ${String(value)}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Builds a `{ name: "<start>px" }` breakpoints object from the manifest's layout grids, ready to
+ * pass to Mantine's `createTheme({ breakpoints })`. Opt-in: nothing in the
+ * adapters calls this for you, and the result is a plain object you can edit.
+ *
+ * Mantine breakpoints are mobile-first start widths, so each non-default grid maps to its
+ * `min-width`; a grid with only a `max-width` (e.g. `mobile`, up to 480px) starts at `0px`. The
+ * `default` grid has no width of its own: when other grids exist it is included, named `default`,
+ * starting one pixel past the widest `max-width`. A manifest with only the `default` grid (the
+ * stock Forge export) returns `{}`, so the theme is left untouched.
+ *
+ * Throws for a non-default grid with neither width, for non-numeric widths, and when no other grid
+ * has a `max-width` for `default` to start after.
+ */
+export function breakpointsFromRecManifest(
+  manifest: ManifestWithLayoutGrids,
+): Record<string, string> {
+  const grids = (manifest.brand?.["layout-grids"] ?? {}) as Record<
+    string,
+    ManifestLayoutGrid
+  >;
+  const entries: [string, number][] = [];
+  let widestMax: number | undefined;
+  for (const [name, grid] of Object.entries(grids)) {
+    if (name === "default") continue;
+    const min = width(grid, "min-width");
+    const max = width(grid, "max-width");
+    if (min === undefined && max === undefined) {
+      throw new Error(
+        `layout-grid "${name}" has neither min-width nor max-width`,
+      );
+    }
+    if (max !== undefined && (widestMax === undefined || max > widestMax)) {
+      widestMax = max;
+    }
+    entries.push([name, min ?? 0]);
+  }
+  if (entries.length > 0) {
+    if (widestMax === undefined) {
+      throw new Error(
+        'Cannot place the "default" layout-grid: no other grid has a max-width to start after',
+      );
+    }
+    entries.push(["default", widestMax + 1]);
+  }
+  return Object.fromEntries(
+    entries
+      .sort((a, b) => a[1] - b[1])
+      .map(([name, start]) => [name, `${start}px`]),
+  );
+}

package/src/utils/index.ts

@@ -1 +1,2 @@
 export * from "./copyToClipboard";
+export * from "./breakpointsFromRecManifest";

package/src/components/Grid/GRID_IMPLEMENTATION_NOTES.md

@@ -1,85 +0,0 @@
-# Grid Implementation Notes
-
-The `Grid` component wraps Mantine's `Grid`/`Grid.Col`, but — unlike the other primitive layout
-components (`Flex`, `Stack`, `Group`, `Container`) — it now has a formal Recursica prop contract
-(`RecursicaGridProps` in `adapter-common`) wiring the design system's `layout-grids` tokens.
-Earlier versions of this file documented the opposite policy ("no intrinsic design-system styles
-required"); that was revisited on 2026-09-21 once Forge's export added `layout-grids` tokens
-(`default_columns`, `default_column-gutter`, `default_row-gutter`, `default_margin` — see
-`docs/migration/2026-09-21-forge-token-export.md`) with no equivalent anywhere else to consume
-them.
-
-## Only `columns` is an integrator-facing prop
-
-Column-gutter, row-gutter, and margin are design-system-managed values (Forge-controlled, applied
-via CSS variables), not per-instance settings — the integrator does not configure them. Only
-`columns` is exposed as an override, the same pattern `Container.size` uses for its own
-token-backed default. An earlier draft of this component exposed `columnGutter`/`rowGutter`/
-`margin` as props too; that was reverted after review — see git history on this file for that
-approach if it's ever needed again.
-
-## How each token actually gets applied
-
-- **`columns`** has no CSS-variable equivalent in Mantine — it computes each column's flex-basis
-  from a plain number. The design system default (6) is baked into `Grid.tsx` as a JS default
-  (`columns ?? 6`), not wired live through CSS. If the token's value changes, this line needs a
-  manual update. Callers may still override it (see `CustomColumnCount` story).
-- **`columnGutter`** (the design token, not a prop) is passed straight to Mantine's own `gutter`
-  prop as `var(--recursica_brand_layout-grids_default_column-gutter)` — always, not
-  caller-configurable. This is the only axis Mantine's Grid natively parameterizes, so it drives
-  Mantine's own internal width/margin-inline math unmodified.
-- **`rowGutter`/`margin`** (the design tokens) have no Mantine equivalent at all. `Grid.module.css`
-  reads them directly, always:
-  - `.root.root` applies `margin: var(--recursica_brand_layout-grids_default_margin)` (Mantine has
-    no root-level margin concept to conflict with).
-  - `.inner.inner` overrides only `margin-block` (not the `margin` shorthand) with
-    `var(--recursica_brand_layout-grids_default_row-gutter)` so it doesn't disturb Mantine's own
-    horizontal `margin-inline` math, which stays driven by `columnGutter`.
-  - `.col.col` overrides only `padding-block` for the same reason (`padding-inline` stays Mantine's
-    own, driven by `gutter`).
-  - All three use the doubled-class-selector trick (`.root.root`, not `.root`) to reliably beat
-    Mantine's own compiled single-class specificity regardless of stylesheet load order — same
-    idiom used elsewhere in this codebase (e.g. Chip).
-
-## `Grid.Col`'s formal contract is scaffolded, not filled in yet
-
-`RecursicaGridColProps` exists in `adapter-common`, and `Grid.tsx` here intersects `GridColProps`
-with it — but as of 2026-09-22 it only contributes `children`. `span`, `order`, `visibleFrom`, and
-`hiddenFrom` were all drafted as real contract fields during this work and then commented out
-(Matt: get Grid merged first, come back to this later), so `Grid.Col` still types all four
-straight off `MantineGridColProps`, same as before any of this started. No runtime change — this
-is purely about where the types come from, not behavior.
-
-What's queued up in `adapter-common/src/components/Grid/RecursicaGridColProps.ts` (commented,
-with a TODO) for whenever this gets picked back up:
-
-- `span`/`order`: both mantine-v8 and mui-v7 independently built matching versions of these with
-  no shared contract driving either — worth formalizing. `span` also resolves a naming mismatch:
-  Mantine calls the column-width prop `span`, mui-v7 calls it `size` — Matt already decided on
-  Mantine's naming (2026-09-22), so mui-v7 will need to rename `size` to `span` when this lands.
-- `visibleFrom`/`hiddenFrom`: same "both adapters independently agree" signal, but blocked on a
-  real Recursica breakpoint naming convention — their `xs`/`sm`/`md`/`lg`/`xl` values are
-  Mantine's own naming, not Recursica's, and Recursica doesn't have its own yet. Don't just copy
-  Mantine's keys back in.
-- `offset`: never added — still undiffed between the two adapters.
-- Also note: `span`/`order`'s own per-breakpoint map variants (`{ xs: 6, sm: 3 }`) have the same
-  `xs`/`sm`/`md`/`lg`/`xl` naming gap as `visibleFrom`/`hiddenFrom` — worth resolving together.
-
-## Brand-layer exemption
-
-`layout-grids` tokens have no `ui-kit`-layer representation in Forge's model — a grid is a
-page-layout primitive, not a "component," so there was never going to be a
-`ui-kit_components_grid_*` indirection layer for it to go through. `Grid.module.css` reads
-`brand_layout-grids_default_*` directly, with `recursica-allow-brand:` exemption headers
-documenting why (see the analyzer's own exemption-system docs,
-`packages/recursica-token-analyzer/README.md` in the monorepo).
-
-## Stories
-
-`ResponsiveSpans` and `ResponsiveSizes` explicitly override `columns={12}` — they test Mantine's
-own breakpoint/span system at standard 12-column proportions and aren't meant to exercise the
-design system's 6-column default. `ResponsiveSizes` exists purely so mui-adapter's
-`ui-kit-grid--responsive-sizes` story id has a source-of-truth counterpart to diff against (Mantine's
-`Grid.Col` has no `size` prop, only `span` — `ResponsiveSpans` already covers that). `Default`,
-`Offset`, `Grow`, and `CustomColumnCount` all exercise the real 6-column default (or an explicit
-override of it) and were resized from the old 12-column assumptions accordingly.

package/src/components/Grid/Grid.module.css

@@ -1,41 +0,0 @@
-/* HARDCODED VALUES:
- * None.
- */
-
-/* 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
- * Grid is the one component that reads brand_layout-grids_* directly. See
- * GRID_IMPLEMENTATION_NOTES.md.
- *   recursica-allow-brand: --recursica_brand_layout-grids_default_column-gutter
- *   recursica-allow-brand: --recursica_brand_layout-grids_default_row-gutter
- *   recursica-allow-brand: --recursica_brand_layout-grids_default_margin
- */
-
-.root.root {
-  /* Mantine handles column geometry (span, gutter width/margin-inline math) natively — the
-     column-gutter design token is applied via Grid.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_default_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_default_row-gutter) / -2
-  );
-}
-
-.col.col {
-  /* Mantine handles column sizing (span, offset, order, visibleFrom/hiddenFrom) and inline padding
-     (from `gutter`) natively. Overriding just the block (vertical) padding here applies the
-     row-gutter design token independently of column-gutter, always from the design token. */
-  padding-block: calc(
-    var(--recursica_brand_layout-grids_default_row-gutter) / 2
-  );
-}

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

@@ -1,200 +0,0 @@
-import React from "react";
-import type { Meta, StoryObj } from "@storybook/react";
-import { Grid } from "./Grid";
-import { Card } from "../Card/Card";
-import { Text } from "../Text/Text";
-
-type GridStoryProps = React.ComponentProps<typeof Grid>;
-
-const meta: Meta<GridStoryProps> = {
-  title: "UI-Kit/Grid",
-  component: Grid,
-  tags: ["autodocs"],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          "Grid is a responsive grid layout mapped to Mantine's Grid/Grid.Col, providing column spans, offsets, ordering, and breakpoint-based visibility. Defaults to the design system's own layout-grid tokens: 6 columns, with design-system-managed column-gutter/row-gutter/margin values applied automatically (not integrator-configurable).",
-      },
-    },
-  },
-  args: {
-    grow: false,
-  },
-  argTypes: {
-    columns: {
-      control: "number",
-      description:
-        "Number of columns in each row. Defaults to the design system's default column count (6).",
-    },
-    grow: {
-      control: "boolean",
-      description: "Columns in the last row expand to fill available space",
-    },
-    justify: {
-      control: "select",
-      options: [
-        "flex-start",
-        "center",
-        "flex-end",
-        "space-between",
-        "space-around",
-      ],
-      description: "Justify-content property",
-    },
-    align: {
-      control: "select",
-      options: ["flex-start", "center", "flex-end", "stretch"],
-      description: "Align-items property",
-    },
-  },
-};
-
-export default meta;
-
-type Story = StoryObj<GridStoryProps>;
-
-const Swatch = ({ children }: { children: React.ReactNode }) => (
-  <Card>
-    <Card.Content>
-      <Text>{children}</Text>
-    </Card.Content>
-  </Card>
-);
-
-// Uses the design system default (6 columns) with no explicit `columns` override.
-export const Default: 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={2}>
-        <Swatch>span 2 of 6 (default)</Swatch>
-      </Grid.Col>
-      <Grid.Col span={2}>
-        <Swatch>span 2 of 6 (default)</Swatch>
-      </Grid.Col>
-      <Grid.Col span={2}>
-        <Swatch>span 2 of 6 (default)</Swatch>
-      </Grid.Col>
-    </Grid>
-  ),
-};
-
-// Explicitly overrides `columns` to 12 — this story exercises Mantine's own breakpoint/span
-// system at standard 12-column proportions, independent of the design system's 6-column default.
-export const ResponsiveSpans: Story = {
-  args: {
-    columns: 12,
-  },
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
-  render: ({ withLayer, layer, ...args }: any) => (
-    <Grid {...args}>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-    </Grid>
-  ),
-};
-
-// Mirrors mui-adapter's `ResponsiveSizes` story (same breakpoints/content) under mantine's own
-// prop name — Mantine's Grid.Col has no `size` prop, only `span`, which is what `ResponsiveSpans`
-// above already exercises. This one exists purely so mui-adapter's `responsive-sizes` story id
-// has a source-of-truth counterpart to diff against (see GRID_IMPLEMENTATION_NOTES.md). Same
-// explicit 12-column override as `ResponsiveSpans`, for the same reason.
-export const ResponsiveSizes: Story = {
-  args: {
-    columns: 12,
-  },
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
-  render: ({ withLayer, layer, ...args }: any) => (
-    <Grid {...args}>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
-        <Swatch>xs 12 / sm 6 / md 3</Swatch>
-      </Grid.Col>
-    </Grid>
-  ),
-};
-
-export const Offset: 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={2} offset={2}>
-        <Swatch>span 2, offset 2 (of 6)</Swatch>
-      </Grid.Col>
-      <Grid.Col span={2}>
-        <Swatch>span 2 (of 6)</Swatch>
-      </Grid.Col>
-    </Grid>
-  ),
-};
-
-export const Grow: Story = {
-  args: {
-    grow: true,
-  },
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
-  render: ({ withLayer, layer, ...args }: any) => (
-    <Grid {...args}>
-      <Grid.Col span={3}>
-        <Swatch>span 3 (of 6)</Swatch>
-      </Grid.Col>
-      <Grid.Col span={3}>
-        <Swatch>span 3 (of 6)</Swatch>
-      </Grid.Col>
-      <Grid.Col span={3}>
-        <Swatch>span 3 (grows to fill row)</Swatch>
-      </Grid.Col>
-    </Grid>
-  ),
-};
-
-// Overrides the design system's default column count (6) to demonstrate a genuinely custom value.
-export const CustomColumnCount: Story = {
-  args: {
-    columns: 4,
-  },
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
-  render: ({ withLayer, layer, ...args }: any) => (
-    <Grid {...args}>
-      <Grid.Col span={2}>
-        <Swatch>span 2 of 4</Swatch>
-      </Grid.Col>
-      <Grid.Col span={2}>
-        <Swatch>span 2 of 4</Swatch>
-      </Grid.Col>
-    </Grid>
-  ),
-};
-
-export const VisibleHiddenFrom: 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={3} hiddenFrom="sm">
-        <Swatch>hidden from sm and up</Swatch>
-      </Grid.Col>
-      <Grid.Col span={3} visibleFrom="sm">
-        <Swatch>visible from sm and up</Swatch>
-      </Grid.Col>
-    </Grid>
-  ),
-};

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

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

package/src/components/Grid/Grid.tsx

@@ -1,179 +0,0 @@
-import { forwardRef } from "react";
-import {
-  Grid as MantineGrid,
-  type GridProps as MantineGridProps,
-  type GridColProps as MantineGridColProps,
-  createPolymorphicComponent,
-} from "@mantine/core";
-import {
-  mapLayoutProps,
-  type WithRecursicaSpacing,
-} from "../../utils/filterStylingProps";
-import {
-  type RecursicaGridColProps,
-  type RecursicaGridProps,
-} from "@recursica/adapter-common";
-import styles from "./Grid.module.css";
-
-/**
- * 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.
- *
- * Recursica's `layout-grids` tokens (column-gutter, row-gutter, margin) are design-system-managed
- * values, not integrator-facing settings — Grid applies them itself via CSS variables. Mantine's
- * own `gutter` prop is not accepted; only `columns` (from `RecursicaGridProps` in
- * `adapter-common`) is exposed as an override, matching how `Container.size` overrides its own
- * token-backed default. See `GRID_IMPLEMENTATION_NOTES.md`.
- */
-export type GridProps = WithRecursicaSpacing<
-  Omit<MantineGridProps, "gutter" | "columns"> & RecursicaGridProps
->;
-
-const _Grid = forwardRef<HTMLDivElement, GridProps>(function Grid(
-  { children, columns, ...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>,
-  );
-
-  // `columns` has no CSS-variable equivalent in Mantine — it computes each column's flex-basis
-  // from a plain number, so the design system default is baked in here as a JS default rather
-  // than wired live through CSS. Sourced from --recursica_brand_layout-grids_default_columns.
-  const resolvedColumns = columns ?? 6;
-
-  return (
-    <MantineGrid
-      ref={ref}
-      columns={resolvedColumns}
-      gutter="var(--recursica_brand_layout-grids_default_column-gutter)"
-      className={finalClass}
-      classNames={mergedClassNames}
-      {...(mappedRest as unknown as Omit<
-        MantineGridProps,
-        "gutter" | "columns"
-      >)}
-    >
-      {children}
-    </MantineGrid>
-  );
-});
-_Grid.displayName = "Grid";
-
-/**
- * Recursica Grid layout wrapper.
- *
- * Supports polymorphism via the `component` prop for custom element rendering.
- * @example
- * ```tsx
- * <Grid>
- *   <Grid.Col span={3}>Quarter width (defaults to 6 columns)</Grid.Col>
- *   <Grid.Col span={3}>Quarter width</Grid.Col>
- * </Grid>
- * ```
- */
-const GridBase = createPolymorphicComponent<"div", GridProps>(_Grid);
-
-// ============================================================
-// GRID.COL
-// ============================================================
-
-// TODO(grid-col-contract): `RecursicaGridColProps` 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
-// `RecursicaGridColProps` picks these back up. See `GRID_IMPLEMENTATION_NOTES.md`.
-export type GridColProps = WithRecursicaSpacing<
-  MantineGridColProps & RecursicaGridColProps
->;
-
-const _GridCol = forwardRef<HTMLDivElement, GridColProps>(function GridCol(
-  { 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;
-
-  return (
-    <MantineGrid.Col
-      ref={ref}
-      className={finalClass}
-      classNames={mergedClassNames}
-      {...(mapLayoutProps(
-        rest as Record<string, unknown>,
-      ) as unknown as MantineGridColProps)}
-    >
-      {children}
-    </MantineGrid.Col>
-  );
-});
-_GridCol.displayName = "GridCol";
-
-export const GridCol = createPolymorphicComponent<"div", GridColProps>(
-  _GridCol,
-);
-
-// ============================================================
-// DOT NOTATION EXPORT
-// ============================================================
-
-type GridComponent = typeof GridBase & {
-  Col: typeof GridCol;
-};
-
-export const Grid = GridBase as GridComponent;
-Grid.Col = GridCol;

package/src/components/Grid/USAGE.md

@@ -1,61 +0,0 @@
-# Grid - Usage Guide
-
-This document describes how to integrate and use the `Grid` component in your projects using `@recursica/adapter-mantine-v8`.
-
----
-
-## 1. Import Reference
-
-```tsx
-import { Grid } from "@recursica/adapter-mantine-v8";
-```
-
----
-
-## 2. Basic Example
-
-```tsx
-import React from "react";
-import { Grid } from "@recursica/adapter-mantine-v8";
-
-export default function Demo() {
-  return (
-    // No props needed for the design system default: 6 columns, with the design system's own
-    // column-gutter/row-gutter/margin values.
-    <Grid>
-      <Grid.Col span={3}>Half width (of 6)</Grid.Col>
-      <Grid.Col span={{ xs: 6, sm: 3, md: 2 }}>Responsive width</Grid.Col>
-    </Grid>
-  );
-}
-```
-
----
-
-## 3. Design System Integration
-
-All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
-
-> [!IMPORTANT]
->
-> - **Anti-override protection**: `Grid` is a primitive layout component (see [OVERSTYLING.md](../../../OVERSTYLING.md)), so standard Mantine layout props pass through freely without needing `overStyled`.
-> - **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**: Grid follows the design system's own `layout-grids` tokens — 6 columns, with column-gutter/row-gutter/margin applied automatically. Only `columns` is an integrator-facing override; the gutter/margin values are design-system-managed and not configurable via props.
-
----
-
-## 4. Key Integration Features & Constraints
-
-`Grid.Col`'s `span`, `offset`, `order`, `visibleFrom`, `hiddenFrom` match Mantine's own naming and
-accept the same shapes, including per-breakpoint objects (`{ xs, sm, md, lg, xl }`) — all still a
-straight Mantine pass-through for now. A formal `RecursicaGridColProps` contract in
-`adapter-common` is scaffolded but not filled in yet (TODO, tracked in
-`GRID_IMPLEMENTATION_NOTES.md`).
-
-`Grid` no longer accepts Mantine's own `gutter` prop — column-gutter, row-gutter, and margin are
-design-system-managed (Forge-controlled, applied via CSS variables) rather than integrator
-settings:
-
-- `columns?: number` — the only design-token-backed override on Grid; defaults to 6.
-
-`grow`, `justify`, `align` are unchanged, matching Mantine's own naming.