@recursica/adapter-mui-v7 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -13,6 +13,7 @@ import { CardProps as CardProps_2 } from '@mui/material';
 import { CheckboxProps as CheckboxProps_2 } from '@mui/material';
 import { ChipProps as ChipProps_2 } from '@mui/material';
 import { CommonProps } from '@mui/material/OverridableComponent';
+import { ComponentPropsWithoutRef } from 'react';
 import { ContainerProps as ContainerProps_2 } from '@mui/material';
 import { CSSProperties } from 'react';
 import { DatePickerProps as DatePickerProps_2 } from '@mui/x-date-pickers/DatePicker';
@@ -31,7 +32,7 @@ import { FormControlProps } from '@mui/material';
 import { FormGroupProps } from '@mui/material';
 import { FormHelperTextProps } from '@mui/material';
 import { ForwardRefExoticComponent } from 'react';
-import { GridProps as GridProps_2 } from '@mui/material';
+import { GridProps } from '@mui/material';
 import { HTMLAttributes } from 'react';
 import { InputBaseProps } from '@mui/material';
 import { InputLabelProps } from '@mui/material';
@@ -39,7 +40,6 @@ import { JSX } from 'react';
 import { LinkProps as LinkProps_2 } from '@mui/material';
 import { MenuItemProps as MenuItemProps_2 } from '@mui/material';
 import { MenuProps as MenuProps_2 } from '@mui/material';
-import { PaginationProps as PaginationProps_2 } from '@mui/material';
 import { RadioGroupProps as RadioGroupProps_2 } from '@mui/material';
 import { RadioProps as RadioProps_2 } from '@mui/material';
 import { ReactNode } from 'react';
@@ -68,11 +68,11 @@ import { RecursicaFileUploadItem } from '@recursica/adapter-common';
 import { RecursicaFileUploadProps as RecursicaFileUploadProps_2 } from '@recursica/adapter-common';
 import { RecursicaFormControlLayoutProps } from '@recursica/adapter-common';
 import { RecursicaFormControlWrapperProps as RecursicaFormControlWrapperProps_2 } from '@recursica/adapter-common';
-import { RecursicaGridColProps } from '@recursica/adapter-common';
-import { RecursicaGridProps } from '@recursica/adapter-common';
 import { RecursicaHeadingProps } from '@recursica/adapter-common';
 import { RecursicaHoverCardProps } from '@recursica/adapter-common';
 import { RecursicaLabelProps } from '@recursica/adapter-common';
+import { RecursicaLayoutGridColProps } from '@recursica/adapter-common';
+import { RecursicaLayoutGridProps } from '@recursica/adapter-common';
 import { RecursicaLinkProps } from '@recursica/adapter-common';
 import { RecursicaLoaderProps } from '@recursica/adapter-common';
 import { RecursicaMenuProps } from '@recursica/adapter-common';
@@ -139,6 +139,7 @@ import { TimePickerProps as TimePickerProps_2 } from '@mui/x-date-pickers/TimePi
 import { ToggleButtonGroupProps } from '@mui/material';
 import { TooltipProps as TooltipProps_2 } from '@mui/material';
 import { TypographyProps as TypographyProps_2 } from '@mui/material';
+import { UsePaginationProps } from '@mui/material/usePagination';
 import { WithRecursicaSpacing } from '@recursica/adapter-common';
 
 export declare const Accordion: AccordionComponent;
@@ -352,6 +353,23 @@ export declare type BreadcrumbProps = RecursicaOverStyled<Omit<BreadcrumbsProps,
 
 declare type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl";
 
