@recursica/mantine-adapter 0.36.0 → 0.38.0

package/dist/src/components/Dropdown/BareDropdown.d.ts

@@ -0,0 +1,19 @@
+import { SelectProps as MantineSelectProps } from '@mantine/core';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+/**
+ * Bare, unwrapped Select — no `FormControlWrapper`/`WithReadOnlyWrapper`, no label/assistiveText/
+ * error/required. Tied to the same `Dropdown.module.css` variables/classes as the public
+ * `Dropdown` component, so it looks identical, but is meant to be embedded inside another
+ * component that already owns its own `FormControlWrapper` (e.g. `TimePicker`'s AM/PM control) —
+ * nesting the full `Dropdown` there would double up `FormControl`/`FormControlLayout` wrapping.
+ *
+ * Not exported from this folder's `index.ts` — internal use only. Import it directly:
+ * `import { BareDropdown } from "../Dropdown/BareDropdown"`.
+ */
+export interface BareDropdownProps extends Omit<MantineSelectProps, "size" | "variant" | "radius" | "wrapperProps" | "label" | "description" | "error"> {
+    data: MantineSelectProps["data"];
+    /** Applies the error visual state (via `data-error`) — no error message is rendered here. */
+    error?: boolean;
+}
+export type BareDropdownComponentProps = RecursicaOverStyled<BareDropdownProps>;
+export declare const BareDropdown: import('react').ForwardRefExoticComponent<BareDropdownComponentProps & import('react').RefAttributes<HTMLInputElement>>;

package/dist/src/components/TimePicker/TimePicker.d.ts

@@ -1,4 +1,10 @@
 import { default as React } from 'react';
-import { RecursicaTimePickerProps } from '@recursica/adapter-common';
-export type TimePickerProps = React.HTMLAttributes<HTMLDivElement> & RecursicaTimePickerProps;
-export declare const TimePicker: React.FC<TimePickerProps>;
+import { TimePickerProps as MantineTimePickerProps } from '@mantine/dates';
+import { InputWrapperProps } from '@mantine/core';
+import { ReadOnlyControlProps, RecursicaTimePickerProps as BaseRecursicaTimePickerProps } from '@recursica/adapter-common';
+import { RecursicaOverStyled } from '../../utils/filterStylingProps';
+import { RecursicaFormControlWrapperProps } from '../FormControlWrapper/FormControlWrapper';
+export interface RecursicaTimePickerProps extends Omit<MantineTimePickerProps, "size" | "variant" | "radius" | "wrapperProps" | "format" | "min" | "max" | "amPmInputLabel" | "amPmLabels" | "amPmSelectProps" | "amPmRef" | "withDropdown" | "presets" | "maxDropdownContentHeight" | "scrollAreaProps" | "reverseTimeControlsList" | "popoverProps">, Pick<InputWrapperProps, "label" | "error" | "required" | "withAsterisk" | "id">, Omit<RecursicaFormControlWrapperProps, "controlMaxWidth" | "controlMinWidth">, ReadOnlyControlProps, BaseRecursicaTimePickerProps {
+}
+export type TimePickerProps = RecursicaOverStyled<RecursicaTimePickerProps>;
+export declare const TimePicker: React.ForwardRefExoticComponent<TimePickerProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/Tree/Tree.d.ts

@@ -9,5 +9,10 @@ export type TreeProps = RecursicaOverStyled<RecursicaTreeProps & Omit<React.Comp
  * Wraps Mantine's `Tree` with a fully custom node renderer so every visual aspect (row box
  * model, selected/unselected colors and typography, indent, item spacing) comes from
  * Recursica's `tree` design tokens rather than Mantine's defaults.
+ *
+ * **Interaction pattern (fixed, not prop-configurable):** expand/collapse and select are
+ * independent — the chevron button toggles a node's subtree only, clicking the rest of a row
+ * (or pressing `Enter`/`Space`) selects it only, and `ArrowLeft`/`ArrowRight` toggle expansion
+ * only. See `RecursicaTreeProps` for the full breakdown.
  */
 export declare const Tree: React.ForwardRefExoticComponent<TreeProps & React.RefAttributes<HTMLUListElement>>;

package/dist/src/index.d.ts

@@ -217,4 +217,4 @@ export declare const Toast: typeof rawComponents.Toast;
 export declare const Tooltip: typeof rawComponents.Tooltip;
 export declare const TransferList: typeof rawComponents.TransferList;
 export declare const Tree: typeof rawComponents.Tree;
