@recursica/mantine-adapter 0.32.0 → 0.33.0

package/src/components/Label/USAGE.md

@@ -0,0 +1,87 @@
+# Label - Usage Guide
+
+This document describes how to integrate and use the `Label` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Label } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Label } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Label required>Field Label</Label>;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Architecture Overview
+
+The `Label` component is fundamentally built as a strict, localized wrapper around Mantine's native `Input.Label`. The core goal is to preserve context, ref-forwarding, and native accessibility links, while completely overriding visual behaviors via Recursica design variables in scoped CSS.
+
+## Key Design Decisions
+
+### **Layout Architecture**
+
+- Because Recursica dictates complex alignments between primary label text, asterisks, edit icons, and optional strings, Mantine's rigid form label flow could not be used out-of-the-box.
+- Implemented `display: flex; flex-wrap: wrap;` directly on `.root`.
+- Injected strict integer-based flex `order` properties (e.g. `order: 1` for text, `order: 2` for `required`, `order: 5` for `optionalText`) to physically decouple DOM rendering from markup flow.
+- Because `optionalText` often acts as secondary contextual detail, it forces `flex-basis: 100%`, securely wrapping to a secondary line underneath the primary label properties and transforming the horizontal gap spacing seamlessly into a `margin-top` vector.
+
+### **Optional Text & Required Mutually Exclusive Parsing**
+
+- By design standards, a component cannot logically be both "Required" and mapped as "Optional".
+- To bulletproof implementations natively, the adapter forcibly suppresses rendering of the `resolvedOptionalText` strings if the parent wrapper invokes `required={true}`.
+- `optionalText` can operate as dynamic data or specifically as a boolean `true`, which forces the adapter to natively render the formal `(Optional)` string map.
+
+### **The "Edit Icon" Replacer Logic**
+
+- Passing `withEditIcon={true}` evaluates it as fundamentally mutually exclusive to the standard required indicator asterisk.
+- `required={required && !withEditIcon}` is passed to the underlying Mantine structure so the native `*` is entirely suppressed.
+- Added localized styling via `data-replaces-asterisk={required ? "true" : undefined}` onto the `.editIconWrapper` element. If an editable instance is simultaneously designated as required, the edit icon functionally assumes the indicator role natively, overriding its default icon metrics explicitly to match `--recursica_ui-kit_components_label_properties_colors_asterisk`.
+
+### **Bypassing `Input.Wrapper` Integrations**
+
+- By decoupling from Mantine's standard `Input.Wrapper`, the `Label` component is exclusively mapped manually through `FormControlWrapper`. This grants us exact visual sync regarding where the label renders based on `formLayout="stacked"` or `formLayout="side-by-side"`, without fighting internal Mantine positional hooks that assume vertical stacking by default.
+
+### **Label Size Container Constraints**
+
+- The `labelSize` parameter (mapping values like `"small"`) internally **does not scale typographic font metrics**. Instead, it dynamically defines the explicit horizontal bounding width limit of the block container itself.
+- **Architectural Rule:** `labelSize` modifications are strictly designed to execute exclusively when `formLayout="side-by-side"` is active. It acts as an optical grid threshold ensuring left-aligned string wrappers constrain correctly uniformly down a column without bleeding into the physical input arrays alongside them.
+
+## Outstanding Technical Debt / Issues
+
+### **Description Property Omission**
+
+- **Issue:** Currently, the adapter `Label` does not natively parse or support a structured `description` node directly attached beneath it.
+- **Context:** Standard forms often attach subtext beneath inputs, but mapping a description purely within the `<Label>` (distinct from an overall form-control description) is omitted structurally until subsequent UI Kit requirements mandate dedicated `description` styles locally on the label component itself.
+
+### **Global Interactive Hover Mappings**
+
+- **Issue:** Currently, the `editIconWrapper` lacks a dedicated hover background layer.
+- **Context:** While the global theme abstracts interactive hover environments deeply using layered variable syntax (e.g., `--recursica_brand_layer_1_elements_interactive_hover-color`), Recursica's token generation framework natively fails to expose a universally generic placeholder token (e.g., `--recursica_elements_interactive_hover-color`) which downstream wrappers can map their `<Layer>` injections directly into safely.
+- **Resolution Path:** We are explicitly ignoring the `.editIconWrapper:hover` background color assignment until the raw Figma token exports directly scaffold a generic token placeholder that we can interface cleanly with across arbitrary `<Layer>` contexts, avoiding manually mapping statically hardcoded depths (`layer-0`, `layer-1`).

