@recursica/mantine-adapter 0.41.0 → 0.42.1

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.41.0",
+  "version": "0.42.1",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

package/src/GlobalExemptions.modules.css

@@ -5,9 +5,3 @@
  * recursica_variables_scoped.css but are not used by any specific component.
  * Isolating them here keeps individual component stylesheets clean and focused.
  */
-
-/* ==== GLOBAL ICON STYLE ====
-   Global layout option specifying the overall SVG rendering style (solid/outline).
-   Note to Forge Devs: style is not a CSS property or variable type and cannot be applied in standard CSS stylesheets.
-   This variable is ignored in the UI adapters and should be reviewed by the Forge team. */
-/* recursica-ignore: --recursica_ui-kit_globals_icon_style */

package/src/components/Accordion/Accordion.module.css

@@ -1,11 +1,3 @@
-/* EXEMPTIONS:
-   - accordion-header open-appearance background-color/border-color are ignored because Forge does
-     not apply a visual swap on expand, even though the token schema defines "open" appearance
-     colors distinct from "closed" (see .control below, which intentionally keeps a constant
-     background/border across collapsed/expanded). */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-header_variants_appearance_open_properties_colors_background-color */
-/* recursica-ignore: --recursica_ui-kit_components_accordion-header_variants_appearance_open_properties_colors_border-color */
-
 /* ==== ACCORDION CONTAINER ==== */
 .root {
   box-sizing: border-box;

package/src/components/AutoComplete/AutoComplete.module.css

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - border-size variables are ignored because the input box uses a uniform static boundary to prevent
-     unexpected layout shifts or flickering when switching between focused, disabled, or error states. */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --autocomplete-control-{max,min}-width hooks consumed inline in AutoComplete.tsx,

package/src/components/Avatar/Avatar.module.css

@@ -7,14 +7,6 @@ HARDCODED VALUES:
 - Image has no explicit size tokens other than root size, assume it scales 100%
 */
 
-/* EXEMPTIONS:
-   The generic size variables below are defined in Figma but unused.
-   We explicitly style the avatar's dimensions using the dedicated width and height tokens
-   (e.g., small_properties_width and small_properties_height) for precise component layout. */
-/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_size */
-/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_size */
-/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_size */
-
 .root {
   box-sizing: border-box;
   margin: 0;

package/src/components/Checkbox/CheckboxGroup.tsx

@@ -68,6 +68,16 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
     // Delete prohibited sizing hooks from bypassing the variables
     delete restRecord["size"];
 
+    // Mantine's own `Checkbox.Group` always establishes a context whose `value` defaults to
+    // `[]` (see @mantine/core's `useUncontrolled({ finalValue: [] })`), and its `Checkbox` spreads
+    // that context-derived `checked` *after* the individually-passed `checked` prop — so any
+    // `Checkbox` nested in a real `Checkbox.Group`, even one given neither `value` nor
+    // `defaultValue`, has its own `checked` prop silently forced to `false`. Callers who only want
+    // this component for its layout (item-gap spacing), not array-tracked selection — e.g.
+    // `TransferList`'s ungrouped rows, which pass each `Checkbox` its own controlled `checked` —
+    // must skip Mantine's real group primitive entirely rather than hand it an empty value.
+    const isArrayControlled = value !== undefined || defaultValue !== undefined;
+
     return (
       <WithReadOnlyWrapper
         className={className}
@@ -97,18 +107,30 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
         readOnlyValue={value !== undefined ? value : defaultValue}
         readOnlyNativeProps={props}
         activeComponent={
-          <MantineCheckbox.Group
-            ref={ref}
-            /* Natively bind local disabled lock dynamically */
-            {...(sanitizedProps as unknown as MantineCheckboxGroupProps)}
-            disabled={readOnly || (restRecord as any).disabled}
-            value={value as any}
-            defaultValue={defaultValue as any}
-          >
-            <div className={styles.groupRoot} data-layout={formLayout}>
+          isArrayControlled ? (
+            <MantineCheckbox.Group
+              ref={ref}
+              /* Natively bind local disabled lock dynamically */
+              {...(sanitizedProps as unknown as MantineCheckboxGroupProps)}
+              disabled={readOnly || (restRecord as any).disabled}
+              value={value as any}
+              defaultValue={defaultValue as any}
+            >
+              <div className={styles.groupRoot} data-layout={formLayout}>
+                {children}
+              </div>
+            </MantineCheckbox.Group>
+          ) : (
+            <div
+              ref={ref}
+              role="group"
+              {...(sanitizedProps as Record<string, unknown>)}
+              className={styles.groupRoot}
+              data-layout={formLayout}
+            >
               {children}
             </div>
-          </MantineCheckbox.Group>
+          )
         }
       />
     );

package/src/components/Chip/Chip.module.css

@@ -1,19 +1,3 @@
-/* EXEMPTIONS:
-   - close-icon-color, leading-icon-color, and select-specific state icon variables are ignored because 
-     Chip uses explicit state color definitions (e.g. unselected, selected, error, error-selected variant colors) 
-     to drive pixel-perfect hover and click transitions, rather than generic single-color overrides.
-   - text-size is ignored since actual chip sizing is dynamically driven by precise vertical padding and line-heights. */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_close-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_properties_text-size */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_selected-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_selected-icon-color */
-
 /* HARDCODED VALUES
    border-style: solid;  (Baseline reset)
    box-sizing: border-box; (Baseline reset)

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -8,9 +8,22 @@ The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerI
 
 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.
+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, hover, today, in-range). To solve this organically within the framework without breaking strict token adherence, we manually map every calendar state to the closest existing Recursica token instead of leaving any of it on Mantine's own un-tokenized defaults:
+   - **Surface** (`.dropdown`) & **selected day** (`.day[data-selected]`): `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surface, `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected day fill (unchanged from before).
+   - **Header content, weekday row** (`.calendarHeader`, `.weekday`): the hover-card-popover content-color token — previously unmapped, so these leaked Mantine's own text colors.
+   - **Header nav controls & month/year label** (`.calendarHeaderControl`, `.calendarHeaderLevel`, `.calendarHeaderControlIcon`): these are functionally buttons, so they're now styled with `--recursica_ui-kit_components_button_variants_styles_text` tokens (border/background/color/elevation) plus small-size `Button` sizing tokens (height, icon-only vs. label-content border-radius/padding/min-width, icon size, typography) — the same tokens `Button`'s `data-variant="text"` uses. Disabled opacity/elevation and the focus-visible ring also mirror `Button`'s own treatment instead of the generic brand tokens used elsewhere in this file.
+   - **Hover** (any day cell, header nav, header level button): the generic `--recursica_brand_states_hover_color`/`_hover_opacity` pair, via the same `::after`-overlay technique used by `Button`/`Menu` — the standard convention for components with no dedicated hover token. Unlike `Button`, the day number is a bare text node with no wrapping span to `z-index` above the overlay, so here the overlay sits at `z-index: -1` instead of the text getting `z-index: 1` — same visual effect, opposite side of the layering. Also unlike `Button` (a plain button with no library-native hover CSS), Mantine's `Day`/`CalendarHeaderControl`/`CalendarHeaderLevel` all ship their own native `:hover { background-color: ... }` rule — an explicit `background-color: transparent` reset on `:hover` was needed first, or the overlay would just layer on top of Mantine's own gray-0/dark-5 fill instead of replacing it. (Caught in review: the first pass added the overlay without this reset, and the visible hover color was indistinguishable from Mantine's plain default — confirmed via computed-style diffing, not just eyeballing the screenshot.)
+   - **Disabled / outside-month days**: the generic `--recursica_brand_states_disabled` opacity token — the same one used repo-wide (Button, Chip, Tree, Pagination, Accordion) for elements with no dedicated disabled token. **Disabled header nav/label controls** use `Button`'s own text-variant disabled opacity/elevation tokens instead, since they're now styled as `Button`.
+   - **Today marker**: no dedicated token exists, so it reuses the hover-card-popover border-size/color tokens already used for the dropdown surface's own border (previously hardcoded `1px`). `highlightToday` is now defaulted to `true` in `DatePicker.tsx` (Mantine ships it `false`, meaning today was never marked at all before this pass).
+   - **Weekend days**: Mantine's default colors these red; the UI Kit has no such concept, so weekend text is explicitly forced back to the same color as any other day rather than left on that unrelated default.
+   - **Range selection** (`.day[data-in-range]`/`[data-first-in-range]`/`[data-last-in-range]`): styled with the generic `--recursica_brand_states_overlay_color`/`_overlay_opacity` pair — previously unused anywhere in the codebase, but its name and shape (a translucent tint token) is exactly this use case. **Not currently reachable through our public API**: `RecursicaDatePickerProps` doesn't discriminate on `type`, so `value`/`defaultValue` are typed for single-date selection only — `type="range"` fails typecheck for consumers. This CSS is forward-compatible groundwork, not a demoed feature; proper range-mode typing would be a separate, larger follow-up. Also flagged as a judgment call on the token pairing itself: first usage anywhere, no prior precedent or design-team confirmation.
 
 ## 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.
+- **Popover `classNames` gotcha (bug fix)**: `.dropdown` was previously passed via the top-level `classNames` prop alongside `wrapper`/`input`/`section`/`day`/etc., which silently did nothing — the calendar surface is rendered by Mantine's internal `Popover`, whose style API is a separate namespace only reachable via `popoverProps.classNames` (`PickerInputBaseProps.popoverProps: Partial<Omit<PopoverProps, 'children'>>`). The `.dropdown` CSS (background/border/border-radius/box-shadow/padding/font-family, matching `Popover`'s own `.dropdown` rules 1:1) was never actually applied until this was fixed — confirmed via computed styles before/after (`box-shadow: none` → the real elevation token). `DatePicker.tsx` now merges any consumer-supplied `popoverProps`/`popoverProps.classNames` with our default instead of overwriting them.
+- **Default value format**: `valueFormat="MM/DD/YY"` (a `dayjs` format string, Mantine's default is `"MMMM D, YYYY"`), set before the `sanitizedProps` spread so consumers can still override via their own `valueFormat` prop.
+- **Default leading icon**: `leftSection={<CalendarIcon />}` (new `DatePicker.icons.tsx`, following the existing local-inline-SVG convention used by `Pagination.icons.tsx` — no icon library is a dependency of either adapter) is set the same way, overridable via `leftSection`.
+- **Default placeholder**: `placeholder="MM / DD / YY"`, set the same way (before `sanitizedProps`, so consumers can override).
+- **Single-line enforcement (bug fix)**: `DatePickerInput` renders its value/placeholder as a `<button>`'s text content, not a native `<input>` — it wraps like any other block text by default. A long placeholder (e.g. the original story's `"Select a deadline..."`) wrapped to two lines, inflating the field's height well past its `min-height` token and making the field visually look narrower than its actual `width` token value even though the box itself was always the right size. Fixed with `white-space: nowrap`/`text-overflow: ellipsis`/`overflow-x: clip`/`overflow-y: visible` on `.input`, the same convention `FileInput.module.css`'s `.value` uses.

package/src/components/DatePicker/DatePicker.icons.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+
+/**
+ * Default leading icon for DatePicker's left section. Consumers can override it by passing
+ * their own `leftSection` prop (see DatePicker.tsx). Sized/colored entirely via the generic
+ * `.section :global(svg)` rule in DatePicker.module.css, same as the icon in the
+ * WithLeadingIcon story — no width/height/color hardcoded here on purpose.
+ */
+export function CalendarIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      {...props}
+    >
+      <rect x="3" y="4" width="18" height="18" rx="2" ry="2" />
+      <line x1="16" y1="2" x2="16" y2="6" />
+      <line x1="8" y1="2" x2="8" y2="6" />
+      <line x1="3" y1="10" x2="21" y2="10" />
+    </svg>
+  );
+}

