@recursica/mui-adapter 0.2.0 → 0.4.0

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

@@ -1,3 +1,41 @@
 import { default as React } from 'react';
-export type ButtonProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Button: React.FC<ButtonProps>;
+import { RecursicaLoaderProps } from '../Loader/Loader';
+import { ButtonProps as MuiButtonProps } from '@mui/material';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export interface RecursicaButtonProps {
+    variant?: "solid" | "outline" | "text";
+    size?: "default" | "small";
+    icon?: React.ReactNode;
+    /**
+     * For polymorphic support (e.g., `component="a"`), native to MUI.
+     */
+    component?: React.ElementType;
+    /** Which Recursica Loader variant to use */
+    loaderVariant?: RecursicaLoaderProps["variant"];
+    /** The size variant for the loader */
+    loaderSize?: RecursicaLoaderProps["size"];
+    /** Whether to use the Recursica loader or fallback to the Mantine loader */
+    useRecursicaLoader?: boolean;
+}
+export type ButtonProps = RecursicaOverStyled<Omit<MuiButtonProps, "variant" | "size" | "color" | "fullWidth"> & RecursicaButtonProps>;
+/**
+ * Recursica Button component wrapping MUI's Button.
+ *
+ * Supports polymorphism via the `component` prop for custom element rendering.
+ * This is particularly useful when you need a button that behaves as a hyperlink (rendering an `<a>` tag)
+ * or integrates with a routing library (e.g., `react-router-dom` or Next.js), while preserving full visual styling.
+ *
+ * @example
+ * ```tsx
+ * // Renders as an <a> tag natively
+ * <Button component="a" href="/dashboard" target="_blank">Navigate</Button>
+ *
+ * // Renders using a custom router link
+ * <Button component={Link} to="/home">Home</Button>
+ * ```
+ */
+export declare const Button: React.ForwardRefExoticComponent<(Omit<Omit<Omit<MuiButtonProps, "color" | "variant" | "size" | "fullWidth"> & RecursicaButtonProps, "style" | "className" | "classes" | "border" | "borderTop" | "borderRight" | "borderBottom" | "borderLeft" | "borderColor" | "borderRadius" | "display" | "bgcolor" | "color" | "zIndex" | "position" | "boxShadow" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "letterSpacing" | "lineHeight" | "textAlign" | "backgroundColor" | "sx"> & import('../../utils/filterStylingProps').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiButtonProps, "color" | "variant" | "size" | "fullWidth"> & RecursicaButtonProps & {
+    overStyled: true;
+}, "ref">) & React.RefAttributes<HTMLButtonElement>>;

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

@@ -1,3 +1,9 @@
 import { default as React } from 'react';
-export type ContainerProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Container: React.FC<ContainerProps>;
+import { ContainerProps as MUIContainerProps } from '@mui/material';
+import { RecursicaSpacing } from '../../utils/filterStylingProps';
+export interface RecursicaContainerProps {
+    children?: React.ReactNode;
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | RecursicaSpacing | (string & {}) | number;
+}
+export type ContainerProps = Omit<MUIContainerProps, "maxWidth"> & RecursicaContainerProps;
+export declare const Container: React.ForwardRefExoticComponent<Omit<ContainerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,3 +1,26 @@
 import { default as React } from 'react';
-export type FlexProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Flex: React.FC<FlexProps>;
+import { BoxProps as MUIBoxProps } from '@mui/material';
+import { RecursicaSpacing, OmitSx } from '../../utils/filterStylingProps';
+export interface RecursicaFlexProps {
+    /**
+     * Content to render inside the flex container.
+     */
+    children?: React.ReactNode;
+    /**
+     * The gap between flex items. Accepts standard MUI spacing or Recursica gap tokens
+     * (e.g. "rec-md").
+     */
+    gap?: string | number | RecursicaSpacing;
+    /**
+     * The vertical gap between flex items when wrapping. Accepts standard MUI spacing
+     * or Recursica gap tokens.
+     */
+    rowGap?: string | number | RecursicaSpacing;
+    /**
+     * The horizontal gap between flex items when wrapping. Accepts standard MUI spacing
+     * or Recursica gap tokens.
+     */
+    columnGap?: string | number | RecursicaSpacing;
+}
+export type FlexProps = OmitSx<MUIBoxProps & RecursicaFlexProps>;
+export declare const Flex: React.ForwardRefExoticComponent<Omit<FlexProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,3 +1,11 @@
 import { default as React } from 'react';
