@recursica/mui-adapter 0.3.0 → 0.5.0

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

@@ -0,0 +1,74 @@
+/* EXEMPTIONS:
+   This component is a placeholder stub. Once fully implemented, its specific
+   tokens will be fully wired up to direct styles. */
+
+/* recursica-ignore: --recursica_ui-kit_components_avatar_properties_elevation */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_height */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_icon-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-family */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-style */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-weight */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_letter-spacing */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_line-height */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_text-decoration */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_default_properties_width */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_height */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_icon-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-family */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-style */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-weight */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_letter-spacing */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_line-height */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_text-decoration */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_large_properties_width */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_height */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_icon-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-family */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-style */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-weight */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_letter-spacing */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_line-height */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_text-decoration */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_sizes_small_properties_width */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_properties_border-radius */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_properties_padding */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_ghost_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_ghost_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_ghost_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_ghost_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_outline_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_outline_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_outline_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_outline_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_solid_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_solid_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_solid_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_icon_variants_types_solid_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_image_properties_border-radius */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_image_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_image_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_image_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_image_properties_padding */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_properties_border-radius */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_properties_padding */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_ghost_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_ghost_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_ghost_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_ghost_properties_colors_text-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_outline_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_outline_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_outline_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_outline_properties_colors_text-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_solid_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_solid_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_solid_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_avatar_variants_styles_text_variants_types_solid_properties_colors_text-color */

package/src/components/Avatar/Avatar.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import "./Avatar.module.css";
 
 export type AvatarProps = React.HTMLAttributes<HTMLDivElement>;
 

package/src/components/Badge/Badge.module.css

@@ -0,0 +1,29 @@
+/* EXEMPTIONS:
+   This component is a placeholder stub. Once fully implemented, its specific
+   tokens will be fully wired up to direct styles. */
+
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_border-radius */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_elevation */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_padding-horizontal */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_padding-vertical */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_font-family */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_font-size */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_font-style */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_font-weight */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_letter-spacing */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_line-height */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_text-decoration */
+/* recursica-ignore: --recursica_ui-kit_components_badge_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_alert_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_alert_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_alert_properties_colors_text */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_primary-color_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_primary-color_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_primary-color_properties_colors_text */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_success_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_success_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_success_properties_colors_text */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_warning_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_warning_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_badge_variants_styles_warning_properties_colors_text */

package/src/components/Badge/Badge.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import "./Badge.module.css";
 
 export type BadgeProps = React.HTMLAttributes<HTMLDivElement>;
 

package/src/components/Breadcrumb/Breadcrumb.module.css

@@ -0,0 +1,6 @@
+/* EXEMPTIONS:
+   This component is a placeholder stub. Once fully implemented, its specific
+   tokens will be fully wired up to direct styles. */
+
+/* recursica-ignore: --recursica_ui-kit_components_breadcrumb_properties_item-gap */
+/* recursica-ignore: --recursica_ui-kit_components_breadcrumb_properties_padding */

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import "./Breadcrumb.module.css";
 
 export type BreadcrumbProps = React.HTMLAttributes<HTMLDivElement>;
 

package/src/components/Button/BUTTON_IMPLEMENTATION_NOTES.md

@@ -15,3 +15,19 @@ We explicitly pass `disableRipple` and `disableElevation` to block MUI's dynamic
 **Accessibility:**
 
 - We inject a development-time warning explicitly requiring `aria-label` when the component detects an icon-only configuration.
+
+---
+
+## Loader color contrast
+
+**Decision:** When a Button is in a loading state, the `Recursica Loader` component is injected via the `loadingIndicator` prop. The `Loader` component strictly defines its own colors and styles per variant, meaning it does not automatically inherit the text color (`currentColor`) from the Button.
+
+**Constraint:** This can lead to contrast issues (e.g., a blue dots loader inside a solid blue button). Design has explicitly decided not to address this at the moment. As such, developers using the `loading` prop must be aware that the loader's color is fixed by its internal tokens, not by the button's context.
+
+---
+
+## Loading state enforces disabled state
+
+**Decision:** When `loading={true}` is passed to the Button, the component explicitly forces `disabled={true}` natively on the underlying element.
+
+**Implementation:** This ensures that loading buttons automatically inherit the brand theme disabled opacities (via the `:disabled` CSS pseudo-class) rather than relying solely on MUI's internal loading opacity adjustments.

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

