@recursica/mantine-adapter 0.32.0 → 0.33.0

package/src/components/Popover/USAGE.md

@@ -0,0 +1,121 @@
+# Popover - Usage Guide
+
+This document describes how to integrate and use the `Popover` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Popover } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Popover } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Popover position="bottom" withArrow>
+      <Popover.Target>
+        <Button>Open Popover</Button>
+      </Popover.Target>
+      <Popover.Dropdown>
+        <Text size="sm">This is the popover content.</Text>
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
+```
+
+---
+
+## 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 (`<Popover>`, `<Popover.Target>`, `<Popover.Dropdown>`) as a 1:1 React component mapping.
+
+**Implementation:** Mantine's Popover internally manages click detection, open/close state, Floating UI positioning, and portal rendering. By preserving the exact sub-component tree, Recursica safely inherits all of these behaviors without reimplementation.
+
+---
+
+## 2. Popover.Target Pass-Through
+
+**Decision:** `Popover.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>`). This is identical to the `Menu.Target` and `HoverCard.Target` pattern.
+
+---
+
+## 3. Token Namespace: `hover-card-popover`
+
+**Decision:** The CSS module exclusively uses variables from the `--recursica_ui-kit_components_hover-card-popover_*` namespace.
+
+**Implementation:** The Recursica token system defines a single shared namespace (`hover-card-popover`) for this component and HoverCard. It covers geometry (border-radius, border-size, padding, min/max-width), typography (content-text\_\*), elevation, and layer-aware colors (background, border-color, content).
+
+---
+
+## 4. Hardcoded Values
+
+**Decision:** Two hardcoded values exist in the component.
+
+### `border-style: solid` (CSS module)
+
+Mantine renders the dropdown using its `Paper` component, which does not set `border-style` natively. Without this hardcoded value, the border-width and border-color tokens would have no visible effect. This is the same pattern used in the Menu component's dropdown.
+
+### `arrowSize` defaulted to `16` (Popover.tsx)
+
+Mantine's `arrowSize` prop is a JavaScript number used for inline style calculations: it sets `width`, `height`, and a positioning offset (`-arrowSize/2`) directly on the arrow `<div>` element. These inline styles **cannot** be overridden via CSS without `!important`, and the positioning offset has no CSS equivalent. This means the beak size cannot be fully CSS-driven — it is one of the rare cases where a design token value must be mirrored as a JS prop.
+
+The default value `16` matches the Recursica `beak-size` token (`--recursica_ui-kit_components_hover-card-popover_properties_beak-size: 16px`). Developers can override `arrowSize` if needed, but should be aware this is a design system concern. If the token value changes, the default in `Popover.tsx` must also be updated.
+
+This is documented as an open issue in `docs/COMPONENT_ISSUES.md`.
+
+**Note:** Mantine calls this the "arrow"; Recursica calls it the "beak". The Recursica prop `withBeak` (defaulting to `true`) maps to Mantine's `withArrow`. Both `withBeak` and `withArrow` are accepted; `withBeak` takes precedence.
+
+---
+
+## 5. Minimal CSS Override Philosophy
+
+**Decision:** The CSS module only overrides visual design tokens (colors, typography, spacing, borders, shadows). All structural layout properties are deferred to Mantine's native behavior.
+
+**Implementation:** Popover is an overlay component where Mantine's native Floating UI positioning and Paper layout are already correct. We avoid setting:
+
+- `overflow` on the dropdown (Mantine handles scroll behavior natively)
+- `display`, `position`, `z-index` (Floating UI controls these)
+- `pointer-events` (Mantine manages hover detection across target and dropdown)
+
+**Rationale:** Default to Mantine's native behavior and only override what the Recursica token system explicitly needs to control.
+
+---
+
+## 6. ClassNames Merging on Root
+
+**Decision:** The root `Popover` component binds CSS module classes via `classNames` on the Mantine root.
+
+**Implementation:** The root component receives `classNames={{ dropdown: styles.dropdown, arrow: styles.arrow }}` and merges any consumer-provided `classNames` when `overStyled` is true. This ensures our token-driven styles are applied to the dropdown panel without wrapper divs, and the consumer's classes are additive.
+
+---
+
+## 7. Default Position Override
+
+**Decision:** Recursica defaults `position` to `"top"`. Mantine defaults to `"bottom"`.
+
+**Implementation:** The `position="top"` default is set on the Mantine root element before the prop spread, so developer-provided `position` values still take precedence. This aligns with Recursica's design intent for overlay components to appear above their trigger by default.

package/src/components/Radio/USAGE.md

@@ -0,0 +1,36 @@
+# Radio - Usage Guide
+
+This document describes how to integrate and use the `Radio` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Radio } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Radio } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Radio label="Option 1" name="radio-group" value="1" defaultChecked />;
+}
+```
+
+---
+
+## 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.