-export type GroupProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Group: React.FC<GroupProps>;
+import { StackProps as MUIStackProps } from '@mui/material';
+import { RecursicaSpacing, OmitSx } from '../../utils/filterStylingProps';
+export interface RecursicaGroupProps {
+    children?: React.ReactNode;
+    gap?: MUIStackProps["spacing"] | RecursicaSpacing;
+    rowGap?: MUIStackProps["spacing"] | RecursicaSpacing;
+    columnGap?: MUIStackProps["spacing"] | RecursicaSpacing;
+}
+export type GroupProps = OmitSx<Omit<MUIStackProps, "spacing" | "direction"> & RecursicaGroupProps>;
+export declare const Group: React.ForwardRefExoticComponent<Omit<GroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,3 +1,14 @@
 import { default as React } from 'react';
-export type LinkProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Link: React.FC<LinkProps>;
+import { LinkProps as MUILinkProps } from '@mui/material';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export interface RecursicaLinkProps {
+    icon?: React.ReactNode;
+    children?: React.ReactNode;
+    component?: React.ElementType;
+}
+export type LinkProps = RecursicaOverStyled<Omit<MUILinkProps, "underline"> & RecursicaLinkProps>;
+export declare const Link: React.ForwardRefExoticComponent<(Omit<Omit<Omit<MUILinkProps, "underline"> & RecursicaLinkProps, "style" | "className" | "classes" | "border" | "borderTop" | "borderRight" | "borderBottom" | "borderLeft" | "borderColor" | "borderRadius" | "display" | "bgcolor" | "color" | "zIndex" | "position" | "boxShadow" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "letterSpacing" | "lineHeight" | "textAlign" | "backgroundColor" | "sx"> & import('../../utils/filterStylingProps').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MUILinkProps, "underline"> & RecursicaLinkProps & {
+    overStyled: true;
+}, "ref">) & React.RefAttributes<HTMLAnchorElement>>;

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

@@ -1,3 +1,10 @@
 import { default as React } from 'react';
-export type LoaderProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Loader: React.FC<LoaderProps>;
+import { RecursicaOverStyled, RecursicaSize } from '../../utils/filterStylingProps';
+export interface RecursicaLoaderProps {
+    /** Map to the component styles defined in variables */
+    variant?: "oval" | "bars" | "dots";
+    /** Map to Recursica sizes */
+    size?: "sm" | "md" | "lg" | RecursicaSize;
+}
+export type LoaderProps = RecursicaOverStyled<React.HTMLAttributes<HTMLSpanElement> & RecursicaLoaderProps>;
+export declare const Loader: React.ForwardRefExoticComponent<LoaderProps & React.RefAttributes<HTMLSpanElement>>;

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

@@ -1,3 +1,9 @@
 import { default as React } from 'react';
-export type StackProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Stack: React.FC<StackProps>;
+import { StackProps as MUIStackProps } from '@mui/material';
+import { RecursicaSpacing, OmitSx } from '../../utils/filterStylingProps';
+export interface RecursicaStackProps {
+    children?: React.ReactNode;
+    gap?: MUIStackProps["spacing"] | RecursicaSpacing;
+}
+export type StackProps = OmitSx<Omit<MUIStackProps, "spacing"> & RecursicaStackProps>;
+export declare const Stack: React.ForwardRefExoticComponent<Omit<StackProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,3 +1,19 @@
 import { default as React } from 'react';