@@ -44,7 +44,7 @@
 }
 
 /* Internal layout logic for Truncation */
-.root > * {
+.root > *:not(:global(.MuiButton-loadingIndicator)) {
   min-width: 0;
   position: relative;
   z-index: 1;
@@ -66,42 +66,101 @@
   font-size: inherit;
   line-height: inherit;
 }
+.root[data-loading="true"] .labelText {
+  visibility: hidden;
+}
+
+/* 
+ * Keep the loader fully opaque, but make the background transparent 
+ * to create contrast for solid variants without changing the loader color. 
+ */
+.root[data-loading="true"] {
+  opacity: 1 !important;
+}
+
+.root[data-size="default"][data-variant="solid"][data-loading="true"] {
+  background-color: color-mix(
+    in srgb,
+    var(
+        --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background
+      )
+      calc(
+        var(
+            --recursica_ui-kit_components_button_variants_sizes_default_properties_disabled-opacity
+          ) *
+          100%
+      ),
+    transparent
+  ) !important;
+}
+
+.root[data-size="small"][data-variant="solid"][data-loading="true"] {
+  background-color: color-mix(
+    in srgb,
+    var(
+        --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_background
+      )
+      calc(
+        var(
+            --recursica_ui-kit_components_button_variants_sizes_small_properties_disabled-opacity
+          ) *
+          100%
+      ),
+    transparent
+  ) !important;
+}
 
 /* ==== SIZES ==== */
 .root[data-size="default"] {
-  border-radius: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_border-radius
-  );
   height: var(
     --recursica_ui-kit_components_button_variants_sizes_default_properties_height
   );
+}
+.root[data-size="default"][data-content="label"] {
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_label_variants_sizes_default_properties_border-radius
+  );
   min-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_min-width
+    --recursica_ui-kit_components_button_variants_content_label_variants_sizes_default_properties_min-width
   );
   padding: 0
     var(
-      --recursica_ui-kit_components_button_variants_sizes_default_properties_horizontal-padding
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_default_properties_horizontal-padding
     );
 }
-.root[data-size="default"] .labelText {
-  max-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_default_properties_max-label-width
+.root[data-size="default"][data-content="icon-label"] {
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_default_properties_border-radius
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_default_properties_min-width
   );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_default_properties_horizontal-padding
+    );
 }
-.root[data-size="small"] {
+.root[data-size="default"][data-content="icon-only"] {
   border-radius: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_border-radius
-  );
-  height: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_border-radius
   );
   min-width: var(
-    --recursica_ui-kit_components_button_variants_sizes_small_properties_min-width
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_min-width
   );
   padding: 0
     var(
-      --recursica_ui-kit_components_button_variants_sizes_small_properties_horizontal-padding
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_default_properties_horizontal-padding
     );
+}
+.root[data-size="default"] .labelText {
+  max-width: var(
+    --recursica_ui-kit_components_button_variants_sizes_default_properties_max-label-width
+  );
+}
+.root[data-size="small"] {
+  height: var(
+    --recursica_ui-kit_components_button_variants_sizes_small_properties_height
+  );
 
   /* Override specific typography for small */
   font-family: var(
@@ -123,6 +182,42 @@
     )
   );
 }
+.root[data-size="small"][data-content="label"] {
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_border-radius
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_label_variants_sizes_small_properties_horizontal-padding
+    );
+}
+.root[data-size="small"][data-content="icon-label"] {
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_small_properties_border-radius
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-label_variants_sizes_small_properties_horizontal-padding
+    );
+}
+.root[data-size="small"][data-content="icon-only"] {
+  border-radius: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_border-radius
+  );
+  min-width: var(
+    --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_min-width
+  );
+  padding: 0
+    var(
+      --recursica_ui-kit_components_button_variants_content_icon-only_variants_sizes_small_properties_horizontal-padding
+    );
+}
 .root[data-size="small"] .labelText {
   max-width: var(
     --recursica_ui-kit_components_button_variants_sizes_small_properties_max-label-width
@@ -175,8 +270,11 @@
 }
 
 /* Icon-only logic overrides */
-.root[data-icon-only] .MuiButton-startIcon,
-.root[data-icon-only] .MuiButton-endIcon {
+.root[data-content="icon-only"] .labelText {
+  display: none;
+}
+.root[data-content="icon-only"] .MuiButton-startIcon,
+.root[data-content="icon-only"] .MuiButton-endIcon {
   margin-right: 0;
   margin-left: 0;
 }
@@ -245,10 +343,18 @@
     --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text
   );
 }