package/src/components/Link/USAGE.md

@@ -0,0 +1,69 @@
+# Link - Usage Guide
+
+This document describes how to integrate and use the `Link` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Link } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Link } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Link href="/dashboard" variant="inline">
+      Go to Dashboard
+    </Link>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Missing States in Design Tokens
+
+Currently, the design tokens (`recursica_variables_scoped.css`) only provide states for:
+
+- `default`
+- `hover`
+- `visited`
+- `visited-hover`
+
+There are no tokens for the `active` or `focus` states. If these are needed, they must be added to the Figma variables and exported via the token pipeline. The component relies on the browser's default focus outline for accessibility unless overriden by a global reset.
+
+## Overriding Mantine's underline Prop
+
+Mantine's `Anchor` component uses `underline="hover"` by default. Because our design system specifies exact `text-decoration` styles via CSS tokens, we explicitly pass `underline="never"` to the underlying Mantine component. This prevents Mantine from injecting its own text-decoration inline or via generic classnames, ensuring our scoped CSS remains the single source of truth.
+
+## Base Layout
+
+Mantine's `Anchor` renders an inline element by default and does not natively support `leftSection` like the `Button` component. To support an optional `icon` alongside the text, we enforce a baseline layout of `display: inline-flex` and `align-items: center` in `Link.module.css`.
+
+When an icon is present, the component conditionally passes a `data-has-icon` attribute to the root element. The CSS module uses this attribute to apply the `icon-text-gap` token via the CSS `gap` property.
+
+## Inner Wrappers
+
+The icon and children are wrapped in internal `<span>` tags (`.iconWrapper` and `.labelText` respectively). This follows the component development guide for structural robustness, allowing us to enforce specific sizing on the icon and intrinsic text truncation behavior if the link is placed in a bounded container.

package/src/components/Loader/USAGE.md

@@ -0,0 +1,63 @@
+# Loader - Usage Guide
+
+This document describes how to integrate and use the `Loader` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Loader } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Loader } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Loader size="md" />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Architecture & Integration
+
+The `Loader` component acts as a strictly tokenized wrapper bridging the Recursica UI-Kit `loader` variables to the generic Mantine `@mantine/core` `Loader` primitive.
+
+### Key Decisions:
+
+- **Variant Mapping:** Recursica's `variant` directly proxies to Mantine's `type` prop for `"oval" | "bars" | "dots"`.
+- **Property Overrides Disabled:** Natively overriding specific structural variants directly on the JSX interface like `thickness` and `borderRadius` has been intentionally omitted. Component rendering relies entirely on variables exposed by the underlying UI Kit mappings tied to the size prop.
+
+### Token Mapping:
+
+Sizes are bound through `data-size` attributes (`sm`, `md`, `lg` parsing to target `<div data-size="small">`, etc.).
+
+Mantine natively sets sizing dynamically at the component root and parses thickness/variants differently natively (e.g., `oval` styles its geometry strictly via CSS `border`, while `bars` and `dots` utilize specific DOM inner spans `span.dot` / `span.bar`).
+
+#### Specific CSS Targeting Hacks Used
+
+- `border-width` and `border-radius` structurally style the `thickness` and `border-radius` configuration of the `oval` variant on the `::after` pseudo-element by resolving `--recursica_ui-kit_components_loader_variants_sizes_..._properties_thickness` and `_border-radius`.
+
+### Unsupported Properties
+
+- **xs and xl Sizing:** These sizes are explicitly unsupported in the Recursica standard logic (as surfaced in `filterStylingProps` and UI Kit mappings). Attempting to use them will safely default back or fallthrough statically unless defined later. See `COMPONENT_ISSUES.md`.

