@recursica/mui-adapter 0.21.1 → 0.22.0

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

@@ -86,8 +86,14 @@
   );
 }
 
-/* Base explicit reset masking underlying framework defaults */
+/* Base explicit reset masking underlying framework defaults.
+   display: flex + centering: the checkmark icon renders as a nested child of this box
+   (see Checkbox.tsx — icon/checkedIcon are combined nodes, icon inside .input), so this
+   box has to center it itself rather than relying on a parent's centering. */
 .input {
+  display: flex;
+  align-items: center;
+  justify-content: center;
   cursor: pointer; /* HARDCODE: core interaction behavior */
   appearance: none; /* HARDCODE: reset native widget */
   box-sizing: border-box; /* HARDCODE: ensures size includes borders */
@@ -199,7 +205,14 @@
   );
 }
 
+/* display: flex (not the browser default block) blockifies the native inline <label>
+   child per the CSS Display spec's flex-item blockification rule — matches Mantine's
+   own labelWrapper (inline-flex), whose flex context does the same to its label.
+   Without it, the label stays inline and its line box picks up extra half-leading
+   height, visually shifting it below vertical center against the checkbox. */
 .labelWrapper {
+  display: flex;
+  flex-direction: column;
   padding: 0; /* HARDCODE: structural layout reset */
   margin: 0; /* HARDCODE: structural layout reset */
   flex: 1;
@@ -250,26 +263,9 @@
   );
 }
 
