@recursica/adapter-mui-v7 1.0.0

package/OVERSTYLING.md

@@ -0,0 +1,59 @@
+# Over Styling (`overStyled`)
+
+By default, all Recursica components are strictly sandboxed. This means they are protected against arbitrary styling configurations (like passing generic React `style` objects, custom `className` injections, or using deep MUI layout props like `sx`). This strict compile-time and run-time enforcement guarantees that your design system tokens remain true across your application.
+
+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 **escape hatch** property: `overStyled={true}`.
+
+```tsx
+<Button
+  overStyled={true}
+  style={{ backgroundColor: "pink", color: "black", borderRadius: "24px" }}
+>
+  Unsafe Pink Marketing Button
+</Button>
+```
+
+## The Core Philosophy
+
+**You should not over-style components.** Using `overStyled` explicitly signifies that you are breaking design system rules.
+
+1. **Technical Debt:** 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.
+2. **Auditing & Searching:** Because this pattern creates technical debt, we enforce the explicit `overStyled` boolean. This provides a highly auditable, easily searchable string. Product managers and engineers can quickly grep the codebase for `overStyled` (or the `RecursicaOverStyled` typings) to hunt down components that don't match standard patterns.
+3. **Highly Custom Components:** If your application genuinely requires massive custom layouts that the UI kit cannot support, **do not hack the Recursica component**. Instead, it is highly encouraged that you import the underlying primitive component directly from `@mui/material` 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!
+
+## Permitted Layout Properties
+
+Unlike deep styling bounds (colors, typography, padding, dimensions), external **layout spacing properties** like margins (`m`, `mt`, `mb`, `mx`) are safely **permitted by default**. This allows integrators to structurally compose components alongside siblings without breaching internal token boundaries.
+
+When using layout properties, you have the flexibility to use either ecosystem seamlessly:
+
+1. **MUI Core Values:** Passing standard MUI sizes (like `mt={2}`) 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.
+2. **Recursica Strict Tokens:** Passing our custom prefixed tokens (like `mt="rec-md"`) signals our internal layout interceptor to securely translate the value directly to our native `--recursica_brand_dimensions_*` CSS variables. This ensures strict design token measurements while sharing the exact same prop interface!
+
+Available Recursica layout tokens:
+
+- `rec-none` (0px limit)
+- `rec-sm` (0.5x scaling)
+- `rec-default` (1.0x scaling)
+- `rec-md` (1.5x scaling)
+- `rec-lg` (2.0x scaling)
+- `rec-xl` (3.0x scaling)
+- `rec-2xl` (4.0x scaling)
+
+## Primitive Layout Components Exemption
+
+Unlike complex UI components (Buttons, Tabs, Inputs) which are strictly protected, **Primitive Layout Components** (`Flex`, `Stack`, `Group`, `Container`, `Grid`) are entirely exempt from the `RecursicaOverStyled` gatekeeper.
+
+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 `overStyled={true}`. The internal custom token mapper (such as converting `gap="rec-md"`) is still active natively on these wrappers.
+
+## Visual Auditing & Highlights (Development Only)
+
+To make it easy to spot technical debt and design system violations, Recursica automatically tracks any component that uses the `overStyled={true}` prop.
+
+In **development builds**, you can highlight all over-styled components on the page. Open your browser's developer console and run:
+
+```js
+recursica.toggleOverStyled();
+```
+
+This toggles a **cyan 2px box shadow** outline around the children of all over-styled components. The wrapping elements use `display: contents` 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.

package/README.md