package/src/components/Menu/USAGE.md

@@ -0,0 +1,124 @@
+# Menu - Usage Guide
+
+This document describes how to integrate and use the `Menu` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Menu } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Menu } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Menu>
+      <Menu.Target>
+        <Button>Toggle Menu</Button>
+      </Menu.Target>
+      <Menu.Dropdown>
+        <Menu.Item>Profile</Menu.Item>
+        <Menu.Item>Settings</Menu.Item>
+        <Menu.Item color="red">Logout</Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## 1. Composable API Preservation (1:1 Mapping)
+
+**Decision:** We maintain the exact library composition API structure (`<Menu>`, `<Menu.Target>`, `<Menu.Dropdown>`, `<Menu.Item>`, `<Menu.Divider>`, `<Menu.Label>`, `<Menu.Sub>`, `<Menu.Sub.Target>`, `<Menu.Sub.Item>`, `<Menu.Sub.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's Menu internally manages WAI-ARIA role assignments (`role="menu"`, `role="menuitem"`, `aria-haspopup`, `aria-expanded`, `aria-controls`), keyboard navigation (arrow keys, Enter, Escape), and focus trapping natively across its composable hierarchy. By preserving the exact sub-component tree, Recursica safely adopts all of these accessibility behaviors without reimplementation.
+
+---
+
+## 2. Hover State Overlay Technique
+
+**Decision:** We nullify Mantine's native hover background on `Menu.Item` and exclusively utilize Recursica's hover structure via a `::after` pseudo-element overlay.
+
+**Implementation:** The `.item::after` pseudo-object dynamically pulls `hover-color` & `hover-opacity` bindings from the Recursica token system. Mantine natively changes `background-color` on item hover which would override our token-driven colors. We enforce `background-color` to remain the unselected-item background on hover, then layer our pseudo-overlay on top. This is the same technique used in the Accordion component.
+
+---
+
+## 3. Selected vs Unselected Item States
+
+**Decision:** Menu items map to Recursica's `selected-item` and `unselected-item` color token groups.
+
+**Implementation:** The CSS module defaults all items to `unselected-item_*` tokens (background, text, opacity). Items with `[data-selected]` switch to `selected-item_*` tokens. This mapping is natively driven by Mantine's internal state tracking without React state hooks.
+
+---
+
+## 4. `color` Prop Stripping
+
+**Decision:** Mantine's `color` prop on `Menu.Item` (used for semantics like "danger/red") is explicitly stripped in strict mode.
+
+**Implementation:** The `color` prop is deleted from the sanitized props when `overStyled` is `false`. This enforces strict design token adherence — all item colors come from the CSS module referencing Recursica variables. Developers requiring custom color semantics must either:
+
+1. Use `overStyled={true}` as an explicit escape hatch
+2. Contribute a proper Recursica variant to the token system
+
+**Rationale:** The Recursica token set does not currently include danger-specific or semantic-color variants for menu items. Allowing arbitrary `color` values would break design system consistency.
+
+---
+
+## 5. Menu.Target Pass-Through
+
+**Decision:** `Menu.Target` is a transparent pass-through with no styling applied.
+
+**Implementation:** The target wrapper exists solely to manage Mantine's ref forwarding and event binding for the trigger element. No `filterStylingProps` or CSS module classes are applied — the trigger's appearance is entirely controlled by whatever component the integrator places inside it (e.g., `<Button>`).
+
+---
+
+## 6. Sub-Menu Support
+
+**Decision:** We wrap the full Mantine sub-menu hierarchy (`Menu.Sub`, `Menu.Sub.Target`, `Menu.Sub.Item`, `Menu.Sub.Dropdown`).
+
+**Implementation:** Sub-menu components inherit the same CSS module classes as their top-level counterparts since the Recursica token set does not distinguish sub-menu-specific styling. `Menu.Sub.Item` also strips the `color` prop in strict mode, consistent with `Menu.Item`. The sub-menu dropdown portal inherits the same `classNames` from the root Menu's `classNames` mapping.
+
+---
+
+## 7. Dropdown Container Padding
+
+**Decision:** The dropdown container uses `divider-item-gap` as its internal padding.
+
+**Implementation:** This ensures consistent spacing between the dropdown border and its content items. The gap token (`4px` by default) creates a subtle inset that visually separates items from the container edge, matching the Figma design specifications.
+
+---
+
+## 8. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties (flex, cursor, pointer-events, box-sizing, etc.) are deferred to Mantine's native behavior.
+
+**Implementation:** Unlike form-field components (e.g., Dropdown/TextField) which require deep structural overrides to strip Mantine's macro wrappers, the Menu is an overlay component where Mantine's native layout is already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine renders sub-menu dropdowns inside the parent DOM tree using Floating UI absolute positioning — setting overflow clips them)
+- `display`, `align-items`, `width`, `cursor` on items (Mantine's button-based items already handle this)
+- `pointer-events` on disabled items (Mantine handles disabled natively)
+
+**Rationale:** Early iterations included aggressive structural resets (like `overflow: hidden`, `box-sizing: border-box`, `margin: 0`) cargo-culted from the Dropdown component. These caused sub-menus to render clipped inside the parent dropdown with scrollbars. The lesson: default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.

package/src/components/Modal/USAGE.md

@@ -0,0 +1,58 @@
+# Modal - Usage Guide
+
+This document describes how to integrate and use the `Modal` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Modal } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Modal } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Modal opened={isOpen} onClose={close} title="Modal Title">
+      <Text>This is a styled Modal wrapping the native primitive.</Text>
+    </Modal>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Architecture
+
+The `Modal` component strictly wraps Mantine's `<Modal>` primitive. We strip Mantine's abstract native styling props (`size`, `radius`, `shadow`) via the `overStyled` interface and strictly inject CSS variable definitions onto the internal node abstractions (`.content`, `.header`, `.body`, `.title`).
+
+## Limitations & Structural Decisions
+
+### 1. Stripped `size` Prop
+
+Mantine natively exposes an abstract `size` prop (`"sm" | "md" | "lg" | "xl"`) that scales the Modal geometry. The Recursica UI Kit explicitly dictates strict geometric bounding boxes: `max-width: 960px` and `min-width: 304px`. To enforce absolute parity with the design system, the `size` prop has been intentionally omitted from the component's interface. The width of the Modal will scale fluidly strictly between these Figma-driven pixel limits.
+
+### 2. Scroll Dividers behavior
+
+Mantine internally handles scroll state natively, dynamically showing/hiding a divider line when content overflows in `.body`. This logic is tightly coupled to React DOM measurements internally. Our component inherits this dynamic behavior rather than statically rendering a permanent divider, matching Mantine's robust overflow UX. However, we aggressively override the generated `border-bottom` via CSS modules to ensure that when it _does_ appear, it correctly utilizes the `--recursica_ui-kit_components_modal_colors_scroll-divider` variable and `--recursica_ui-kit_components_modal_properties_scroll-divider-thickness` token.

package/src/components/NumberInput/USAGE.md

@@ -0,0 +1,55 @@
+# NumberInput - Usage Guide
+
+This document describes how to integrate and use the `NumberInput` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { NumberInput } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { NumberInput } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <NumberInput label="Quantity" min={1} max={10} defaultValue={1} />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## 1. Native Macro Wrapper Bypass
+
+**Decision:** The `<NumberInput>` component explicitly bypasses Mantine's native `Input.Wrapper` DOM injections.
+**Implementation:** We pass `label={undefined}`, `description={undefined}`, and `error={undefined}` directly into the primitive `<MantineNumberInput>`. All visual form control geometry is delegated exclusively to our unified `<FormControlWrapper>`, ensuring 100% token adherence for label spacing and assistive text styling without duplicate DOM rendering.
+
+## 2. Right Section & Controls Override
+
+**Decision:** Passing a `rightSection` element will natively remove the increment/decrement arrow controls.
+**Implementation:** Mantine inherently renders its stepper controls inside the `rightSection` DOM slot. Providing a custom right-aligned icon or text element intentionally overwrites this slot. If a layout strictly requires both a custom right-aligned element and the stepper controls simultaneously, the integrator must manually rebuild the arrows using Mantine's `handlersRef` within a custom right-section wrapper.
+
+## 3. Controls Styling
+
+**Decision:** The increment/decrement control arrows rely partially on native Mantine CSS inheritance.
+**Implementation:** The current Recursica design system tokens do not provide explicit UI styling parameters (`background`, `border`, `hover` states) for the inner number-input arrows. We have explicitly removed Mantine's default borders to cleanly nest them inside the unified input box, and mapped the icon colors to the generic `trailing-icon` token variable, but further visual configurations currently fall back to Mantine defaults.

package/src/components/Pagination/USAGE.md

@@ -0,0 +1,55 @@
+# Pagination - Usage Guide
+
+This document describes how to integrate and use the `Pagination` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Pagination } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Pagination } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Pagination total={10} value={activePage} onChange={setPage} />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## Architecture Decision: CSS Inheritance vs. Composition
+
+The Figma design tokens for the `Pagination` component dictate that pagination pages perfectly mimic `Button` variants (e.g. `active-pages_style: "solid"`, `inactive-pages_style: "outline"`, `navigation-controls_style: "text"`).
+
+As of the `1.2.0` scoped CSS update, the Figma exporter automatically handles these variants. It flattens and aliases the referenced Button properties directly into the `Pagination` component's variable namespace.
+
+We opted to use Mantine's native `PaginationControl` components to ensure all DOM structure, focus management, and accessibility attributes are preserved natively without us needing to carefully rebuild `Pagination.Items` mappings.
+
+To honor the Figma design intents while using Mantine's raw `<button>` elements:
+
+1. We inherit and map all natively scoped `Pagination` variant styles (small typography, outline/solid/text colors, and hover overlays) directly into `.control` and `.control[data-active]` within `Pagination.module.css`. We do not need to manually reference `Button` variables cross-component.
+2. We inject `data-variant="text"` via `getControlProps` onto the navigation buttons so that they inherit the explicitly aliased text style variables (`navigation-controls`) defined by the UI Kit for pagination.
+
+This achieves exact optical alignment with the tokens while maintaining Mantine's robust internal event handling for pagination.

package/src/components/Panel/USAGE.md

@@ -0,0 +1,145 @@
+# Panel - Usage Guide
+
+This document describes how to integrate and use the `Panel` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Panel } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Panel } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Panel>
+      <Text>This is a clean, structured visual container.</Text>
+    </Panel>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mantine-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+## 1. Mapping to Mantine Drawer
+
+**Decision:** Panel maps to Mantine's `Drawer` component, not `Paper` or `Card`.
+
+**Implementation:** Per the Recursica design system specification, "Panels slide in or expand from the edge of the screen to reveal additional content or functionality." This is the exact behavior of Mantine's `Drawer` component, which provides:
+
+- Slide-in animation from any screen edge
+- Overlay/backdrop
+- Portal rendering
+- Focus trapping
+- Scroll locking
+- Close button and title in header
+
+Paper and Card are static containers; Drawer is an overlay that matches Panel's defined behavior.
+
+---
+
+## 2. Token Namespace: `panel`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_panel_*` namespace.
+
+**Implementation:** The Recursica token system defines the `panel` namespace covering:
+
+- Geometry: border-radius, border-size, min-width (200px), max-width (960px)
+- Content padding: content-horizontal-padding (xl), content-vertical-padding (lg)
+- Header/Footer padding: header-footer-horizontal-padding (xl), header-footer-vertical-padding (md)
+- Spacing: header-close-gap (md), footer-button-gap (md)
+- Divider: divider-size (1px), divider-color
+- Elevation: elevation-3
+- Colors (layer-aware): background, border-color, content, divider-color, header-footer-background, title
+- Non-CSS: header-style ("h3") — see §7
+
+No tokens from other component namespaces are referenced.
+
+---
+
+## 3. ClassNames Mapping to Drawer
+
+**Decision:** Panel maps CSS module classes to Mantine Drawer's stylesNames.
+
+**Implementation:** The Drawer stylesNames used are:
+
+- `content` — Outer container (background, border, elevation)
+- `header` — Title bar with close button (padding, divider, gap)
+- `title` — Title text color
+- `body` — Scrollable content area (padding)
+
+Other stylesNames (`overlay`, `root`, `inner`, `close`) are left to Mantine defaults.
+
+---
+
+## 4. Default Placement Override
+
+**Decision:** Use `placement` instead of `position` for configuring slide-out direction, and default it to `"right"`.
+
+**Implementation:** The prop was renamed from `position` to `placement` to prevent collision with the CSS `position` keyword, which is strictly blocked by the styling gatekeeper (`BLOCKED_STYLING_KEYS`). This allows configuring the drawer direction natively while maintaining strict design-system boundaries. The `placement="right"` default is mapped internally to Mantine Drawer's `position` prop before any other sanitized props are applied. Right-side panels are the most common pattern for supplementary content, settings, and detail views.
+
+---
+
+## 5. Custom Panel.Footer
+
+**Decision:** A custom `Panel.Footer` sub-component is provided. Mantine's Drawer does not have a native footer.
+
+**Implementation:** `Panel.Footer` is a `<div>` with inline styles referencing Recursica CSS variables for:
+
+- `header-footer-background` and `header-footer-padding` tokens
+- Top divider using `divider-size` and `divider-color`
+- `footer-button-gap` for action button spacing
+- `margin-top: auto` to push the footer to the bottom
+
+Inline styles are used instead of a CSS module class because the footer is rendered inside the Drawer's `<body>` element, and the CSS variables are applied to the body's parent container. The inline styles ensure the footer correctly references the panel tokens regardless of DOM position.
+
+---
+
+## 6. Hardcoded Values
+
+### `border-style: solid` (CSS module, `.content`)
+
+Mantine's Drawer content does not set `border-style` natively. Without this, the border-width and border-color tokens have no visible effect. Same pattern as Card, Menu, HoverCard, Tooltip.
+
+---
+
+## 7. `header-style` Typography Utility Class
+
+**Decision:** The `header-style` token exports as the string `"h3"`, so we use the generated global utility class `.recursica_brand_typography_h3`.
+
+**Implementation:** The PostCSS compiler generates `.recursica_brand_typography_<typeName>` classes at the bottom of the scoped variables file to apply full typography definitions without assigning variables inline. We apply this to the `.title` class via `composes: recursica_brand_typography_h3 from global;`.
+
+---
+
+## 8. Panel Types: Standard vs Scrollable
+
+**Decision:** Both standard and scrollable types are supported natively.
+
+**Implementation:** Per the Recursica specification:
+
+- **Standard** — All content visible without scrolling. The default behavior when content fits.
+- **Scrollable** — Internal scrollbar enabled when content exceeds the panel height. Header and footer CTAs remain pinned.
+
+Mantine's Drawer handles this automatically — the `body` section scrolls when content overflows, while the `header` remains fixed. The `Panel.Footer` uses `margin-top: auto` to stay at the bottom.