+/**
+ * Builds a `{ name: <start px> }` breakpoint values object from the manifest's layout grids, to
+ * merge into MUI's `createTheme({ breakpoints: { values } })`. Opt-in: nothing in the adapter
+ * calls this for you, and the result is a plain object you can edit.
+ *
+ * MUI 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 `0`. 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 `{}`. MUI's `values` replaces its defaults rather than merging, so
+ * spread MUI's own defaults first: `values: { ...createTheme().breakpoints.values, ...result }`.
+ *
+ * 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 declare function breakpointsFromRecManifest(manifest: ManifestWithLayoutGrids): Record<string, number>;
+
 /**
  * Recursica Button component wrapping MUI's Button.
  *
@@ -620,32 +638,6 @@ export declare const FormControlWrapper: default_2.ForwardRefExoticComponent<Omi
 
 export declare type FormControlWrapperProps = RecursicaFormControlWrapperProps;
 
-export declare const Grid: GridComponent;
-
-declare const GridBase: ForwardRefExoticComponent<Omit<GridProps, "ref"> & RefAttributes<HTMLDivElement>>;
-
-export declare const GridCol: ForwardRefExoticComponent<Omit<GridColProps, "ref"> & RefAttributes<HTMLDivElement>>;
-
-export declare type GridColProps = WithRecursicaSpacing<OmitSx<Omit<GridProps_2, "container" | "order">>> & RecursicaGridColProps & {
-    /** Sets the CSS `order` property. Applied via inline style — see notes above. */
-    order?: number;
-    /** Hides the column below the given breakpoint. MUI has no native equivalent. */
-    visibleFrom?: Breakpoint;
-    /** Hides the column above the given breakpoint. MUI has no native equivalent. */
-    hiddenFrom?: Breakpoint;
-};
-
-declare type GridComponent = typeof GridBase & {
-    Col: typeof GridCol;
-};
-
-export declare type GridProps = WithRecursicaSpacing<OmitSx<Omit<GridProps_2, "container" | "justifyContent" | "alignItems" | "spacing" | "columnSpacing" | "rowSpacing" | "columns">>> & RecursicaGridProps & {
-    /** Sets `justify-content` on the container. Applied via inline style — see notes above. */
-    justifyContent?: CSSProperties["justifyContent"];
-    /** Sets `align-items` on the container. Applied via inline style — see notes above. */
-    alignItems?: CSSProperties["alignItems"];
-};
-
 export declare const Group: ForwardRefExoticComponent<Omit<GroupProps, "ref"> & RefAttributes<HTMLDivElement>>;
 
 declare interface GroupOwnProps {
@@ -724,6 +716,32 @@ export declare interface LabelProps extends InputLabelProps, RecursicaLabelProps
     overStyled?: boolean;
 }
 
