@recursica/mantine-adapter 0.32.0 → 0.34.0

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

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { Modal as MantineModal, ModalProps as MantineModalProps } from '@mantine/core';
+import { ModalProps as MantineModalProps, ModalRootProps as MantineModalRootProps, ModalOverlayProps as MantineModalOverlayProps, ModalContentProps as MantineModalContentProps, ModalHeaderProps as MantineModalHeaderProps, ModalTitleProps as MantineModalTitleProps, ModalCloseButtonProps as MantineModalCloseButtonProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { RecursicaModalProps } from '@recursica/adapter-common';
 /**
@@ -20,18 +20,31 @@ export type ModalProps = RecursicaOverStyled<Omit<MantineModalProps, "size" | "r
  * > primary action button MUST be the right-most element, with the secondary
  * > (outline variant) action placed immediately to the left of it.
  */
-declare const ModalFooter: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export type ModalFooterProps = RecursicaOverStyled<React.ComponentPropsWithoutRef<"div">>;
+declare const ModalFooter: React.ForwardRefExoticComponent<ModalFooterProps & React.RefAttributes<HTMLDivElement>>;
 declare const ModalBody: React.ForwardRefExoticComponent<Omit<import('@mantine/core').ModalBodyProps & React.RefAttributes<HTMLDivElement> & {
     component?: any;
     renderRoot?: (props: Record<string, any>) => React.ReactNode;
 }, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export type ModalRootProps = RecursicaOverStyled<MantineModalRootProps>;
+declare const ModalRoot: React.ForwardRefExoticComponent<ModalRootProps & React.RefAttributes<HTMLDivElement>>;
+export type ModalOverlayProps = RecursicaOverStyled<MantineModalOverlayProps>;
+declare const ModalOverlay: React.ForwardRefExoticComponent<ModalOverlayProps & React.RefAttributes<HTMLDivElement>>;
+export type ModalContentProps = RecursicaOverStyled<MantineModalContentProps>;
+declare const ModalContent: React.ForwardRefExoticComponent<ModalContentProps & React.RefAttributes<HTMLDivElement>>;
+export type ModalHeaderProps = RecursicaOverStyled<MantineModalHeaderProps>;
+declare const ModalHeader: React.ForwardRefExoticComponent<ModalHeaderProps & React.RefAttributes<HTMLElement>>;
+export type ModalTitleProps = RecursicaOverStyled<MantineModalTitleProps>;
+declare const ModalTitle: React.ForwardRefExoticComponent<ModalTitleProps & React.RefAttributes<HTMLHeadingElement>>;
+export type ModalCloseButtonProps = RecursicaOverStyled<MantineModalCloseButtonProps>;
+declare const ModalCloseButton: React.ForwardRefExoticComponent<ModalCloseButtonProps & React.RefAttributes<HTMLButtonElement>>;
 interface ModalComponent extends React.ForwardRefExoticComponent<ModalProps & React.RefAttributes<HTMLDivElement>> {
-    Root: typeof MantineModal.Root;
-    Overlay: typeof MantineModal.Overlay;
-    Content: typeof MantineModal.Content;
-    Header: typeof MantineModal.Header;
-    Title: typeof MantineModal.Title;
-    CloseButton: typeof MantineModal.CloseButton;
+    Root: typeof ModalRoot;
+    Overlay: typeof ModalOverlay;
+    Content: typeof ModalContent;
+    Header: typeof ModalHeader;
+    Title: typeof ModalTitle;
+    CloseButton: typeof ModalCloseButton;
     Body: typeof ModalBody;
     Footer: typeof ModalFooter;
 }

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

@@ -1,45 +1,65 @@
 import { default as React } from 'react';
-import { Pagination as MantinePagination, PaginationProps as MantinePaginationProps, PaginationRootProps as MantinePaginationRootProps } from '@mantine/core';
+import { Pagination as MantinePagination, PaginationProps as MantinePaginationProps, PaginationRootProps as MantinePaginationRootProps, PaginationControlProps as MantinePaginationControlProps, PaginationDotsProps as MantinePaginationDotsProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { PaginationIcon } from './Pagination.icons';
 import { RecursicaPaginationProps } from '@recursica/adapter-common';
 export type PaginationProps = RecursicaOverStyled<MantinePaginationProps & RecursicaPaginationProps>;
 export type PaginationRootProps = RecursicaOverStyled<MantinePaginationRootProps>;
-export type PaginationEdgeProps<T extends React.ElementType> = React.ComponentProps<T> & {
+export type PaginationEdgeProps<T extends React.ElementType> = RecursicaOverStyled<React.ComponentProps<T> & {
     /** If set to true, displays text labels alongside the icon. */
     withLabel?: boolean;
     icon?: any;
-};
+}>;
 declare const _PaginationRoot: React.ForwardRefExoticComponent<PaginationRootProps & React.RefAttributes<HTMLDivElement>>;
-declare const _PaginationNext: React.ForwardRefExoticComponent<{
-    /** If set to true, displays text labels alongside the icon. */
-    withLabel?: boolean;
-    icon?: any;
-} & React.RefAttributes<HTMLButtonElement>>;
-declare const _PaginationPrevious: React.ForwardRefExoticComponent<{
-    /** If set to true, displays text labels alongside the icon. */
-    withLabel?: boolean;
-    icon?: any;
-} & React.RefAttributes<HTMLButtonElement>>;
-declare const _PaginationFirst: React.ForwardRefExoticComponent<{
-    /** If set to true, displays text labels alongside the icon. */
-    withLabel?: boolean;
-    icon?: any;
-} & React.RefAttributes<HTMLButtonElement>>;
-declare const _PaginationLast: React.ForwardRefExoticComponent<{
-    /** If set to true, displays text labels alongside the icon. */
-    withLabel?: boolean;
-    icon?: any;
-} & React.RefAttributes<HTMLButtonElement>>;
+declare const _PaginationNext: React.ForwardRefExoticComponent<PaginationEdgeProps<(<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, import('@mantine/core').PaginationEdgeProps>) => React.ReactElement) & Omit<React.FunctionComponent<(import('@mantine/core').PaginationEdgeProps & {
+    component?: any;
+} & Omit<Omit<any, "ref">, "component" | keyof import('@mantine/core').PaginationEdgeProps> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (import('@mantine/core').PaginationEdgeProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>> & React.RefAttributes<HTMLButtonElement>>;
+declare const _PaginationPrevious: React.ForwardRefExoticComponent<PaginationEdgeProps<(<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, import('@mantine/core').PaginationEdgeProps>) => React.ReactElement) & Omit<React.FunctionComponent<(import('@mantine/core').PaginationEdgeProps & {
+    component?: any;
+} & Omit<Omit<any, "ref">, "component" | keyof import('@mantine/core').PaginationEdgeProps> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (import('@mantine/core').PaginationEdgeProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>> & React.RefAttributes<HTMLButtonElement>>;
+declare const _PaginationFirst: React.ForwardRefExoticComponent<PaginationEdgeProps<(<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, import('@mantine/core').PaginationEdgeProps>) => React.ReactElement) & Omit<React.FunctionComponent<(import('@mantine/core').PaginationEdgeProps & {
+    component?: any;
+} & Omit<Omit<any, "ref">, "component" | keyof import('@mantine/core').PaginationEdgeProps> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (import('@mantine/core').PaginationEdgeProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>> & React.RefAttributes<HTMLButtonElement>>;
+declare const _PaginationLast: React.ForwardRefExoticComponent<PaginationEdgeProps<(<C = "button">(props: import('@mantine/core').PolymorphicComponentProps<C, import('@mantine/core').PaginationEdgeProps>) => React.ReactElement) & Omit<React.FunctionComponent<(import('@mantine/core').PaginationEdgeProps & {
+    component?: any;
+} & Omit<Omit<any, "ref">, "component" | keyof import('@mantine/core').PaginationEdgeProps> & {
+    ref?: any;
+    renderRoot?: (props: any) => any;
+}) | (import('@mantine/core').PaginationEdgeProps & {
+    component: React.ElementType;
+    renderRoot?: (props: Record<string, any>) => any;
+})>, never> & Record<string, never>> & React.RefAttributes<HTMLButtonElement>>;
 declare const _Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLDivElement>>;
+export type PaginationControlProps = RecursicaOverStyled<MantinePaginationControlProps>;
+declare const _PaginationControl: React.ForwardRefExoticComponent<PaginationControlProps & React.RefAttributes<HTMLButtonElement>>;
+export type PaginationDotsProps = RecursicaOverStyled<MantinePaginationDotsProps>;
+declare const _PaginationDots: React.ForwardRefExoticComponent<PaginationDotsProps & React.RefAttributes<HTMLDivElement>>;
 /**
  * Recursica Pagination component wrapping Mantine's Pagination.
  */
 export declare const Pagination: typeof _Pagination & {
     Root: typeof _PaginationRoot;
     Items: typeof MantinePagination.Items;
-    Control: typeof MantinePagination.Control;
-    Dots: typeof MantinePagination.Dots;
+    Control: typeof _PaginationControl;
+    Dots: typeof _PaginationDots;
     Next: typeof _PaginationNext;
     Previous: typeof _PaginationPrevious;
     First: typeof _PaginationFirst;

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

@@ -1,4 +1,4 @@
-import { Drawer as MantineDrawer, DrawerProps as MantineDrawerProps } from '@mantine/core';
+import { Drawer as MantineDrawer, DrawerProps as MantineDrawerProps, DrawerRootProps as MantineDrawerRootProps, DrawerOverlayProps as MantineDrawerOverlayProps, DrawerContentProps as MantineDrawerContentProps, DrawerHeaderProps as MantineDrawerHeaderProps, DrawerTitleProps as MantineDrawerTitleProps, DrawerCloseButtonProps as MantineDrawerCloseButtonProps, DrawerBodyProps as MantineDrawerBodyProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { RecursicaPanelProps as BaseRecursicaPanelProps } from '@recursica/adapter-common';
 /**
@@ -45,14 +45,28 @@ export type PanelFooterProps = RecursicaOverStyled<React.HTMLAttributes<HTMLDivE
  * natively provide a footer.
  */
 export declare const PanelFooter: import('react').ForwardRefExoticComponent<PanelFooterProps & import('react').RefAttributes<HTMLDivElement>>;
+export type PanelRootProps = RecursicaOverStyled<MantineDrawerRootProps>;
+export declare const PanelRoot: import('react').ForwardRefExoticComponent<PanelRootProps & import('react').RefAttributes<HTMLDivElement>>;
+export type PanelOverlayProps = RecursicaOverStyled<MantineDrawerOverlayProps>;
+export declare const PanelOverlay: import('react').ForwardRefExoticComponent<PanelOverlayProps & import('react').RefAttributes<HTMLDivElement>>;
+export type PanelContentProps = RecursicaOverStyled<MantineDrawerContentProps>;
+export declare const PanelContent: import('react').ForwardRefExoticComponent<PanelContentProps & import('react').RefAttributes<HTMLDivElement>>;
+export type PanelHeaderProps = RecursicaOverStyled<MantineDrawerHeaderProps>;
+export declare const PanelHeader: import('react').ForwardRefExoticComponent<PanelHeaderProps & import('react').RefAttributes<HTMLElement>>;
+export type PanelTitleProps = RecursicaOverStyled<MantineDrawerTitleProps>;
+export declare const PanelTitle: import('react').ForwardRefExoticComponent<PanelTitleProps & import('react').RefAttributes<HTMLHeadingElement>>;
+export type PanelCloseButtonProps = RecursicaOverStyled<MantineDrawerCloseButtonProps>;
+export declare const PanelCloseButton: import('react').ForwardRefExoticComponent<PanelCloseButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
+export type PanelBodyProps = RecursicaOverStyled<MantineDrawerBodyProps>;
+export declare const PanelBody: import('react').ForwardRefExoticComponent<PanelBodyProps & import('react').RefAttributes<HTMLDivElement>>;
 type PanelComponent = typeof PanelBase & {
-    Root: typeof MantineDrawer.Root;
-    Overlay: typeof MantineDrawer.Overlay;
-    Content: typeof MantineDrawer.Content;
-    Header: typeof MantineDrawer.Header;
-    Title: typeof MantineDrawer.Title;
-    CloseButton: typeof MantineDrawer.CloseButton;
-    Body: typeof MantineDrawer.Body;
+    Root: typeof PanelRoot;
+    Overlay: typeof PanelOverlay;
+    Content: typeof PanelContent;
+    Header: typeof PanelHeader;
+    Title: typeof PanelTitle;
+    CloseButton: typeof PanelCloseButton;
+    Body: typeof PanelBody;
     Stack: typeof MantineDrawer.Stack;
     Footer: typeof PanelFooter;
 };

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

@@ -1,13 +1,15 @@
 import { default as React } from 'react';
-import { Stepper as MantineStepper, StepperProps as MantineStepperProps } from '@mantine/core';
+import { Stepper as MantineStepper, StepperProps as MantineStepperProps, StepperStepProps as MantineStepperStepProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { RecursicaStepperProps } from '@recursica/adapter-common';
 export interface RecursicaStepperPropsExtended extends Omit<MantineStepperProps, "size">, RecursicaStepperProps {
 }
 export type StepperProps = RecursicaOverStyled<RecursicaStepperPropsExtended>;
 declare const _Stepper: React.ForwardRefExoticComponent<StepperProps & React.RefAttributes<HTMLDivElement>>;
+export type StepperStepProps = RecursicaOverStyled<MantineStepperStepProps>;
+declare const _StepperStep: React.ForwardRefExoticComponent<StepperStepProps & React.RefAttributes<HTMLButtonElement>>;
 export declare const Stepper: typeof _Stepper & {
-    Step: typeof MantineStepper.Step;
+    Step: typeof _StepperStep;
     Completed: typeof MantineStepper.Completed;
 };
 export {};

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

@@ -1,17 +1,33 @@
-import { Table as MantineTable, TableProps as MantineTableProps } from '@mantine/core';
+import { TableProps as MantineTableProps, TableTheadProps as MantineTableTheadProps, TableTbodyProps as MantineTableTbodyProps, TableTrProps as MantineTableTrProps, TableThProps as MantineTableThProps, TableTdProps as MantineTableTdProps, TableTfootProps as MantineTableTfootProps, TableCaptionProps as MantineTableCaptionProps, TableScrollContainerProps as MantineTableScrollContainerProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { RecursicaTableProps } from '@recursica/adapter-common';
 export type TableProps = RecursicaOverStyled<MantineTableProps & RecursicaTableProps>;
 declare const TableBase: import('react').ForwardRefExoticComponent<TableProps & import('react').RefAttributes<HTMLTableElement>>;
+export type TableTheadProps = RecursicaOverStyled<MantineTableTheadProps>;
+export declare const TableThead: import('react').ForwardRefExoticComponent<TableTheadProps & import('react').RefAttributes<HTMLTableSectionElement>>;
+export type TableTbodyProps = RecursicaOverStyled<MantineTableTbodyProps>;
+export declare const TableTbody: import('react').ForwardRefExoticComponent<TableTbodyProps & import('react').RefAttributes<HTMLTableSectionElement>>;
+export type TableTrProps = RecursicaOverStyled<MantineTableTrProps>;
+export declare const TableTr: import('react').ForwardRefExoticComponent<TableTrProps & import('react').RefAttributes<HTMLTableRowElement>>;
+export type TableThProps = RecursicaOverStyled<MantineTableThProps>;
+export declare const TableTh: import('react').ForwardRefExoticComponent<TableThProps & import('react').RefAttributes<HTMLTableCellElement>>;
+export type TableTdProps = RecursicaOverStyled<MantineTableTdProps>;
+export declare const TableTd: import('react').ForwardRefExoticComponent<TableTdProps & import('react').RefAttributes<HTMLTableCellElement>>;
+export type TableTfootProps = RecursicaOverStyled<MantineTableTfootProps>;
+export declare const TableTfoot: import('react').ForwardRefExoticComponent<TableTfootProps & import('react').RefAttributes<HTMLTableSectionElement>>;
+export type TableCaptionProps = RecursicaOverStyled<MantineTableCaptionProps>;
+export declare const TableCaption: import('react').ForwardRefExoticComponent<TableCaptionProps & import('react').RefAttributes<HTMLTableCaptionElement>>;
+export type TableScrollContainerProps = RecursicaOverStyled<MantineTableScrollContainerProps>;
+export declare const TableScrollContainer: import('react').ForwardRefExoticComponent<TableScrollContainerProps & import('react').RefAttributes<HTMLDivElement>>;
 type TableComponent = typeof TableBase & {
-    Thead: typeof MantineTable.Thead;
-    Tbody: typeof MantineTable.Tbody;
-    Tr: typeof MantineTable.Tr;
-    Th: typeof MantineTable.Th;
-    Td: typeof MantineTable.Td;
-    Tfoot: typeof MantineTable.Tfoot;
-    Caption: typeof MantineTable.Caption;
-    ScrollContainer: typeof MantineTable.ScrollContainer;
+    Thead: typeof TableThead;
+    Tbody: typeof TableTbody;
+    Tr: typeof TableTr;
+    Th: typeof TableTh;
+    Td: typeof TableTd;
+    Tfoot: typeof TableTfoot;
+    Caption: typeof TableCaption;
+    ScrollContainer: typeof TableScrollContainer;
 };
 export declare const Table: TableComponent;
 export {};

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

@@ -1,4 +1,4 @@
-import { Tooltip as MantineTooltip, TooltipProps as MantineTooltipProps } from '@mantine/core';
+import { Tooltip as MantineTooltip, TooltipProps as MantineTooltipProps, TooltipFloatingProps as MantineTooltipFloatingProps } from '@mantine/core';
 import { RecursicaOverStyled } from '../../utils/filterStylingProps';
 import { RecursicaTooltipProps } from '@recursica/adapter-common';
 /**
@@ -23,8 +23,10 @@ declare const TooltipBase: {
     ({ overStyled, withBeak, ...rest }: TooltipProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
+export type TooltipFloatingProps = RecursicaOverStyled<MantineTooltipFloatingProps>;
+export declare const TooltipFloating: import('react').ForwardRefExoticComponent<TooltipFloatingProps & import('react').RefAttributes<HTMLDivElement>>;
 type TooltipComponent = typeof TooltipBase & {
-    Floating: typeof MantineTooltip.Floating;
+    Floating: typeof TooltipFloating;
     Group: typeof MantineTooltip.Group;
 };
 export declare const Tooltip: TooltipComponent;

package/llms.txt

@@ -9,8 +9,63 @@ This adapter converts Recursica design tokens into Mantine-specific themes and c
 - Relies on `@mantine/core`, `@mantine/dates`, and `@mantine/hooks` 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)
+- [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)
+- [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)
+- [Popover](src/components/Popover/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)

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.32.0",
+  "version": "0.34.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -34,7 +34,8 @@
     "llms.txt",
     "USAGE.md",
     "ARCHITECTURE.md",
-    "SETUP.md"
+    "SETUP.md",
+    "OVERSTYLING.md"
   ],
   "keywords": [
     "react",

package/src/OverStyling.tsx

@@ -1,3 +1,5 @@
+import ReactMarkdown from "react-markdown";
+import { TypographyStylesProvider } from "@mantine/core";
 import {
   Container,
   Card,
@@ -13,6 +15,7 @@ import {
   toggleGlobalOverStyled,
   wrapComponent,
 } from "@recursica/adapter-common";
+import overStylingDoc from "../OVERSTYLING.md?raw";
 
 const Button = wrapComponent(RawButton);
 const Text = wrapComponent(RawText);
@@ -24,246 +27,27 @@ export const OverStylingInfo = () => {
     <Container size="md" style={{ padding: "32px 0" }}>
       <Card>
         <Card.Content>
-          <Title order={1} mb="rec-md">
-            Over Styling (<code>overStyled</code>)
-          </Title>
-          <Text mb="rec-md">
-            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>classNames</code> injections, or using deep Mantine layout
-            hooks like <code>bg</code> and <code>c</code>). This strict
-            compile-time and run-time enforcement guarantees that your design
-            system tokens remain true across your application.
-          </Text>
-          <Text mb="rec-md">
-            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={3} mb="rec-sm">
-            The Core Philosophy
-          </Title>
-          <Text mb="rec-sm">
-            **You should not over-style components.** Using{" "}
-            <code>overStyled</code> explicitly signifies that you are breaking
-            design system rules.
-          </Text>
-          <Stack
-            component="ol"
-            style={{ paddingLeft: "24px" }}
-            mb="rec-xl"
-            gap="rec-sm"
-          >
-            <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>@mantine/core</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>
-          </Stack>
+          <TypographyStylesProvider>
+            <ReactMarkdown>{overStylingDoc}</ReactMarkdown>
+          </TypographyStylesProvider>
 
           <Stack
             style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
+            my="rec-xl"
           />
 
-          <Title order={3} mb="rec-sm">
-            Permitted Layout Properties
-          </Title>
-          <Text mb="rec-sm">
-            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="rec-xl">
-            When using layout properties, you have the flexibility to use either
-            ecosystem seamlessly:
-          </Text>
-          <Stack
-            component="ol"
-            style={{ paddingLeft: "24px" }}
-            mb="rec-md"
-            gap="rec-sm"
-          >
-            <li>
-              <Text>
-                <strong>Mantine Core Values:</strong> Passing standard Mantine
-                sizes (like <code>mt="md"</code>) passes straight through to
-                Mantine natively, allowing you to interface completely normally
-                with a parent application's existing Mantine 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>
-          </Stack>
-          <Text mb="rec-sm" overStyled fw={500}>
-            Available Recursica Layout Tokens:
-          </Text>
-          <Stack
-            component="ul"
-            style={{ paddingLeft: "24px" }}
-            mb="rec-xl"
-            gap="rec-none"
-          >
-            <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>
-          </Stack>
-
-          <Stack
-            style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
-          />
-
-          <Title order={3} mb="rec-sm">
-            Primitive Layout Components Exemption
+          <Title order={3} mb="rec-md">
+            Try It Yourself
           </Title>
-          <Text mb="rec-sm">
-            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="rec-xl">
-            Because the entire functional purpose of these components is
-            structural layout composition, developers are free to pass any
-            standard Mantine 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>
-
-          <Stack
-            style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
-          />
 
-          <Title order={3} mb="rec-sm">
-            Visual Auditing & Highlights (Development Only)
-          </Title>
-          <Text mb="rec-sm">
-            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="rec-sm">
-            In <strong>development builds</strong>, you can highlight all
-            over-styled components on the page. Open your browser's developer
-            console and run:
-          </Text>
-          <Stack
-            style={{
-              padding: 12,
-              backgroundColor: "#f5f5f5",
-              borderRadius: 6,
-              fontSize: 13,
-              marginTop: 8,
-              marginBottom: 16,
-            }}
-          >
-            <code>recursica.toggleOverStyled()</code>
-          </Stack>
-          <Group mb="rec-md">
+          <Group mb="rec-xl">
             <Switch
               label="Highlight Over-Styled Components"
               checked={isHighlightActive}
               onChange={() => toggleGlobalOverStyled()}
             />
           </Group>
-          <Text mb="rec-xl">
-            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>
 
-          <Stack
-            style={{ height: 1, backgroundColor: "#eaeaea" }}
-            mb="rec-xl"
-          />
-
-          <Title order={3} mb="rec-md">
-            Live Example
-          </Title>
           <Text mb="rec-xl">
             Below is a side-by-side comparison. The first is a standard
             Recursica Button protected by the design tokens mapping. The second