@recursica/mui-adapter 0.6.0 → 0.7.0

package/ARCHITECTURE.md

@@ -0,0 +1,15 @@
+# Architecture
+
+## Overview
+
+This document describes the high-level architecture and philosophy of the `@recursica/mui-adapter` package.
+
+## Dependencies
+
+- **`@mui/material`**: The underlying UI framework.
+- **`@recursica/adapter-common`**: Shared primitives and hooks across all framework adapters.
+
+## Key Design Decisions
+
+- Components map closely to Material UI's structure but enforce Recursica design tokens.
+- We avoid over-styling; components only diverge from MUI defaults when dictated by the Recursica design system.

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @recursica/mui-adapter
 
+## 0.7.0
+
+### Minor Changes
+
+- 4031b12: Updated docs and finalized MCP
+
 ## 0.6.0
 
 ### Minor Changes

package/SETUP.md

@@ -0,0 +1,77 @@
+# Installing `@recursica/mui-adapter`
+
+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/mui-adapter
+```
+
+### 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. **Export Theme Files**: Export theme files from [Forge Recursica](https://forge.recursica.com) into your repository to generate `recursica_variables_scoped.css` and its associated JSON files. Its suggested to put it in the root of your project.
+2. **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/mui-adapter/style.css"; // MUI adapter styles
+   ```
+
+3. **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:
+
+   ```tsx
+   import { StyledEngineProvider } from "@mui/material/styles";
+   import { RecursicaThemeProvider } from "@recursica/mui-adapter";
+
+   function App() {
+     return (
+       <StyledEngineProvider injectFirst>
+         <RecursicaThemeProvider theme="light">
+           {/* Your App Components */}
+         </RecursicaThemeProvider>
+       </StyledEngineProvider>
+     );
+   }
+   ```
+
+4. **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");
+   ```
+
+5. **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",
+       },
+     },
+   };
+   ```

package/USAGE.md

@@ -0,0 +1,55 @@
+# MUI Adapter Usage Guide
+
+This guide outlines how human developers and AI agents should consume the `mui-adapter` 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 `mui-adapter`.
+
+```tsx
+import { Button, Stack, Container } from "@recursica/mui-adapter";
+```
+
+**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 `mui-adapter`.
+
+## 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 `mui-adapter` 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.