@recursica/mantine-adapter 0.32.0 → 0.34.0

package/src/components/Pagination/Pagination.tsx

@@ -4,6 +4,8 @@ import {
   Pagination as MantinePagination,
   type PaginationProps as MantinePaginationProps,
   type PaginationRootProps as MantinePaginationRootProps,
+  type PaginationControlProps as MantinePaginationControlProps,
+  type PaginationDotsProps as MantinePaginationDotsProps,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -28,11 +30,13 @@ export type PaginationRootProps =
   RecursicaOverStyled<MantinePaginationRootProps>;
 
 export type PaginationEdgeProps<T extends React.ElementType> =
-  React.ComponentProps<T> & {
-    /** If set to true, displays text labels alongside the icon. */
-    withLabel?: boolean;
-    icon?: any;
-  };
+  RecursicaOverStyled<
+    React.ComponentProps<T> & {
+      /** If set to true, displays text labels alongside the icon. */
+      withLabel?: boolean;
+      icon?: any;
+    }
+  >;
 
 function usePaginationClassNames(restRecord: Record<string, unknown>): {
   className: string;
@@ -88,14 +92,18 @@ _PaginationRoot.displayName = "Pagination.Root";
 const _PaginationNext = forwardRef<
   HTMLButtonElement,
   PaginationEdgeProps<typeof MantinePagination.Next>
->(function PaginationNext({ withLabel, icon, ...props }, ref) {
+>(function PaginationNext(
+  { overStyled = false, withLabel, icon, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
   const renderIcon = icon || (withLabel ? NextWithLabel : undefined);
   return (
     <MantinePagination.Next
       ref={ref}
       data-variant="text"
       icon={renderIcon as any}
-      {...props}
+      {...sanitizedProps}
     />
   );
 });
@@ -104,14 +112,18 @@ _PaginationNext.displayName = "Pagination.Next";
 const _PaginationPrevious = forwardRef<
   HTMLButtonElement,
   PaginationEdgeProps<typeof MantinePagination.Previous>
->(function PaginationPrevious({ withLabel, icon, ...props }, ref) {
+>(function PaginationPrevious(
+  { overStyled = false, withLabel, icon, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
   const renderIcon = icon || (withLabel ? PrevWithLabel : undefined);
   return (
     <MantinePagination.Previous
       ref={ref}
       data-variant="text"
       icon={renderIcon as any}
-      {...props}
+      {...sanitizedProps}
     />
   );
 });
@@ -120,14 +132,18 @@ _PaginationPrevious.displayName = "Pagination.Previous";
 const _PaginationFirst = forwardRef<
   HTMLButtonElement,
   PaginationEdgeProps<typeof MantinePagination.First>
->(function PaginationFirst({ withLabel, icon, ...props }, ref) {
+>(function PaginationFirst(
+  { overStyled = false, withLabel, icon, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
   const renderIcon = icon || (withLabel ? FirstWithLabel : undefined);
   return (
     <MantinePagination.First
       ref={ref}
       data-variant="text"
       icon={renderIcon as any}
-      {...props}
+      {...sanitizedProps}
     />
   );
 });
@@ -136,14 +152,18 @@ _PaginationFirst.displayName = "Pagination.First";
 const _PaginationLast = forwardRef<
   HTMLButtonElement,
   PaginationEdgeProps<typeof MantinePagination.Last>
->(function PaginationLast({ withLabel, icon, ...props }, ref) {
+>(function PaginationLast(
+  { overStyled = false, withLabel, icon, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
   const renderIcon = icon || (withLabel ? LastWithLabel : undefined);
   return (
     <MantinePagination.Last
       ref={ref}
       data-variant="text"
       icon={renderIcon as any}
-      {...props}
+      {...sanitizedProps}
     />
   );
 });
@@ -192,14 +212,47 @@ const _Pagination = forwardRef<HTMLDivElement, PaginationProps>(
 );
 _Pagination.displayName = "Pagination";
 
+export type PaginationControlProps =
+  RecursicaOverStyled<MantinePaginationControlProps>;
+
+const _PaginationControl = forwardRef<
+  HTMLButtonElement,
+  PaginationControlProps
+>(function PaginationControl({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  return (
+    <MantinePagination.Control
+      ref={ref}
+      {...(sanitizedProps as unknown as MantinePaginationControlProps)}
+    />
+  );
+});
+_PaginationControl.displayName = "Pagination.Control";
+
+export type PaginationDotsProps =
+  RecursicaOverStyled<MantinePaginationDotsProps>;
+
+const _PaginationDots = forwardRef<HTMLDivElement, PaginationDotsProps>(
+  function PaginationDots({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantinePagination.Dots
+        ref={ref}
+        {...(sanitizedProps as unknown as MantinePaginationDotsProps)}
+      />
+    );
+  },
+);
+_PaginationDots.displayName = "Pagination.Dots";
+
 /**
  * Recursica Pagination component wrapping Mantine's Pagination.
  */
 export const Pagination = _Pagination as typeof _Pagination & {
   Root: typeof _PaginationRoot;
   Items: typeof MantinePagination.Items;
-  Control: typeof MantinePagination.Control;
-  Dots: typeof MantinePagination.Dots;
+  Control: typeof _PaginationControl;
+  Dots: typeof _PaginationDots;
   Next: typeof _PaginationNext;
   Previous: typeof _PaginationPrevious;
   First: typeof _PaginationFirst;
@@ -208,9 +261,12 @@ export const Pagination = _Pagination as typeof _Pagination & {
 };
 
 Pagination.Root = _PaginationRoot;
+// Pagination.Items has no styling props of its own (just a `dotsIcon` prop, no
+// `style`/`className`/BoxProps), so re-exporting Mantine's implementation
+// directly is not a styling-gate gap.
 Pagination.Items = MantinePagination.Items;
-Pagination.Control = MantinePagination.Control;
-Pagination.Dots = MantinePagination.Dots;
+Pagination.Control = _PaginationControl;
+Pagination.Dots = _PaginationDots;
 Pagination.Next = _PaginationNext;
 Pagination.Previous = _PaginationPrevious;
 Pagination.First = _PaginationFirst;

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/Panel.tsx

@@ -2,6 +2,13 @@ import { forwardRef } from "react";
 import {
   Drawer as MantineDrawer,
   type DrawerProps as MantineDrawerProps,
+  type DrawerRootProps as MantineDrawerRootProps,
+  type DrawerOverlayProps as MantineDrawerOverlayProps,
+  type DrawerContentProps as MantineDrawerContentProps,
+  type DrawerHeaderProps as MantineDrawerHeaderProps,
+  type DrawerTitleProps as MantineDrawerTitleProps,
+  type DrawerCloseButtonProps as MantineDrawerCloseButtonProps,
+  type DrawerBodyProps as MantineDrawerBodyProps,
 } from "@mantine/core";
 import {
   filterStylingProps,
@@ -128,29 +135,142 @@ export const PanelFooter = forwardRef<HTMLDivElement, PanelFooterProps>(
 );
 PanelFooter.displayName = "PanelFooter";
 
+// ============================================================
+// PANEL SUB-COMPONENTS (wrapped so overStyled/filterStylingProps applies)
+// ============================================================
+
+export type PanelRootProps = RecursicaOverStyled<MantineDrawerRootProps>;
+
+export const PanelRoot = forwardRef<HTMLDivElement, PanelRootProps>(
+  function PanelRoot({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Root
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerRootProps)}
+      />
+    );
+  },
+);
+PanelRoot.displayName = "PanelRoot";
+
+export type PanelOverlayProps = RecursicaOverStyled<MantineDrawerOverlayProps>;
+
+export const PanelOverlay = forwardRef<HTMLDivElement, PanelOverlayProps>(
+  function PanelOverlay({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Overlay
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerOverlayProps)}
+      />
+    );
+  },
+);
+PanelOverlay.displayName = "PanelOverlay";
+
+export type PanelContentProps = RecursicaOverStyled<MantineDrawerContentProps>;
+
+export const PanelContent = forwardRef<HTMLDivElement, PanelContentProps>(
+  function PanelContent({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Content
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerContentProps)}
+      />
+    );
+  },
+);
+PanelContent.displayName = "PanelContent";
+
+export type PanelHeaderProps = RecursicaOverStyled<MantineDrawerHeaderProps>;
+
+export const PanelHeader = forwardRef<HTMLElement, PanelHeaderProps>(
+  function PanelHeader({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Header
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerHeaderProps)}
+      />
+    );
+  },
+);
+PanelHeader.displayName = "PanelHeader";
+
+export type PanelTitleProps = RecursicaOverStyled<MantineDrawerTitleProps>;
+
+export const PanelTitle = forwardRef<HTMLHeadingElement, PanelTitleProps>(
+  function PanelTitle({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Title
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerTitleProps)}
+      />
+    );
+  },
+);
+PanelTitle.displayName = "PanelTitle";
+
+export type PanelCloseButtonProps =
+  RecursicaOverStyled<MantineDrawerCloseButtonProps>;
+
+export const PanelCloseButton = forwardRef<
+  HTMLButtonElement,
+  PanelCloseButtonProps
+>(function PanelCloseButton({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  return (
+    <MantineDrawer.CloseButton
+      ref={ref}
+      {...(sanitizedProps as unknown as MantineDrawerCloseButtonProps)}
+    />
+  );
+});
+PanelCloseButton.displayName = "PanelCloseButton";
+
+export type PanelBodyProps = RecursicaOverStyled<MantineDrawerBodyProps>;
+
+export const PanelBody = forwardRef<HTMLDivElement, PanelBodyProps>(
+  function PanelBody({ overStyled = false, ...rest }, ref) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    return (
+      <MantineDrawer.Body
+        ref={ref}
+        {...(sanitizedProps as unknown as MantineDrawerBodyProps)}
+      />
+    );
+  },
+);
+PanelBody.displayName = "PanelBody";
+
 // ============================================================
 // DOT NOTATION EXPORT
 // ============================================================
 
 type PanelComponent = typeof PanelBase & {
-  Root: typeof MantineDrawer.Root;
-  Overlay: typeof MantineDrawer.Overlay;
-  Content: typeof MantineDrawer.Content;
-  Header: typeof MantineDrawer.Header;
-  Title: typeof MantineDrawer.Title;
-  CloseButton: typeof MantineDrawer.CloseButton;
-  Body: typeof MantineDrawer.Body;
+  Root: typeof PanelRoot;
+  Overlay: typeof PanelOverlay;
+  Content: typeof PanelContent;
+  Header: typeof PanelHeader;
+  Title: typeof PanelTitle;
+  CloseButton: typeof PanelCloseButton;
+  Body: typeof PanelBody;
   Stack: typeof MantineDrawer.Stack;
   Footer: typeof PanelFooter;
 };
 
 export const Panel = PanelBase as PanelComponent;
-Panel.Root = MantineDrawer.Root;
-Panel.Overlay = MantineDrawer.Overlay;
-Panel.Content = MantineDrawer.Content;
-Panel.Header = MantineDrawer.Header;
-Panel.Title = MantineDrawer.Title;
-Panel.CloseButton = MantineDrawer.CloseButton;
-Panel.Body = MantineDrawer.Body;
+Panel.Root = PanelRoot;
+Panel.Overlay = PanelOverlay;
+Panel.Content = PanelContent;
+Panel.Header = PanelHeader;
+Panel.Title = PanelTitle;
+Panel.CloseButton = PanelCloseButton;
+Panel.Body = PanelBody;
+// Panel.Stack (DrawerStack) only accepts `children` — no styling props to
+// strip, so re-exporting Mantine's implementation directly is not a gap.
 Panel.Stack = MantineDrawer.Stack;
 Panel.Footer = PanelFooter;

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.

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.