+export declare const LayoutGrid: LayoutGridComponent;
+
+declare const LayoutGridBase: ForwardRefExoticComponent<Omit<LayoutGridProps, "ref"> & RefAttributes<HTMLDivElement>>;
+
+export declare const LayoutGridCol: ForwardRefExoticComponent<Omit<LayoutGridColProps, "ref"> & RefAttributes<HTMLDivElement>>;
+
+export declare type LayoutGridColProps = WithRecursicaSpacing<OmitSx<Omit<GridProps, "container" | "order">>> & RecursicaLayoutGridColProps & {
+    /** Sets the CSS `order` property. Applied via inline style. */
+    order?: number;
+    /** Hides the column below the given breakpoint. MUI has no native equivalent. */
+    visibleFrom?: Breakpoint;
+    /** Hides the column above the given breakpoint. MUI has no native equivalent. */
+    hiddenFrom?: Breakpoint;
+};
+
+declare type LayoutGridComponent = typeof LayoutGridBase & {
+    Col: typeof LayoutGridCol;
+};
+
+export declare type LayoutGridProps = WithRecursicaSpacing<OmitSx<Omit<GridProps, "container" | "justifyContent" | "alignItems" | "spacing" | "columnSpacing" | "rowSpacing" | "columns">>> & RecursicaLayoutGridProps & {
+    /** Sets `justify-content` on the container. Applied via inline style. */
+    justifyContent?: CSSProperties["justifyContent"];
+    /** Sets `align-items` on the container. Applied via inline style. */
+    alignItems?: CSSProperties["alignItems"];
+};
+
 export declare const Link: ForwardRefExoticComponent<(Omit<Omit<WithRecursicaSpacing<Omit<LinkProps_2, "underline"> & RecursicaLinkProps>, "className" | "classes" | "style" | "sx" | "color" | "bgcolor" | "backgroundColor" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "lineHeight" | "letterSpacing" | "textAlign" | "border" | "borderTop" | "borderBottom" | "borderLeft" | "borderRight" | "borderColor" | "borderRadius" | "boxShadow" | "display" | "position" | "zIndex" | "p" | "py" | "px" | "pt" | "pb" | "pl" | "pr" | "classNames" | "styles" | "vars" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "bdw" | "bds" | "bdc" | "bdr" | "shadow" | "w" | "miw" | "maw" | "h" | "mih" | "mah"> & Omit<ForbiddenStyles, never> & {
 overStyled?: false | undefined;
 }, "ref"> | Omit<Omit<Omit<LinkProps_2, "underline"> & RecursicaLinkProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap" | "gutter" | "spacing"> & {
@@ -749,6 +767,12 @@ export declare const Loader: default_2.ForwardRefExoticComponent<LoaderProps & d
 
 export declare type LoaderProps = RecursicaOverStyled<default_2.HTMLAttributes<HTMLSpanElement> & RecursicaLoaderProps>;
 
+declare interface ManifestWithLayoutGrids {
+    brand?: {
+        "layout-grids"?: Record<string, unknown>;
+    };
+}
+
 export declare const Menu: ForwardRefExoticComponent<(Omit<Omit<WithRecursicaSpacing<MenuProps_2 & RecursicaMenuProps>, "className" | "classes" | "style" | "sx" | "color" | "bgcolor" | "backgroundColor" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "lineHeight" | "letterSpacing" | "textAlign" | "border" | "borderTop" | "borderBottom" | "borderLeft" | "borderRight" | "borderColor" | "borderRadius" | "boxShadow" | "display" | "position" | "zIndex" | "p" | "py" | "px" | "pt" | "pb" | "pl" | "pr" | "classNames" | "styles" | "vars" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "bdw" | "bds" | "bdc" | "bdr" | "shadow" | "w" | "miw" | "maw" | "h" | "mih" | "mah"> & Omit<ForbiddenStyles, never> & {
 overStyled?: false | undefined;
 }, "ref"> | Omit<Omit<MenuProps_2 & RecursicaMenuProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap" | "gutter" | "spacing"> & {
@@ -902,6 +926,8 @@ declare const ModalTitle: default_2.ForwardRefExoticComponent<(Omit<Omit<WithRec
 
 export declare type ModalTitleProps = RecursicaOverStyled<DialogTitleProps>;
 
+declare type NavControl = "first" | "previous" | "next" | "last";
+
 export declare const NumberInput: default_2.ForwardRefExoticComponent<(Omit<Omit<WithRecursicaSpacing<RecursicaNumberInputProps>, "className" | "classes" | "style" | "sx" | "color" | "bgcolor" | "backgroundColor" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "lineHeight" | "letterSpacing" | "textAlign" | "border" | "borderTop" | "borderBottom" | "borderLeft" | "borderRight" | "borderColor" | "borderRadius" | "boxShadow" | "display" | "position" | "zIndex" | "p" | "py" | "px" | "pt" | "pb" | "pl" | "pr" | "classNames" | "styles" | "vars" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "bdw" | "bds" | "bdc" | "bdr" | "shadow" | "w" | "miw" | "maw" | "h" | "mih" | "mah"> & Omit<ForbiddenStyles, never> & {
     overStyled?: false | undefined;
 }, "ref"> | Omit<Omit<RecursicaNumberInputProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap" | "gutter" | "spacing"> & {
@@ -926,28 +952,20 @@ export declare type NumberInputProps = RecursicaOverStyled<RecursicaNumberInputP
 declare type OmitSx<T> = Omit<T, "sx">;
 
 /**
- * Recursica Pagination component wrapping Mui's Pagination.
+ * Recursica Pagination. Its page and navigation buttons are Recursica `Button`s whose style and
+ * size come from the manifest's `ui-kit.components.pagination` selected variants. Requires the
+ * `manifest` prop on `RecursicaThemeProvider`.
  */
-export declare const Pagination: ForwardRefExoticComponent<(Omit<Omit<WithRecursicaSpacing<PaginationProps_2 & RecursicaPaginationProps>, "className" | "classes" | "style" | "sx" | "color" | "bgcolor" | "backgroundColor" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "lineHeight" | "letterSpacing" | "textAlign" | "border" | "borderTop" | "borderBottom" | "borderLeft" | "borderRight" | "borderColor" | "borderRadius" | "boxShadow" | "display" | "position" | "zIndex" | "p" | "py" | "px" | "pt" | "pb" | "pl" | "pr" | "classNames" | "styles" | "vars" | "bg" | "c" | "opacity" | "ff" | "fz" | "fw" | "lts" | "ta" | "lh" | "fs" | "tt" | "td" | "bd" | "bdw" | "bds" | "bdc" | "bdr" | "shadow" | "w" | "miw" | "maw" | "h" | "mih" | "mah"> & Omit<ForbiddenStyles, never> & {
-overStyled?: false | undefined;
-}, "ref"> | Omit<Omit<PaginationProps_2 & RecursicaPaginationProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap" | "gutter" | "spacing"> & {
-m?: string | number | RecursicaSpacing;
-mx?: string | number | RecursicaSpacing;
-my?: string | number | RecursicaSpacing;
-mt?: string | number | RecursicaSpacing;
-mb?: string | number | RecursicaSpacing;
-ml?: string | number | RecursicaSpacing;
-mr?: string | number | RecursicaSpacing;
-gap?: string | number | RecursicaSpacing;
-rowGap?: string | number | RecursicaSpacing;
-columnGap?: string | number | RecursicaSpacing;
-gutter?: string | number | RecursicaSpacing;
-spacing?: string | number | RecursicaSpacing;
-} & {
-overStyled: true;
-}, "ref">) & RefAttributes<HTMLDivElement>>;
-
-export declare type PaginationProps = RecursicaOverStyled<PaginationProps_2 & RecursicaPaginationProps>;
+export declare const Pagination: ForwardRefExoticComponent<PaginationProps & RefAttributes<HTMLElement>>;
+
+export declare type PaginationProps = RecursicaOverStyled<RecursicaPaginationProps & Pick<UsePaginationProps, "page" | "defaultPage" | "onChange" | "siblingCount" | "boundaryCount" | "disabled"> & {
+    /** Extra props for each page button */
+    getItemProps?: (page: number) => Record<string, unknown>;
+    /** Extra props for each first/previous/next/last button */
+    getControlProps?: (control: NavControl) => Record<string, unknown>;
+    /** Replaces the dots between page ranges */
+    dotsIcon?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<"nav">, "onChange" | "children">>;
 
 export declare const Panel: PanelComponent;
 

package/llms.txt

@@ -40,11 +40,11 @@ Each component has its own `USAGE.md` documenting its props, adapter-specific be
 - [Flex](src/components/Flex/USAGE.md)
 - [FormControlLayout](src/components/FormControlLayout/USAGE.md)
 - [FormControlWrapper](src/components/FormControlWrapper/USAGE.md)
-- [Grid](src/components/Grid/USAGE.md)
 - [Group](src/components/Group/USAGE.md)
 - [HoverCard](src/components/HoverCard/USAGE.md)
 - [Label](src/components/Label/USAGE.md)
 - [Layer](src/components/Layer/USAGE.md)
+- [LayoutGrid](src/components/LayoutGrid/USAGE.md)
 - [Link](src/components/Link/USAGE.md)
 - [Loader](src/components/Loader/USAGE.md)
 - [Menu](src/components/Menu/USAGE.md)

package/package.json

@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica-adapter-mui-v7.git"
   },
-  "version": "1.1.0",
+  "version": "1.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -83,9 +83,9 @@
     "@mui/x-date-pickers": "^9.11.0",
     "@mui/x-tree-view": "^9.11.0",
     "@playwright/test": "^1.62.1",
-    "@recursica/adapter-tester": "^5.2.0",
+    "@recursica/adapter-tester": "^5.3.1",
     "@recursica/recursica-postcss-vars": "^1.5.0",
-    "@recursica/storybook-template": "^0.7.11",
+    "@recursica/storybook-template": "^0.7.15",
     "@recursica/token-analyzer": "^1.8.0",
     "@storybook/addon-a11y": "^10.3.3",
     "@storybook/addon-docs": "^10.3.3",
@@ -122,7 +122,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.31.0",
+    "@recursica/adapter-common": "^1.1.1",
     "@recursica/official-release": "^2.8.0",
     "dayjs": "^1.11.21"
   },

package/recursica_brand.json

@@ -2603,8 +2603,8 @@
   },
   "$extensions": {
     "recursica.metadata": {
-      "exportedAt": "2026-09-23T16:11:12.118Z",
-      "version": "0.28.2"
+      "exportedAt": "2026-10-02T22:19:36.595Z",
+      "version": "0.29.0"
     }
   }
 }