+.root[data-variant="solid"] .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_icon-color
+  );
+}
 .root[data-variant="solid"]:hover:not(:disabled):not(:global(.Mui-disabled)) {
   color: var(
     --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-hover
   );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_hover-elevation
+  );
 }
 
 /* OUTLINE */
@@ -269,10 +375,18 @@
     --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text
   );
 }
+.root[data-variant="outline"] .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_icon-color
+  );
+}
 .root[data-variant="outline"]:hover:not(:disabled):not(:global(.Mui-disabled)) {
   color: var(
     --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text-hover
   );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_hover-elevation
+  );
 }
 
 /* TEXT */
@@ -293,8 +407,30 @@
     --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text
   );
 }
+.root[data-variant="text"] .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_icon-color
+  );
+}
 .root[data-variant="text"]:hover:not(:disabled):not(:global(.Mui-disabled)) {
   color: var(
     --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-hover
   );
+  box-shadow: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_hover-elevation
+  );
 }
+
+/* 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_line-height */
+/* 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.stories.tsx

@@ -10,6 +10,9 @@ const meta: Meta<ButtonStoryProps> = {
   component: Button,
   tags: ["autodocs"],
   argTypes: {
+    disabled: {
+      control: "boolean",
+    },
     variant: {
       control: "select",
       options: ["solid", "outline", "text"],
@@ -20,6 +23,30 @@ const meta: Meta<ButtonStoryProps> = {
       options: ["default", "small"],
       description: "The size of the button",
     },
+    loading: {
+      control: "boolean",
+      description: "Sets the button to a loading state",
+    },
+    useRecursicaLoader: {
+      control: "boolean",
+      description:
+        "Use the Recursica Loader component instead of the default Mantine loader",
+    },
+    loaderVariant: {
+      control: "select",
+      options: ["oval", "bars", "dots"],
+      description: "The visual variant of the Recursica Loader",
+    },
+    loaderSize: {
+      control: "select",
+      options: [undefined, "sm", "md", "lg", "small", "default", "large"],
+      description: "The size variant for the loader",
+    },
+  },
+  args: {
+    useRecursicaLoader: true,
+    loaderVariant: "oval",
+    loaderSize: undefined,
   },
   parameters: {
     controls: {
@@ -37,6 +64,10 @@ const meta: Meta<ButtonStoryProps> = {
         "onChange",
         "value",
         "checked",
+        "loading",
+        "useRecursicaLoader",
+        "loaderVariant",
+        "loaderSize",
       ],
     },
   },
@@ -145,3 +176,20 @@ export const TruncatedLabel: Story = {
     </div>
   ),
 };
+
+export const Loading: Story = {
+  args: {
+    children: "Saving Changes",
+    variant: "solid",
+    size: "default",
+    loading: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "When `loading={true}` is applied, the Button injects the Recursica `<Loader />` component. Per Recursica design rules, placing a Button in a loading state automatically forces the `disabled={true}` state on the underlying element. This ensures the button immediately receives the brand theme disabled opacities without relying solely on semantic logic.",
+      },
+    },
+  },
+};

package/src/components/Button/Button.tsx

@@ -1,4 +1,6 @@
 import React, { forwardRef } from "react";
+import { Loader } from "../Loader/Loader";
+import type { RecursicaLoaderProps } from "../Loader/Loader";
 import {
   Button as MuiButton,
   type ButtonProps as MuiButtonProps,
@@ -17,6 +19,12 @@ export interface RecursicaButtonProps {
    * For polymorphic support (e.g., `component="a"`), native to MUI.
    */
   component?: React.ElementType;
+  /** Which Recursica Loader variant to use */
+  loaderVariant?: RecursicaLoaderProps["variant"];
+  /** The size variant for the loader */
+  loaderSize?: RecursicaLoaderProps["size"];
+  /** Whether to use the Recursica loader or fallback to the Mantine loader */
+  useRecursicaLoader?: boolean;
 }
 
 export type ButtonProps = RecursicaOverStyled<
@@ -54,6 +62,9 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
       icon,
       children,
       overStyled = false,
