@recursica/adapter-mui-v7 1.0.4 → 1.3.0

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/FormControlLayout/FormControlLayout.module.css

@@ -7,8 +7,6 @@
 
   /* Recursica Layout Overrides mapped down dynamically from components */
   padding: 0; /* Hardcoded structural reset */
-  max-width: var(--form-control-max-width);
-  min-width: var(--form-control-min-width);
 }
 
 /* =========================================
@@ -88,5 +86,10 @@
   display: flex; /* Groups internal field alongside subsequent errors/descriptions */
   flex-direction: column;
   flex: 1; /* Consumes the remaining x-axis in grid columns natively */
-  min-width: 0; /* Break boundary preventing internal flex explosion */
+  /* Constrains only the control itself, never the label in .leftSection. */
+  max-width: var(--form-control-max-width, 100%);
+  min-width: var(
+    --form-control-min-width,
+    0
+  ); /* Break boundary preventing internal flex explosion */
 }

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/Heading/Heading.stories.tsx

@@ -20,6 +20,18 @@ const meta: Meta<typeof Heading> = {
       description:
         "Controls the `h` tag and the resultant typographical weighting natively mapped to Recursica.",
     },
+    color: {
+      control: "select",
+      options: ["default", "warning", "alert", "success"],
+      description:
+        "Semantic text color, bound to the active layer's text-element tokens via `data-color`.",
+    },
+    emphasis: {
+      control: "inline-radio",
+      options: ["high", "low"],
+      description:
+        "Emphasis level, bound to the theme's text-emphasis opacity tokens via `data-emphasis`.",
+    },
   },
 };
 
@@ -48,3 +60,53 @@ export const StaticVariations: Story = {
     </div>
   ),
 };
+
+export const Colors: Story = {
+  args: {},
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Semantic colors map to the active layer's text-element tokens. `default` follows the layer's base text color; `warning`, `alert`, and `success` pull their respective semantic tones.",
+      },
+    },
+  },
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+      <Heading order={2} color="default">
+        Default heading
+      </Heading>
+      <Heading order={2} color="warning">
+        Warning heading
+      </Heading>
+      <Heading order={2} color="alert">
+        Alert heading
+      </Heading>
+      <Heading order={2} color="success">
+        Success heading
+      </Heading>
+    </div>
+  ),
+};
+
+export const Emphasis: Story = {
+  args: {},
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Emphasis controls text opacity via the theme's text-emphasis tokens. `high` (the default) is solid; `low` dims the heading for secondary content.",
+      },
+    },
+  },
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+      <Heading order={2} emphasis="high">
+        High emphasis heading
+      </Heading>
+      <Heading order={2} emphasis="low">
+        Low emphasis heading
+      </Heading>
+    </div>
+  ),
+};

package/src/components/Heading/Heading.tsx

@@ -5,11 +5,13 @@ import { type RecursicaOverStyled } from "../../utils/filterStylingProps";
 import { type RecursicaHeadingProps } from "@recursica/adapter-common";
 
 export type HeadingProps = RecursicaOverStyled<
