@recursica/mui-adapter 0.21.1 → 0.23.0

package/src/components/Switch/SWITCH_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,123 @@
+# Switch Implementation Notes
+
+Decisions and gotchas specific to wrapping `@mui/material`'s `Switch` for the UI Kit's Switch.
+
+## Label/description/error
+
+MUI's `Switch` has no built-in label/description/error rendering — built by hand here.
+The label is a plain `<label>`; description/error render through the shared
+`AssistiveElement` component (`assistiveWithIcon={false}`) instead of local styled divs,
+so they inherit real design tokens rather than hardcoded Mantine defaults.
+
+## `Switch.Group` compound export
+
+`SwitchGroup.tsx` existed but wasn't attached as `Switch.Group`. Fixed.
+
+## `SwitchGroup` didn't control its children — now fixed
+
+MUI's `FormGroup` has no controlled-value concept — no equivalent to Mantine's real
+`Switch.Group`, which threads a `string[]` of checked values and `checked`/`onChange` to each
+child via context. This adapter's `SwitchGroup` used to destructure and discard
+`value`/`defaultValue`/`onChange` entirely — purely cosmetic.
+
+Fixed the same way this adapter's own `Checkbox`/`CheckboxGroup` already solved the identical
+problem (a closer, in-repo precedent than `Accordion`, which the notes previously pointed to
+without checking Checkbox first): a `SwitchGroupContext` provider on `SwitchGroup` carrying
+`value`/`onChange`/`name`/`readOnly`, consumed by `Switch` to compute `isChecked` from array
+membership and to translate each toggle into an add/remove against that array before calling
+the group's `onChange`. Standalone (ungrouped) `Switch` usage is untouched — the group-derived
+`checked`/`onChange` are only spread onto `<MuiSwitch>` when a `SwitchGroupContext` is present.
+Verified live: initial `value`/`defaultValue` now renders correctly, clicking a sibling
+switch toggles only its own entry in the array, and `readOnly` on the group disables every
+child — all confirmed against the existing `SwitchGroup.stories.tsx` scenarios via Playwright.
+
+## Thumb icon (check/x glyph)
+
+MUI's `icon`/`checkedIcon` props are the _same mechanism_ MUI uses internally to render its
+own default circular thumb (`icon: <the circle>, checkedIcon: <the circle>`, then
+spread-overwritten by whatever public `icon`/`checkedIcon` the caller passes) — confirmed
+against MUI's own `Switch.js`/`SwitchBase.js` source. Passing a raw glyph into them replaces
+the whole thumb circle, it doesn't add an icon inside it.
+
+Fixed the same way `Checkbox` in this adapter already solved the identical problem: build our
+own combined node — a `.thumb`-styled `<span>` wrapping `.thumbIconWrapper` with both
+`CheckIcon`/`CloseIcon` (inline SVGs, same paths as Mantine's, copied rather than imported
+since mui-adapter doesn't depend on `@mantine/core`) — and pass _that same node reference_ as
+both `icon` and `checkedIcon` (mirroring MUI's own `icon={icon} checkedIcon={icon}` pattern).
+Same reference means it never unmounts/remounts on toggle, which is what lets the two glyphs
+crossfade via CSS opacity instead of a hard swap — matching Mantine's `thumbIcon` behavior.
+Verified against a live Storybook via adapter-tester (geometry + SVG count now match Mantine
+1:1 across Default/Static Variations stories).
+
+## Track/thumb geometry, checked-state selectors, focus ring
+
+Original CSS was a copy of mantine-adapter's file, but MUI's DOM is structurally different
+(`track`/`switchBase` are siblings, not nested; MUI hardcodes its own root box, hit-area
+padding, and thumb travel distance for its own 20px default thumb). Fixed by driving
+`.switchRoot`/`.switchBase`/`.thumb` sizing entirely from our tokens, replacing
+`input:checked + .track` sibling selectors (never matched in MUI's DOM) with `:has()`-scoped
+selectors, adding an explicit focus ring from `--recursica_brand_states_focus_*` tokens, and
+hardcoding `color="default"` so MUI's own primary-blue hover/focus circle never activates.
+Verified via live measurement (adapter-tester): track/thumb box dimensions now match Mantine
+exactly (64×28 track, 20×20 thumb).
+
+Two gotchas worth flagging for future MUI adapter work:
+
+1. `classes.root` targets MUI's own switch span, but this component's outer wrapper `<div>`
+   (switch+label row) also uses `.root` — sizing one squeezes the other. Split into
+   `.switchRoot` (MUI switch only) vs `.root` (outer wrapper, cursor only).
+2. CSS Modules hashes literal MUI state classes (`Mui-checked`, `Mui-focusVisible`) unless
+   wrapped in `:global()` — same pattern already used in `Accordion`/`Button`.
+
+## Disabled-state opacity didn't reach the thumb
+
+**Found 2026-08-14, reported by Matt:** the Read Only story's thumb stayed full-color/opacity
+while Mantine's dimmed along with the track. Same root cause as the geometry work above:
+Mantine nests `.thumb` inside `.track`, so an `opacity` on `.track` visually dims the thumb for
+free; MUI has them as siblings, so the disabled-opacity selectors (which only targeted
+`.track`) never touched the thumb at all. Fixed by adding `.thumb` to both selectors alongside
+`.track`. Verified live: thumb now dims identically to Mantine in both the plain-disabled and
+disabled-checked cases.
+
+## Track opacity — MUI's own always-on defaults, unrelated to our tokens
+
+MUI's `SwitchTrack` styled component sets `opacity: 0.38` unconditionally (its own faded-pill
+baseline), and separately `.Mui-checked + .track { opacity: 0.5 }` when checked — neither has
+an equivalent in our token schema, and neither was being cancelled. Result: every enabled track
+was dimmed by MUI's own opacity, most visibly on the checked state (deep red washed out to
+pink). Fixed with an explicit `opacity: 1` in both the base `.track` rule and the
+`.root:has(input:checked) .track` rule (needed in both — MUI's checked-specific selector is
+more specific than its own base rule, so overriding only the base wasn't enough). Disabled-state
+opacity is unaffected; those selectors are already more specific than either of these.
+
+## Focus ring was on the thumb's hit-area circle, not the track
+
+`.switchBase:global(.Mui-focusVisible)` is MUI's actual focusable element, but it's sized to
+the thumb's 20×20 hit area, not the 64×28 track — so the ring drew a small circle instead of
+outlining the switch. Moved to `.switchBase:global(.Mui-focusVisible) ~ .track` (siblings under
+`.switchRoot`, switchBase first) so the ring renders on the track itself. Mantine-adapter had
+the mirror-image bug: no override at all, so Mantine's own default outline (blue) showed on the
+hidden `<input>` — fixed there with `.root input:focus-visible { outline: none }` +
+`.root input:focus-visible + .track { ... }`, drawing the same Recursica-token ring in the same
+place.
+
+## `classNames` prop-name bug — external override was silently inert
+
+The external override merge read `restRecord.classNames`, but MUI's actual prop is `classes`
+(that's Mantine's naming, copied over by mistake) — fixed. Note only `root`/`track`/
+`switchBase` are real MUI `classes` slots; `body`/`trackLabel`/`labelWrapper`/`label` are this
+component's own hardcoded elements (styled directly in JSX, not via MUI's `classes` prop) and
+remain unreachable through this override path — a separate, pre-existing gap, not something the
+prop-name fix could address.
+
+## `SwitchGroup` side-by-side layout always rendered as if stacked
+
+**Found 2026-08-14, reported by Matt:** the `SideBySideLayout` story showed the group label
+above the switches instead of beside them. Root cause: `SwitchGroup` passed the switch-item's
+own inline label max-width token (200px) as the group's `controlMaxWidth` — but the mandatory
+side-by-side label column is a fixed 224px, wider than that cap, so the label always overflowed
+onto its own line regardless of layout mode. Reproduced identically in Mantine (same code
+pattern, not a MUI-only bug). Fixed by not capping the group's control width at all — each
+switch's own label already wraps at 200px via `.labelWrapper`, so no group-level cap is needed.
+Verified live in both adapters: side-by-side now shows the label column at left with the
+switches beside it; stacked layout unaffected.

package/src/components/Switch/Switch.module.css

@@ -1,13 +1,46 @@
-/* HARDCODED VALUES 
+/* HARDCODED VALUES
  *
  * 1. track border: none; (we do not use border for the switch track)
  * 2. thumb border: none; (we do not use border for the thumb)
- * 3. outline: none; (focus rings handled internally by mantine)
+ * 3. .switchBase background-color: transparent; (cancels MUI's built-in primary-color
+ *    hover/focus circle so only our tokens and our own explicit focus ring show — see
+ *    SWITCH_IMPLEMENTATION_NOTES.md #5)
+ * 4. .track opacity: 1; (cancels MUI's own always-on track opacity — 0.38 unchecked, 0.5
+ *    checked, both MUI defaults with no equivalent in our tokens; our disabled-state opacity
+ *    rules below are the only intended dimming)
  */
 
 .root {
   /* Provide a stable cursor when not disabled */
   cursor: pointer;
+}
+
+.root:has(input:disabled) {
+  cursor: not-allowed;
+}
+
+/* Sizes MUI's actual switch root span (mapped via classes.root — MUI requires that exact key,
+   but the class name it points to is ours). Kept separate from .root above: when a label is
+   present, .root is applied to *this component's own outer wrapper div* (switch + label side
+   by side), not to the switch itself — giving both the same box-model rules would squeeze that
+   wrapper (and the label inside it) down to the track's own width. See
+   SWITCH_IMPLEMENTATION_NOTES.md #5. */
+.switchRoot {
+  /* Cancel MUI's own hardcoded root box (width: 58px, height: 38px, padding: 12px,
+     overflow: hidden for the medium size) — without this the track/thumb tokens below get
+     clipped/shrunk to MUI's default geometry instead of driving the real size. */
+  width: var(--recursica_ui-kit_components_switch_properties_track-width);
+  height: calc(
+    var(--recursica_ui-kit_components_switch_properties_thumb-height) +
+      (
+        var(
+            --recursica_ui-kit_components_switch_properties_track-inner-padding
+          ) *
+          2
+      )
+  );
+  padding: 0;
+  overflow: visible;
 
   --switch-track-padding: var(
     --recursica_ui-kit_components_switch_properties_track-inner-padding
@@ -23,17 +56,19 @@
   );
 }
 
-.root:has(input:disabled) {
-  cursor: not-allowed;
-}
-
 /* Track/thumb dim per selection state; label dims via its own (single, state-agnostic) token */
-.root:has(input:checked:disabled) .track {
+/* In mantine-adapter, .thumb nests inside .track, so dimming .track's opacity visually dims
+   the thumb too "for free". MUI's DOM has .track and .thumb as siblings (documented
+   structural difference, see SWITCH_IMPLEMENTATION_NOTES.md), so the same selector only dimmed
+   the track — the thumb stayed at full color/opacity. Each selector targets both explicitly. */
+.root:has(input:checked:disabled) .track,
+.root:has(input:checked:disabled) .thumb {
   opacity: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_variants_states_disabled_properties_opacity
   );
 }
-.root:has(input:disabled):not(:has(input:checked)) .track {
+.root:has(input:disabled):not(:has(input:checked)) .track,
+.root:has(input:disabled):not(:has(input:checked)) .thumb {
   opacity: var(
     --recursica_ui-kit_components_switch_variants_selection-states_unselected_variants_states_disabled_properties_opacity
   );
@@ -51,7 +86,7 @@
     --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_track-color
   );
 }
-.root input:checked + .track:hover {
+.root:has(input:checked) .track:hover {
   background-color: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_track-color
   );
@@ -69,28 +104,71 @@
   box-shadow: var(
     --recursica_ui-kit_components_switch_properties_track-elevation
   );
-  padding: var(--switch-track-padding);
   border: none; /* HARDCODE */
-
-  /* Mantine uses variables internally for these, but we explicitly override the CSS to ensure our dimensions */
-  --switch-width: var(--switch-track-width);
-  --switch-height: calc(
-    var(--switch-thumb-height) + (var(--switch-track-padding) * 2)
-  );
-  --switch-thumb-size: var(--switch-thumb-width);
-
-  display: flex;
-  align-items: center;
+  opacity: 1; /* HARDCODE */
   box-sizing: border-box;
   transition: background-color 150ms ease;
   cursor: inherit;
 }
 
-.root input:checked + .track {
+.root:has(input:checked) .track {
   background-color: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_track-color
   );
   border-color: transparent;
+  /* HARDCODE #4: MUI's own checked-state selector (`.Mui-checked + .track { opacity: 0.5 }`)
+     is more specific than the base .track rule above, so it still wins there — needs its own
+     override here too. */
+  opacity: 1;
+}
+
+/* Positions/sizes the thumb's clickable hit area (MUI's internal SwitchBase). MUI's own
+   defaults here (padding: 9px; top/left: 0) are calibrated for its own hardcoded 20px thumb
+   and 58x38 root — meaningless against our tokens, so every dimension is replaced. The thumb
+   itself (the visible circle) renders as this element's only child, sized by .thumb below;
+   with padding: 0 and matching width/height, .switchBase and .thumb become the same box, so
+   the thumb sits flush inside the track's own inner padding. See
+   SWITCH_IMPLEMENTATION_NOTES.md #5. */
+.switchBase {
+  top: var(--switch-track-padding);
+  left: var(--switch-track-padding);
+  width: var(--switch-thumb-width);
+  height: var(--switch-thumb-height);
+  padding: 0;
+  box-sizing: border-box;
+}
+
+.switchBase:hover,
+.switchBase:global(.Mui-focusVisible) {
+  background-color: transparent; /* HARDCODE */
+}
+
+/* Focus ring reads on the whole visible track (the pill), not the thumb's small 20x20 hit-area
+   circle .switchBase actually is — .switchBase and .track are siblings under .switchRoot (in
+   that DOM order), so the ring is drawn on .track via the general sibling combinator when the
+   hit area is focus-visible. */
+.switchBase:global(.Mui-focusVisible) ~ .track {
+  outline: var(--recursica_brand_states_focus_border-size) solid
+    var(--recursica_brand_states_focus_color);
+  outline-offset: var(--recursica_brand_states_focus_margin);
+  box-shadow: 0 0 var(--recursica_brand_states_focus_blur)
+    var(--recursica_brand_states_focus_color);
+}
+
+/* Moves the thumb from resting-left to resting-right. MUI hardcodes this same transform to
+   translateX(20px) for its own default thumb; ours is calculated from our tokens instead —
+   the exact distance between the thumb's checked and unchecked resting positions inside the
+   track's inner padding. .Mui-checked is MUI's own global state class (not a CSS Modules
+   local class), so it must be wrapped in :global() — same as Accordion's .Mui-expanded and
+   Button's .Mui-disabled — or the build hashes/scopes it into a name that never matches the
+   real DOM. */
+.switchBase:global(.Mui-checked) {
+  transform: translateX(
+    calc(
+      var(--switch-track-width) - var(--switch-thumb-width) -
+        (var(--switch-track-padding) * 2)
+    )
+  );
 }
 
 .thumb {
@@ -110,12 +188,61 @@
   transition: background-color 150ms ease;
 }
 
-.root input:checked + .track .thumb {
+.root:has(input:checked) .thumb {
   background-color: var(
     --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_thumb-color
   );
 }
 
+.thumbIconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.checkIcon,
+.closeIcon {
+  width: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
+  height: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
+  position: absolute;
+  transition:
+    opacity 150ms ease,
+    transform 150ms ease;
+}
+
+/* Unchecked state */
+.checkIcon {
+  opacity: 0;
+  transform: scale(0.5);
+  color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_icon-color
+  );
+}
+
+.closeIcon {
+  opacity: 1;
+  transform: scale(1);
+  color: var(
+    --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_icon-color
+  );
+}
+
+/* Checked state — same :has() scoping already used for track/thumb color above; .thumb isn't
+   a sibling of input here (MUI nests both under switchBase), but :has() only needs input:checked
+   to be a descendant of .root, so this still scopes correctly. */
+.root:has(input:checked) .thumb .checkIcon {
+  opacity: 1;
+  transform: scale(1);
+}
+
+.root:has(input:checked) .thumb .closeIcon {
+  opacity: 0;
+  transform: scale(0.5);
+}
+
 .labelWrapper {
   display: flex;
   flex-direction: column;
@@ -166,73 +293,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_switch-item_variants_states_disabled_properties_opacity
-  );
-}
-
-.thumbIconWrapper {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 100%;
-  height: 100%;
-  position: relative;
-}
-
-.checkIcon,
-.closeIcon {
-  width: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
-  height: var(--recursica_ui-kit_components_switch_properties_thumb-icon-size);
-  position: absolute;
-  transition:
-    opacity 150ms ease,
-    transform 150ms ease;
-}
-
-/* Unchecked state */
-.checkIcon {
-  opacity: 0;
-  transform: scale(0.5);
-  color: var(
-    --recursica_ui-kit_components_switch_variants_selection-states_selected_properties_colors_icon-color
-  );
-}
-
-.closeIcon {
-  opacity: 1;
-  transform: scale(1);
-  color: var(
-    --recursica_ui-kit_components_switch_variants_selection-states_unselected_properties_colors_icon-color
-  );
-}
-
-/* Checked state */
-.root input:checked + .track .thumb .checkIcon {
-  opacity: 1;
-  transform: scale(1);
-}
-
-.root input:checked + .track .thumb .closeIcon {
-  opacity: 0;
-  transform: scale(0.5);
-}
+/* description/error text renders via AssistiveElement directly (see Switch.tsx) —
+   it owns its own tokenized styling. AssistiveElement has no disabled state and
+   must never dim. */
 
 /* --- GROUP STYLES --- */
 .groupRoot {

package/src/components/Switch/Switch.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from "react";
+import { forwardRef, useContext } from "react";
 import {
   Switch as MuiSwitch,
   type SwitchProps as MuiSwitchProps,
@@ -17,9 +17,49 @@ import {
   FormControlLayout,
   type FormControlLayoutProps,
 } from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 import styles from "./Switch.module.css";
 
-// Removed unused SwitchGroup import
+import { SwitchGroup, SwitchGroupContext } from "./SwitchGroup";
+
+// Same glyphs as mantine-adapter's Switch (re-exported from @mantine/core's CheckIcon/CloseIcon,
+// not importable here since mui-adapter doesn't depend on @mantine/core) — kept pixel-identical
+// so adapter-tester's cross-adapter diff stays clean. Same precedent as Checkbox's inline icons.
+function CheckIcon(props: React.ComponentProps<"svg">) {
+  return (
+    <svg
+      viewBox="0 0 10 7"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M4 4.586L1.707 2.293A1 1 0 1 0 .293 3.707l3 3a.997.997 0 0 0 1.414 0l5-5A1 1 0 1 0 8.293.293L4 4.586z"
+        fill="currentColor"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </svg>
+  );
+}
+
+function CloseIcon(props: React.ComponentProps<"svg">) {
+  return (
+    <svg
+      viewBox="0 0 15 15"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M11.7816 4.03157C12.0062 3.80702 12.0062 3.44295 11.7816 3.2184C11.5571 2.99385 11.193 2.99385 10.9685 3.2184L7.50005 6.68682L4.03164 3.2184C3.80708 2.99385 3.44301 2.99385 3.21846 3.2184C2.99391 3.44295 2.99391 3.80702 3.21846 4.03157L6.68688 7.49999L3.21846 10.9684C2.99391 11.193 2.99391 11.557 3.21846 11.7816C3.44301 12.0061 3.80708 12.0061 4.03164 11.7816L7.50005 8.31316L10.9685 11.7816C11.193 12.0061 11.5571 12.0061 11.7816 11.7816C12.0062 11.557 12.0062 11.193 11.7816 10.9684L8.31322 7.49999L11.7816 4.03157Z"
+        fill="currentColor"
+        fillRule="evenodd"
+        clipRule="evenodd"
+      />
+    </svg>
+  );
+}
 
 export type SwitchWrapperProps = Omit<
   MuiSwitchProps,
@@ -37,7 +77,11 @@ export type RecursicaSwitchPropsAlias =
 
 export type SwitchProps = RecursicaOverStyled<RecursicaSwitchPropsAlias>;
 
-type SwitchComponent = React.ComponentType<SwitchProps>;
+type SwitchComponent = React.ForwardRefExoticComponent<
+  SwitchProps & React.RefAttributes<HTMLInputElement>
+> & {
+  Group: typeof SwitchGroup;
+};
 
 export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
   function Switch(props, ref) {
@@ -46,7 +90,6 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       readOnly,
       readOnlyComponent,
       disabled,
-      // Removed thumbIcon from destructured props since it's not supported
       formLayout,
       labelSize,
       controlMaxWidth,
@@ -66,31 +109,47 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
     delete restRecord["radius"];
     delete restRecord["variant"];
 
+    // NOTE: classes.root must stay keyed "root" (MUI's own slot name), but it targets a
+    // dedicated .switchRoot CSS class, not .root — .root is this component's own outer
+    // wrapper class (applied separately, see finalClass below) and sizing the actual MUI
+    // switch span the same way would squeeze that wrapper down to the track's own width.
+    // See SWITCH_IMPLEMENTATION_NOTES.md #5.
+    // NOTE: no "thumb" key here — the default MuiSwitch-thumb slot classes.thumb targets is
+    // never rendered. We supply our own icon/checkedIcon node below (see thumbNode), which
+    // replaces that slot outright (confirmed against MUI's SwitchBase/Switch source: icon and
+    // checkedIcon substitute the whole default thumb, they don't add to it), so the .thumb
+    // class is applied directly to our own node instead.
     const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
+      root: styles.switchRoot,
       body: styles.body,
       track: styles.track,
-      thumb: styles.thumb,
+      switchBase: styles.switchBase,
       trackLabel: styles.trackLabel,
       labelWrapper: styles.labelWrapper,
       label: styles.label,
     };
 
-    const classNamesProp = restRecord.classNames;
+    // NOTE: MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+    // was reading the wrong key and silently doing nothing. Fixed. Also note "body"/
+    // "trackLabel"/"labelWrapper"/"label" below aren't real MUI `classes` slots at all (MUI
+    // only recognizes root/switchBase/track/thumb/input/checked/disabled/colorX/sizeX/edgeX) —
+    // those four are this component's own hardcoded elements, styled directly in the JSX below,
+    // not through MUI's classes mechanism. Only root/track/switchBase actually take effect via
+    // this override path; the rest are pre-existing dead weight, unrelated to the classNames bug.
+    const classesProp = restRecord.classes;
     if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
+      classesProp &&
+      typeof classesProp === "object" &&
+      !Array.isArray(classesProp)
     ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+      const o = classesProp as Partial<Record<string, string>>;
+      mergedClassNames.root = o.root
+        ? `${styles.switchRoot} ${o.root}`
+        : styles.switchRoot;
       mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
       mergedClassNames.track = o.track
         ? `${styles.track} ${o.track}`
         : styles.track;
-      mergedClassNames.thumb = o.thumb
-        ? `${styles.thumb} ${o.thumb}`
-        : styles.thumb;
       mergedClassNames.trackLabel = o.trackLabel
         ? `${styles.trackLabel} ${o.trackLabel}`
         : styles.trackLabel;
@@ -107,8 +166,29 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       ? `${styles.root} ${classNameProp}`
       : styles.root;
 
+    // Threads a grouped Switch's checked state through SwitchGroupContext (mirrors Checkbox's
+    // identical CheckboxGroupContext pattern) — FormGroup itself has no controlled-value
+    // concept, so this is the only place group membership is actually computed. Standalone
+    // (ungrouped) Switch usage is untouched: isChecked/isGroupReadOnly are no-ops outside a
+    // <Switch.Group>. See SWITCH_IMPLEMENTATION_NOTES.md.
+    const groupContext = useContext(SwitchGroupContext);
+    const isGrouped = groupContext !== null;
+    const isGroupReadOnly = isGrouped ? !!groupContext.readOnly : false;
+    const isChecked = isGrouped
+      ? (groupContext.value || []).includes(restRecord.value as string)
+      : !!(restRecord.checked ?? restRecord.defaultChecked);
+
+    const handleGroupChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+      if (!isGrouped) return;
+      const currentValue = groupContext.value || [];
+      const thisValue = restRecord.value as string;
+      const newValue = event.target.checked
+        ? [...currentValue, thisValue]
+        : currentValue.filter((v) => v !== thisValue);
+      groupContext.onChange?.(event, newValue);
+    };
+
     if (readOnly && !!readOnlyComponent) {
-      const isChecked = !!(restRecord.checked ?? restRecord.defaultChecked);
       const ReadOnlyComp = readOnlyComponent;
       const roNode = (
         <ReadOnlyComp
@@ -134,17 +214,41 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       return <>{roNode}</>;
     }
 
-    // We omit Mui's sizing/coloring so we rely strictly on variables from Switch.module.css
+    // Same node passed as both icon and checkedIcon (mirrors MUI's own Switch.js, which does
+    // the same: `icon={icon} checkedIcon={icon}`) so it never unmounts/remounts on toggle —
+    // that's what lets the checkIcon/closeIcon crossfade via CSS opacity instead of a hard swap,
+    // matching mantine-adapter's thumbIcon (single node, both glyphs always mounted).
+    const thumbNode = (
+      <span className={styles.thumb}>
+        <span className={styles.thumbIconWrapper}>
+          <CheckIcon className={styles.checkIcon} />
+          <CloseIcon className={styles.closeIcon} />
+        </span>
+      </span>
+    );
+
+    // We omit Mui's sizing/coloring so we rely strictly on variables from Switch.module.css.
+    // color is hardcoded to "default" (never left to MUI's "primary" fallback) so MUI's own
+    // palette-driven blue checked/hover/focus styling never activates in the first place —
+    // see SWITCH_IMPLEMENTATION_NOTES.md #5.
+    const isSwitchDisabled = readOnly || disabled || isGroupReadOnly;
+
     const switchNode = (
       <MuiSwitch
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ref={ref as any}
         className={!label ? `${finalClass} ${styles.inner}` : styles.inner}
         classes={mergedClassNames}
-        disabled={readOnly || disabled}
-        data-disabled={readOnly || disabled || undefined}
-        // thumbIcon={thumbIcon ?? FinalThumbIcon}
+        color="default"
+        disabled={isSwitchDisabled}
+        data-disabled={isSwitchDisabled || undefined}
+        icon={thumbNode}
+        checkedIcon={thumbNode}
         {...(sanitizedProps as unknown as MuiSwitchProps)}
+        {...(isGrouped
+          ? { checked: isChecked, onChange: handleGroupChange }
+          : {})}
+        disableRipple
       />
     );
 
@@ -160,21 +264,23 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
             >
               {label as React.ReactNode}
             </label>
-            {description && (
-              <div
-                className={styles.description}
-                data-disabled={readOnly || disabled ? true : undefined}
-              >
-                {description}
-              </div>
-            )}
-            {error && (
-              <div
-                className={styles.error}
-                data-disabled={readOnly || disabled ? 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>
@@ -201,3 +307,4 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
 ) as SwitchComponent;
 
 Switch.displayName = "Switch";
+Switch.Group = SwitchGroup;