-export type TextProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Text: React.FC<TextProps>;
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { TypographyProps as MuiTypographyProps } from '@mui/material';
+export type TextVariant = "body" | "body-small" | "caption" | "overline" | "subtitle" | "subtitle-small";
+export type RecursicaTextProps = Omit<MuiTypographyProps, "variant"> & {
+    variant?: TextVariant;
+    children?: React.ReactNode;
+    component?: React.ElementType;
+};
+export type TextProps = RecursicaOverStyled<RecursicaTextProps>;
+export declare const Text: React.ForwardRefExoticComponent<(Omit<Omit<RecursicaTextProps, "style" | "className" | "classes" | "border" | "borderTop" | "borderRight" | "borderBottom" | "borderLeft" | "borderColor" | "borderRadius" | "display" | "bgcolor" | "color" | "zIndex" | "position" | "boxShadow" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "letterSpacing" | "lineHeight" | "textAlign" | "backgroundColor" | "sx"> & import('../../utils/filterStylingProps').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTypographyProps, "variant"> & {
+    variant?: TextVariant;
+    children?: React.ReactNode;
+    component?: React.ElementType;
+} & {
+    overStyled: true;
+}, "ref">) & React.RefAttributes<HTMLElement>>;

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

@@ -1,3 +1,18 @@
 import { default as React } from 'react';
-export type TitleProps = React.HTMLAttributes<HTMLDivElement>;
-export declare const Title: React.FC<TitleProps>;
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { TypographyProps as MuiTypographyProps } from '@mui/material';
+export type RecursicaTitleProps = Omit<MuiTypographyProps, "variant"> & {
+    order?: 1 | 2 | 3 | 4 | 5 | 6;
+    children?: React.ReactNode;
+    component?: React.ElementType;
+};
+export type TitleProps = RecursicaOverStyled<RecursicaTitleProps>;
+export declare const Title: React.ForwardRefExoticComponent<(Omit<Omit<RecursicaTitleProps, "style" | "className" | "classes" | "border" | "borderTop" | "borderRight" | "borderBottom" | "borderLeft" | "borderColor" | "borderRadius" | "display" | "bgcolor" | "color" | "zIndex" | "position" | "boxShadow" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "letterSpacing" | "lineHeight" | "textAlign" | "backgroundColor" | "sx"> & import('../../utils/filterStylingProps').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTypographyProps, "variant"> & {
+    order?: 1 | 2 | 3 | 4 | 5 | 6;
+    children?: React.ReactNode;
+    component?: React.ElementType;
+} & {
+    overStyled: true;
+}, "ref">) & React.RefAttributes<HTMLElement>>;

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

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+import { TypographyProps as MuiTypographyProps } from '@mui/material';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+export type TypographyProps = RecursicaOverStyled<Omit<MuiTypographyProps, "variant"> & {
+    /**
+     * Internal typography class mapping
+     */
+    typographyClass: string;
+    component?: React.ElementType;
+}>;
+export declare const Typography: React.ForwardRefExoticComponent<(Omit<Omit<Omit<MuiTypographyProps, "variant"> & {
+    /**
+     * Internal typography class mapping
+     */
+    typographyClass: string;
+    component?: React.ElementType;
+}, "style" | "className" | "classes" | "border" | "borderTop" | "borderRight" | "borderBottom" | "borderLeft" | "borderColor" | "borderRadius" | "display" | "bgcolor" | "color" | "zIndex" | "position" | "boxShadow" | "typography" | "fontFamily" | "fontSize" | "fontWeight" | "letterSpacing" | "lineHeight" | "textAlign" | "backgroundColor" | "sx"> & import('../../utils/filterStylingProps').ForbiddenStyles & {
+    overStyled?: false | undefined;
+}, "ref"> | Omit<Omit<MuiTypographyProps, "variant"> & {
+    /**
+     * Internal typography class mapping
+     */
+    typographyClass: string;
+    component?: React.ElementType;
+} & {
+    overStyled: true;
+}, "ref">) & React.RefAttributes<HTMLElement>>;

package/dist/src/utils/filterStylingProps.d.ts