package/recursica_tokens.json

@@ -762,8 +762,8 @@
   },
   "$extensions": {
     "recursica.metadata": {
-      "exportedAt": "2026-09-23T16:11:12.114Z",
-      "version": "0.28.2"
+      "exportedAt": "2026-10-02T22:19:36.595Z",
+      "version": "0.29.0"
     }
   }
 }

package/recursica_ui-kit.json

@@ -9042,8 +9042,8 @@
   },
   "$extensions": {
     "recursica.metadata": {
-      "exportedAt": "2026-09-23T16:11:12.142Z",
-      "version": "0.28.2"
+      "exportedAt": "2026-10-02T22:19:36.595Z",
+      "version": "0.29.0"
     }
   }
 }

package/recursica_variables_scoped.css

@@ -1,8 +1,8 @@
 /*
  * Recursica CSS Variables - Scoped
- * Transform version: 1.3.3
- * Source JSON version: 0.28.2
- * Generated: Wed, 23 Sep 2026 16:11:12 GMT
+ * Transform version: 1.4.0
+ * Source JSON version: 0.29.0
+ * Generated: Fri, 02 Oct 2026 22:19:36 GMT
  *
  * --- How to integrate this file ---
  *
@@ -133,10 +133,14 @@
   --recursica_brand_layer_1_elements_interactive_tone: var(--recursica_tokens_colors_scale-06_400);
   --recursica_brand_layer_2_elements_interactive_tone: var(--recursica_tokens_colors_scale-06_400);
   --recursica_brand_layer_3_elements_interactive_tone: var(--recursica_tokens_colors_scale-06_400);
+  --recursica_brand_layout-grids_column-gutter: var(--recursica_brand_layout-grids_default_column-gutter);
+  --recursica_brand_layout-grids_columns: var(--recursica_brand_layout-grids_default_columns);
   --recursica_brand_layout-grids_default_column-gutter: var(--recursica_tokens_sizes_2x);
   --recursica_brand_layout-grids_default_columns: 6;
   --recursica_brand_layout-grids_default_margin: var(--recursica_tokens_sizes_3x);
   --recursica_brand_layout-grids_default_row-gutter: var(--recursica_tokens_sizes_3x);
+  --recursica_brand_layout-grids_margin: var(--recursica_brand_layout-grids_default_margin);
+  --recursica_brand_layout-grids_row-gutter: var(--recursica_brand_layout-grids_default_row-gutter);
   --recursica_brand_modes_dark_elevations_elevation-0: var(--recursica_brand_modes_dark_elevations_elevation-0_x) var(--recursica_brand_modes_dark_elevations_elevation-0_y) var(--recursica_brand_modes_dark_elevations_elevation-0_blur) var(--recursica_brand_modes_dark_elevations_elevation-0_spread) var(--recursica_brand_modes_dark_elevations_elevation-0_color);
   --recursica_brand_modes_dark_elevations_elevation-0_blur: 0px;
   --recursica_brand_modes_dark_elevations_elevation-0_color: var(--recursica_brand_modes_dark_palettes_neutral_500_color_tone);

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
   );
@@ -278,8 +278,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-mui-v7` package adhere stric
 
 > [!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

@@ -52,6 +52,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

@@ -30,6 +30,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

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

package/src/components/Flex/USAGE.md

@@ -36,6 +36,7 @@ All Recursica components in the `@recursica/adapter-mui-v7` package adhere stric
 
 > [!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 MUI theme's breakpoints, not Forge's.** Keys such as `{ xs, sm, md }` come from `theme.breakpoints`; Forge's layout grids switch via plain CSS `@media` and never edit the MUI theme. Build your theme with `breakpointsFromRecManifest` so the two agree (see [LayoutGrid](../LayoutGrid/USAGE.md)).

package/src/components/Group/USAGE.md

@@ -36,6 +36,7 @@ All Recursica components in the `@recursica/adapter-mui-v7` package adhere stric
 
 > [!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 MUI theme's breakpoints, not Forge's.** Keys such as `{ xs, sm, md }` come from `theme.breakpoints`; Forge's layout grids switch via plain CSS `@media` and never edit the MUI theme. Build your theme with `breakpointsFromRecManifest` so the two agree (see [LayoutGrid](../LayoutGrid/USAGE.md)).

package/src/components/LayoutGrid/LAYOUT_GRID_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,82 @@
+# LayoutGrid Implementation Notes
+
+`LayoutGrid` is the Recursica layout grid. MUI has no native Grid/Grid.Col split: its `Grid`
+merges "container" and "item" behavior into one component (toggled by `container` and a `size`
+prop). `LayoutGrid` always renders `<MuiGrid container>` and `LayoutGrid.Col` renders `<MuiGrid>`
+in item mode, to keep the same dot-notation shape as the Mantine adapter. It was named `Grid`
+before 2026-10-05.
+
+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. Its other props are MUI's own vocabulary, not a shared
+contract:
+
+- **`size`** (not Mantine's `span`): a column count, `"auto"`, `"grow"`, or a responsive object keyed by
+  MUI's breakpoints (`xs`/`sm`/`md`/`lg`/`xl`, no `"base"`). It renames to `span` when
+  `RecursicaLayoutGridColProps` picks `span` up (queued in `adapter-common`).
+- **`offset`**: MUI's own prop, used as is.
+- **`grow` (container)**: not implemented; use `size="grow"` per column.
+- **`order`, `justifyContent`, `alignItems`**: typed by MUI but never read by its Grid generator
+  (`@mui/system` `gridGenerator`), so they're applied via inline `style`.
+- **`visibleFrom` / `hiddenFrom`**: no MUI mechanism, so `LayoutGrid.module.css` has media-query
+  classes hardcoded to MUI's default breakpoints (0/600/900/1200/1536). They do not follow a
+  customized `theme.breakpoints`.
+
+## 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, so
+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`, `spacing`, `columnSpacing` and `rowSpacing` were removed from the public type and are
+deleted at runtime so they can't shadow the token-driven values. For an arbitrary N-column grid,
+use MUI's `Grid` directly.
+
+## How each token is applied
+
+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.
+
+- **Columns**: MUI's Grid computes widths in CSS from `--Grid-parent-columns`, so unlike Mantine no
+  per-column style rule is needed. `LayoutGrid` passes the alias as `columns`
+  (`var(--recursica_brand_layout-grids_columns)`); MUI types it as a number but writes it
+  verbatim into the custom property, which the width `calc()` then reads. Verified in
+  `@mui/system`'s `gridGenerator`.
+- **Column gutter / row gutter**: passed to MUI's own `columnSpacing`/`rowSpacing` as the
+  responsive aliases. MUI applies each independently (strings are not multiplied by `theme.spacing`).
+- **Margin**: no MUI Grid prop equivalent; `.root` in `LayoutGrid.module.css` reads it directly.
+- **Clamping**: MUI's width calc does not clamp, so `size={6}` at 3 columns would overflow.
+  `.col { max-width: 100% }` makes it fill the row instead, matching Mantine's `min(span, columns)`.
+
+## Breakpoints
+
+Responsive `size`/`offset` switch at the MUI theme's breakpoints, which Forge never edits.
+Integrators should merge `breakpointsFromRecManifest(manifest)` into `theme.breakpoints.values`
+so both switch at the same widths (MUI's `values` replaces its defaults, so spread them first;
+see SETUP.md). `RecursicaThemeProvider` is UI-kit agnostic and does not compare the manifest
+against the theme. The helper returns numbers (MUI's unit), not the `"Npx"` strings the Mantine
+one returns.
+
+## `LayoutGrid.Col` contract is scaffolded
+
+`RecursicaLayoutGridColProps` currently only contributes `children`; `span`, `order`,
+`visibleFrom` and `hiddenFrom` are drafted and commented out in `adapter-common`. No runtime
+effect here.
+
+## Brand-layer exemption
+
+`layout-grids` tokens have no `ui-kit` layer in Forge's model, so `LayoutGrid.module.css` reads
+`brand_layout-grids_margin` directly with a `recursica-allow-brand:` header. The other three are
+read in `LayoutGrid.tsx` (a TSX prop value), which the analyzer does not scan.
+
+## 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. Same story id as the
+Mantine adapter's, so it diffs against its golden. Only `size` is used, so the story stays valid
+for every adapter.

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

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { StyledEngineProvider } from "@mui/material/styles";
+import { LayoutGrid } from "./LayoutGrid";
+
+function mount(node: React.ReactElement) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  // injectFirst, as RecursicaThemeProvider does, so the component CSS beats MUI's.
+  flushSync(() =>
+    root.render(
+      <StyledEngineProvider injectFirst>{node}</StyledEngineProvider>,
+    ),
+  );
+  return {
+    container,
+    done: () => {
+      root.unmount();
+      container.remove();
+    },
+  };
+}
+
+describe("LayoutGrid tokens", () => {
+  it("takes columns and gutters from the responsive Forge variables", () => {
+    document.documentElement.style.setProperty(
+      "--recursica_brand_layout-grids_columns",
+      "3",
+    );
+    document.documentElement.style.setProperty(
+      "--recursica_brand_layout-grids_column-gutter",
+      "10px",
+    );
+    document.documentElement.style.setProperty(
+      "--recursica_brand_layout-grids_row-gutter",
+      "20px",
+    );
+    const { container, done } = mount(
+      <LayoutGrid>
+        <LayoutGrid.Col size={1}>a</LayoutGrid.Col>
+      </LayoutGrid>,
+    );
+    const grid = container.querySelector(".MuiGrid-container") as HTMLElement;
+    const style = getComputedStyle(grid);
+    expect(style.getPropertyValue("--Grid-columns").trim()).toBe("3");
+    expect(style.getPropertyValue("--Grid-columnSpacing").trim()).toBe("10px");
+    expect(style.getPropertyValue("--Grid-rowSpacing").trim()).toBe("20px");
+    done();
+  });
+
+  it("drops columns and spacing props passed at runtime", () => {
+    const { container, done } = mount(
+      <LayoutGrid {...({ columns: 12, spacing: 8 } as Record<string, unknown>)}>
+        <LayoutGrid.Col size={1}>a</LayoutGrid.Col>
+      </LayoutGrid>,
+    );
+    const grid = container.querySelector(".MuiGrid-container") as HTMLElement;
+    expect(
+      getComputedStyle(grid).getPropertyValue("--Grid-columns").trim(),
+    ).toBe("3");
+    done();
+  });
+
+  it("clamps a column wider than the grid to the row", () => {
+    const { container, done } = mount(
+      <LayoutGrid>
+        <LayoutGrid.Col size={6}>a</LayoutGrid.Col>
+      </LayoutGrid>,
+    );
+    const col = container.querySelector(
+      ".MuiGrid-container > div",
+    ) as HTMLElement;
+    expect(getComputedStyle(col).maxWidth).toBe("100%");
+    done();
+  });
+});

package/src/components/{Grid/Grid.module.css → LayoutGrid/LayoutGrid.module.css}

@@ -3,25 +3,26 @@
  * - Breakpoint pixel thresholds below (600/900/1200/1536) match MUI's own default
  *   theme.breakpoints (xs/sm/md/lg/xl). They drive `visibleFrom`/`hiddenFrom`, which
  *   have no native MUI Grid equivalent to hook into. If the consuming app customizes
- *   its MUI theme breakpoints, these thresholds will not follow that change —
+ *   its MUI theme breakpoints, these thresholds will not follow that change:
  *   structural layout mechanics, not a design token.
  */
 