package/src/components/DatePicker/DatePicker.module.css

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - border-size variables are ignored because a uniform 1px border is applied globally to prevent
-     unexpected layout shift or flickering during focused, disabled, or error state transitions. */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_date-picker_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
 .layoutOverride {
@@ -117,6 +110,14 @@
   );
 
   outline: none;
+
+  /* Single-line enforcement: DatePickerInput renders its value/placeholder as a <button>'s text
+     content (not a native <input>), so it wraps by default like any other block text — clip it to
+     one line with ellipsis instead, same convention as FileInput's .value. */
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  overflow-x: clip;
+  overflow-y: visible;
 }
 
 .input::placeholder {
@@ -263,10 +264,257 @@
   );
 }
 
+/* Month label + prev/next nav controls: styled as Recursica's own "text" button variant (small
+   size) rather than bare popover text — same border/background/color/typography tokens Button
+   uses for data-variant="text", since these are functionally buttons inside the popover. */
+.calendarHeaderControl,
+.calendarHeaderLevel {
+  position: relative;
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_background-color
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_elevation
+  );
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-color
+  );
+  font-family: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_letter-spacing
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-transform
+  );
+  transition: all 0.2s ease;
+}
+
+/* Prev/next nav: icon-only button sizing (small). */
+.calendarHeaderControl {
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+    );
+}
+
+/* Month/year label: label-content button sizing (small). */
+.calendarHeaderLevel {
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_border-radius
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_horizontal-padding
+    );
+}
+
+/* Neutralize Mantine's own native :hover background-color (gray-0/dark-5) so only our
+   token-driven overlay below is visible — same reasoning as .day above. */
+.calendarHeaderControl:hover:not(:disabled, [data-disabled]),
+.calendarHeaderLevel:hover:not(:disabled, [data-disabled]) {
+  background-color: transparent;
+}
+
+.calendarHeaderControl::after,
+.calendarHeaderLevel::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_hover_color);
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.calendarHeaderControl:hover:not(:disabled, [data-disabled])::after,
+.calendarHeaderLevel:hover:not(:disabled, [data-disabled])::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+.calendarHeaderControl:disabled,
+.calendarHeaderControl[data-disabled],
+.calendarHeaderLevel:disabled,
+.calendarHeaderLevel[data-disabled] {
+  opacity: var(
+    --recursica_ui-kit_components_button_variants_styles_text_variants_states_disabled_properties_opacity
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_text_variants_states_disabled_properties_elevation
+  );
+}
+
+/* Focus ring, same convention as Button's own :focus-visible treatment. */
+.calendarHeaderControl:focus-visible,
+.calendarHeaderLevel:focus-visible {
+  outline: none;
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
+.calendarHeaderControlIcon {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+  );
+  width: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_icon
+  );
+}
+
+/* Weekday row (Mo, Tu, We...) */
+.weekday {
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+}
+
 .day {
+  position: relative;
+  color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_content
+  );
+  border-radius: var(--recursica_brand_dimensions_border-radii_default);
+}
+
+/* Weekend days: Mantine's default colors them red; the UI Kit has no such concept, so they're
+   intentionally kept identical to any other day rather than left on Mantine's un-tokenized default. */
+.day[data-weekend] {
   color: var(
     --recursica_ui-kit_components_hover-card-popover_properties_colors_content
   );
+}
+
+/* Today marker: reuse the popover border-size/color tokens already used for the dropdown
+   surface itself, since the UI Kit exports no dedicated "today" indicator token. */
+.day[data-today][data-highlight-today]:not([data-selected], [data-in-range]) {
+  border-style: solid;
+  border-width: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_border-color
+  );
+}
+
+/* Outside-month & disabled days: dim with the generic disabled-opacity token used everywhere else
+   in the design system for elements with no dedicated disabled token. */
+.day[data-outside],
+.day[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+}
+
+.day[data-disabled] {
+  cursor: not-allowed;
+}
+
+/* Unlike Button (a plain button with no built-in library hover), Mantine's Day ships its own
+   native :hover background-color (gray-0/dark-5) — neutralize it so only our token-driven
+   overlay below is visible. Same specificity as Mantine's own selector, so this relies on our
+   CSS module loading after @mantine/dates' stylesheet to win the tie (true today; see
+   DATEPICKER_IMPLEMENTATION_NOTES.md if that load order ever changes). */
+.day:hover:not(:disabled, [data-disabled], [data-static]) {
+  background-color: transparent;
+}
+
+/* Hover overlay, same generic mechanism used by Button/Menu for components without a dedicated
+   hover token. Unlike Button, the day number here is a bare text node (Mantine's Day renders it
+   directly, with no wrapping span to z-index above the overlay), so this sits at z-index: -1
+   instead — still scoped to .day's own positioned box, just painted behind the digit rather than
+   in front of it. */
+.day::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_hover_color);
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+
+.day:hover:not(:disabled, [data-disabled], [data-static])::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* Range selection (type="range"): the UI Kit exports no dedicated in-range token, so the generic
+   overlay token — meant for exactly this kind of translucent tint — fills the band between the
+   two selected endpoints. Painted via ::before (behind the day number and the ::after hover
+   overlay) so the fill's opacity never dims the text itself. */
+.day[data-in-range] {
+  border-radius: 0;
+}
+
+.day[data-in-range]::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_overlay_color);
+  opacity: var(--recursica_brand_states_overlay_opacity);
+}
+
+.day[data-first-in-range] {
+  border-radius: 0;
+  border-start-start-radius: var(
+    --recursica_brand_dimensions_border-radii_default
+  );
+  border-end-start-radius: var(
+    --recursica_brand_dimensions_border-radii_default
+  );
+}
+
+.day[data-last-in-range] {
+  border-radius: 0;
+  border-end-end-radius: var(--recursica_brand_dimensions_border-radii_default);
+  border-start-end-radius: var(
+    --recursica_brand_dimensions_border-radii_default
+  );
+}
+
+.day[data-first-in-range][data-last-in-range] {
   border-radius: var(--recursica_brand_dimensions_border-radii_default);
 }
 