@@ -25,9 +25,12 @@ export declare const BLOCKED_STYLING_KEYS: readonly ["className", "classes", "st
 export type BlockedStylingKeys = (typeof BLOCKED_STYLING_KEYS)[number];
 export type RecursicaSpacing = "rec-none" | "rec-sm" | "rec-default" | "rec-md" | "rec-lg" | "rec-xl" | "rec-2xl";
 export type RecursicaSize = "small" | "default" | "large";
+export declare const SPACING_MAP: Record<string, string>;
 export type ForbiddenStyles = {
     [K in BlockedStylingKeys]?: never;
 };
+export type OmitSx<T> = Omit<T, "sx">;
+export declare function filterSxProp<T extends Record<string, unknown>>(props: T): Omit<T, "sx">;
 export type RecursicaOverStyled<T> = (Omit<T, BlockedStylingKeys> & ForbiddenStyles & {
     overStyled?: false | undefined;
 }) | (T & {

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.2.0",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -82,6 +82,7 @@
     "storybook": "^10.3.3",
     "storybook-dark-mode": "^5.0.0",
     "strip-literal": "^3.0.0",
+    "ts-morph": "^28.0.0",
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.30.1",
     "vite": "^6.3.5",

package/src/Introduction.stories.tsx

@@ -1,157 +1,160 @@
 import type { Meta } from "@storybook/react-vite";
 import { AdaptersContent, MuiLogo } from "@recursica/storybook-template";
-import { Button } from "./components/Button/Button";
 import { VersionInfo } from "./Version";
 import { OverStylingInfo } from "./OverStyling";
 
 const DOCS_URL = "https://recursica.com";
 const FORGE_URL = "https://forge.recursica.com";
 
-const sectionStyle: React.CSSProperties = {
-  marginBottom: 32,
-};
-
-const headingStyle: React.CSSProperties = {
-  fontSize: 14,
-  fontWeight: 600,
-  color: "#333",
-  marginBottom: 8,
-  marginTop: 0,
-};
-
-const bodyStyle: React.CSSProperties = {
-  fontSize: 14,
-  lineHeight: 1.6,
-  color: "#444",
-  margin: 0,
-};
-
-const linkStyle: React.CSSProperties = {
-  color: "#0066cc",
-  textDecoration: "none",
-};
+import { Container, Box, Group, Title, Text, Link } from "./components";
 
 function IntroductionContent() {
   return (
-    <div style={{ padding: 24, maxWidth: 640 }}>
-      <div
-        style={{
-          display: "flex",
-          alignItems: "center",
-          gap: "16px",
-          marginBottom: "16px",
-        }}
-      >
+    <Container size="md" style={{ padding: "32px 0", maxWidth: 640 }}>
+      <Group gap="rec-md" mb={2}>
         <MuiLogo width={40} height={40} />
-        <div>
-          <h1 style={{ fontSize: 24, fontWeight: 700, margin: 0 }}>
+        <Box>
+          <Title order={1} m={0}>
             Recursica Design System (MUI Adapter)
-          </h1>
-          <a
-            href="https://mui.com"
-            target="_blank"
-            rel="noreferrer"
-            style={linkStyle}
-          >
+          </Title>
+          <Link href="https://mui.com" target="_blank" rel="noreferrer">
             mui.com
-          </a>
-        </div>
-      </div>
-      <p style={{ ...bodyStyle, marginBottom: 24 }}>
+          </Link>
+        </Box>
+      </Group>
+      <Text mb={4}>
         This Storybook showcases the Recursica design system implemented for the{" "}
         <strong>Material UI (MUI) Kit</strong>. It provides reusable components
         that map our design tokens to MUI's robust component layer.
-      </p>
+      </Text>
 
-      <section style={sectionStyle}>
-        <h2 style={headingStyle}>Looking for another UI Kit?</h2>
-        <p style={bodyStyle}>
+      <Box component="section" sx={{ mb: 4 }}>
+        <Title order={2} mb={1}>
+          Looking for another UI Kit?
+        </Title>
+        <Text>
           Are you using a different UI Kit (like Mantine)? Recursica provides
           multiple adapters for different frameworks.
-        </p>
-        <div style={{ marginTop: "16px" }}>
-          <Button
+        </Text>
+        <Box sx={{ mt: 2 }}>
+          <a
             href="./?path=/story/introduction--adapters"
             target="_parent"
-            variant="solid"
+            className="adapter-btn"
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              backgroundColor:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background)",
+              color:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text)",
+              textDecoration: "none",
+              borderRadius:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_border-radius)",
+              height:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_height)",
+              padding:
+                "0 var(--recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding)",
+              fontFamily:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-family)",
+              fontSize:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-size)",
+              fontWeight:
+                "var(--recursica_ui-kit_components_button_variants_sizes_default_properties_text_font-weight)",
+              boxShadow:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_elevation)",
+              border:
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_border-size) solid var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_border-color)",
+              transition: "opacity 0.2s ease",
+            }}
+            onMouseOver={(e) => {
+              e.currentTarget.style.opacity = "0.85";
+              e.currentTarget.style.color =
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-hover)";
+            }}
+            onMouseOut={(e) => {
+              e.currentTarget.style.opacity = "1";
+              e.currentTarget.style.color =
+                "var(--recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text)";
+            }}
           >
             View Supported Adapters