+      loaderVariant = "oval",
+      loaderSize,
+      useRecursicaLoader = true,
       ...rest
     },
     ref,
@@ -67,8 +78,15 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
 
     const hasStartIcon = !!icon || !!restRecord["startIcon"];
     const hasEndIcon = !!restRecord["endIcon"];
-    const isIconOnly =
-      (hasStartIcon || hasEndIcon) && !hasVisibleChildren(children);
+    const hasVisibleText = hasVisibleChildren(children);
+    const isIconOnly = (hasStartIcon || hasEndIcon) && !hasVisibleText;
+
+    let contentType = "label";
+    if (isIconOnly) {
+      contentType = "icon-only";
+    } else if (hasStartIcon || hasEndIcon) {
+      contentType = "icon-label";
+    }
 
     if (
       typeof process !== "undefined" &&
@@ -91,12 +109,24 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     // 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");
+
+    let loadingIndicator = restRecord.loadingIndicator as React.ReactNode;
+    if (useRecursicaLoader) {
+      loadingIndicator = (
+        <Loader variant={loaderVariant} size={resolvedLoaderSize} />
+      );
+    }
+
     return (
       <MuiButton
         ref={ref}
         disableRipple
         disableElevation
         className={finalClass}
+        loading={!!restRecord.loading}
+        loadingIndicator={loadingIndicator}
         startIcon={
           icon != null ? (
             <span className={styles.iconWrapper} aria-hidden>
@@ -106,8 +136,10 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
         }
         data-variant={variant}
         data-size={size}
-        {...(isIconOnly ? { "data-icon-only": "" } : {})}
+        data-content={contentType}
+        {...(restRecord.loading ? { "data-loading": "true" } : {})}
         {...sanitizedProps}
+        disabled={!!restRecord.disabled || !!restRecord.loading}
       >
         <span className={styles.labelText}>{children}</span>
       </MuiButton>

package/src/components/Card/Card.module.css

@@ -0,0 +1,38 @@
+/* EXEMPTIONS:
+   This component is a placeholder stub. Once fully implemented, its specific
+   tokens will be fully wired up to direct styles. */
+
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_borders_border-radius */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_borders_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_colors_background */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_colors_border-color */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_colors_content */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_colors_divider-color */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_colors_footer-background */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_colors_header-background */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_colors_title */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_fontFamily */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_fontSize */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_fontStyle */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_fontWeight */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_letterSpacing */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_lineHeight */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_textCase */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_content-style_textDecoration */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_divider-size */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_elevations_elevation */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_footer-padding */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-padding */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_fontFamily */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_fontSize */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_fontStyle */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_fontWeight */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_letterSpacing */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_lineHeight */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_textCase */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_header-style_textDecoration */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_max-width */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_min-width */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_padding */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_section-gap */
+/* recursica-ignore: --recursica_ui-kit_components_card_properties_vertical-gutter */

package/src/components/Card/Card.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import "./Card.module.css";
 
 export type CardProps = React.HTMLAttributes<HTMLDivElement>;
 

package/src/components/Checkbox/Checkbox.module.css

@@ -0,0 +1,39 @@
+/* EXEMPTIONS:
+   This component is a placeholder stub. Once fully implemented, its specific
+   tokens will be fully wired up to direct styles. */
+
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-group_properties_item-gap */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-group_properties_padding */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_gutter */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_top-bottom-margin */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-group_variants_layouts_side-by-side_properties_vertical-padding */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-group_variants_layouts_stacked_properties_label-field-gap */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-group_variants_layouts_stacked_properties_top-bottom-margin */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_colors_disabled-text */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_colors_text */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_disabled-opacity */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_label-gap */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_max-width */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_font-family */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_font-size */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_font-style */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_font-weight */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_letter-spacing */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_line-height */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_text-decoration */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox-item_properties_text_text-transform */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_border-radius */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_background-checked */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_background-indeterminate */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_background-unchecked */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_border-checked */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_border-indeterminate */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_border-unchecked */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_disabled-background */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_disabled-border */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_disabled-icon */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_disabled-opacity */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_icon-size */
+/* recursica-ignore: --recursica_ui-kit_components_checkbox_properties_size */

package/src/components/Checkbox/Checkbox.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import "./Checkbox.module.css";
 
 export type CheckboxProps = React.HTMLAttributes<HTMLDivElement>;