package/src/components/ReadOnlyField/USAGE.md

@@ -0,0 +1,52 @@
+# ReadOnlyField - Usage Guide
+
+This document describes how to integrate and use the `ReadOnlyField` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { ReadOnlyField } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { ReadOnlyField } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <ReadOnlyField label="API Key" value="sk_test_123456789" copyable />;
+}
+```
+
+---
+
+## 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. Stripping Mantine Assumptions
+
+Unlike standard input variables, standard HTML output `<p>` tags inherently carry margin and spacing assumptions from core browser stylesheets. To correctly map `ReadOnlyTextField` elements gracefully inside the generic `FormControlWrapper` bounded context, we hardcode resets:
+
+- `margin: 0` explicitly strips block flow gap so `FormControlWrapper` handles vertical rhythm.
+- `min-height`: Native `Input` boxes typically have baseline padding borders. We map directly to `var(--recursica_ui-kit_components_read-only-field_properties_min-height)` to ensure a side-by-side editable `TextField` and `ReadOnlyField` perfectly share roughly identical visual heights.
+
+## 2. Unidirectional Editable Mode
+
+The main wrapper intercepts `readOnly` boolean blocks, maintaining its own `isReadOnly` state. Natively, if a user clicks an exposed 'Edit' action (like our legacy SVG or custom `labelActionArea`), the context permanently switches to active.
+There is intentionally no built-in reverse toggle inside typical field bindings (like input "Blur") to revert state. Parents must pass external controls to `readOnly` forcing the internal hooks to reset via standard `useEffect` propagation.

package/src/components/SegmentedControl/USAGE.md

@@ -0,0 +1,56 @@
+# SegmentedControl - Usage Guide
+
+This document describes how to integrate and use the `SegmentedControl` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { SegmentedControl } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { SegmentedControl } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <SegmentedControl data={["Preview", "Code", "Edit"]} />;
+}
+```
+
+---
+
+## 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. Stripping Mantine's Native Variants and Sizes
+
+The Figma design tokens for the SegmentedControl component do not define nested layers of variants (such as `solid`, `outline`) or specific sizing steps (`xs`, `sm`, etc.). They are defined globally. Therefore, we explicitly `Omit` the standard `variant`, `size`, `radius`, and `color` props from the generic Mantine `SegmentedControlProps` interface.
+
+## 2. Hardcoded Overrides for Figma Strictness
+
+Mantine injects inline hover styles on `.label` (specifically, adding a subtle gray background when hovering). Since Recursica defines explicit transparent or specifically-driven hover states, we use `!important` tags within `SegmentedControl.module.css` for background and typography overriding.
+
+## 3. Divider Separators
+
+Mantine uses an `::before` pseudo-element on the `.control` block to draw standard visual separators between adjacent elements. Instead of stripping this functionality out, we hook directly into the pseudo-element and override its `background-color` with `--recursica_ui-kit_components_segmented-control_properties_colors_divider-color`.
+
+## 4. Indicator Mapping
+
+The moving active background element (`.indicator`) is decoupled from the actual text label. It is styled natively with its own background color, border size, and elevation shadow variables to match the exact visual parity of a "floating active chip" as defined in the Recursica properties map.

package/src/components/Slider/USAGE.md