-/* Brand-layer exemption (recursica-allow-brand) — layout-grid tokens have no ui-kit-layer
+/* Brand-layer exemption (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. Column-gutter/row-gutter
- * are applied via MUI's own native `columnSpacing`/`rowSpacing` props in Grid.tsx instead (MUI's
- * Grid generator reads them straight off the prop, no CSS declaration needed); `margin` has no
- * MUI Grid prop equivalent at all, so it's applied here, always from the design token — margin is
- * design-system-managed, not an integrator-facing override. See IMPLEMENTATION_NOTES.md.
- *   recursica-allow-brand: --recursica_brand_layout-grids_default_margin
+ * LayoutGrid reads the responsive brand_layout-grids_* alias directly (Forge redefines it per
+ * breakpoint inside @media). Columns, column-gutter and row-gutter are applied in
+ * LayoutGrid.tsx through MUI's own props; `margin` has no MUI Grid prop equivalent, so it's
+ * applied here. See LAYOUT_GRID_IMPLEMENTATION_NOTES.md.
+ *   recursica-allow-brand: --recursica_brand_layout-grids_margin
  */
 
-.root.root {
-  margin: var(--recursica_brand_layout-grids_default_margin);
+.root {
+  margin: var(--recursica_brand_layout-grids_margin);
 }
 
+/* A numeric size larger than the current column count fills the row instead of overflowing. */
 .col {
+  max-width: 100%;
 }
 
 .hiddenFromXs {