-export type { RecursicaCheckboxGroupProps, RecursicaDatePickerProps, RecursicaDropdownProps, RecursicaNumberInputProps, RecursicaRadioGroupProps, RecursicaReadOnlyFieldProps, RecursicaReadOnlyTextFieldProps, RecursicaSliderProps, RecursicaSwitchGroupProps, RecursicaTextAreaProps, RecursicaTextFieldProps, } from './components';
+export type { RecursicaCheckboxGroupProps, RecursicaDatePickerProps, RecursicaDropdownProps, RecursicaNumberInputProps, RecursicaRadioGroupProps, RecursicaReadOnlyFieldProps, RecursicaReadOnlyTextFieldProps, RecursicaSliderProps, RecursicaSwitchGroupProps, RecursicaTextAreaProps, RecursicaTextFieldProps, RecursicaTimePickerProps, } from './components';

package/docs/PHILOSOPHY.md

@@ -0,0 +1,39 @@
+# Recursica Mantine Adapter: Core Philosophy
+
+Recursica's component architecture isn't just a wrapper; it's a strict enforcing layer over Mantine's massive API surface. Our primary goal is to ensure consistency, eliminate "design system rot," and provide clear boundaries for application developers using the UI Kit.
+
+This document serves as the governing framework for why the `mantine-adapter` components are built the way they are.
+
+## 1. Strict Separation of Props (The Unified Recursica Prop Layer)
+
+Recursica has a **single universal API surface** internally regardless of whether we use Mantine or another underlying UI library.
+
+- We decouple our visual properties natively. Instead of mapping perfectly to Mantine's variants `(solid, outline)`, we intentionally use Recursica's semantic and behavioral structures (e.g., `<Badge variant="alert" />`).
+- We intentionally omit and strip complex underlying parameters if they collide with or circumvent our UI tokens (like stripping `--size` out of Mantine Badge when Recursica enforces a universal single size).
+
+## 2. Component Wrappers (Leaving Mantine Alone)
+
+We actively avoid mutating or patching Mantine source code or deeply hooking into the Mantine Theme object to apply our token system.
+
+- We rely on standard DOM `module.css` bridging with strictly targeted `className`/`classNames` overrides.
+- This creates total decoupled isolation: updating Mantine natively will not fracture our styles, and we avoid dealing with deep Emotion/styled-component theme clashing logic.
+
+## 3. The `overStyled` Property
+
+Mantine encourages deep styling access by injecting properties like `p` (padding), `bg` (background), `c` (color), or `styles`/`classNames` directly into component tags.
+
+- By default, **Recursica components block all arbitrary styling vectors**. `className` maps, system styles, and inline logic are proactively stripped before they hit Mantine using central utility functions.
+- **Why?** To prevent the design system from deteriorating over time as developers write one-off hotfixes into their TSX rendering blocks.
+- **The Caveat:** We allow _external DOM layout positioning props_ (e.g., margin `m`, `mt`, `mb`, etc.) to pass through so developers can still structure components organically within their parent layouts.
+
+### Escape Hatches
+
+If a developer _strictly must_ heavily alter a component, they are required to explicitly declare `<Component overStyled={true} />`. This immediately raises a visible red flag during code reviews.
+
+## 4. Expectations for External Developers (Modifying Recursica)
+
+If a developer finds that a component does not fit their needs and styling must be modified, their path of execution should follow these principles sequentially:
+
+1. **Leverage Native Mantine First:** If a Recursica component lacks the functionality or styling variant needed for a highly custom edge case (e.g., a massive marketing hero button), do not try to forcibly hack the Recursica component. Instead, import the raw underlying `Button` component directly from `@mantine/core` and style it manually. Use Recursica for standard systematic needs, and native libraries for isolated custom one-offs.
+2. **Accept `overStyled` as Technical Debt:** If you must override the Recursica component immediately but intend to roll it back, use `overStyled={true}`. The expectation is that `overStyled` uses will eventually be replaced once the actual Recursica Figma variants are natively updated to accommodate your usecase, at which point `overStyled={true}` can be safely removed.
+3. **Contribute to the Kit:** Avoid building private custom wrappers around Recursica components. If the system is missing a variant, that is a shared project deficit—raise a concern and have the variant integrated directly into the universal token libraries!

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.36.0",
+  "version": "0.38.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -35,7 +35,8 @@
     "USAGE.md",
     "ARCHITECTURE.md",
     "SETUP.md",