-  Omit<MuiTypographyProps, "variant" | "classes"> & RecursicaHeadingProps
+  Omit<MuiTypographyProps, "variant" | "classes" | "color"> &
+    RecursicaHeadingProps,
+  "color"
 >;
 
 export const Heading = forwardRef<HTMLElement, HeadingProps>(function Heading(
-  { order = 1, component, ...rest },
+  { order = 1, component, emphasis = "high", color = "default", ...rest },
   ref,
 ) {
   const typographyClass = `recursica_brand_typography_h${order}`;
@@ -20,6 +22,8 @@ export const Heading = forwardRef<HTMLElement, HeadingProps>(function Heading(
       ref={ref}
       typographyClass={typographyClass}
       component={component || defaultComponent}
+      data-color={color}
+      data-emphasis={emphasis}
       {...rest}
     />
   );

package/src/components/Heading/USAGE.md

@@ -25,7 +25,25 @@ export default function Demo() {
 
 ---
 
-## 3. Design System Integration
+## 3. Semantic `color` and `emphasis`
+
+`Heading` exposes two Recursica-native, token-bound props (not MUI's freeform `color`):
+
+- **`color`** — semantic text color: `"default"` (the active layer's base text color), `"warning"`, `"alert"`, or `"success"`. Applied as a `data-color` attribute mapped to the layer's text-element tokens.
+- **`emphasis`** — `"high"` (default, solid) or `"low"` (dimmed for secondary content). Applied as a `data-emphasis` attribute mapped to the theme's text-emphasis opacity tokens.
+
+```tsx
+<Heading order={2} color="alert" emphasis="high">
+  Something went wrong.
+</Heading>
+<Heading order={3} color="default" emphasis="low">
+  Secondary section header.
+</Heading>
+```
+
+---
+
+## 4. Design System Integration
 
 All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
 

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,14 +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
+ * representation in Forge's model (a grid is a page-layout primitive, not a "component"), so
+ * 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 {
+  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 {

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} size={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,181 @@
+/**
+ * LayoutGrid: the Recursica layout grid.
+ *
+ * MUI merges "container" and "item" into a single `Grid` component (no separate Grid.Col,
+ * unlike Mantine). To keep the LayoutGrid/LayoutGrid.Col dot-notation shape across adapters,
+ * LayoutGrid always renders MUI's `<Grid container>` and LayoutGrid.Col a plain MUI `<Grid>`.
+ *
+ * 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 through the responsive CSS variables, which MUI's own
+ * `columns`/`columnSpacing`/`rowSpacing` accept as strings. None of them are props. For a fixed
+ * N-column grid use MUI's Grid directly. See `LAYOUT_GRID_IMPLEMENTATION_NOTES.md`.
+ *
+ * MUI has no per-item "grow to fill remaining space" container flag like Mantine's `grow`;
+ * use MUI's own `size="grow"` on individual columns instead. `visibleFrom`/`hiddenFrom`
+ * don't exist in MUI at all, so they're added here via CSS classes keyed on MUI's default
+ * breakpoint scale (`xs`/`sm`/`md`/`lg`/`xl`).
+ *
+ * `justifyContent`/`alignItems` (container) and `order` (item) are typed on `MuiGridProps`
+ * but MUI's Grid style generator never reads them, so they're applied via inline `style`.
+ *
+ * Like Flex, Stack, Group, and Container, this is a primitive layout component and
+ * does not use the `RecursicaOverStyled` gatekeeper; only the `sx` prop is stripped.
+ */
+import { forwardRef, type CSSProperties } from "react";
+import { Grid as MuiGrid, type GridProps as MuiGridProps } from "@mui/material";
+import {
+  type OmitSx,
+  filterSxProp,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import {
+  type RecursicaLayoutGridColProps,
+  type RecursicaLayoutGridProps,
+} from "@recursica/adapter-common";
+import styles from "./LayoutGrid.module.css";
+
+type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl";
+
+const HIDDEN_FROM_CLASS: Record<Breakpoint, string> = {
+  xs: styles.hiddenFromXs,
+  sm: styles.hiddenFromSm,
+  md: styles.hiddenFromMd,
+  lg: styles.hiddenFromLg,
+  xl: styles.hiddenFromXl,
+};
+
+// "xs" intentionally absent: visible from the smallest breakpoint means never hidden.
+const VISIBLE_FROM_CLASS: Partial<Record<Breakpoint, string>> = {
+  sm: styles.visibleFromSm,
+  md: styles.visibleFromMd,
+  lg: styles.visibleFromLg,
+  xl: styles.visibleFromXl,
+};
+
+// ============================================================
+// LAYOUT GRID
+// ============================================================
+
+export type LayoutGridProps = WithRecursicaSpacing<
+  OmitSx<
+    Omit<
+      MuiGridProps,
+      | "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"];
+  };
+
+// MUI types these as numbers, but its generator writes strings straight into CSS custom
+// properties (verified in @mui/system gridGenerator), so the responsive var aliases work.
+const COLUMNS =
+  "var(--recursica_brand_layout-grids_columns)" as unknown as number;
+const COLUMN_GUTTER = "var(--recursica_brand_layout-grids_column-gutter)";
+const ROW_GUTTER = "var(--recursica_brand_layout-grids_row-gutter)";
+
+const LayoutGridBase = forwardRef<HTMLDivElement, LayoutGridProps>(
+  function LayoutGrid(
+    { children, justifyContent, alignItems, style, className, ...rest },
+    ref,
+  ) {
+    // Spacing/columns props are not supported; dropped so a caller still passing one at runtime
+    // can't shadow the token-driven values below.
+    const restWithoutLayout = { ...rest } as Record<string, unknown>;
+    delete restWithoutLayout.spacing;
+    delete restWithoutLayout.columnSpacing;
+    delete restWithoutLayout.rowSpacing;
+    delete restWithoutLayout.columns;
+
+    const safeProps = filterSxProp(restWithoutLayout);
+
+    return (
+      <MuiGrid
+        ref={ref}
+        {...(safeProps as unknown as MuiGridProps)}
+        container
+        columns={COLUMNS}
+        columnSpacing={COLUMN_GUTTER}
+        rowSpacing={ROW_GUTTER}
+        className={className ? `${styles.root} ${className}` : styles.root}
+        style={{ justifyContent, alignItems, ...(style as CSSProperties) }}
+      >
+        {children}
+      </MuiGrid>
+    );
+  },
+);
+LayoutGridBase.displayName = "LayoutGrid";
+
+// ============================================================
+// LAYOUT GRID.COL
+// ============================================================
+
+// TODO(grid-col-contract): `RecursicaLayoutGridColProps` currently only contributes `children`;
+// `span`, `order`, `visibleFrom` and `hiddenFrom` are drafted but commented out in adapter-common.
+// This component's own fields stay MUI-native until that lands, when `size` renames to `span`.
+// See LAYOUT_GRID_IMPLEMENTATION_NOTES.md.
+export type LayoutGridColProps = WithRecursicaSpacing<
+  OmitSx<Omit<MuiGridProps, "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;
+  };
+
+export const LayoutGridCol = forwardRef<HTMLDivElement, LayoutGridColProps>(
+  function LayoutGridCol(
+    { children, order, visibleFrom, hiddenFrom, style, className, ...rest },
+    ref,
+  ) {
+    const safeProps = filterSxProp(rest as Record<string, unknown>);
+
+    const visibilityClass = visibleFrom
+      ? VISIBLE_FROM_CLASS[visibleFrom]
+      : hiddenFrom
+        ? HIDDEN_FROM_CLASS[hiddenFrom]
+        : undefined;
+
+    const finalClassName = [styles.col, visibilityClass, className]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <MuiGrid
+        ref={ref}
+        className={finalClassName}
+        {...(safeProps as unknown as MuiGridProps)}
+        style={{ order, ...(style as CSSProperties) }}
+      >
+        {children}
+      </MuiGrid>
+    );
+  },
+);
+LayoutGridCol.displayName = "LayoutGridCol";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type LayoutGridComponent = typeof LayoutGridBase & {
+  Col: typeof LayoutGridCol;
+};
+
+export const LayoutGrid = LayoutGridBase as LayoutGridComponent;
+LayoutGrid.Col = LayoutGridCol;