@@ -0,0 +1,86 @@
+# Slider - Usage Guide
+
+This document describes how to integrate and use the `Slider` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Slider } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Slider } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Slider defaultValue={50} min={0} max={100} label="Volume" />;
+}
+```
+
+---
+
+## 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. Bidirectional State Synchronization
+
+**Decision:** Maintain a highly responsive, bidirectional connection between the sliding track value and the adjacent numeric text input.
+**Implementation:**
+
+- The slider track requires a clean `number` state, whereas the text box requires a `string` state (`inputValue`) to allow typing intermediate characters like decimals (`2.`), negative signs (`-`), or empty text without breaking standard React input binding.
+- A `useEffect` hook continuously feeds the outer numeric state changes back into the text input value as a string representation.
+- Input changes instantly parsed as float clamp bounds securely. On blur (`onBlur`), the input state is automatically sanitized and reset to the clean, clamped string representation of the final track value.
+
+## 2. Outer Form Control Wrapper Integration
+
+**Decision:** Bypass Mantine's native `Input.Wrapper` and `label` properties.
+**Implementation:**
+
+- Universal form wrappers like `<FormControlWrapper>` and `<WithReadOnlyWrapper>` handle the outer layout architecture, including labels, assistive text, error states, and optional edit-triggering fields.
+- Therefore, we map the outer form label directly to the `label` property of the `Slider` (delegated to the wrapper), and rename Mantine's internal dragging tooltip label property to `tooltipLabel`.
+
+## 3. Custom Min-Max Labels and Step Indicators
+
+**Decision:** Enforce rigid typography tokens on lower bounds and custom mark indicators.
+**Implementation:**
+
+- Mantine's native mark and step structures are fully styles-mapped back to our scoped variables in `Slider.module.css`.
+- Min and Max numeric guides are rendered directly to the left and right of the slider track, centered vertically and spaced automatically using standard input gaps, while dynamically fetching custom typography tokens for min-max labels to avoid hardcoded formatting constraints.
+
+## 4. Visual Overrides for Stacked and Side-by-Side Spacing
+
+**Decision:** Enforce layout margins dynamically based on container orientation parameters.
+**Implementation:**
+
+- Using custom layouts (e.g. `stacked` and `side-by-side`), we override the margins by assigning the component-specific Figma spacing variables to the unified `--form-control-margin-bottom` property.
+
+## 5. Right-Aligned Floating Current Value
+
+**Decision:** Position the current active value of the slider directly above the max guide (or right-side element) on the right side of the track.
+**Implementation:**
+
+- Wrap the max guide element in a relative layout container (`.rightGuideContainer`) to provide a positioning anchor.
+- Place the active value element (`.currentValue`) inside `.rightGuideContainer` and position it absolutely (`bottom: calc(100% + var(--recursica_ui-kit_globals_form_properties_label-field-gap-vertical, 8px))`, `right: 0`).
+- This absolute positioning strategy guarantees that the active value floats cleanly above the track's right side, while aligning it vertically on the Y-axis to sit in perfect baseline alignment with the component's left-aligned form label.
+- Set typography using the Figma-aligned component-specific read-only value variables (`--recursica_ui-kit_components_slider_properties_read-only-value_...`).
+- Allow the text color of both the floating current value (`.currentValue`) and the component's read-only value (`.readOnlyValue`) to naturally inherit from their parent states/form globals, automatically supporting default (`--form-field-text-valued`), disabled (`--form-field-disabled-text`), and error colors without explicit color overrides, matching the min/max guides.
+- If `showInput` is enabled, the floating `.currentValue` is hidden since the active value is already displayed and editable within the adjacent numeric text input, avoiding visual redundancy.
+- In `side-by-side` form layouts, the `.currentValue` is positioned inline (static positioning) to the right of the max label rather than floating above it, centered vertically with the max label and aligned right to the container. This uses CSS flexbox ordering (`order: 2` for `.currentValue` and `order: 1` for `.minMaxGuide`) to visually swap their positions while preserving clean, semantic DOM ordering.
+- To ensure perfect, pixel-perfect vertical track alignment between sliders that show numeric text inputs (`showInput={true}`) and sliders that display the active inline value (`showInput={false}`), the `.currentValue` element is globally given a width equal to the input width (`var(--recursica_ui-kit_components_slider_properties_input-width)`) and right-aligned (`text-align: right`). In `side-by-side` layouts, `.rightGuideContainer`'s flex gap is also matched to the horizontal input-to-track gap (`var(--recursica_ui-kit_components_slider_properties_input-gap)`), making the horizontal space occupied by the rightmost elements exactly identical in both component modes.

package/src/components/Stack/USAGE.md

@@ -0,0 +1,48 @@
+# Stack - Usage Guide
+
+This document describes how to integrate and use the `Stack` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Stack } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Stack } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Stack gap="md" align="stretch">
+      <Text>Item 1</Text>
+      <Text>Item 2</Text>
+    </Stack>
+  );
+}
+```
+
+---
+
+## 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
+
+The `Stack` component is a generic flex layout wrapper mapped directly to Mantine's `Stack`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.

