@recursica/mui-adapter 0.16.0 → 0.18.0

package/dist/src/components/Grid/Grid.d.ts

@@ -0,0 +1,12 @@
+import { GridProps as MuiGridProps } from '@mui/material';
+import { OmitSx, WithRecursicaSpacing } from '../../utils/filterStylingProps';
+import { RecursicaGridProps, RecursicaGridColProps } from '@recursica/adapter-common';
+export type GridProps = WithRecursicaSpacing<OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> & RecursicaGridProps>;
+declare const GridBase: import('react').ForwardRefExoticComponent<Omit<GridProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export type GridColProps = WithRecursicaSpacing<OmitSx<Omit<MuiGridProps, "container" | "size" | "offset">> & RecursicaGridColProps>;
+export declare const GridCol: import('react').ForwardRefExoticComponent<Omit<GridColProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+type GridComponent = typeof GridBase & {
+    Col: typeof GridCol;
+};
+export declare const Grid: GridComponent;
+export {};

package/dist/src/components/Grid/index.d.ts

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

package/dist/src/components/Table/Table.d.ts

@@ -1,4 +1,4 @@
-import { TableProps as MuiTableProps, TableBody as MuiTableBody, TableCell as MuiTableCell, TableContainer as MuiTableContainer, TableHead as MuiTableHead, TableRow as MuiTableRow, TableFooter as MuiTableFooter, TableSortLabel as MuiTableSortLabel } from '@mui/material';
+import { TableProps as MuiTableProps, TableBodyProps as MuiTableBodyProps, TableCellProps as MuiTableCellProps, TableContainerProps as MuiTableContainerProps, TableHeadProps as MuiTableHeadProps, TableRowProps as MuiTableRowProps, TableFooterProps as MuiTableFooterProps, TableSortLabelProps as MuiTableSortLabelProps } from '@mui/material';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { RecursicaTableProps } from '@recursica/adapter-common';
 export type TableProps = RecursicaOverStyled<MuiTableProps & RecursicaTableProps>;
@@ -22,14 +22,133 @@ declare const TableBase: import('react').ForwardRefExoticComponent<(Omit<Omit<im
 } & {
     overStyled: true;
 }, "ref">) & import('react').RefAttributes<HTMLTableElement>>;
+export type TableBodyPropsRecursica = RecursicaOverStyled<MuiTableBodyProps>;
+export declare const TableBodyComponent: import('react').ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<MuiTableBodyProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTableBodyProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & import('react').RefAttributes<HTMLTableSectionElement>>;
+export type TableCellPropsRecursica = RecursicaOverStyled<MuiTableCellProps>;
+export declare const TableCellComponent: import('react').ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<MuiTableCellProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTableCellProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & import('react').RefAttributes<HTMLTableCellElement>>;
+export type TableContainerPropsRecursica = RecursicaOverStyled<MuiTableContainerProps>;
+export declare const TableContainerComponent: import('react').ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<MuiTableContainerProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTableContainerProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & import('react').RefAttributes<HTMLDivElement>>;
+export type TableHeadPropsRecursica = RecursicaOverStyled<MuiTableHeadProps>;
+export declare const TableHeadComponent: import('react').ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<MuiTableHeadProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTableHeadProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & import('react').RefAttributes<HTMLTableSectionElement>>;
+export type TableRowPropsRecursica = RecursicaOverStyled<MuiTableRowProps>;
+export declare const TableRowComponent: import('react').ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<MuiTableRowProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTableRowProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & import('react').RefAttributes<HTMLTableRowElement>>;
+export type TableFooterPropsRecursica = RecursicaOverStyled<MuiTableFooterProps>;
+export declare const TableFooterComponent: import('react').ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<MuiTableFooterProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTableFooterProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & import('react').RefAttributes<HTMLTableSectionElement>>;
+export type TableSortLabelPropsRecursica = RecursicaOverStyled<MuiTableSortLabelProps>;
+export declare const TableSortLabelComponent: import('react').ForwardRefExoticComponent<(Omit<Omit<import('@recursica/adapter-common').WithRecursicaSpacing<MuiTableSortLabelProps>, import('@recursica/adapter-common').BlockedStylingKeys> & import('@recursica/adapter-common').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTableSortLabelProps, "m" | "my" | "mx" | "mt" | "mb" | "ml" | "mr" | "gap" | "rowGap" | "columnGap"> & {
+    m?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mx?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    my?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mt?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mb?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    ml?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    mr?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    gap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    rowGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+    columnGap?: string | number | import('@recursica/adapter-common').RecursicaSpacing;
+} & {
+    overStyled: true;
+}, "ref">) & import('react').RefAttributes<HTMLSpanElement>>;
 type TableComponent = typeof TableBase & {
-    Body: typeof MuiTableBody;
-    Cell: typeof MuiTableCell;
-    Container: typeof MuiTableContainer;
-    Head: typeof MuiTableHead;
-    Row: typeof MuiTableRow;
-    Footer: typeof MuiTableFooter;
-    SortLabel: typeof MuiTableSortLabel;
+    Body: typeof TableBodyComponent;
+    Cell: typeof TableCellComponent;
+    Container: typeof TableContainerComponent;
+    Head: typeof TableHeadComponent;
+    Row: typeof TableRowComponent;
+    Footer: typeof TableFooterComponent;
+    SortLabel: typeof TableSortLabelComponent;
 };
 export declare const Table: TableComponent;
 export {};

