@recursica/mui-adapter 0.25.0 → 0.27.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.25.0",
+  "version": "0.27.0",
   "publishConfig": {
     "access": "public"
   },

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). Mirrors the mantine-adapter reference. */
-/* 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,11 +1,3 @@
-/* EXEMPTIONS:
-   - state-specific border-size variables are ignored because the input box uses a uniform static boundary to prevent 
-     unexpected layout shifts or flickering when switching between active, focused, or error states. */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_variants_states_default_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 */
-/* recursica-ignore: --recursica_ui-kit_components_autocomplete_variants_states_focus_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/Autocomplete/Autocomplete.tsx

@@ -8,6 +8,8 @@ import {
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
@@ -77,42 +79,50 @@ export const Autocomplete = forwardRef<HTMLInputElement, AutocompleteProps>(
       ListboxProps,
       ...rest
     } = props;
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
-
-    // Delete prohibited sizing hooks from bypassing variables natively
-    delete restRecord["size"];
-    delete restRecord["variant"];
-    delete restRecord["radius"];
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the Omit<> above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via design tokens, not MUI's native small/medium size
+    ] as const satisfies readonly (keyof MuiAutocompleteProps<
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      any,
+      "div"
+    >)[];
 
-    // Securely map core native blocks down ensuring nested CSS modules map precisely
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-      inputRoot: styles.input, // Map Mantine .input (wrapper) to MUI's inputRoot
-      listbox: styles.dropdown, // Map Mantine .dropdown to MUI's listbox
-      option: styles.option,
-    };
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
-    const classNamesProp = restRecord.classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.wrapper
-        ? `${styles.root} ${o.wrapper}`
-        : styles.root;
-      mergedClassNames.inputRoot = o.input
-        ? `${styles.input} ${o.input}`
-        : styles.input;
-      mergedClassNames.listbox = o.dropdown
-        ? `${styles.dropdown} ${o.dropdown}`
-        : styles.dropdown;
-      mergedClassNames.option = o.option
-        ? `${styles.option} ${o.option}`
-        : styles.option;
-    }
+    // Securely map core native blocks down ensuring nested CSS modules map precisely. Note MUI's
+    // actual prop is "classes", not "classNames" (that's Mantine's naming) — this used to read
+    // the wrong key, silently no-op-ing any caller-supplied classes. The caller-facing slot names
+    // below (wrapper/input/dropdown/option) mirror the mantine-adapter's own Autocomplete
+    // classNames slots, translated to MUI's real classes slot names (root/inputRoot/listbox/option).
+    const callerClasses = restRecord.classes as
+      | Partial<Record<string, string>>
+      | undefined;
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        inputRoot: styles.input, // Map Mantine .input (wrapper) to MUI's inputRoot
+        listbox: styles.dropdown, // Map Mantine .dropdown to MUI's listbox
+        option: styles.option,
+      },
+      callerClasses && {
+        root: callerClasses.wrapper,
+        inputRoot: callerClasses.input,
+        listbox: callerClasses.dropdown,
+        option: callerClasses.option,
+      },
+    );
 
     const wrapperClass = className
       ? `${styles.layoutOverride} ${className}`
@@ -148,6 +158,8 @@ export const Autocomplete = forwardRef<HTMLInputElement, AutocompleteProps>(
           /* Naked Input execution safely decoupled from Mui's macro Input.Wrapper DOM hooks */
           <MuiAutocomplete
             ref={ref}
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            {...(sanitizedProps as any)}
             freeSolo
             disableClearable
             classes={mergedClassNames}

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

@@ -5,6 +5,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Avatar.module.css";
@@ -42,27 +43,16 @@ const _Avatar = forwardRef<HTMLDivElement, AvatarProps>(function Avatar(
     computedStyle = "icon";
   }
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    image: styles.image,
-    placeholder: styles.placeholder,
-  };
-
-  const classNamesProp = restRecord.classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-    mergedClassNames.image = o.image
-      ? `${styles.image} ${o.image}`
-      : styles.image;
-    mergedClassNames.placeholder = o.placeholder
-      ? `${styles.placeholder} ${o.placeholder}`
-      : styles.placeholder;
-  }
+  // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+  // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      image: styles.image,
+      placeholder: styles.placeholder,
+    },
+    restRecord.classes as Partial<Record<string, string>> | undefined,
+  );
 
   const classNameProp = restRecord.className as string | undefined;
 