package/src/components/Stepper/USAGE.md

@@ -0,0 +1,41 @@
+# Stepper - Usage Guide
+
+This document describes how to integrate and use the `Stepper` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Stepper } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Stepper } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Stepper active={1}>
+      <Stepper.Step label="First step" description="Create account" />
+      <Stepper.Step label="Second step" description="Verify email" />
+    </Stepper>
+  );
+}
+```
+
+---
+
+## 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.

package/src/components/Switch/USAGE.md

@@ -0,0 +1,65 @@
+# Switch - Usage Guide
+
+This document describes how to integrate and use the `Switch` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Switch } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Switch } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return <Switch label="Enable notifications" defaultChecked />;
+}
+```
+
+---
+
+## 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. Stripping Mantine's Size Engine
+
+Mantine uses properties like `size`, `color`, and `radius` to dynamically map CSS layout values across its `.track` and `.thumb` nodes. We proactively strip and delete these properties using `filterStylingProps` to entirely neutralize this native behavior.
+
+## 2. Hardcoded Values & Transitions
+
+Mantine injects dynamic width/height attributes into its switch through inline CSS variables (e.g. `--switch-height`). To strictly enforce the UI Kit tokens without breaking Mantine's internal math, our `Switch.module.css` structurally remaps Mantine's internal variables explicitly:
+
+```css
+--switch-width: var(--switch-track-width);
+--switch-height: calc(
+  var(--switch-thumb-height) + (var(--switch-track-padding) * 2)
+);
+```
+
+We also hardcode `border: none` since the UI kit designs rely purely on box-shadow elevations and background color tracking. Mantine’s default border logic is entirely disabled.
+
+## 3. ReadOnly Behavior
+
+Similar to `Checkbox`, the `Switch` component handles `readOnly` presentation by dropping the entire underlying node tree and falling back structurally onto `<FormControlWrapper>` when `readOnly: true`. This strictly preserves exact baseline alignment across all primitives without trying to hack disabled CSS to look like read-only text.
+
+## 4. Hover State Reset
+
+Mantine forcefully triggers track hover color states globally. Since Recursica currently does not map specific hover states to switch backgrounds across themes (falling back to standard unselected tokens or simply providing a cursor), we structurally wipe out Mantine's `.track:hover` class block inside `Switch.module.css`.

package/src/components/Table/USAGE.md

@@ -0,0 +1,51 @@
+# Table - Usage Guide
+
+This document describes how to integrate and use the `Table` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Table } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from 'react';
+import { Table } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Table>
+      <Table.Thead>
+        <Table.Tr>
+          <Table.Th>Name</Table.Th>
+          <Table.Th>Email</Table.Tr>
+        </Table.Tr>
+      </Table.Thead>
+      <Table.Tbody>
+        <Table.Tr>
+          <Table.Td>Jane Doe</Table.Tr>
+          <Table.Td>jane@example.com</Table.Tr>
+        </Table.Tr>
+      </Table.Tbody>
+    </Table>
+  );
+}
+```
+
+---
+
+## 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.

package/src/components/Tabs/USAGE.md

@@ -0,0 +1,45 @@
+# Tabs - Usage Guide
+
+This document describes how to integrate and use the `Tabs` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Tabs } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Tabs } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Tabs defaultValue="home">
+      <Tabs.List>
+        <Tabs.Tab value="home">Home</Tabs.Tab>
+        <Tabs.Tab value="profile">Profile</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="home">Home content</Tabs.Panel>
+      <Tabs.Panel value="profile">Profile content</Tabs.Panel>
+    </Tabs>
+  );
+}
+```
+
+---
+
+## 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.

package/src/components/Text/USAGE.md

@@ -0,0 +1,40 @@
+# Text - Usage Guide
+
+This document describes how to integrate and use the `Text` component in your projects using `@recursica/mantine-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Text } from "@recursica/mantine-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Text } from "@recursica/mantine-adapter";
+
+export default function Demo() {
+  return (
+    <Text size="md" color="dimmed">
+      This is some styled body text.
+    </Text>
+  );
+}
+```
+
+---
+
+## 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.