-          </Button>
-        </div>
-      </section>
-
-      <section style={sectionStyle}>
-        <h2 style={headingStyle}>Installation</h2>
-        <p style={bodyStyle}>
-          To install the MUI adapter in your project, run:
-        </p>
-        <pre
-          style={{
-            padding: 12,
-            backgroundColor: "#f5f5f5",
-            borderRadius: 6,
+          </a>
+        </Box>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Title order={2} mb={1}>
+          Installation
+        </Title>
+        <Text>To install the MUI adapter in your project, run:</Text>
+        <Box
+          component="pre"
+          sx={{
+            p: 1.5,
+            bgcolor: "grey.100",
+            borderRadius: 1,
             fontSize: 13,
-            marginTop: 8,
+            mt: 1,
           }}
         >
           <code>
             npm install @recursica/mui-adapter @mui/material @emotion/react
             @emotion/styled
           </code>
-        </pre>
-      </section>
-
-      <section style={sectionStyle}>
-        <h2 style={headingStyle}>Tokens</h2>
-        <p style={bodyStyle}>
+        </Box>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Title order={2} mb={1}>
+          Tokens
+        </Title>
+        <Text>
           Raw design tokens (colors, sizes, font weights, opacities, etc.) that
           feed the theme and components. These are the primitive values defined
           in your token set and exposed as CSS custom properties.
-        </p>
-      </section>
-
-      <section style={sectionStyle}>
-        <h2 style={headingStyle}>Theme</h2>
-        <p style={bodyStyle}>
+        </Text>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Title order={2} mb={1}>
+          Theme
+        </Title>
+        <Text>
           Brand and theme layer built on top of tokens. Typography types,
           dimensions, and layout grids are defined here. Theme uses the tokens
           and exposes both CSS variables and helper classes (e.g. typography
           classes) for consistent styling across the product.
-        </p>
-      </section>
-
-      <section style={sectionStyle}>
-        <h2 style={headingStyle}>Configuring Recursica</h2>
-        <p style={bodyStyle}>
+        </Text>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Title order={2} mb={1}>
+          Configuring Recursica
+        </Title>
+        <Text>
           To modify the Recursica configuration (tokens, brand, theme), go to{" "}
-          <a
-            href={FORGE_URL}
-            target="_blank"
-            rel="noopener noreferrer"
-            style={linkStyle}
-          >
+          <Link href={FORGE_URL} target="_blank" rel="noopener noreferrer">
             {FORGE_URL}
-          </a>
+          </Link>
           . Changes there drive the tokens and theme you see in this Storybook.
-        </p>
-      </section>
-
-      <section style={sectionStyle}>
-        <h2 style={headingStyle}>Documentation</h2>
-        <p style={bodyStyle}>
+        </Text>
+      </Box>
+
+      <Box component="section" sx={{ mb: 4 }}>
+        <Title order={2} mb={1}>
+          Documentation
+        </Title>
+        <Text>
           For full documentation, guides, and API reference, visit{" "}
-          <a
-            href={DOCS_URL}
-            target="_blank"
-            rel="noopener noreferrer"
-            style={linkStyle}
-          >
+          <Link href={DOCS_URL} target="_blank" rel="noopener noreferrer">
             {DOCS_URL}
-          </a>
+          </Link>
           .
-        </p>
-      </section>
-    </div>
+        </Text>
+      </Box>
+    </Container>
   );
 }
 