package/src/components/Badge/Badge.tsx

@@ -5,6 +5,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Badge.module.css";
@@ -24,19 +25,14 @@ const _Badge = forwardRef<HTMLDivElement, BadgeProps>(function Badge(
   // External layout props like margins are safely preserved.
   const sanitizedProps = filterStylingProps(rest, overStyled);
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-  };
-
-  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-  }
+  // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+  // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    { root: styles.root },
+    (sanitizedProps as Record<string, unknown>).classes as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
 
   const classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -5,6 +5,7 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Breadcrumb.module.css";
@@ -22,24 +23,17 @@ export const Breadcrumb = forwardRef<HTMLDivElement, BreadcrumbProps>(
       overStyled,
     );
 
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-      separator: styles.separator,
-    };
-
-    const classNamesProp = (sanitizedProps as Record<string, unknown>)
-      .classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-      mergedClassNames.separator = o.separator
-        ? `${styles.separator} ${o.separator}`
-        : styles.separator;
-    }
+    // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+    // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        separator: styles.separator,
+      },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
 
     const classNameProp = (sanitizedProps as Record<string, unknown>)
       .className as string | undefined;

package/src/components/Button/Button.module.css

@@ -378,16 +378,3 @@
       var(--recursica_brand_states_focus_margin)
       var(--recursica_brand_states_focus_color);
 }
-
-/* EXEMPTIONS:
-   These general button properties are redundant because visual mapping has been refactored
-   to content-specific variables (_content_label_sizes_... etc.) or are handled by design defaults. */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_hover-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_button_variants_sizes_small_properties_text_text-transform */

package/src/components/Button/Button.tsx

@@ -6,6 +6,8 @@ import {
 } from "@mui/material";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  withCallerOverride,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Button.module.css";
@@ -54,11 +56,17 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     },
     ref,
   ) {
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the Omit<> above.
+    const UNSUPPORTED_PROPS = [
+      "color", // Recursica handles colors internally via tokens
+    ] as const satisfies readonly (keyof MuiButtonProps)[];
 
-    // Explicitly delete blocked semantic expansion dimension props that MUI uses natively
-    delete restRecord["color"]; // Recursica handles colors internally via tokens
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
     const hasStartIcon = !!icon || !!restRecord["startIcon"];
     const hasEndIcon = !!restRecord["endIcon"];
@@ -87,18 +95,16 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     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
-    // mui-adapter's Dropdown/BareDropdown.tsx had).
-    delete restRecord["className"];
 
     // We don't map Recursica variant/size to MUI's because we want to completely disable MUI's native
     // variant logic (e.g., elevation, shadows) and style everything strictly through our CSS Modules.
     // However, Mui Button requires some string, but we can just leave it as standard or ignore since
     // our CSS resets its properties anyway, but to be clean we just don't pass variant to MUI.
 
-    const resolvedLoaderSize =
-      loaderSize ?? (size === "small" ? "small" : "default");
+    const resolvedLoaderSize = withCallerOverride(
+      size === "small" ? "small" : "default",
+      loaderSize,
+    );
 
     let loadingIndicator = restRecord.loadingIndicator as React.ReactNode;
     if (useRecursicaLoader) {
@@ -110,6 +116,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     return (
       <MuiButton
         ref={ref}
+        {...sanitizedProps}
         disableRipple
         disableElevation
         className={finalClass}
@@ -131,7 +138,6 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
         data-size={size}
         data-content={contentType}
         {...(restRecord.loading ? { "data-loading": "true" } : {})}
-        {...sanitizedProps}
         disabled={!!restRecord.disabled || !!restRecord.loading}
       >
         <span className={styles.labelText}>{children}</span>

package/src/components/Card/Card.tsx

@@ -2,6 +2,7 @@ import { forwardRef } from "react";
 import { Card as MuiCard, type CardProps as MuiCardProps } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Card.module.css";
@@ -51,25 +52,14 @@ const CardBase = forwardRef<HTMLDivElement, CardProps>(function Card(
     }
   });
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-  };
-
-  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Record<string, string>;
-    Object.keys(o).forEach((key) => {
-      if (mergedClassNames[key]) {
-        mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
-      } else {
-        mergedClassNames[key] = o[key];
-      }
-    });
-  }
+  // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+  // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    { root: styles.root },
+    (sanitizedProps as Record<string, unknown>).classes as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
 
   const classNameProp = (sanitizedProps as Record<string, unknown>)
     .className as string | undefined;