package/dist/src/components/index.d.ts

@@ -17,6 +17,7 @@ export * from './FileUpload';
 export * from './Flex';
 export * from './FormControlLayout';
 export * from './FormControlWrapper';
+export * from './Grid';
 export * from './Group';
 export * from './HoverCard';
 export * from './Label';

package/dist/src/index.d.ts

@@ -4,6 +4,10 @@ export declare const Box: <C extends React.ElementType = "div">(props: rawCompon
     ref?: React.ForwardedRef<any>;
 }) => React.ReactElement | null;
 export declare const Flex: import('react').ForwardRefExoticComponent<Omit<rawComponents.FlexProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const Grid: import('react').ForwardRefExoticComponent<Omit<rawComponents.GridProps, "ref"> & import('react').RefAttributes<HTMLDivElement>> & {
+    Col: typeof rawComponents.GridCol;
+};
+export declare const GridCol: import('react').ForwardRefExoticComponent<Omit<rawComponents.GridColProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
 export declare const Group: import('react').ForwardRefExoticComponent<Omit<rawComponents.GroupProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
 export declare const Stack: import('react').ForwardRefExoticComponent<Omit<rawComponents.StackProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
 export declare const Container: import('react').ForwardRefExoticComponent<Omit<rawComponents.ContainerProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/llms.txt

@@ -9,8 +9,65 @@ This adapter converts Recursica design tokens into MUI-specific themes and compo
 - Relies on `@mui/material`, `@emotion/react`, and `@emotion/styled` peer dependencies.
 - When building UI in consumer applications, prioritize using components exported by this package to adhere to the Recursica design system.
 
-## Documentation
+## Reference Documentation
 
-- [USAGE](USAGE.md): Detailed usage instructions.
+- [USAGE](USAGE.md): Detailed usage instructions, import rules, and layout/token conventions.
+- [OVERSTYLING](OVERSTYLING.md): The `overStyled` escape hatch — when it's appropriate, what's permitted by default, and how to visually audit its usage.
+- [SETUP](SETUP.md): Installation and integration steps.
 - [ARCHITECTURE](ARCHITECTURE.md): Package architecture and dependencies.
 - [README](README.md)