package/src/OverStyling.tsx

@@ -1,20 +1,14 @@
-import {
-  Container,
-  Paper,
-  Typography as Text,
-  Divider,
-  Stack,
-  Box,
-} from "@mui/material";
+import { Paper, Divider } from "@mui/material";
+import { Container, Stack, Box, Text, Title } from "./components";
 import { Button } from "./components/Button/Button";
 
 export const OverStylingInfo = () => {
   return (
-    <Container maxWidth="md" sx={{ py: 4 }}>
+    <Container size="md" style={{ padding: "32px 0" }}>
       <Paper variant="outlined" sx={{ p: 4, borderRadius: 2 }}>
-        <Text variant="h4" mb={2}>
+        <Title order={4} mb={2}>
           Over Styling (<code>overStyled</code>)
-        </Text>
+        </Title>
         <Text mb={2}>
           By default, all Recursica components are strictly sandboxed. This
           means they are protected against arbitrary styling configurations
@@ -31,9 +25,9 @@ export const OverStylingInfo = () => {
           <code>overStyled={`{true}`}</code>.
         </Text>
 
-        <Text variant="h6" mb={1} mt={4}>
+        <Title order={6} mb={1} mt={4}>
           The Core Philosophy
-        </Text>
+        </Title>
         <Text mb={1}>
           **You should not over-style components.** Using{" "}
           <code>overStyled</code> explicitly signifies that you are breaking
@@ -77,9 +71,9 @@ export const OverStylingInfo = () => {
 
         <Divider sx={{ mb: 4 }} />
 
-        <Text variant="h6" mb={1}>
+        <Title order={6} mb={1}>
           Permitted Layout Properties
-        </Text>
+        </Title>
         <Text mb={1}>
           Unlike deep styling bounds (colors, typography, padding, dimensions),
           external <strong>layout spacing properties</strong> like Margins (
@@ -113,7 +107,7 @@ export const OverStylingInfo = () => {
             </Text>
           </li>
         </Box>
-        <Text mb={1} sx={{ fontWeight: 500 }}>
+        <Text mb={1} overStyled sx={{ fontWeight: 500 }}>
           Available Recursica Layout Tokens:
         </Text>
         <Box component="ul" sx={{ pl: 4, mb: 4 }}>
@@ -156,9 +150,9 @@ export const OverStylingInfo = () => {
 
         <Divider sx={{ mb: 4 }} />
 
-        <Text variant="h6" mb={1}>
+        <Title order={6} mb={1}>
           Primitive Layout Components Exemption
-        </Text>
+        </Title>
         <Text mb={1}>
           Unlike complex UI components (Buttons, Tabs, Inputs) which are
           strictly protected, <strong>Primitive Layout Components</strong> (
@@ -178,9 +172,9 @@ export const OverStylingInfo = () => {
 
         <Divider sx={{ mb: 4 }} />
 
-        <Text variant="h6" mb={2}>
+        <Title order={6} mb={2}>
           Live Example
-        </Text>
+        </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
@@ -188,26 +182,27 @@ export const OverStylingInfo = () => {
           styling generics to punch right through the sandbox layout.
         </Text>
 
-        <Stack direction="row" spacing={4}>
+        <Stack direction="row" gap="rec-default">
           <Box>
             <Text
               variant="caption"
+              overStyled
               sx={{ color: "text.secondary", mb: 1, display: "block" }}
             >
               Strict Baseline (Default)
             </Text>
-            {/* Note: In mui-adapter, Button is currently a stub so we just pass standard React props */}
             <Button>Standard UI Kit Button</Button>
           </Box>
           <Box>
             <Text
               variant="caption"
+              overStyled
               sx={{ color: "text.secondary", mb: 1, display: "block" }}
             >
               overStyled={`{true}`}
             </Text>
-            {/* Note: Button props are just standard HTML div props for the stub */}
             <Button
+              overStyled={true}
               style={{
                 backgroundColor: "pink",
                 color: "black",