@recursica/adapter-mui-v7 1.0.0

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

@@ -0,0 +1,161 @@
+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 12-column (by default) responsive grid layout hand-composed from MUI's own Grid, providing column sizing, offsets, ordering, and breakpoint-based visibility using MUI's native prop names.",
+      },
+    },
+    controls: {
+      include: ["children", "spacing", "columns", "direction", "wrap"],
+    },
+  },
+  args: {
+    spacing: "rec-default",
+    columns: 12,
+  },
+  argTypes: {
+    spacing: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+      ],
+      description: "Space between columns",
+    },
+    columns: {
+      control: "number",
+      description: "Number of columns in each row",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<GridStoryProps>;
+
+const Swatch = ({ children }: { children: React.ReactNode }) => (
+  <Card>
+    <Card.Content>
+      <Text>{children}</Text>
+    </Card.Content>
+  </Card>
+);
+
+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 size={4}>
+        <Swatch>size 4</Swatch>
+      </Grid.Col>
+      <Grid.Col size={4}>
+        <Swatch>size 4</Swatch>
+      </Grid.Col>
+      <Grid.Col size={4}>
+        <Swatch>size 4</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+export const ResponsiveSizes: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Grid {...args}>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col size={{ 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 size={4} offset={4}>
+        <Swatch>size 4, offset 4</Swatch>
+      </Grid.Col>
+      <Grid.Col size={4}>
+        <Swatch>size 4</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+export const Grow: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Grid {...args}>
+      <Grid.Col size={3}>
+        <Swatch>size 3</Swatch>
+      </Grid.Col>
+      <Grid.Col size={3}>
+        <Swatch>size 3</Swatch>
+      </Grid.Col>
+      <Grid.Col size="grow">
+        <Swatch>size &quot;grow&quot; (fills remaining space)</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
+export const CustomColumnCount: Story = {
+  args: {
+    columns: 6,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Grid {...args}>
+      <Grid.Col size={2}>
+        <Swatch>size 2 of 6</Swatch>
+      </Grid.Col>
+      <Grid.Col size={2}>
+        <Swatch>size 2 of 6</Swatch>
+      </Grid.Col>
+      <Grid.Col size={2}>
+        <Swatch>size 2 of 6</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 size={6} hiddenFrom="sm">
+        <Swatch>hidden from sm and up</Swatch>
+      </Grid.Col>
+      <Grid.Col size={6} visibleFrom="sm">
+        <Swatch>visible from sm and up</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};

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

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

package/src/components/Grid/Grid.tsx

@@ -0,0 +1,155 @@
+/**
+ * Grid layout wrapper.
+ *
+ * MUI merges "container" and "item" into a single `Grid` component (no separate Grid.Col,
+ * unlike Mantine). To preserve the Grid/Grid.Col dot-notation shape across adapters, this
+ * file splits MUI's single component back into two thin wrappers: Grid always renders MUI's
+ * `<Grid container>`, GridCol always renders a plain MUI `<Grid>` (item mode).
+ *
+ * Per the layout-components rule, both wrappers simply pass through MUI's own Grid props
+ * (`size`, `offset`, `spacing`, `columns`, `direction`, `wrap`) with no Recursica renaming.
+ * 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 — per the rule that a missing kit feature is built following
+ * Mantine's own shape — they're added here via CSS classes, keyed on MUI's own breakpoint
+ * scale (`xs`/`sm`/`md`/`lg`/`xl`).
+ *
+ * `justifyContent`/`alignItems` (container) and `order` (item) are typed on `MuiGridProps`
+ * (inherited generically from `SystemProps`) but MUI's Grid style generator — verified by
+ * reading `@mui/system`'s `gridGenerator.js`/`createGrid.js` — only wires up `size`, `offset`,
+ * `columns`, `spacing`/`rowSpacing`/`columnSpacing`, `direction`, and `wrap`; passing these
+ * three straight through would silently no-op. They're pulled out and applied via inline
+ * `style` instead, still using MUI's own native names.
+ *
+ * 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 {
+  SPACING_MAP,
+  type OmitSx,
+  filterSxProp,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Grid.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,
+};
+
+// ============================================================
+// GRID
+// ============================================================
+
+export type GridProps = WithRecursicaSpacing<
+  OmitSx<Omit<MuiGridProps, "container" | "justifyContent" | "alignItems">>
+> & {
+  /** 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"];
+};
+
+const GridBase = forwardRef<HTMLDivElement, GridProps>(function Grid(
+  {
+    children,
+    spacing = "rec-default",
+    justifyContent,
+    alignItems,
+    style,
+    ...rest
+  },
+  ref,
+) {
+  const safeProps = filterSxProp(rest as Record<string, unknown>);
+  const resolvedSpacing =
+    typeof spacing === "string" && spacing in SPACING_MAP
+      ? SPACING_MAP[spacing as keyof typeof SPACING_MAP]
+      : spacing;
+
+  return (
+    <MuiGrid
+      ref={ref}
+      {...(safeProps as unknown as MuiGridProps)}
+      container
+      spacing={resolvedSpacing}
+      className={styles.root}
+      style={{ justifyContent, alignItems, ...(style as CSSProperties) }}
+    >
+      {children}
+    </MuiGrid>
+  );
+});
+GridBase.displayName = "Grid";
+
+// ============================================================
+// GRID.COL
+// ============================================================
+
+export type GridColProps = WithRecursicaSpacing<
+  OmitSx<Omit<MuiGridProps, "container" | "order">>
+> & {
+  /** 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;
+};
+
+export const GridCol = forwardRef<HTMLDivElement, GridColProps>(
+  function GridCol(
+    { 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>
+    );
+  },
+);
+GridCol.displayName = "GridCol";
+
+// ============================================================
+// DOT NOTATION EXPORT
+// ============================================================
+
+type GridComponent = typeof GridBase & {
+  Col: typeof GridCol;
+};
+
+export const Grid = GridBase as GridComponent;
+Grid.Col = GridCol;

package/src/components/Grid/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,24 @@
+# Grid Implementation Notes
+
+MUI has no native Grid/Grid.Col split — MUI's own `Grid` component merges "container" and "item" behavior into one component (toggled by the `container` boolean and a `size` prop). To keep the same `Grid` + `Grid.Col` dot-notation shape as the mantine-adapter, this file hand-composes two thin wrappers around that single underlying component: `Grid` always renders `<MuiGrid container>`, `Grid.Col` always renders `<MuiGrid>` in item mode. This is a structural convenience only — the props on each wrapper are MUI's own, not a Recursica-defined contract.
+
+Per the layout-components rule (no formal Recursica common props definition — layout components simply pass through the underlying kit's own props), this Grid does **not** attempt prop-name parity with the mantine-adapter's Grid. Its public API is MUI's own vocabulary:
+
+- **`spacing`** (not Mantine's `gutter`/the old Recursica `gap` alias) — MUI's own container-spacing prop. Still accepts `rec-*` tokens, resolved through the same `SPACING_MAP` lookup used elsewhere in this adapter.
+- **`size`** (not Mantine's `span`) — MUI's own item-sizing prop on `Grid.Col`: a column count, `"auto"` (size to content), `"grow"` (fill remaining space), or a responsive object keyed by MUI's own breakpoints. No inversion/translation against Mantine's `span` semantics.
+- **`offset`** — MUI's own prop, used as-is.
+- **Breakpoint objects** use MUI's own scale (`xs`/`sm`/`md`/`lg`/`xl`) directly. There is no `"base"` alias — `xs` is MUI's smallest breakpoint, same role Mantine's own smallest breakpoint plays.
+- **`grow` (container-level)**: not implemented. Mantine's container `grow` flag ("last row's columns expand to fill available space") has no MUI equivalent, but MUI's own `size="grow"` on individual `Grid.Col`s already covers the same real-world need — set it per-column instead of on the container.
+- **`order`**: MUI types `order` generically (via `SystemProps`) but its Grid style generator (`gridGenerator.js`/`createGrid.js`, read directly to confirm) never wires it up — passing it straight through silently no-ops. Applied here via inline `style.order` instead, single value only (no per-breakpoint object).
+- **`justifyContent` / `alignItems`** (container only): same issue as `order` — typed but not read by MUI's Grid generator (confirmed by reading `gridGenerator.js`: only `size`, `offset`, `columns`, spacing, `direction`, and `wrap` have generator functions). Applied via inline `style` instead, using MUI's own prop names (not Mantine's `justify`/`align`).
+- **`visibleFrom` / `hiddenFrom`**: no native MUI Grid mechanism at all, so — per the rule that a missing kit feature is built following Mantine's own shape — implemented via `Grid.module.css` media-query classes, hardcoded to MUI's own default `theme.breakpoints` pixel values (`xs:0, sm:600, md:900, lg:1200, xl:1536`). If the consuming app customizes its MUI theme breakpoints, these thresholds won't follow — structural layout mechanics, not a design token.
+
+**Cross-adapter parity caveat**: `visibleFrom`/`hiddenFrom` are pinned to MUI's default breakpoints here, while the mantine-adapter's equivalent behavior is driven by Mantine's own default breakpoints (576/768/992/1200/1408). The two adapters' Grid stories may show different columns at the exact same viewport width in the `adapter-tester` visual-regression suite as a result — a real, structural difference between the two underlying libraries' breakpoint scales, not a bug in either adapter. The two adapters' Grid APIs are also no longer prop-name-identical (`spacing`/`size` here vs. `gutter`/`span` in mantine-adapter) — this is intentional per the layout-components rule; each adapter's Grid speaks its own kit's vocabulary.
+
+**Story parity exclude**: for the same `size`/`span` reason above, this story is named `ResponsiveSizes` here vs. mantine-adapter's `ResponsiveSpans` — different story ids. `ui-kit-grid--responsive-spans` is marked `exclude: true` in `adapter-tester.config.json`'s `story parity with source of truth` check rather than renamed to match, per developer direction (2026-08-30).
+
+**Update (2026-08-30):** mantine-adapter now also has its own `ResponsiveSizes` story (using its
+own `span` prop, same breakpoints/content as this one) purely so this adapter's `responsive-sizes`
+story id has a source-of-truth golden to diff against — see mantine-adapter's own
+`GRID_IMPLEMENTATION_NOTES.md`. The `responsive-spans`/`responsive-sizes` naming split itself is
+unchanged/still intentional; this just closes the one-directional story-parity gap.

package/src/components/Grid/USAGE.md

@@ -0,0 +1,53 @@
+# Grid - Usage Guide
+
+This document describes how to integrate and use the `Grid` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Grid } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Grid } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Grid spacing="rec-default">
+      <Grid.Col size={6}>Half width</Grid.Col>
+      <Grid.Col size={{ xs: 12, sm: 6, md: 3 }}>Responsive width</Grid.Col>
+    </Grid>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` 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)) — only the `sx` prop is stripped, everything else passes 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**: Spacing is entirely determined by the `rec-*` token scale, mapped transparently to MUI's `spacing` value.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+This Grid uses MUI's own prop vocabulary directly (see [IMPLEMENTATION_NOTES.md](./IMPLEMENTATION_NOTES.md)) — it is not name-for-name identical to the mantine-adapter's Grid.
+
+- `spacing` controls the space between grid items (accepts `rec-*` tokens).
+- `size` accepts a column count, `"auto"`, `"grow"`, or a responsive object (`{ xs, sm, md, ... }`).
+- `offset` shifts a column by a number of columns.
+- `order` accepts a fixed number to control a column's visual order (single value only, no responsive object).
+- `visibleFrom`/`hiddenFrom` show or hide a column at the standard breakpoints (600/900/1200/1536px).

package/src/components/Grid/index.ts

@@ -0,0 +1 @@
+export * from "./Grid";

package/src/components/Group/Group.stories.tsx

@@ -0,0 +1,120 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Group } from "./Group";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type GroupStoryProps = React.ComponentProps<typeof Group>;
+
+const meta: Meta<GroupStoryProps> = {
+  title: "UI-Kit/Group",
+  component: Group,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Group is a flex horizontal layout container that maps directly to Mantine's Group component allowing safe layout property passing.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "center",
+    justify: "flex-start",
+    wrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    wrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<GroupStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Primary</Button>
+      <Button variant="outline">Secondary</Button>
+      <Text>Text element within Group</Text>
+    </Group>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    gap: "rec-sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    gap: "rec-xl",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};

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

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

package/src/components/Group/Group.tsx

@@ -0,0 +1,116 @@
+/**
+ * Group layout wrapper.
+ *
+ * NOTE: MUI has no native `<Group>` component. Per the layout-components rule, when a UI kit
+ * lacks an equivalent component it's built following a prop definition similar to Mantine's
+ * own `Group` (gap/rowGap/columnGap/justify/align/wrap) — this shape is owned locally here,
+ * not shared as a formal cross-adapter Recursica contract. It's implemented as a row-direction,
+ * wrapping MUI `Stack`.
+ */
+import { forwardRef } from "react";
+import {
+  Stack as MUIStack,
+  type StackProps as MUIStackProps,
+} from "@mui/material";
+import {
+  SPACING_MAP,
+  type OmitSx,
+  filterSxProp,
+  type WithRecursicaSpacing,
+} from "../../utils/filterStylingProps";
+
+interface GroupOwnProps {
+  /** Gap spacing */
+  gap?: string | number;
+  /** Row gap spacing */
+  rowGap?: string | number;
+  /** Column gap spacing */
+  columnGap?: string | number;
+  /** Align items justify properties */
+  justify?: React.CSSProperties["justifyContent"];
+  /** Align items vertical alignment */
+  align?: React.CSSProperties["alignItems"];
+  /** Flex-wrap settings */
+  wrap?: React.CSSProperties["flexWrap"];
+}
+
+export type GroupProps = WithRecursicaSpacing<
+  OmitSx<Omit<MUIStackProps, "spacing" | "direction"> & GroupOwnProps>
+>;
+
+export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
+  {
+    children,
+    gap = "rec-default",
+    rowGap,
+    columnGap,
+    justify,
+    align,
+    wrap,
+    ...rest
+  },
+  ref,
+) {
+  const safeProps = filterSxProp(rest as Record<string, unknown>);
+  // MUI's `sx`/system props treat spacing shorthands (`gap`, margin/padding
+  // shorthands like `mt`, `p`, ...) as multiples of the theme's 8px unit
+  // (e.g. `gap={8}` -> 64px, `mt={24}` -> 192px). Mantine's `Group` takes a
+  // raw number as literal pixels, so numeric values must be stringified to
+  // `px` here to opt out of that multiplication and keep parity.
+  const resolveGap = (value: string | number | undefined) => {
+    if (typeof value === "string" && value in SPACING_MAP) {
+      return SPACING_MAP[value as keyof typeof SPACING_MAP];
+    }
+    return typeof value === "number" ? `${value}px` : value;
+  };
+  const resolvedGap = resolveGap(gap);
+  const resolvedRowGap = resolveGap(rowGap);
+  const resolvedColumnGap = resolveGap(columnGap);
+
+  const MARGIN_PADDING_KEYS = [
+    "m",
+    "mt",
+    "mr",
+    "mb",
+    "ml",
+    "mx",
+    "my",
+    "p",
+    "pt",
+    "pr",
+    "pb",
+    "pl",
+    "px",
+    "py",
+  ] as const;
+  for (const key of MARGIN_PADDING_KEYS) {
+    const value = safeProps[key];
+    if (typeof value === "number") {
+      safeProps[key] = `${value}px`;
+    }
+  }
+
+  return (
+    <MUIStack
+      ref={ref}
+      {...safeProps}
+      direction="row"
+      flexWrap={wrap || "wrap"}
+      justifyContent={justify}
+      alignItems={align}
+      sx={{
+        // Set gap directly instead of MUI Stack's `spacing` prop: `spacing`
+        // multiplies numeric values by the theme's 8px spacing unit (e.g.
+        // `gap={8}` -> 64px), while Mantine's `Group` treats a raw number as
+        // literal pixels. Using `sx.gap` keeps numeric/px/token values 1:1.
+        gap: resolvedGap,
+        ...(resolvedRowGap ? { rowGap: resolvedRowGap } : {}),
+        ...(resolvedColumnGap ? { columnGap: resolvedColumnGap } : {}),
+      }}
+    >
+      {children}
+    </MUIStack>
+  );
+});
+
+Group.displayName = "Group";

package/src/components/Group/USAGE.md

@@ -0,0 +1,41 @@
+# Group - Usage Guide
+
+This document describes how to integrate and use the `Group` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Group } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Group } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Group gap="md" align="center">
+      <Button variant="secondary">Cancel</Button>
+      <Button variant="primary">Submit</Button>
+    </Group>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!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/Group/index.ts

@@ -0,0 +1 @@
+export * from "./Group";