+
+## Components
+
+Each component has its own `USAGE.md` documenting its props, adapter-specific behaviors, layout constraints, and accessibility requirements.
+
+- [Accordion](src/components/Accordion/USAGE.md)
+- [AssistiveElement](src/components/AssistiveElement/USAGE.md)
+- [Autocomplete](src/components/Autocomplete/USAGE.md)
+- [Avatar](src/components/Avatar/USAGE.md)
+- [Badge](src/components/Badge/USAGE.md)
+- [Box](src/components/Box/USAGE.md)
+- [Breadcrumb](src/components/Breadcrumb/USAGE.md)
+- [Button](src/components/Button/USAGE.md)
+- [Card](src/components/Card/USAGE.md)
+- [Checkbox](src/components/Checkbox/USAGE.md)
+- [Chip](src/components/Chip/USAGE.md)
+- [Container](src/components/Container/USAGE.md)
+- [DatePicker](src/components/DatePicker/USAGE.md)
+- [Dropdown](src/components/Dropdown/USAGE.md)
+- [FileInput](src/components/FileInput/USAGE.md)
+- [FileUpload](src/components/FileUpload/USAGE.md)
+- [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)
+- [Link](src/components/Link/USAGE.md)
+- [Loader](src/components/Loader/USAGE.md)
+- [Menu](src/components/Menu/USAGE.md)
+- [Modal](src/components/Modal/USAGE.md)
+- [NumberInput](src/components/NumberInput/USAGE.md)
+- [Pagination](src/components/Pagination/USAGE.md)
+- [Panel](src/components/Panel/USAGE.md)
+- [Radio](src/components/Radio/USAGE.md)
+- [ReadOnlyField](src/components/ReadOnlyField/USAGE.md)
+- [SegmentedControl](src/components/SegmentedControl/USAGE.md)
+- [Slider](src/components/Slider/USAGE.md)
+- [Stack](src/components/Stack/USAGE.md)
+- [Stepper](src/components/Stepper/USAGE.md)
+- [Switch](src/components/Switch/USAGE.md)
+- [Table](src/components/Table/USAGE.md)
+- [Tabs](src/components/Tabs/USAGE.md)
+- [Text](src/components/Text/USAGE.md)
+- [TextArea](src/components/TextArea/USAGE.md)
+- [TextField](src/components/TextField/USAGE.md)
+- [TimePicker](src/components/TimePicker/USAGE.md)
+- [Timeline](src/components/Timeline/USAGE.md)
+- [Title](src/components/Title/USAGE.md)
+- [Toast](src/components/Toast/USAGE.md)
+- [Tooltip](src/components/Tooltip/USAGE.md)
+- [TransferList](src/components/TransferList/USAGE.md)
+- [Tree](src/components/Tree/USAGE.md)
+- [Typography](src/components/Typography/USAGE.md)

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.16.0",
+  "version": "0.18.0",
   "publishConfig": {
     "access": "public"
   },
@@ -37,7 +37,8 @@
     "llms.txt",
     "USAGE.md",
     "ARCHITECTURE.md",
