@recursica/mui-adapter 0.6.0 → 0.9.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,36 @@
 # @recursica/mui-adapter
 
+## 0.9.0
+
+### Minor Changes
+
+- ccf7d19: Updated to cause a new version release
+
+### Patch Changes
+
+- Updated dependencies [ccf7d19]
+  - @recursica/official-release@0.3.0
+
+## 0.8.0
+
+### Minor Changes
+
+- 4329756: Added official release and update mcp
+
+### Patch Changes
+
+- 8897f92: Updated agent instructions for MCP
+- 4329756: Initialize `@recursica/official-release` package to version and distribute design tokens, configure automatic postinstall copying logic, and integrate fallback setup checks.
+- Updated dependencies [4329756]
+- Updated dependencies [4329756]
+  - @recursica/official-release@0.2.0
+
+## 0.7.0
+
+### Minor Changes
+
+- 4031b12: Updated docs and finalized MCP
+
 ## 0.6.0
 
 ### Minor Changes

package/SETUP.md

@@ -0,0 +1,78 @@
+# 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. **Theme Files Setup**: When you install `@recursica/mui-adapter`, a postinstall script automatically creates default theme files (including `recursica_variables_scoped.css` and JSON config files) in your project root. If they are missing, simply run `npm install` to create them. To customize or update these variables, you should use [Forge Recursica](https://forge.recursica.com) to export the updated theme files into your project.
+   > [!IMPORTANT] > **AI Agent Directive**: The theme files (`recursica_variables_scoped.css` and associated JSON files) are created at the project root automatically via `npm install`. If they are not present, instruct the user to run `npm install`. Do NOT attempt to generate, mock, or write a placeholder CSS/JSON file yourself. When updates to these files are needed, instruct the user to export them from [Forge Recursica](https://forge.recursica.com) and replace the existing ones.
+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.