package/src/components/Checkbox/Checkbox.tsx

@@ -7,6 +7,8 @@ import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import { CheckboxGroup, CheckboxGroupContext } from "./CheckboxGroup";
 import {
   filterStylingProps,
+  omitUnsupportedProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import {
@@ -58,33 +60,27 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
       ...rest
     } = props;
 
-    const sanitizedProps = filterStylingProps(rest, overStyled);
-    const restRecord = sanitizedProps as Record<string, unknown>;
-
-    delete restRecord["size"];
-    delete restRecord["color"];
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the Omit<> above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via design tokens, not MUI's native small/medium size
+      "color", // Colors are token-driven; MUI's native palette isn't exposed
+    ] as const satisfies readonly (keyof MuiCheckboxProps)[];
 
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-      checked: styles.checked,
-      disabled: styles.disabled,
-    };
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled),
+      UNSUPPORTED_PROPS,
+    );
+    const restRecord = sanitizedProps as Record<string, unknown>;
 
-    const classesProp = restRecord.classes;
-    if (
-      classesProp &&
-      typeof classesProp === "object" &&
-      !Array.isArray(classesProp)
-    ) {
-      const o = classesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-      mergedClassNames.checked = o.checked
-        ? `${styles.checked} ${o.checked}`
-        : styles.checked;
-      mergedClassNames.disabled = o.disabled
-        ? `${styles.disabled} ${o.disabled}`
-        : styles.disabled;
-    }
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        checked: styles.checked,
+        disabled: styles.disabled,
+      },
+      restRecord.classes as Partial<Record<string, string>> | undefined,
+    );
 
     const classNameProp = restRecord.className as string | undefined;
     const finalClass = classNameProp
@@ -172,10 +168,10 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
     const checkboxNode = (
       <MuiCheckbox
         ref={ref}
+        {...(sanitizedProps as unknown as MuiCheckboxProps)}
         className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
         classes={mergedClassNames}
         disabled={readOnly || disabled || isGroupReadOnly}
-        {...(sanitizedProps as unknown as MuiCheckboxProps)}
         {...(isControlled ? { checked: isChecked as boolean } : {})}
         onChange={handleChange}
         disableRipple

package/src/components/Checkbox/CheckboxGroup.tsx

@@ -75,12 +75,12 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
       row,
       ...rest
     } = props;
+    // NOTE: this component's props surface (HTMLAttributes<HTMLDivElement>-based) has no native
+    // "size" (or other Recursica-unsupported) prop to leak through here — nothing to add to an
+    // UNSUPPORTED_PROPS list beyond what filterStylingProps already blocks.
     const sanitizedProps = filterStylingProps(rest, overStyled);
     const restRecord = sanitizedProps as Record<string, unknown>;
 