-.description {
-  margin-top: 5px; /* HARDCODE: mantine default */
-  color: #868e96; /* HARDCODE: mantine default dimmed */
-  font-size: 12px; /* HARDCODE: mantine default xs */
-  line-height: 1.2;
-}
-
-.error {
-  margin-top: 5px; /* HARDCODE: mantine default */
-  color: #fa5252; /* HARDCODE: mantine default error */
-  font-size: 12px; /* HARDCODE: mantine default xs */
-  line-height: 1.2;
-}
-
-.description[data-disabled="true"],
-.error[data-disabled="true"] {
-  opacity: var(
-    --recursica_ui-kit_components_checkbox-item_variants_states_disabled_properties_opacity
-  );
-}
+/* description/error text renders via AssistiveElement directly (see Checkbox.tsx) —
+   it owns its own tokenized styling. AssistiveElement has no disabled state and
+   must never dim. */
 
 /* CheckboxGroup Layouts */
 .groupRoot {

package/src/components/Checkbox/Checkbox.tsx

@@ -17,6 +17,7 @@ import {
   FormControlLayout,
   type FormControlLayoutProps,
 } from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 
 import styles from "./Checkbox.module.css";
 
@@ -96,6 +97,12 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
     const isChecked = isGrouped
       ? (groupContext.value || []).includes(restRecord.value)
       : !!(restRecord.checked ?? restRecord.defaultChecked);
+    // Only force controlled mode when we actually own the source of truth (grouped) or the
+    // caller explicitly passed `checked` (controlled). A plain `defaultChecked`/neither-prop
+    // usage must stay uncontrolled — otherwise `checked` gets pinned to a value that never
+    // updates, and MUI's native input silently snaps back after every click. Mirrors Switch's
+    // identical `isGrouped ? { checked: ... } : {}` pattern (Switch never had this bug).
+    const isControlled = isGrouped || restRecord.checked !== undefined;
 
     if (readOnly && !!readOnlyComponent) {
       const ReadOnlyComp = readOnlyComponent;
@@ -166,8 +173,9 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
         classes={mergedClassNames}
         disabled={readOnly || disabled || isGroupReadOnly}
         {...(sanitizedProps as unknown as MuiCheckboxProps)}
-        checked={isChecked as boolean}
+        {...(isControlled ? { checked: isChecked as boolean } : {})}
         onChange={handleChange}
+        disableRipple
         sx={label ? { padding: 0 } : undefined}
         icon={<div className={styles.input} />}
         checkedIcon={
@@ -204,25 +212,23 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
             >
               {label as React.ReactNode}
             </label>
-            {description && (
-              <div
-                className={styles.description}
-                data-disabled={
-                  readOnly || disabled || isGroupReadOnly ? true : undefined
-                }
-              >
-                {description}
-              </div>
-            )}
-            {error && (
-              <div
-                className={styles.error}
-                data-disabled={
-                  readOnly || disabled || isGroupReadOnly ? true : undefined
-                }
+            {/* description/error are mutually exclusive — error takes precedence */}
+            {error ? (
+              <AssistiveElement
+                assistiveVariant="error"
+                assistiveWithIcon={false}
               >
                 {error}
-              </div>
+              </AssistiveElement>
+            ) : (
+              description && (
+                <AssistiveElement
+                  assistiveVariant="help"
+                  assistiveWithIcon={false}
+                >
+                  {description}
+                </AssistiveElement>
+              )
             )}
           </div>
         </div>

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

@@ -128,8 +128,6 @@
   background-color: var(--chip-bg);
   border-color: var(--chip-border);
   color: var(--chip-text);
-  min-width: var(--recursica_ui-kit_components_chip_properties_min-width);
-  max-width: var(--recursica_ui-kit_components_chip_properties_max-width);
   box-shadow: var(--recursica_ui-kit_components_chip_properties_elevation);
 
   transition: all 0.2s ease;
@@ -195,11 +193,12 @@
   cursor: not-allowed;
 }
 
-/* Override Mantine's built-in check icon colors and size if we keep it */
-.mantineIconWrapper.mantineIconWrapper {
+/* Selected-state check icon colors and size */
+.checkIconWrapper.checkIconWrapper {
   color: var(--chip-icon);
   width: var(--recursica_ui-kit_components_chip_properties_icon-size);
   height: var(--recursica_ui-kit_components_chip_properties_icon-size);
+  margin-left: 0;
   margin-right: var(
     --recursica_ui-kit_components_chip_properties_icon-text-gap
   );
@@ -219,13 +218,21 @@
   white-space: nowrap;
 }
 
-.leadingIcon {
+/* Doubled selector for specificity parity with MUI's own compound
+   `.MuiChip-root .MuiChip-icon` rule, which otherwise wins outright on a
+   plain single-class selector and leaks its default margin/color. */
+.leadingIcon.leadingIcon {
   display: inline-flex;
   align-items: center;
   justify-content: center;
   color: var(--chip-icon);
   width: var(--recursica_ui-kit_components_chip_properties_icon-size);
   height: var(--recursica_ui-kit_components_chip_properties_icon-size);
+  /* Reset MUI's default icon margin, keep the icon-text gap */
+  margin-left: 0;
+  margin-right: var(
+    --recursica_ui-kit_components_chip_properties_icon-text-gap
+  );
 }
 
 .leadingIcon svg {
@@ -233,7 +240,9 @@
   height: 100%;
 }
 
-.removeIconWrapper {
+/* Doubled selector for specificity parity with MUI's own compound
+   `.MuiChip-root .MuiChip-deleteIcon` rule (same reasoning as .leadingIcon). */
+.removeIconWrapper.removeIconWrapper {
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -247,7 +256,7 @@
   margin: 0;
 }
 
-.removeIconWrapper:focus-visible {
+.removeIconWrapper.removeIconWrapper:focus-visible {
   box-shadow: 0 0 0 2px var(--chip-border); /* HARDCODE: Focus indication */
 }
 

package/src/components/Chip/Chip.tsx

@@ -109,7 +109,7 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
       {...sanitizedProps}
       icon={
         checked ? (
-          <span className={styles.mantineIconWrapper} aria-hidden>
+          <span className={styles.checkIconWrapper} aria-hidden>
             <CheckIcon />
           </span>
         ) : icon ? (

package/src/components/Flex/Flex.tsx

@@ -54,8 +54,8 @@ export const Flex = forwardRef<HTMLDivElement, FlexProps>(function Flex(
   return (
     <MUIBox
       ref={ref}
-      display="flex"
       {...safeProps}
+      display="flex"
       gap={resolvedGap}
       rowGap={resolvedRowGap}
       columnGap={resolvedColumnGap}

package/src/components/FormControlWrapper/FORMCONTROLWRAPPER_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,35 @@
+# FormControlWrapper Implementation Notes
+
+## Architectural Philosophy
+
+Unlike the Mantine adapter (which tears out `Input.Wrapper` entirely), this adapter still
+renders MUI's native `FormControl` as the root — MUI's own `disabled`/`error`/`focused`
+cascading via `FormControlContext` to descendants is useful and kept. What's rebuilt on top is
+label tracking, ARIA generation, and the help/error text block, mirroring the Mantine adapter's
+own approach for consistency across frameworks.
+
+### 1. Self-generated `id` fallback
+
+MUI's `FormControl` doesn't generate or require an `id` itself — every ARIA relationship below
+depends on having one. `React.useId()` provides a fallback (`recursica-fc-${generatedId}`)
+whenever the caller doesn't pass their own `id`, matching the Mantine adapter, so the aria
+wiring below fires by default instead of only when a caller happens to supply an `id`.
+
+### 2. The `cloneElement` ARIA map
+
+Same reasoning as the Mantine adapter: `aria-labelledby`/`aria-describedby`/`aria-errormessage`
+are generated from the resolved `id` and injected onto the child field via `React.cloneElement`,
+since there's no shared context gluing the field to this wrapper's label/assistive text.
+
+- `aria-describedby` and `aria-errormessage` use **separate ids** (`${id}-assistive` /
+  `${id}-error`) rather than one shared id — help text and error text are never both visible
+  at once (error takes priority, same as Mantine), but keeping the ids distinct means each
+  attribute only ever points at content that's actually relevant to it.
+- Neither is set if the child already carries its own explicit `aria-describedby`/
+  `aria-errormessage` — `cloneElement` never overwrites a caller's own value.
+
+### 3. Strict `AssistiveElement` coupling
+
+Same as Mantine: no generic MUI `FormHelperText` used directly here. `FormControlWrapper`
+renders `<AssistiveElement>` itself, resolving to `"error"` or `"help"` depending on whether
+`error` is set, and passing whichever id (`errorId`/`assistiveId`) matches.

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -1,4 +1,4 @@
-import React from "react";
+import React, { useId } from "react";
 import { FormControl, type FormControlProps } from "@mui/material";
 import { filterStylingProps } from "../../utils/filterStylingProps";
 import { Label } from "../Label/Label";
@@ -37,7 +37,7 @@ export const FormControlWrapper = React.forwardRef<
     required,
     disabled,
     focused,
-    id,
+    id: userProvidedId,
 
     formLayout = "stacked",
     labelSize = "default",
@@ -57,19 +57,35 @@ export const FormControlWrapper = React.forwardRef<
 
   const sanitizedProps = filterStylingProps(rest, overStyled);
 
+  // Generate a reliable ID when the caller doesn't provide one — matches the Mantine adapter,
+  // and is what makes the aria wiring below actually fire by default instead of only when a
+  // caller happens to pass their own `id`.
+  const generatedId = useId();
+  const id = userProvidedId || `recursica-fc-${generatedId}`;
+
   // Map descriptions fallback exactly like Mantine
   const finalAssistiveText = assistiveText || description || helperText;
 
-  // ARIA Bindings
-  const labelId = id ? `${id}-label` : undefined;
-  const descriptionId = id ? `${id}-description` : undefined;
+  // ARIA Bindings — separate ids for help text and error text (matching Mantine) so each can
+  // be referenced independently via `aria-describedby`/`aria-errormessage` rather than sharing
+  // one id for both.
+  const labelId = `${id}-label`;
+  const assistiveId = finalAssistiveText ? `${id}-assistive` : undefined;
+  const errorId = error ? `${id}-error` : undefined;
 
-  // Wrap children safely cloning aria hooks down natively
+  // Wrap children safely cloning aria hooks down natively. Never clobber a child's own
+  // explicit aria-describedby/aria-errormessage, matching Mantine's guard.
   const mappedChildren = React.Children.map(children, (child) => {
     if (React.isValidElement(child)) {
+      const childProps = child.props as Record<string, unknown>;
       return React.cloneElement(child, {
         "aria-labelledby": labelId,
-        "aria-describedby": finalAssistiveText ? descriptionId : undefined,
+        ...(assistiveId && !childProps["aria-describedby"]
+          ? { "aria-describedby": assistiveId }
+          : {}),
+        ...(errorId && !childProps["aria-errormessage"]
+          ? { "aria-errormessage": errorId }
+          : {}),
       } as React.HTMLAttributes<HTMLElement>);
     }
     return child;
@@ -117,7 +133,7 @@ export const FormControlWrapper = React.forwardRef<
           {/* Append native assistive block dynamically below the input */}
           {(finalAssistiveText || error) && (
             <AssistiveElement
-              id={descriptionId}
+              id={error ? errorId : assistiveId}
               assistiveVariant={error ? "error" : "help"}
               assistiveWithIcon={assistiveWithIcon}
             >

package/src/components/Grid/Grid.tsx

@@ -152,11 +152,11 @@ const GridBase = forwardRef<HTMLDivElement, GridProps>(function Grid(
     <GridContext.Provider value={{ grow }}>
       <MuiGrid
         ref={ref}
+        {...(safeProps as unknown as MuiGridProps)}
         container
         columns={columns}
         spacing={resolvedGap}
         className={styles.root}
-        {...(safeProps as unknown as MuiGridProps)}
         style={{
           justifyContent: justify,
           alignItems: align,

package/src/components/Group/Group.tsx

@@ -46,6 +46,7 @@ export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
   return (
     <MUIStack
       ref={ref}
+      {...safeProps}
       direction="row"
       flexWrap={wrap || "wrap"}
       justifyContent={justify}
@@ -55,7 +56,6 @@ export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
         ...(resolvedRowGap ? { rowGap: resolvedRowGap } : {}),
         ...(resolvedColumnGap ? { columnGap: resolvedColumnGap } : {}),
       }}
-      {...safeProps}
     >
       {children}
     </MUIStack>

package/src/components/HoverCard/HoverCard.tsx

@@ -85,6 +85,7 @@ const HoverCardBase = function HoverCard({
 
   return (
     <MuiTooltip
+      {...(sanitizedProps as unknown as Record<string, unknown>)}
       title={dropdownNode}
       placement={position as unknown as MuiTooltipProps["placement"]}
       arrow={withBeak}
@@ -104,7 +105,6 @@ const HoverCardBase = function HoverCard({
         },
       }}
       classes={mergedClassNames as unknown as MuiTooltipProps["classes"]}
-      {...(sanitizedProps as unknown as Record<string, unknown>)}
     >
       {/* Tooltip requires a single valid React element child that accepts a ref */}
       {isValidElement(targetNode) ? targetNode : <span>{targetNode}</span>}

package/src/components/Label/Label.module.css

@@ -48,6 +48,7 @@
 
 .innerLayout {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: var(
     --recursica_ui-kit_components_label_properties_label-optional-text-gap
@@ -74,8 +75,8 @@
   display: none !important;
 }
 
-/* MUI propagates .Mui-error to the label automatically on FormControl error. 
-   We explicitly override this bleed to prevent the main label text from turning red, 
+/* MUI propagates .Mui-error to the label automatically on FormControl error.
+   We explicitly override this bleed to prevent the main label text from turning red,
    while allowing the asterisk to take the error color! */
 .root:global(.Mui-error) {
   color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
@@ -86,6 +87,15 @@
   );
 }
 
+/* Same bleed, different trigger: MUI's FormControl propagates .Mui-focused to this label
+   whenever any descendant form control (e.g. a grouped Switch/Checkbox) receives focus,
+   turning the whole label MUI's primary blue via InputLabel's own default styling. No
+   Recursica design calls for a focus-reactive label color, so it's reset here — same fix as
+   the .Mui-error case above, just for the focused trigger instead of the error one. */
+.root:global(.Mui-focused) {
+  color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
+}
+
 .endNodes {
   display: flex;
   align-items: center;
@@ -95,6 +105,9 @@
 }
 
 .optionalText {
+  /* Forces the optional text onto its own row below the label text/end nodes,
+     mirroring mantine-adapter's flex-basis: 100% wrap behavior. */
+  flex-basis: 100%;
   color: inherit;
   font-family: var(
     --recursica_ui-kit_components_label_properties_optional-text_font-family

package/src/components/Label/Label.tsx

@@ -46,9 +46,9 @@ export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
     return (
       <InputLabel
         ref={ref}
+        {...(sanitizedProps as InputLabelProps)}
         shrink={true}
         className={className ? `${styles.root} ${className}` : styles.root}
-        {...(sanitizedProps as InputLabelProps)}
       >
         <div className={styles.innerLayout}>
           <span className={styles.textWrapper}>
@@ -60,11 +60,6 @@ export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
             {labelActionArea && (
               <span className={styles.actionArea}>{labelActionArea}</span>
             )}
-            {!required && labelOptionalText && !labelActionArea && (
-              <span className={styles.optionalText}>
-                {labelOptionalText === true ? "Optional" : labelOptionalText}
-              </span>
-            )}
             {labelWithEditIcon && (
               <button
                 type="button"
@@ -76,6 +71,12 @@ export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
               </button>
             )}
           </div>
+
+          {!required && labelOptionalText && !labelActionArea && (
+            <span className={styles.optionalText}>
+              {labelOptionalText === true ? "(optional)" : labelOptionalText}
+            </span>
+          )}
         </div>
       </InputLabel>
     );

package/src/components/Menu/Menu.tsx

@@ -26,12 +26,12 @@ export const Menu = forwardRef<HTMLDivElement, MenuProps>(function Menu(
   return (
     <MuiMenu
       ref={ref}
+      {...(sanitizedProps as MuiMenuProps)}
       className={`${styles.dropdown} ${className || ""}`}
       classes={{
         paper: styles.dropdown,
         list: styles.dropdown,
       }}
-      {...(sanitizedProps as MuiMenuProps)}
     />
   );
 });

package/src/components/Modal/Modal.tsx

@@ -77,11 +77,11 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(function ModalRoot(
   return (
     <MuiDialog
       ref={ref}
+      {...(sanitizedProps as MuiDialogProps)}
       className={`${styles.root} ${className || ""}`}
       classes={{
         paper: styles.inner,
       }}
-      {...(sanitizedProps as MuiDialogProps)}
       open={
         opened ||
         ((sanitizedProps as Record<string, unknown>).open as boolean) ||

package/src/components/NumberInput/NumberInput.tsx

@@ -137,6 +137,7 @@ export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
           /* Naked Input execution safely decoupled from Mui's macro Input.Wrapper DOM hooks */
           <MuiNumberInput
             ref={ref}
+            {...(sanitizedProps as unknown as MuiNumberInputProps)}
             classes={mergedClassNames}
             disabled={disabled}
             value={value}
@@ -154,7 +155,6 @@ export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
               step,
               ...(restRecord.inputProps as Record<string, unknown>),
             }}
-            {...(sanitizedProps as unknown as MuiNumberInputProps)}
           />
         }
       />

package/src/components/Pagination/Pagination.tsx

@@ -63,13 +63,13 @@ const _Pagination = forwardRef<HTMLDivElement, PaginationProps>(
     return (
       <div ref={ref} className={stylingParams.className}>
         <MuiPagination
+          {...(sanitizedProps as MuiPaginationProps)}
           count={total}
           showFirstButton={withEdges}
           showLastButton={withEdges}
           hidePrevButton={withControls === false ? true : undefined}
           hideNextButton={withControls === false ? true : undefined}
           classes={stylingParams.classNames}
-          {...(sanitizedProps as MuiPaginationProps)}
         />
       </div>
     );

package/src/components/Panel/Panel.tsx

@@ -124,7 +124,7 @@ export const PanelFooter = forwardRef<HTMLDivElement, PanelFooterProps>(
       ? `${styles.footer} ${classNameProp}`
       : styles.footer;
 
-    return <div ref={ref} className={finalClassName} {...sanitizedProps} />;
+    return <div ref={ref} {...sanitizedProps} className={finalClassName} />;
   },
 );
 PanelFooter.displayName = "PanelFooter";

package/src/components/Radio/Radio.module.css

@@ -70,7 +70,7 @@
   );
 }
 
-.root .inner {
+.inner {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -82,7 +82,7 @@
     --recursica_ui-kit_components_radio-button-item_properties_text_font-size
   );
   /* Mathematically syncs the physical input radio bounding block visually with the center of the text's first line.
-     NOTE: Since the Figma line-height token resolves to an 'em' length (e.g. 1.05em), we CANNOT multiply it by font-size in CSS. 
+     NOTE: Since the Figma line-height token resolves to an 'em' length (e.g. 1.05em), we CANNOT multiply it by font-size in CSS.
      Instead, it naturally evaluates to the correct height because we applied the font-size above. */
   margin-top: calc(
     (
@@ -95,10 +95,16 @@
   );
 }
 
-/* Base explicit reset masking underlying framework defaults */
-.root .radio {
+/* Base explicit reset masking underlying framework defaults.
+   MUI's native <input type="radio"> stays invisible (SwitchBase overlays it with
+   opacity: 0) — it is not the visual circle. The circle is drawn by our own
+   icon/checkedIcon node (see Radio.tsx), a sibling of the input, so it's styled
+   here directly rather than through MUI's `classes` prop (MUI has no "radio" slot). */
+.radio {
+  display: flex;
+  align-items: center;
+  justify-content: center;
   cursor: pointer; /* HARDCODE: core interaction behavior */
-  appearance: none; /* HARDCODE: reset native widget */
   box-sizing: border-box; /* HARDCODE: ensures size includes borders */
   width: var(--recursica_ui-kit_components_radio-button_properties_size);
   height: var(--recursica_ui-kit_components_radio-button_properties_size);
@@ -121,7 +127,7 @@
 }
 
 /* Checked State */
-.root .radio:checked {
+.radioChecked {
   background-color: var(
     --recursica_ui-kit_components_radio-button_variants_selection-states_selected_properties_colors_background-color
   );
@@ -130,11 +136,14 @@
   );
 }
 
-/* Disabled State (colors now differ per selection state, so each combination is mapped explicitly) */
-.root .radio:disabled {
+/* Disabled State (colors now differ per selection state; MUI applies its `disabled`
+   classKey to the same root element as `root`, so `.root.disabled` targets the
+   actual disabled instance and cascades to the decorative icon div inside it —
+   mirrors Checkbox's split). */
+.root.disabled .radio {
   cursor: not-allowed; /* HARDCODE: disabled state default */
 }
-.root .radio:disabled:not(:checked) {
+.root.disabled .radio:not(.radioChecked) {
   opacity: var(
     --recursica_ui-kit_components_radio-button_variants_selection-states_unselected_variants_states_disabled_properties_opacity
   );
@@ -145,7 +154,7 @@
     --recursica_ui-kit_components_radio-button_variants_selection-states_unselected_variants_states_disabled_properties_colors_border-color
   );
 }
-.root .radio:checked:disabled {
+.root.disabled .radioChecked {
   opacity: var(
     --recursica_ui-kit_components_radio-button_variants_selection-states_selected_variants_states_disabled_properties_opacity
   );
@@ -157,29 +166,32 @@
   );
 }
 
-.root .icon {
-  position: absolute;
-  inset: 0;
-  margin: auto;
+.icon {
   pointer-events: none;
   width: var(--recursica_ui-kit_components_radio-button_properties_icon-size);
   height: var(--recursica_ui-kit_components_radio-button_properties_icon-size);
 }
 /* No icon-color token exists for the unselected state (no icon is visible then) */
-.root .radio:checked + .iconWrapper .icon,
-.root .radio:checked + .icon {
+.radioChecked .icon {
   color: var(
     --recursica_ui-kit_components_radio-button_variants_selection-states_selected_properties_colors_icon-color
   );
 }
-.root .radio:checked:disabled + .iconWrapper .icon,
-.root .radio:checked:disabled + .icon {
+.root.disabled .radioChecked .icon {
   color: var(
     --recursica_ui-kit_components_radio-button_variants_selection-states_selected_variants_states_disabled_properties_colors_icon-color
   );
 }
 
 .root .labelWrapper {
+  /* display: flex (not the browser default block) blockifies the native inline
+     <label> child per the CSS Display spec's flex-item blockification rule —
+     matches Mantine's own labelWrapper (inline-flex), whose flex context does
+     the same to its label. Without it, the label stays inline and its line box
+     picks up extra half-leading height, visually shifting it below vertical
+     center against the circle. */
+  display: flex;
+  flex-direction: column;
   padding: 0; /* HARDCODE: structural layout reset */
   margin: 0; /* HARDCODE: structural layout reset */
   flex: 1;
@@ -230,23 +242,6 @@
   );
 }
 
-.root .description {
-  margin-top: 5px; /* HARDCODE: mantine default */
-  color: #868e96; /* HARDCODE: mantine default dimmed */
-  font-size: 12px; /* HARDCODE: mantine default xs */
-  line-height: 1.2;
-}
-
-.root .error {
-  margin-top: 5px; /* HARDCODE: mantine default */
-  color: #fa5252; /* HARDCODE: mantine default error */
-  font-size: 12px; /* HARDCODE: mantine default xs */
-  line-height: 1.2;
-}
-
-.root .description[data-disabled="true"],
-.root .error[data-disabled="true"] {
-  opacity: var(
-    --recursica_ui-kit_components_radio-button-item_variants_states_disabled_properties_opacity
-  );
-}
+/* description/error text renders via AssistiveElement directly (see Radio.tsx) —
+   it owns its own tokenized styling. AssistiveElement has no disabled state and
+   must never dim. */