@@ -278,4 +526,5 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-color
   );
+  opacity: 1;
 }

package/src/components/DatePicker/DatePicker.stories.tsx

@@ -65,7 +65,6 @@ export const Default: Story = {
   args: {
     disabled: false,
     label: "Project Deadline",
-    placeholder: "Select a deadline...",
     assistiveText: "Specify the absolute cutoff for code submission.",
   },
 };
@@ -73,7 +72,6 @@ export const Default: Story = {
 export const FormsSideBySide: Story = {
   args: {
     label: "Incident Start Date",
-    placeholder: "Pick date...",
     assistiveText: "When did the incident originally occur?",
     formLayout: "side-by-side",
   },
@@ -82,7 +80,6 @@ export const FormsSideBySide: Story = {
 export const WithLeadingIcon: Story = {
   args: {
     label: "Launch Date",
-    placeholder: "Select launch date...",
     leftSection: (
       <svg
         width="24"
@@ -106,7 +103,6 @@ export const WithLeadingIcon: Story = {
 export const Disabled: Story = {
   args: {
     label: "Disabled Date Range",
-    placeholder: "Disabled selection...",
     disabled: true,
   },
 };
@@ -114,7 +110,6 @@ export const Disabled: Story = {
 export const ErrorState: Story = {
   args: {
     label: "Execution Date",
-    placeholder: "Pick a valid date...",
     error: "The chosen date conflicts with an existing deployment freeze.",
     required: true,
   },
@@ -123,7 +118,6 @@ export const ErrorState: Story = {
 export const StaticReadOnly: Story = {
   args: {
     label: "Static ReadOnly Review",
-    placeholder: "Ignored...",
     value: new Date("2026-05-21"),
     readOnly: true,
   },
@@ -132,7 +126,6 @@ export const StaticReadOnly: Story = {
 export const EditableReadOnly: Story = {
   args: {
     label: "Editable ReadOnly Review",
-    placeholder: "Ignored until active...",
     defaultValue: new Date("2026-06-01"),
     readOnly: true,
     labelWithEditIcon: true,

package/src/components/DatePicker/DatePicker.tsx

@@ -7,6 +7,7 @@ import {
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import { CalendarIcon } from "./DatePicker.icons";
 import styles from "./DatePicker.module.css";
 
 import { type RecursicaDatePickerProps as BaseRecursicaDatePickerProps } from "@recursica/adapter-common";
@@ -83,9 +84,12 @@ export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
       wrapper: styles.root, // The nested Input internal relative wrapper bounding box
       input: styles.input,
       section: styles.section,
-      dropdown: styles.dropdown,
       day: styles.day,
+      weekday: styles.weekday,
       calendarHeader: styles.calendarHeader,
+      calendarHeaderControl: styles.calendarHeaderControl,
+      calendarHeaderLevel: styles.calendarHeaderLevel,
+      calendarHeaderControlIcon: styles.calendarHeaderControlIcon,
     };
 
     const classNamesProp = restRecord.classNames;
@@ -106,6 +110,33 @@ export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
         : styles.section;
     }
 
+    // The calendar popover surface (.dropdown) is styled by Mantine's underlying `Popover`
+    // component, not `DatePickerInput` itself — it only accepts classNames via `popoverProps`,
+    // not the top-level `classNames` map above (which only reaches the Input/Calendar parts).
+    const popoverPropsInput = restRecord.popoverProps;
+    const consumerPopoverProps =
+      popoverPropsInput &&
+      typeof popoverPropsInput === "object" &&
+      !Array.isArray(popoverPropsInput)
+        ? (popoverPropsInput as Record<string, unknown>)
+        : undefined;
+    const consumerPopoverClassNames =
+      consumerPopoverProps?.classNames &&
+      typeof consumerPopoverProps.classNames === "object" &&
+      !Array.isArray(consumerPopoverProps.classNames)
+        ? (consumerPopoverProps.classNames as Partial<Record<string, string>>)
+        : undefined;
+    delete restRecord["popoverProps"];
+    const mergedPopoverProps = {
+      ...consumerPopoverProps,
+      classNames: {
+        ...consumerPopoverClassNames,
+        dropdown: consumerPopoverClassNames?.dropdown
+          ? `${styles.dropdown} ${consumerPopoverClassNames.dropdown}`
+          : styles.dropdown,
+      },
+    };
+
     const wrapperClass = className
       ? `${styles.layoutOverride} ${className}`
       : styles.layoutOverride;
@@ -158,6 +189,11 @@ export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
               "data-disabled": disabled ? "true" : undefined,
               "data-error": error ? "true" : undefined,
             }}
+            highlightToday // Default on so today is visually marked; consumers can still override via rest
+            valueFormat="MM/DD/YY" // Default display format; consumers can still override via rest
+            placeholder="MM / DD / YY" // Default placeholder; consumers can still override via rest
+            leftSection={<CalendarIcon />} // Default leading icon; consumers can still override via rest
+            popoverProps={mergedPopoverProps}
             {...(sanitizedProps as unknown as DatePickerInputProps)}
           />
         }

package/src/components/DatePicker/USAGE.md

@@ -19,7 +19,7 @@ import React from "react";
 import { DatePicker } from "@recursica/mantine-adapter";
 
 export default function Demo() {
-  return <DatePicker label="Select Date" placeholder="Pick a date" />;
+  return <DatePicker label="Select Date" />;
 }
 ```
 
@@ -42,4 +42,8 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 ## Structural Constraints
 
 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.
+2. **Calendar Popover Styling**: The UI Kit exports no calendar-specific tokens (surface, selected day, hover, today, weekend, in-range), so the calendar reuses the closest existing tokens — see `DATEPICKER_IMPLEMENTATION_NOTES.md` for the exact mapping. All calendar states are token-driven; none are left on Mantine's un-tokenized defaults. The header's prev/next arrows and month/year label are styled as Recursica `text`-variant buttons.
+3. **Today Highlighting**: `highlightToday` defaults to `true` so the current day is always visually marked; pass `highlightToday={false}` to turn it off.
+4. **Default Value Format**: Displayed values default to `MM/DD/YY` (e.g. `08/19/26`); pass your own `valueFormat` (a `dayjs` format string) to override.
+5. **Default Leading Icon**: A calendar icon is shown in the left section by default; pass your own `leftSection` to override it.
+6. **Default Placeholder**: Defaults to `"MM / DD / YY"` when not set; pass your own `placeholder` to override it.

package/src/components/Dropdown/Dropdown.module.css

@@ -1,10 +1,3 @@
-/* EXEMPTIONS:
-   - border-size variables are ignored because a uniform 1px border is applied globally to prevent
-     unexpected layout shift or flickering during focus, disabled, or error state transitions. */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_error_properties_border-size */
-
 /* LAYOUT SPACING OVERRIDES:
    - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
    - Also sets the --dropdown-control-{max,min}-width hooks consumed inline in Dropdown.tsx, since