-    "OVERSTYLING.md"
+    "OVERSTYLING.md",
+    "docs/PHILOSOPHY.md"
   ],
   "keywords": [
     "react",

package/src/components/Accordion/USAGE.md

@@ -46,45 +46,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Hybrid Composition API (Smart Rendering Flow)
+### Composition Patterns
 
-**Decision:** We fundamentally maintain the exact library composition API structure (`<Accordion>`, `<Accordion.Item>`, `<Accordion.Control>`, `<Accordion.Panel>`) while actively supporting an auto-completing flattened prop schema matching the unified Recursica API (`title`, `leftIcon`, `divider`).
-**Implementation:** Avoid rigid raw parameter dumps. Mantine dynamically injects explicit `id` logic, keyboard ARIA mapping, and focus tracking correctly across `Control` to `Panel` DOM connections natively. By exposing the hierarchical mapping 1:1, Recursica safely adopts these capabilities. However, to strictly support Recursica's unified prop mapping interface:
-
-- **Auto-Construction:** If integrators natively pass `title` and/or `leftIcon` props into `<AccordionItem>`, the component structurally auto-generates the internal `AccordionControl` sub-wrappers mapping the text and SVG natively, whilst treating `children` implicitly as the Panel contents.
-- **Graceful Falldown:** If `title` is heavily omitted, the node immediately falls backward into raw Mantine composability expecting integrators mapped `<Accordion.Control>` entirely manually.
-
----
-
-## 2. Default Configuration Reset (`unstyled`)
-
-**Decision:** We strip Mantine's inner styles away completely from Accordion mappings by leveraging React's default `variant="unstyled"`.
-**Implementation:** In `Accordion.tsx`, `<MantineAccordion>` binds `variant="unstyled"`. This effectively deletes Mantine's precomputed padding, borders, and shadow mappings allowing our targeted `classNames` inside `Accordion.module.css` to become the exact source of foundational truth without "fighting" `!important` tags or unpredictable flex-layouts inherited globally.
-
----
-
-## 3. Strict SVG Icons Wrapper (`.iconLeftWrapper`)
-
-**Decision:** Identical logic enforced as seen within Buttons: SVG scales dynamically inside `.mantine-leftSection` based on SVGs internal definition boundaries potentially corrupting header gaps.
-**Implementation:** `AccordionControl` captures `<span className={styles.iconLeftWrapper} aria-hidden>` forcing `object-fit: contain` mapped exactly to the `properties_icon-left-size` Recursica dimension token forcing integrator SVG overrides inline perfectly.
-
----
-
-## 4. Transparent Global Hover Fixes
-
-**Decision:** We nullify internal Mantine button hover actions and exclusively utilize Recursica's hover structure natively.
-**Implementation:** We construct `.control::after` pseudo-objects dynamically pulling our `hover-color` & `hover-opacity` bindings. Mantine's native action sets `.control:hover { background-color: var(...) }` dynamically causing internal layer overlaps. We enforce `background-color: transparent` strictly overriding it, preserving our pseudo-overlay layer-cascade cleanly.
-
----
-
-## 5. Active Target Hooks (`[data-active]`)
-
-**Decision:** Collapsed and expanded state tracking requires separate background maps across `AccordionItem`.
-**Implementation:** Rather than syncing React `useState` hooks matching `Accordion.value`, we defer to Mantine's inherent DOM mapping: `.item[data-active]` implicitly triggers exactly when Mantine registers an expansion state swap changing values down dynamically on the element layer, perfectly binding to `--recursica_..._background-expanded`.
-
----
-
-## 6. Nullifying Isolated State Bounds (`open` boolean)
-
-**Decision:** We do not bind isolated `open={true}` state properties natively on individual `<AccordionItem>` configurations.
-**Implementation:** Recursica natively dictates an item-level `open` tracking mapping. However, internally mapping boolean flags structurally across specific tree nodes heavily corrupts Mantine's DOM layout algorithms mapping parent-driven transition listeners. Mantine forces all expanded-height logic to run symmetrically off the `<Accordion value="...">` string matching array to accurately bind ARIA transitions. We explicitly ignore isolated item `<AccordionItem open={...}>` booleans to shield the rendering sequence cleanly.
+`Accordion.Item` supports two ways of providing content: pass `title` (and optionally `leftIcon`) directly on `Accordion.Item` for a simple control/panel pair, with `children` treated as the panel content; or omit `title` and compose manually with `Accordion.Control` and `Accordion.Panel` for full control over the control's contents.

package/src/components/AutoComplete/USAGE.md

@@ -45,22 +45,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Form Control Wrapping
+### Known Limitation: Active Option Highlight
 
-The `AutoComplete` component is wrapped using the `WithReadOnlyWrapper` to seamlessly bridge standard `InputWrapperProps` attributes (like `label`, `error`, `assistiveText`) directly onto the macro Recursica `<FormControlWrapper>`.
-
-## CSS Layout Execution
-
-The baseline structure maps identical `HARDCODED VALUES` as standard text inputs (`border-width: 1px`, `display: flex`). The `.root` dynamically overrides the `--input-left-section-size` and `--input-right-section-size` to accurately allocate whitespace for prepended or appended icons natively matching the underlying UI token layout system securely.
-
-## Dropdown Styling
-
-The Mantine `<Autocomplete>` dropdown menu and options are styled strictly using native UI-Kit variables mapping border radii, shadows, and base colors (`.dropdown` and `.option`).
-
-## State Cascade Architecture
-
-Focus, errors, and disabled visual states are enforced explicitly via the outer `<FormControlWrapper>` boundary emitting context down structurally (`[data-error]`, `[data-disabled]`) and evaluated efficiently against scoped nested selectors natively inside `AutoComplete.module.css`.
-
-## Missing Active Option Color
-
-Currently, there is no explicit JSON token for the background color of an active/hovered option in the AutoComplete dropdown. We temporarily map `.option:hover` and `.option[data-combobox-active]` to the `--recursica_ui-kit_components_autocomplete_variants_states_focus_properties_colors_background` variable. Because this variable maps to the base field background, the highlight is currently invisible. This will be updated once the correct token is added to the UI kit.
+The background highlight for a hovered or active option in the dropdown is not currently visible. This will be addressed in a future update.

package/src/components/Avatar/USAGE.md

@@ -36,30 +36,3 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 > - **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 Decisions
-
-The `Avatar` component is an adapter over Mantine's `Avatar`. To ensure adherence to the `COMPONENT_GUIDE_WALKTHROUGH.md`:
-
-- We do not wrap `MantineAvatar` in any custom standard `div` elements, preserving DOM structure.
-- All styles strictly pull from explicit `--recursica_ui-kit_components_avatar_*` CSS tokens.
-
-## Structural Workarounds
-
-### Implicit `data-style`
-
-Mantine's Avatar implicitly renders an image, an icon, or a text node based on the properties passed (`src`, `var`, `children`).
-Recursica Tokens split Avatar styling distinctly across three separate categories: `image`, `icon`, and `text`.
-To correctly map these variables, our React component observes standard prop states and manually injects a `data-style="image|icon|text"` onto the root. The `Avatar.module.css` explicitly gates padding and generic sizing modifiers under these `data-style` attributes.
-
-### Flex Layout & Internal Spans
-
-Since Avatar children (icons or initials) require robust centering that might differ heavily across Recursica size mappings, all child content defaults to being wrapped in `span` elements (either `.textWrapper` or `.iconWrapper`). These spans enforce 100% height and flex formatting independent of the Mantine container constraints.
-
-### CSS Reset Hacks
-
-Noticeable `/* HARDCODE: ... */` hacks are deployed within `.root` to completely zero-out Mantine's `--avatar-bg` and internal variables statically since Recursica handles background-colors inherently via the CSS variants cascade.

package/src/components/Badge/USAGE.md

@@ -43,16 +43,13 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## 1. Stripped Size Properties
+## 1. Sizing
 
-As logged in `COMPONENT_ISSUES.md`, there are currently no Figma variables mapped for different `size` variants (`small`, `default`, etc.). The component explicitly `Omit`s the Mantine `size` property from its signature to prevent integrators from attempting to drive sizes that do not exist in the tokens.
+Badge does not currently support a `size` prop; badges render at a single fixed size.
 
 ## 2. Intent-Based Variants
 
-Mantine supports multiple visual variants (`outline`, `filled`, `light`). However, the existing variable schema for `Badge` only defines "Styles" which act as intents (`alert`, `primary-color`, `success`, `warning`).
-
-- Default is arbitrarily mapped to `primary-color` as we lack a pure `neutral` schema right now.
-- `variant` mapped to underlying Mantine prop has been hardcoded to `filled`, since the Recursica coloring fully replaces the Mantine DOM.
+Badge exposes a `variant` prop with intent-based values (`alert`, `primary-color`, `success`, `warning`) rather than Mantine's `outline`/`filled`/`light` style options. The default variant is `primary-color`.
 
 ## 3. The `overStyled` Prop
 

package/src/components/Breadcrumb/USAGE.md

@@ -47,11 +47,7 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## Missing Variants and Sizes
 
-The `Breadcrumb` currently does not establish any size (`xs`, `sm`, etc.) or variant variables in the underlying design tokens (`recursica_ui-kit.json`). Only basic structural definitions for `padding` and `item-gap` exist. Because of this, the `size` and `variant` properties have been explicitly omitted from the passed mantine props.
-
-## Gap Styling
-
-We attach `gap` to `.root` directly within `.module.css`. Mantine's inner `separator` divs can natively accept our CSS variables for structural layout.
+Breadcrumb does not currently support `size` or `variant` props.
 
 ## Composition and Separators
 

package/src/components/Button/Button.tsx

@@ -101,6 +101,11 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
   const finalClass = classNameProp
     ? `${styles.root} ${classNameProp}`
     : styles.root;
+  // className is merged explicitly above — don't let the {...sanitizedProps} spread below
+  // silently overwrite finalClass with just the caller's own class (same bug class as
+  // mantine-adapter's Dropdown/BareDropdown.tsx had). Masked here today since `classNames.root`
+  // (a separate prop, unaffected) also carries styles.root — but a real latent bug regardless.
+  delete restRecord["className"];
 
   const userLoaderProps = restRecord.loaderProps as
     | Record<string, unknown>

package/src/components/Button/IMPLEMENTATION_NOTES.md

@@ -59,3 +59,11 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 **Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
 
 **Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on Mantine's native `data-disabled` dataset logic, which may not trigger the strict visual fade required by the Recursica design system.
+
+---
+
+## `className` overwrite bug (Matt Massey, 2026-08-08)
+
+**Bug:** with `overStyled` and a custom `className` (surfaced by Tree embedding a `Button` for its expand chevron — see `Tree/IMPLEMENTATION_NOTES.md`), `finalClass` (`` `${styles.root} ${classNameProp}` ``) was set explicitly on `<MantineButton>`, but `{...sanitizedProps}` was spread _after_ it — and `sanitizedProps` still contained the original, unmodified `className` key, since it had only been _read_, never deleted. The later spread would silently overwrite `finalClass` with just the caller's own class. Same bug class as `Dropdown.tsx`/`BareDropdown.tsx` had.
+
+**Why it wasn't visible here:** `classNames={{root: mergedClassNames.root, ...}}` is a _separate_ Mantine prop from the plain `className` string, unaffected by the overwrite, and `mergedClassNames.root` always includes `styles.root` independently — so the root element kept its Recursica styling regardless of the bug. mui-adapter's equivalent `Button.tsx` has no such secondary path (`@mui/material` only has a plain `className`), so the identical mistake there was fully visible (chevron rendered in MUI's own default color). Fixed in both regardless, since this is a real latent bug independent of whether it happens to be masked today.

package/src/components/Button/USAGE.md

@@ -45,37 +45,19 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## Icon size: Recursica defines it
 
-**Decision:** Icon size is **not** left to the developer. Recursica defines it via the design tokens; the Button enforces it so callers cannot pass an arbitrarily sized icon.
-
-**Implementation:**
-
-- When `icon` is provided, the Button wraps it in a single element with class `iconWrapper` before passing it to Mantine’s `leftSection`.
-- In `Button.module.css`, `.iconWrapper` has explicit `width` and `height` from the Recursica tokens mapping natively based on `data-size`.
-- The rule `.iconWrapper > *` sets `width: 100%`, `height: 100%`, and `object-fit: contain` so whatever the caller passes scales cleanly with the token constraints.
+Icon size is **not** left to the developer. Recursica defines it via the design tokens, so callers cannot pass an arbitrarily sized icon — whatever is passed in `icon` is scaled to fit the token-defined dimensions for the button's size.
 
 ---
 
-## Icon-only buttons: accessibility and width
-
-**Decision:** When the button has an icon and no visible label (icon-only), callers must provide an accessible name, and the button must not show extra space to the right of the icon.
-
-**Accessibility:** We document that icon-only buttons must pass `aria-label` (e.g. `aria-label="Submit"`). In development we log a console warning if `icon` is set, `children` is empty, and `aria-label` is missing.
+## Icon-only buttons: accessibility
 
-**Width:** Mantine’s layout natively applies structural section gaps. We detect icon-only and set a `data-icon-only` hook so that `Button.module.css` zeros out the sections spacing allowing the button to precisely hit `min-width` perfectly centered.
+When the button has an icon and no visible label (icon-only), callers must provide an accessible name via `aria-label` (e.g. `aria-label="Submit"`). In development, a console warning is logged if `icon` is set, `children` is empty, and `aria-label` is missing.
 
 ---
 
 ## Label truncation at max-width
 
-**Decision:** When the button hits its Recursica max-width (500px), the label truncates with an ellipsis instead of wrapping.
-
-**Implementation:**
-Mantine's `.mantine-Button-label` flex centering breaks primitive truncation logic. To combat this:
-
-- **`.root`** has `overflow: hidden`.
-- **`.root > *`** forces `min-width: 0`.
-- The structural children wrap into `<span className={styles.labelText}>`.
-- **`.labelText`** binds `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;` creating flawless string cutoffs strictly at exact UI constraints.
+When the button hits its Recursica max-width (500px), the label truncates with an ellipsis instead of wrapping.
 
 ---
 
@@ -95,6 +77,4 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 
 ## Loading state enforces disabled state
 
-**Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
-
-**Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on Mantine's native `data-disabled` dataset logic, which may not trigger the strict visual fade required by the Recursica design system.
+When `loading={true}` is passed to the Button, it is also treated as disabled — the button cannot be interacted with while loading.

package/src/components/Card/USAGE.md

@@ -54,18 +54,10 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture Overrides
+## Header & Footer Styling
 
-Because Mantine natively constructs `Card` bounding boxes with generic inner `<Card.Section>` elements that depend on explicit user styling (and lack implicit native designations for "Header" vs "Footer"), we implemented an explicit component wrapper departure:
+`Card.Header` and `Card.Footer` automatically receive their background color and padding from the design system; no manual styling is needed.
 
-- `<Card.Header>` explicitly hooks `--recursica_ui-kit_components_card_properties_header-background` and corresponding padding variables.
-- `<Card.Footer>` explicitly hooks `--recursica_ui-kit_components_card_properties_footer-background` and corresponding padding variables.
+## Layout Alignment
 
-Mantine's generic `<Card.Section>` calculates negative margins implicitly. Because of this, it is crucial that our local CSS module declares `--card-padding: var(--recursica_ui-kit_components_card_properties_padding)` directly on `.root` so that all generic or explicit section wrappers natively stretch across the bounding box properly.
-
-## Layout Alignment Exceptions
-
-To allow Cards to fit cleanly inside dynamic/flex layouts (like dashboard panels, grid tracks, or sidebar layout segments), the Card wrapper implements a custom gatekeeper bypass for outer styling properties:
-
-- Exposes a safe subset of flexbox/dimensions styling properties (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) on the root `<Card>` component to allow proper sizing alongside layout siblings.
-- Sets `<Card.Content>` to `flex-grow: 1;` by default via CSS modules. Since the root `<Card>` has `display: flex; flex-direction: column;`, this makes the content area expand to fill all vertical space, pushing `<Card.Footer>` to align at the absolute bottom of the bounding box.
+`Card` accepts a safe subset of flexbox/sizing props (`flex`, `flexGrow`, `flexShrink`, `flexBasis`, `grow`, `h`, `height`) so it can participate cleanly in flex or grid layouts (dashboard panels, grid tracks, sidebar segments, etc.). `Card.Content` grows to fill available vertical space, which keeps `Card.Footer` pinned to the bottom of the card.

package/src/components/Checkbox/USAGE.md

@@ -39,26 +39,10 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architectural Philosophy
+### Checkbox Alignment with Multi-line Labels
 
-The `Checkbox` primitive requires aggressive structural modifications to decouple Mantine's built-in arrays (`<Checkbox.Group>`) tying the raw DOM nodes seamlessly back into Recursica's unified form definitions flawlessly.
+Checkbox visually aligns to the first line of a wrapping, multi-line label.
 
-### Checkbox Alignment Anchoring (gap overflow hack)
+### Checkbox.Group
 
-By default, placing a Checkbox alongside a deeply wrapping multi-line label causes native geometric drifts natively. Because Mantine aligns the Checkbox graphic to the top of standard `display: flex` boxes, its optical center will appear natively skewed slightly _too high_ against the very first typographic text-line.
-
-We mathematically fix this alignment within `Checkbox.module.css` using explicit design variable arithmetic natively.
-\`\`\`css
-margin-top: calc(
-(
-var(--recursica_ui-kit_components_checkbox-item_properties_text_line-height) \*
-var(--recursica_ui-kit_components_checkbox-item_properties_text_font-size) -
-var(--recursica_ui-kit_components_checkbox_properties_size)
-) / 2
-) !important;
-\`\`\`
-This calculation ensures that the optical center of the `.inner` checkmark vector perfectly snaps onto the relative center of the text's line-height, permanently solving pixel-drifts natively!
-
-### Checkbox.Group Overrides
-
-To decouple `<CheckboxGroup>` away from `<Input.Wrapper>`, we explicitly extract the raw array execution mapped correctly against our identical `RecursicaFormControlWrapperProps` schema structurally!
+`Checkbox.Group` integrates with the same label, description, and error props as other Recursica form components.

package/src/components/Chip/USAGE.md

@@ -39,39 +39,10 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture decisions
-
-### Mantine DOM Structure & Label Overrides
-
-Mantine's `<Chip>` behaves like an input element (`radio` or `checkbox`). Under the hood, it renders:
-
-1. `.mantine-Chip-root` (wrapper)
-2. `input` (hidden visual structure)
-3. `.mantine-Chip-label` (The actual visible button-like pill)
-
-Because the `.label` is the primary visual surface and handles Mantine's built-in `:hover` and active states, we direct our Recursica styling natively to `.label`.
-
-### Icon and Remove Implementations
-
-To achieve this without breaking Mantine's `Chip` input architecture, we wrapped the internal `children` using a standard `span` DOM strategy:
-
-```tsx
-<span className={styles.innerWrapper}>
-  {icon}
-  <span className={styles.children}>{children}</span>
-  {onRemove}
-</span>
-```
-
-#### Intermediate Children Wrapper Span display fix:
-
-Mantine internally wraps the children passed to `Chip` in a default `<span>` which has `display: inline`. This intermediate `span` inherits the `line-height` of the `.label` container, causing the computed height of the Chip to be ~2px taller than expected. To address this, `.label > span:not(.mantineIconWrapper)` is targeted to force `display: inline-flex; align-items: center;` on that intermediate wrapper `span`, allowing it to collapse perfectly to the `16px` height of the `innerWrapper`.
-
 ### Accessibility of Remove Action
 
-Because the Chip fundamentally functions as a `<label>` linked to an `<input>`, placing a raw interactive element like `<button>` directly inside the standard Chip sub-tree violates nested interactive element ARIA constraints in strict validators.
-To accommodate this, the visual "close" icon uses a `<span>` element configured with `role="button"` and `tabIndex={0}` to hook into standard keyboard activations without triggering generic nested `<form>` conflicts native to Mantine's baseline constraints.
+The remove/close action is keyboard accessible — it can be activated via keyboard as well as mouse click.
 
-### Removing Sizing Properties
+### Sizing
 
-During implementation, the parsed Figma design tokens natively exported specific height/padding vectors dynamically (e.g., `--recursica_ui-kit_components_chip_properties_icon-size`) rather than explicit string variants (`sm`, `md`, `lg`). Therefore, we omitted `size` conceptually from the `RecursicaChipProps` wrapper to lock down size evaluation natively against the active layer variables.
+Chip does not support a `size` prop; chips render at a fixed size.

package/src/components/DatePicker/USAGE.md

@@ -39,17 +39,7 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Architecture Overview
-
-The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerInput` component, implementing the `FormControlWrapper` macro structure for Recursica. This ensures that the component visually and structurally aligns with standard Recursica input primitives.
-
 ## Structural Constraints
 
-1. **Naked Input Usage**: We intentionally pass `label={undefined}`, `description={undefined}`, and `error={undefined}` to the Mantine `DatePickerInput` component. This suppresses Mantine's internal macro form wrapping and ensures that only our `WithReadOnlyWrapper` > `FormControlWrapper` orchestrates labels, description text, and ARIA state error boundaries.
-2. **Read-Only Implementation**: Since the value type for `DatePickerInput` can be a date object, string, or array, the `WithReadOnlyWrapper` attempts to safely cast the output value using standard `String(value)`. For production apps utilizing heavy date formatting logic, developers can pass a custom `readOnlyComponent` explicitly to bypass this default cast.
-3. **Calendar Portal/Dropdown (Figma Token Issue)**: The Recursica UI Kit's `date-picker` component in Figma fails to export any explicit structural or color properties for the calendar popover itself (e.g. elevation, surface background, selected day colors). To solve this organically within the framework without breaking strict token adherence, we manually override the Mantine `.dropdown` and `.day[data-selected]` classes using `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surfaces, and `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected primary blue day. This guarantees strict visual adherence to the system until explicitly mapped tokens are provided in the UI Kit.
-
-## Styling Quirks
-
-- The `DatePickerInput` mimics Mantine's `Input` structure natively (`.input`, `.wrapper`, `.section`). We attach our `styles.input` and `styles.root` classes exactly like `TextField`.
-- The global layout margin override (`.layoutOverride`) utilizes `--form-control-margin-bottom` driven by specific stacked/side-by-side design tokens.
+1. **Read-Only Rendering**: When rendered in read-only mode, the selected date is displayed via a plain string conversion of the value. If you need custom date formatting, pass a `readOnlyComponent` prop to control how the value is rendered.
+2. **Calendar Popover Styling**: The calendar popover is not yet fully styled by design tokens.

package/src/components/Dropdown/BareDropdown.tsx

@@ -0,0 +1,85 @@
+import { forwardRef } from "react";
+import {
+  Select as MantineSelect,
+  type SelectProps as MantineSelectProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Dropdown.module.css";
+
+/**
+ * Bare, unwrapped Select — no `FormControlWrapper`/`WithReadOnlyWrapper`, no label/assistiveText/
+ * error/required. Tied to the same `Dropdown.module.css` variables/classes as the public
+ * `Dropdown` component, so it looks identical, but is meant to be embedded inside another
+ * component that already owns its own `FormControlWrapper` (e.g. `TimePicker`'s AM/PM control) —
+ * nesting the full `Dropdown` there would double up `FormControl`/`FormControlLayout` wrapping.
+ *
+ * Not exported from this folder's `index.ts` — internal use only. Import it directly:
+ * `import { BareDropdown } from "../Dropdown/BareDropdown"`.
+ */
+export interface BareDropdownProps
+  extends Omit<
+    MantineSelectProps,
+    | "size"
+    | "variant"
+    | "radius"
+    | "wrapperProps"
+    | "label"
+    | "description"
+    | "error"
+  > {
+  data: MantineSelectProps["data"];
+  /** Applies the error visual state (via `data-error`) — no error message is rendered here. */
+  error?: boolean;
+}
+
+export type BareDropdownComponentProps = RecursicaOverStyled<BareDropdownProps>;
+
+export const BareDropdown = forwardRef<
+  HTMLInputElement,
+  BareDropdownComponentProps
+>(function BareDropdown(props, ref) {
+  const { overStyled = false, className, disabled, error, ...rest } = props;
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  delete restRecord["size"];
+  delete restRecord["variant"];
+  delete restRecord["radius"];
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    wrapper: className ? `${styles.root} ${className}` : styles.root,
+    input: styles.input,
+    section: styles.section,
+    dropdown: styles.dropdown,
+    option: styles.option,
+  };
+
+  return (
+    <MantineSelect
+      ref={ref}
+      classNames={mergedClassNames}
+      disabled={disabled}
+      label={undefined}
+      description={undefined}
+      error={undefined}
+      // `wrapperProps` targets Mantine's *outer* `Input.Wrapper` (the label/description/error
+      // stacking element) — a different, ancestor element from the "wrapper" styles-api slot that
+      // actually carries `styles.root`'s border/background. Dropdown.module.css's error/disabled
+      // rules (`.root[data-error]`/`[data-disabled]`) need the attribute on that inner element, so
+      // `attributes.wrapper` (which targets the same slot as `classNames.wrapper`/`styles.wrapper`)
+      // is the correct hook here, not `wrapperProps`. See TIMEPICKER_IMPLEMENTATION_NOTES.md.
+      attributes={{
+        wrapper: {
+          "data-disabled": disabled ? "true" : undefined,
+          "data-error": error ? "true" : undefined,
+        },
+      }}
+      {...(sanitizedProps as unknown as MantineSelectProps)}
+    />
+  );
+});
+
+BareDropdown.displayName = "BareDropdown";

package/src/components/Dropdown/Dropdown.tsx

@@ -156,9 +156,18 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
             error={undefined}
             required={undefined}
             withAsterisk={undefined}
-            wrapperProps={{
-              "data-disabled": disabled ? "true" : undefined,
-              "data-error": error ? "true" : undefined,
+            // `wrapperProps` targets Mantine's *outer* `Input.Wrapper` (the label/description/error
+            // stacking element) — a different, ancestor element from the "wrapper" styles-api slot
+            // that actually carries `styles.root`'s border/background. Dropdown.module.css's error/
+            // disabled rules (`.root[data-error]`/`[data-disabled]`) need the attribute on that
+            // inner element, so `attributes.wrapper` (which targets the same slot as
+            // `classNames.wrapper`) is the correct hook — `wrapperProps` here meant the error state
+            // never actually applied a border color.
+            attributes={{
+              wrapper: {
+                "data-disabled": disabled ? "true" : undefined,
+                "data-error": error ? "true" : undefined,
+              },
             }}
             {...(sanitizedProps as unknown as MantineSelectProps)}
           />

package/src/components/Dropdown/USAGE.md

@@ -42,10 +42,6 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ---
 
-## 4. Key Integration Features & Constraints
+## 4. Notes
 
-The `Dropdown` component is mapped explicitly to Mantine's `<Select>` following the exact same strict encapsulation rules as `TextField`.
-
-1. **Naked Primitive Mapping:** Mantine's `Select` natively executes macro-label generation. To decouple it, we explicitly disable internal labels (`label={undefined}`) and inject it purely inside our generic `FormControlWrapper`.
-2. **Strict Dropdown Design Tokens:** The adapter implements strictly sandboxed styling utilizing only `--recursica_ui-kit_components_dropdown_...` variables. It explicitly does NOT inherit general `text-field` tokens despite geometric similarities, ensuring dropdown menus can be themed independently.
-3. **Dropdown Appendages:** To correctly map Mantine's detached Popover `.dropdown` and list `.option` items, we targeted focus and geometric bindings appending standard padding structures matched to the dropdown height overrides dynamically into our `Dropdown.module.css`.
+- `Dropdown` is styled independently from `TextField`; even though they look similar, they are themed using separate design tokens.

package/src/components/Flex/USAGE.md

@@ -45,4 +45,4 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 ## 4. Key Integration Features & Constraints
 
 The `Flex` component is a generic unopinionated flex layout wrapper mapped directly to Mantine's `Flex`.
-It currently does not require any custom logical layouts or CSS workarounds since it serves only to provide absolute, raw manipulation of standard CSS flex properties. All spacing props (gap, align, justify, direction, wrap) pass safely through via the `filterStylingProps` layout-property allowance, with `rec-` dimension tokens scaling transparently mapped to standard gap limits.
+All spacing props (`gap`, `align`, `justify`, `direction`, `wrap`) pass through as normal, with `rec-` dimension tokens mapped transparently to standard gap values.