@@ -0,0 +1,70 @@
+# @recursica/adapter-mui-v7
+
+A modern React component library built with TypeScript and **MUI 7**. This package serves as the core UI kit for Recursica applications, providing reusable UI components, centralized theme configurations, and a comprehensive Storybook environment for development.
+
+## Installation
+
+```bash
+npm install @recursica/adapter-mui-v7
+# or
+yarn add @recursica/adapter-mui-v7
+# or
+pnpm add @recursica/adapter-mui-v7
+```
+
+## Peer Dependencies
+
+This library requires the following peer dependencies to be installed in your project:
+
+```bash
+npm install @mui/core@>=7.0.0 @mui/dates@>=7.0.0 @mui/hooks@>=7.0.0 react@>=16.8.0 react-dom@>=16.8.0
+```
+
+**Important**: Make sure you have these exact versions or higher installed, as the components rely on MUI 7+ features and React 16.8+ hooks.
+
+## Philosophy
+
+Please read [PHILOSOPHY.md](./docs/PHILOSOPHY.md) to understand the core principles of the adapter.
+
+## Developer & AI Guidelines
+
+This repository provides dedicated routing documents for both human developers and AI Agents to ensure strict adherence to our design system constraints. These are contributor-facing docs that live in the [recursica monorepo](https://github.com/borderux/recursica) rather than in this published package, so they're linked here as GitHub URLs rather than relative paths.
+
+- **For Human Developers:** This `README.md` acts as your primary routing document. If you are integrating this library into an application, please read [USAGE.md](./USAGE.md) (published alongside this README). If you are building or modifying components inside this library, please read [CONTRIBUTING.md](https://github.com/borderux/recursica/blob/main/packages/adapter-mui-v7/CONTRIBUTING.md).
+- **For AI Agents:** All AI Agents operating in the monorepo must start by reading [AGENT.md](https://github.com/borderux/recursica/blob/main/packages/adapter-mui-v7/AGENT.md), which serves as the primary routing document for AI workflows.
+
+## Development and Architecture
+
+This project is built using:
+
+- **Vite (Library Mode)**: For fast builds, producing optimized ES and CJS modules.
+- **MUI 7**: Base components, hooks, and native standard styling architecture.
+- **Storybook**: Used heavily for interactive component development, documentation, and prototyping.
+
+> **Note:** We relying completely on MUI's built-in CSS styling and Vite's native CSS/CSS Modules capabilities. No complex CSS-in-JS overhead!
+
+## Storybook Documentation
+
+This library includes Storybook for all components. You can:
+
+- **View live examples** of components.
+- **Test component interactions** and accessibility.
+- **Explore UI tokens** and layout utilities.
+
+### Accessing Storybook Locally
+
+If you're contributing or developing locally, clone the repository and run:
+
+```bash
+npm run storybook
+```
+
+This will spin up a local server (typically at `http://localhost:6006`) with a hot-reloading environment for component prototyping.
+
+## TypeScript Support
+
+All newly built components will include full TypeScript support with comprehensive prop types exported.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

package/SETUP.md

@@ -0,0 +1,92 @@
+# Installing `@recursica/adapter-mui-v7`
+
+Follow these instructions to install and configure the MUI Adapter in your host project.
+
+## 1. Install Dependencies
+
+First, install the Recursica MUI Adapter package:
+
+```bash
+npm install @recursica/adapter-mui-v7
+```
+
+### Peer Dependencies
+
+This library requires the following peer dependencies. Ensure they are installed in your project:
+
+```bash
+npm install @mui/material@>=7.0.0 @emotion/react@>=11.14.0 @emotion/styled@>=11.14.0 react@>=16.8.0 react-dom@>=16.8.0
+```
+
+---
+
+## 2. Setup and Integration
+
+Before consuming Recursica components, integrate the CSS and design tokens into your application:
+
+1. **Integrate CSS**: Import `recursica_variables_scoped.css` and the MUI adapter CSS `style.css` into your application entrypoint (e.g., `main.tsx` or `App.tsx`).
+
+   ```tsx
+   import "./path/to/recursica_variables_scoped.css"; // Recursica theme variables
+   import "@recursica/adapter-mui-v7/style.css"; // MUI adapter styles
+   ```
+
+2. **Configure MUI's CSS Injection & Theme Provider**: Because the Recursica UI components use native CSS modules, they must be given a higher priority than MUI's default engine styles. You **must** wrap your application root in `<StyledEngineProvider injectFirst>` and `<RecursicaThemeProvider theme="light">` to correctly cascade design token properties. By default `RecursicaThemeProvider` also wraps its children in a `<Layer layer={0}>` (via the `initLayer0` prop, which defaults to `true`), so the base page surface/border/elevation variables resolve automatically with no extra setup:
+
+   ```tsx
+   import { StyledEngineProvider } from "@mui/material/styles";
+   import { RecursicaThemeProvider } from "@recursica/adapter-mui-v7";
+
+   function App() {
+     return (
+       <StyledEngineProvider injectFirst>
+         <RecursicaThemeProvider theme="light">
+           {/* Your App Components */}
+         </RecursicaThemeProvider>
+       </StyledEngineProvider>
+     );
+   }
+   ```
+
+3. **Integrate Google Fonts**: Integrating custom fonts depends on how you load fonts in your project and which fonts are specified in your `recursica_variables_scoped.css` (since it is project-dependent). We suggest loading them via Google Fonts, as shown in this example:
+
+   ```css
+   @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
+   ```
+
+4. **Configure PostCSS Plugin (Optional but Recommended)**: It is highly recommended (but optional) to install the `@recursica/recursica-postcss-vars` plugin to verify that Recursica CSS variables are properly connected in case they change.
+
+   Install the plugin as a dev dependency:
+
+   ```bash
+   npm install @recursica/recursica-postcss-vars --save-dev
+   ```
+
+   Then, configure it in your `postcss.config.js`:
+
+   ```javascript
+   export default {
+     plugins: {
+       "@recursica/recursica-postcss-vars": {
+         cssPath: "./path/to/recursica_variables_scoped.css",
+         strict: process.env.NODE_ENV === "production",
+       },
+     },
+   };
+   ```
+
+5. **Configure ESLint Plugin (Optional but Recommended)**: It is highly recommended (but optional) to install `eslint-plugin-recursica`, which flags use of the `overStyled` escape-hatch prop so it stays easy to audit.
+
+   Install the plugin as a dev dependency:
+
+   ```bash
+   npm install eslint-plugin-recursica --save-dev
+   ```
+
+   Then, add it to your `eslint.config.js`:
+
+   ```javascript
+   import recursica from "eslint-plugin-recursica";
+
+   export default [recursica.configs.recommended];
+   ```

package/USAGE.md

@@ -0,0 +1,57 @@
+# MUI Adapter Usage Guide
+
+This guide outlines how human developers and AI agents should consume the `adapter-mui-v7` library when building applications.
+
+## 1. Setup and Integration
+
+Before consuming the components, the application must be properly integrated with Recursica design tokens. Please refer to [SETUP.md](SETUP.md) for full installation and integration instructions.
+
+> [!IMPORTANT]
+> If you are an AI agent, you must verify that all setup and integration steps described in [SETUP.md](SETUP.md) (including `<StyledEngineProvider injectFirst>` configuration) are fully followed before attempting to use or customize Recursica components in the application.
+
+## 2. Importing Components
+
+All UI components should be imported directly from the `adapter-mui-v7`.
+
+```tsx
+import { Button, Stack, Container } from "@recursica/adapter-mui-v7";
+```
+
+**Rule:** Do NOT import components directly from `@mui/material` unless a specific exception has been documented (e.g. `Alert`, which has no planned Recursica equivalent). If you need a standard component, always check the adapter first.
+
+## 3. Passing Design Tokens & Layout Constraints
+
+Our components strictly separate logical structural layouts from visual design tokens.
+
+- **DO NOT** try to inject arbitrary styling objects, generic MUI styling properties (`sx`), or custom `className` strings directly into component JSX. The components use `filterStylingProps` to actively strip these out.
+- **DO** use the defined logical layout properties (like `gap`, `margin`, `mt`, etc.).
+- When passing sizes to layout wrappers (like `Stack`, `Flex`, `Group`, `Container`), use the `rec-` prefixed sizes explicitly mapped in the library (e.g., `"rec-sm"`, `"rec-default"`, `"rec-md"`, `"rec-lg"`, `"rec-xl"`).
+
+## 4. The `overStyled` Escape Hatch
+
+If you encounter an absolute necessity to break out of the design system (e.g., a highly custom one-off hero section where a button needs an arbitrary height and custom background), you must pass `overStyled={true}`.
+
+```tsx
+<Button overStyled={true} style={{ backgroundColor: "red", height: 120 }}>
+  Custom Button
+</Button>
+```
+
+**Warning:** Using `overStyled` should be treated as technical debt. If you find yourself repeatedly needing it for a specific variant, you should instead switch context and **contribute** that variant natively into the `adapter-mui-v7`.
+
+See [OVERSTYLING.md](OVERSTYLING.md) for the full philosophy behind this escape hatch, which layout properties are permitted by default, and how to visually audit over-styled components in development builds.
+
+## 5. Fallback Behavior for Missing Components
+
+If the adapter does not yet implement a required component:
+
+1. You may try utilizing standard `recursica_variables_scoped.css` properties on the native MUI component.
+2. However, **this is not recommended**. The preferred approach is to pause integration, navigate into the `adapter-mui-v7` package, and natively build the missing wrapper component following the `CONTRIBUTING.md` guidelines.
+
+## 6. Managing CSS Changes with PostCSS Plugin
+
+When the `recursica-postcss-plugin` is incorporated into your build process, it helps maintain sync between your application and the Recursica design system.
+
+- **Missing Variables**: If Recursica CSS variables are used in the application but cannot be found in `recursica_variables_scoped.css`, the plugin will throw **warnings during development** and **errors during production builds**. This typically means that tokens in the design system have been renamed or deleted.
+- **Resolution**: When these errors occur, the developer (or AI agent) must locate the issue and reconnect the broken styling to the correct (new) CSS variables found in the updated `recursica_variables_scoped.css`. While this cannot be done automatically, the semantic naming of Recursica variables makes it relatively easy to infer intent and find the proper replacement.
+- **New Variables**: Whenever a new version of the scoped CSS is imported, you should review if any new CSS variables have been added to the design system. If so, review these new tokens and consider integrating them into the associated components where appropriate.