-    "SETUP.md"
+    "SETUP.md",
+    "OVERSTYLING.md"
   ],
   "keywords": [
     "react",

package/src/OverStyling.tsx

@@ -1,3 +1,4 @@
+import ReactMarkdown from "react-markdown";
 import { Paper, Divider } from "@mui/material";
 import {
   Container,
@@ -13,6 +14,7 @@ import {
   toggleGlobalOverStyled,
   wrapComponent,
 } from "@recursica/adapter-common";
+import overStylingDoc from "../OVERSTYLING.md?raw";
 
 const Button = wrapComponent(RawButton);
 const Text = wrapComponent(RawText);
@@ -23,198 +25,16 @@ export const OverStylingInfo = () => {
   return (
     <Container size="md" style={{ padding: "32px 0" }}>
       <Paper variant="outlined" sx={{ p: 4, borderRadius: 2 }}>
-        <Title order={4} mb={2}>
-          Over Styling (<code>overStyled</code>)
-        </Title>
-        <Text mb={2}>
-          By default, all Recursica components are strictly sandboxed. This
-          means they are protected against arbitrary styling configurations
-          (like passing generic React <code>style</code> objects, custom{" "}
-          <code>className</code> injections, or using deep MUI layout props like{" "}
-          <code>sx</code>). This strict compile-time and run-time enforcement
-          guarantees that your design system tokens remain true across your
-          application.
-        </Text>
-        <Text mb={2}>
-          However, there may be edge cases where a developer absolutely must
-          modify a component beyond what the design tokens natively allow. For
-          this, we provide the <strong>escape hatch</strong> property:{" "}
-          <code>overStyled={`{true}`}</code>.
-        </Text>
-
-        <Title order={6} mb={1} mt={4}>
-          The Core Philosophy
-        </Title>
-        <Text mb={1}>
-          **You should not over-style components.** Using{" "}
-          <code>overStyled</code> explicitly signifies that you are breaking
-          design system rules.
-        </Text>
-        <Box component="ol" sx={{ pl: 4, mb: 4 }}>
-          <li>
-            <Text>
-              <strong>Technical Debt:</strong> If over-styling is required, it
-              should be treated as a short-term workaround. Ideally, the
-              component will be refactored once the required layouts or variants
-              are officially integrated into the core Recursica component
-              library.
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <strong>Auditing & Searching:</strong> Because this pattern
-              creates technical debt, we enforce the explicit{" "}
-              <code>overStyled</code> boolean. This provides a highly auditable,
-              easily searchable string. Product managers and engineers can
-              quickly grep the codebase for <code>overStyled</code> (or the{" "}
-              <code>RecursicaOverStyled</code> typings) to hunt down components
-              that don't match standard patterns.
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <strong>Highly Custom Components:</strong> If your application
-              genuinely requires massive custom layouts that the UI kit cannot
-              support, <strong>do not hack the Recursica component</strong>.
-              Instead, it is highly encouraged that you import the underlying
-              primitive component directly from <code>@mui/material</code> and
-              construct your independent feature there. While you can utilize
-              raw Recursica CSS variables on these custom components, note that
-              they are not guaranteed to be accurately maintained as Recursica
-              evolves. Keep strict components strict!
-            </Text>
-          </li>
-        </Box>
-
-        <Divider sx={{ mb: 4 }} />
-
-        <Title order={6} mb={1}>
-          Permitted Layout Properties
-        </Title>
-        <Text mb={1}>
-          Unlike deep styling bounds (colors, typography, padding, dimensions),
-          external <strong>layout spacing properties</strong> like Margins (
-          <code>m</code>, <code>mt</code>, <code>mb</code>, <code>mx</code>) are
-          safely <strong>permitted by default</strong>. This allows integrators
-          to structurally compose components alongside siblings without
-          breaching internal token boundaries.
-        </Text>
-        <Text mb={3}>
-          When using layout properties, you have the flexibility to use either
-          ecosystem seamlessly:
-        </Text>
-        <Box component="ol" sx={{ pl: 4, mb: 2 }}>
-          <li>
-            <Text>
-              <strong>MUI Core Values:</strong> Passing standard MUI sizes (like{" "}
-              <code>mt={"{2}"}</code>) passes straight through to MUI natively,
-              allowing you to interface completely normally with a parent
-              application's existing MUI Theme setup that might fall outside
-              Recursica's scope.
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <strong>Recursica Strict Tokens:</strong> Passing our custom
-              prefixed tokens (like <code>mt="rec-md"</code>) signals our
-              internal layout interceptor to securely translate the value
-              directly to our native <code>--recursica_brand_dimensions_*</code>{" "}
-              CSS variables. This ensures strict design token measurements while
-              sharing the exact same prop interface!
-            </Text>
-          </li>
-        </Box>
-        <Text mb={1} overStyled sx={{ fontWeight: 500 }}>
-          Available Recursica Layout Tokens:
-        </Text>
-        <Box component="ul" sx={{ pl: 4, mb: 4 }}>
-          <li>
-            <Text>
-              <code>rec-none</code> (0px limit)
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <code>rec-sm</code> (0.5x scaling)
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <code>rec-default</code> (1.0x scaling)
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <code>rec-md</code> (1.5x scaling)
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <code>rec-lg</code> (2.0x scaling)
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <code>rec-xl</code> (3.0x scaling)
-            </Text>
-          </li>
-          <li>
-            <Text>
-              <code>rec-2xl</code> (4.0x scaling)
-            </Text>
-          </li>
+        <Box className="markdown-body">
+          <ReactMarkdown>{overStylingDoc}</ReactMarkdown>
         </Box>
 
-        <Divider sx={{ mb: 4 }} />
+        <Divider sx={{ my: 4 }} />
 
-        <Title order={6} mb={1}>
-          Primitive Layout Components Exemption
+        <Title order={6} mb={2}>
+          Try It Yourself
         </Title>
-        <Text mb={1}>
-          Unlike complex UI components (Buttons, Tabs, Inputs) which are
-          strictly protected, <strong>Primitive Layout Components</strong> (
-          <code>Flex</code>,<code>Stack</code>, <code>Group</code>,{" "}
-          <code>Container</code>) are entirely exempt from the{" "}
-          <code>RecursicaOverStyled</code> gatekeeper.
-        </Text>
-        <Text mb={4}>
-          Because the entire functional purpose of these components is
-          structural layout composition, developers are free to pass any
-          standard MUI width, height, padding, margin, gap, and alignment
-          property directly to them without needing to flag{" "}
-          <code>overStyled={`{true}`}</code>. The internal custom token mapper
-          (such as converting <code>gap="rec-md"</code>) is still active
-          natively on these wrappers.
-        </Text>
 
-        <Divider sx={{ mb: 4 }} />
-
-        <Title order={6} mb={1}>
-          Visual Auditing & Highlights (Development Only)
-        </Title>
-        <Text mb={2}>
-          To make it easy to spot technical debt and design system violations,
-          Recursica automatically tracks any component that uses the{" "}
-          <code>overStyled={`{true}`}</code> prop.
-        </Text>
-        <Text mb={2}>
-          In <strong>development builds</strong>, you can highlight all
-          over-styled components on the page. Open your browser's developer
-          console and run:
-        </Text>
-        <Box
-          component="pre"
-          sx={{
-            p: 1.5,
-            bgcolor: "grey.100",
-            borderRadius: 1,
-            fontSize: 13,
-            mt: 1,
-            mb: 2,
-          }}
-        >
-          <code>recursica.toggleOverStyled()</code>
-        </Box>
         <Stack direction="row" alignItems="center" gap="rec-sm" mb="rec-md">
           <Switch
             label="Highlight Over-Styled Components"
@@ -222,20 +42,7 @@ export const OverStylingInfo = () => {
             onChange={() => toggleGlobalOverStyled()}
           />
         </Stack>
-        <Text mb={4}>
-          This toggles a <strong>cyan 2px box shadow</strong> outline around the
-          children of all over-styled components. The wrapping elements use{" "}
-          <code>display: contents</code> under the hood to ensure they occupy
-          zero DOM space and do not affect flex, grid, or absolute positioning
-          flow. In production builds, this debugging helper is completely
-          disabled and stripped with zero performance overhead.
-        </Text>
-
-        <Divider sx={{ mb: 4 }} />
 
-        <Title order={6} mb={2}>
-          Live Example
-        </Title>
         <Text mb={4}>
           Below is a side-by-side comparison. The first is a standard Recursica
           Button protected by the design tokens mapping. The second flagrantly

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

@@ -0,0 +1,72 @@
+/*
+ * HARDCODED VALUES:
+ * - 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 —
+ *   structural layout mechanics, not a design token.
+ */
+
+.root {
+}
+
+.col {
+}
+
+.hiddenFromXs {
+  display: none;
+}
+
+@media (min-width: 600px) {
+  .hiddenFromSm {
+    display: none;
+  }
+}
+
+@media (min-width: 900px) {
+  .hiddenFromMd {
+    display: none;
+  }
+}
+
+@media (min-width: 1200px) {
+  .hiddenFromLg {
+    display: none;
+  }
+}
+
+@media (min-width: 1536px) {
+  .hiddenFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 599.98px) {
+  .visibleFromSm,
+  .visibleFromMd,
+  .visibleFromLg,
+  .visibleFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 899.98px) {
+  .visibleFromMd,
+  .visibleFromLg,
+  .visibleFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 1199.98px) {
+  .visibleFromLg,
+  .visibleFromXl {
+    display: none;
+  }
+}
+
+@media (max-width: 1535.98px) {
+  .visibleFromXl {
+    display: none;
+  }
+}