-    // Delete prohibited sizing hooks
-    delete restRecord["size"];
-
     const handleChange = (_event: React.SyntheticEvent, childValue: any) => {
       if (onChange) {
         onChange(childValue);

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

@@ -1,30 +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_styles_error_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_error_properties_colors_selected-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_error-selected_properties_colors_icon */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_error-selected_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_selected_properties_colors_leading-icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_chip_variants_styles_unselected_properties_colors_selected-icon-color */
-
-/* Additional exemptions matching the reference mantine-adapter's Chip.module.css: per selection/error
-   state, Figma defines multiple icon-color slots (leading-icon-color, selected-icon-color, and for
-   error states also a generic icon-color), but each state only ever consumes ONE of them (leading
-   when unselected, selected when selected). The remaining "off" slots per state are intentionally
-   unused, same as in the mantine reference. */
-/* 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_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_unselected_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_unselected_variants_states_error_properties_colors_selected-icon-color */
-
 /* HARDCODED VALUES
    border-style: solid;  (Baseline reset)
    box-sizing: border-box; (Baseline reset)

package/src/components/Chip/Chip.tsx

@@ -2,6 +2,7 @@ import React, { forwardRef } from "react";
 import { Chip as MuiChip, type ChipProps as MuiChipProps } from "@mui/material";
 import {
   filterStylingProps,
+  mergeClassNames,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Chip.module.css";
@@ -75,25 +76,17 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
   const sanitizedProps = filterStylingProps(rest, overStyled);
   const restRecord = sanitizedProps as Record<string, unknown>;
 
-  const mergedClassNames: Partial<Record<string, string>> = {
-    root: styles.root,
-    label: styles.label,
-    icon: styles.leadingIcon,
-    deleteIcon: styles.removeIconWrapper,
-  };
-
-  const classNamesProp = restRecord.classNames;
-  if (
-    classNamesProp &&
-    typeof classNamesProp === "object" &&
-    !Array.isArray(classNamesProp)
-  ) {
-    const o = classNamesProp as Partial<Record<string, string>>;
-    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
-    mergedClassNames.label = o.label
-      ? `${styles.label} ${o.label}`
-      : styles.label;
-  }
+  // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+  // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    {
+      root: styles.root,
+      label: styles.label,
+      icon: styles.leadingIcon,
+      deleteIcon: styles.removeIconWrapper,
+    },
+    restRecord.classes as Partial<Record<string, string>> | undefined,
+  );
 
   const classNameProp = restRecord.className as string | undefined;
   const finalClass = classNameProp

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,29 @@
+# DatePicker Implementation Notes
+
+## Architecture Overview
+
+The `DatePicker` component is a wrapper around MUI X's `@mui/x-date-pickers` `DatePicker`, implementing the `FormControlWrapper` macro structure for Recursica. This ensures that the component visually and structurally aligns with standard Recursica input primitives, and mirrors the mantine-adapter's own `DatePicker` behavior and token mapping wherever the two libraries' APIs allow it.
+
+## Structural Constraints
+
+1. **Naked Field Usage**: We intentionally pass `label={undefined}`/`description`/`error` through `WithReadOnlyWrapper` rather than MUI X's own field label/helper-text props, so only our `WithReadOnlyWrapper` > `FormControlWrapper` orchestrates labels, description text, and ARIA state error boundaries — same convention as TimePicker.tsx.
+2. **Value Type**: MUI X's `DatePicker` only speaks `Dayjs` (via `AdapterDayjs`); the public API converts to/from plain `Date` internally so `value`/`defaultValue`/`onChange` match the mantine-adapter's convention exactly.
+3. **Read-Only Rendering**: The selected date is displayed formatted as `MM/DD/YY` (via `dayjs(...).format(...)`), not a raw `String(value)` cast (unlike the mantine-adapter, which has no reason to reach for `dayjs` outside read-only formatting). Pass `readOnlyComponent` to override.
+4. **Typing vs. Popover Entry**: Unlike the mantine-adapter (`DatePickerInput`, popover-only), MUI X's field natively supports typing directly into masked date segments in addition to the popup calendar — no adapter code needed to enable this, it's the library default.
+5. **Calendar Popover (Figma Token Issue)**: Same root cause as the mantine-adapter — the UI Kit's `date-picker` component exports no calendar-specific tokens (surface, selected day, hover, today, in-range) — so the calendar reuses the closest existing tokens, mapped 1:1 to the mantine-adapter's choices:
+   - **Surface** (`.dropdown`, applied to `slotProps.desktopPaper`) & **selected day** (`.MuiPickerDay-root.Mui-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.
+   - **Header content, weekday row** (`.MuiPickersCalendarHeader-root`, `.MuiDayCalendar-weekDayLabel`): the hover-card-popover content-color token.
+   - **Header nav controls** (`.MuiPickersArrowSwitcher-button`, `.MuiPickersCalendarHeader-switchViewButton`) **& month/year label** (`.MuiPickersCalendarHeader-label`): styled with `--recursica_ui-kit_components_button_variants_styles_text` tokens (border/background/color/elevation) plus small-size `Button` sizing tokens — the same tokens the mantine-adapter's `.calendarHeaderControl`/`.calendarHeaderLevel` use. Note the DOM shape differs from mantine: MUI splits the month/year control into a plain, non-interactive `.label` text node (`role="none"` on its `labelContainer` parent) plus a separate small `.switchViewButton` that's the actual clickable control — only the label's _color/typography_ is recolored to match (no border/background chrome on a non-interactive element), while the switchViewButton gets the full button treatment.
+   - **Hover** (day cells, header nav, header level button): the generic `--recursica_brand_states_hover_color`/`_hover_opacity` pair via the same `::after`-overlay technique the mantine-adapter and `Button`/`Menu` use — a plain `background-color`+`opacity` change on the element itself would dim its icon/text along with the fill, not just tint the surface.
+   - **Disabled / outside-month days** (`.Mui-disabled`, `.MuiPickerDay-dayOutsideMonth`): the generic `--recursica_brand_states_disabled` opacity token, same convention used repo-wide. Disabled header nav/label controls use `Button`'s own text-variant disabled opacity/elevation tokens instead.
+   - **Today marker** (`.MuiPickerDay-today`): reuses the hover-card-popover border-size/color tokens already used for the dropdown surface's own border — same reasoning as mantine-adapter (no dedicated "today" token exists). MUI ships its own default light-primary-color background tint on this class, which is explicitly reset to `transparent` since the design system has no equivalent.
+   - **Range selection / weekend styling**: not mapped. MUI X's default `DatePicker` doesn't render range selection or weekend-specific styling at all (unlike Mantine, which colors weekends red by default and needed an explicit override), so neither state needed a Recursica mapping.
+
+## Styling Quirks
+
+- **Native field decoration suppression**: MUI X's field variant can't be forced to a bare/unstyled mode from this component's public API (same constraint TimePicker.module.css documents) — whichever native outline/underline decoration it renders by default is suppressed via `:global(...)` overrides, and `.field` draws the Recursica border/background/color instead.
+- **Popover `slotProps` gotcha, same shape as mantine-adapter's `popoverProps` bug**: the calendar popup is portaled to `document.body`, entirely outside this component's own DOM subtree, so it can only be reached by handing MUI X's `slotProps.desktopPaper` a `className` directly — a descendant CSS selector from `.root` would never match it. `DatePicker.tsx` merges any consumer-supplied `slotProps.field`/`slotProps.desktopPaper` (and their `className`s) with our own defaults instead of overwriting them.
+- **`.dropdown`'s `!important`s**: unlike the mantine-adapter's equivalent rule (plain CSS-module specificity, no `!important` needed — `@mantine/dates`' own stylesheet reliably loads first), MUI X injects its own `Paper`/`Popper` styles at runtime via emotion, with no guaranteed load-order relative to this CSS module. `!important` here just re-asserts token values against a same-specificity emotion rule that could otherwise win on source order alone.
+- **Default display/entry format**: `format="MM/DD/YY"` (a `dayjs` format string, MUI X's own default is `"MM/DD/YYYY"`), matching the mantine-adapter's `valueFormat` default.
+- **Default leading icon**: the calendar icon is MUI X's own built-in "open picker" button (`slots.openPickerIcon`, positioned via `openPickerButtonPosition="start"` on the field slot) rather than a separate decorative `InputAdornment` — clicking it opens the calendar, unlike the mantine-adapter's purely decorative `leftSection` icon (there, the whole field is the click target). Overridable via `slots={{ openPickerIcon: MyIcon }}`, following the same override-prop convention as `leftSection` elsewhere in this adapter.
+- **No native `::placeholder`**: empty date segments ("MM", "DD", "YYYY") render via MUI X's own internal placeholder styling, not a native `::placeholder` pseudo-element — there's no selector to hook the `placeholder-opacity` token onto, same constraint TimePicker.module.css documents for its own empty sections.