@recursica/mui-adapter 0.24.0 → 0.25.0

package/src/components/Popover/USAGE.md

@@ -0,0 +1,69 @@
+# Popover - Usage Guide
+
+This document describes how to integrate and use the `Popover` component in your projects using `@recursica/mui-adapter`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Popover } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Popover, Button, Text } from "@recursica/mui-adapter";
+
+export default function Demo() {
+  return (
+    <Popover position="bottom" withBeak>
+      <Popover.Target>
+        <Button>Open Popover</Button>
+      </Popover.Target>
+      <Popover.Dropdown>
+        <Text size="rec-sm">This is the popover content.</Text>
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogue style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Composition
+
+`Popover`, `Popover.Target`, and `Popover.Dropdown` are used together: `Popover.Target` wraps the trigger element and applies no styling of its own, while `Popover.Dropdown` renders the styled panel content. Both `Popover.Target` and `Popover.Dropdown` are required — omitting either throws.
+
+### Open/close behavior
+
+The dropdown opens when the user clicks the target and closes on an outside click, on Escape, or by clicking the target again. Use `opened`/`onChange` for controlled usage, or `defaultOpened` to set the initial uncontrolled state.
+
+### Beak (Arrow)
+
+The Recursica prop `withBeak` (defaulting to `true`) controls whether the pointer beak is shown.
+
+### Position
+
+`position` accepts the same 12 placement values as `HoverCard`/`Tooltip` (e.g. `"top"`, `"bottom-start"`, `"right-end"`) and defaults to `"top"`.
+
+### Width
+
+An optional `width` prop sets a fixed width on the dropdown panel.

package/src/components/Popover/index.ts

@@ -0,0 +1 @@
+export * from "./Popover";

package/src/components/SegmentedControl/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,6 @@
+# SegmentedControl Implementation Notes
+
+## Labels rendering uppercase (2026-08-19)
+
+- **Root cause:** `--recursica_ui-kit_components_segmented-control-item_variants_selection-states_{unselected,selected}_properties_text_text-transform` resolves to `--recursica_tokens_font_cases_original`, which has no definition in `recursica_variables_scoped.css` (only `_lowercase`/`_titlecase`/`_uppercase` are defined there). The resulting `var()` on `.label` is invalid, and since `text-transform` is an inherited property, the invalid value falls back to the inherited value from `.control` (`.MuiToggleButton-root`) — which carries MUI's own `text-transform: uppercase` button default. Mantine's control has no such native uppercase default, so the same broken token never surfaced there.
+- **Fix:** Reset `text-transform: none` on `.root .control` alongside the other MUI ToggleButton baseline resets (padding/border/etc.) already there, so nothing uppercase is left to inherit. Matches the existing `text-transform: none` MUI-baseline reset pattern in `Button.module.css`. Not a design-token value — it's a structural reset of MUI's own default, same category as the other hardcoded resets already exempted at the top of this file.

package/src/components/SegmentedControl/SegmentedControl.module.css

@@ -2,12 +2,17 @@
    - border-style: solid; on container and indicator
    - background-color: transparent; on label hover (overriding Mantine)
    - Scope prefix .root to enforce Figma tokens over Mantine's inline calculation without using !important
+   - padding/border/border-radius/min-height/min-width: 0 and background-color: transparent on
+     .control (MUI's ToggleButton root) so its own baseline button box model does not stack on
+     top of .label's token-driven height/border/radius, mirroring Mantine's transparent .control wrapper
+   - text-transform: none on .control resets MUI's ToggleButton uppercase default (see comment
+     above that rule); needed because the item text-transform token has no valid scoped value
 */
 
 /* EXEMPTIONS:
    - segmented-control-item_properties_item_border-radius is ignored because the item border-radius
      is fully governed by the per-selection-state tokens (unselected/selected `properties_border-radius`,
-     already applied to `.label` and `.control.Mui-selected` below); this generic, state-agnostic radius
+     already applied to `.label` and `.control:global(.Mui-selected)` below); this generic, state-agnostic radius
      token has no distinct consumption site without conflicting with those state-specific overrides.
      The Mantine reference adapter exempts this same variable for the same reason. */
 /* recursica-ignore: --recursica_ui-kit_components_segmented-control-item_properties_item_border-radius */
@@ -38,6 +43,28 @@
   gap: var(--recursica_ui-kit_components_segmented-control_properties_item-gap);
 }
 
+/* MUI's ToggleButton root ships its own padding/border/border-radius/min-height/min-width and a
+   text-transform: uppercase button default; reset all of it so it doesn't stack on top of (or leak
+   through, via inheritance, into) .label's token-driven box model/typography below. The
+   text-transform reset matters because the item's text-transform token
+   (segmented-control-item_..._text_text-transform) currently has no valid scoped value to resolve
+   to, so without this reset .label's own `text-transform: var(...)` below is invalid and the
+   inherited MUI uppercase default would otherwise show through (Mantine has no such native
+   default, so it never surfaced there). */
+.root .control {
+  padding: 0;
+  border: none;
+  border-radius: 0;
+  min-height: 0;
+  min-width: 0;
+  background-color: transparent;
+  text-transform: none;
+}
+
+.root .control:hover {
+  background-color: transparent;
+}
+
 .root .label {
   padding-left: var(
     --recursica_ui-kit_components_segmented-control-item_properties_item_padding-horizontal
@@ -128,8 +155,10 @@
   );
 }
 
-/* Indicator mapping (MUI ToggleButton applies .Mui-selected to the button instead of rendering a sliding indicator) */
-.root .control.Mui-selected {
+/* Indicator mapping (MUI ToggleButton applies .Mui-selected to the button instead of rendering a sliding indicator).
+   Mui-selected must be wrapped in :global() — otherwise CSS Modules locally hashes it and the
+   selector never matches MUI's actual global class (silently dropping the selected state). */
+.root .control:global(.Mui-selected) {
   background-color: var(
     --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_colors_background-color
   );
@@ -149,7 +178,7 @@
 }
 
 /* Selected label text color override */
-.root .control.Mui-selected .label {
+.root .control:global(.Mui-selected) .label {
   color: var(
     --recursica_ui-kit_components_segmented-control-item_variants_selection-states_selected_properties_colors_text-color
   );

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -1,4 +1,4 @@
-import { forwardRef } from "react";
+import { forwardRef, useState } from "react";
 import {
   ToggleButtonGroup as MuiSegmentedControl,
   ToggleButton,
@@ -85,12 +85,26 @@ const _SegmentedControl = forwardRef<HTMLDivElement, SegmentedControlProps>(
 
     const stylingParams = useSegmentedControlClassNames(restRecord);
 
+    // MUI's ToggleButtonGroup is controlled-only and selects nothing when `value` is
+    // undefined; Mantine's SegmentedControl instead defaults to the first data item. Track an
+    // uncontrolled fallback so both adapters render the same default selection.
+    const firstValue = data.length
+      ? typeof data[0] === "string"
+        ? data[0]
+        : data[0].value
+      : undefined;
+    const [uncontrolledValue, setUncontrolledValue] = useState<
+      string | undefined
+    >(value ?? firstValue);
+    const activeValue = value !== undefined ? value : uncontrolledValue;
+
     const handleChange = (
       _event: React.MouseEvent<HTMLElement>,
       newValue: string | null,
     ) => {
-      if (newValue !== null && onChange) {
-        onChange(newValue);
+      if (newValue !== null) {
+        setUncontrolledValue(newValue);
+        onChange?.(newValue);
       }
     };
 
@@ -107,7 +121,7 @@ const _SegmentedControl = forwardRef<HTMLDivElement, SegmentedControlProps>(
         fullWidth={fullWidth}
         data-orientation={orientation}
         exclusive
-        value={value}
+        value={activeValue}
         onChange={
           handleChange as React.ComponentProps<
             typeof MuiSegmentedControl

package/src/components/Slider/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,29 @@
+# Slider Implementation Notes
+
+This document contains specific design decisions, architectural constraints, and hacks required to bridge the Recursica design system with MUI's underlying `Slider` primitive.
+
+## 1. Pointer Clicks Falsely Trigger MUI's `Mui-focusVisible` Ring
+
+**Symptom:** Clicking or dragging the thumb showed the keyboard focus ring, which Mantine never shows for a plain mouse interaction.
+
+**Root cause:** MUI's `Slider` always programmatically re-focuses its hidden native `<input type="range">` on pointer-down (`focusThumb()` in `useSlider`). Because the focus target (`<input>`) differs from the element the pointer actually interacted with, and because a script-driven `.focus()` call is what browsers use to decide visibility, the native `:focus-visible` heuristic (which MUI's own `isFocusVisible` check relies on) resolves to `true` even for a plain click. Mantine's thumb is a plain `<div tabIndex>` that receives real native focus directly from the click, so the same heuristic correctly resolves to `false` there.
+
+**Fix:** `Slider.tsx` tracks pointer-vs-keyboard itself (`onMouseDown` sets a ref, `onFocus` reads it to flag `suppressFocusRing`, `onKeyDown`/`onBlur` clear it — mirroring how real `:focus-visible` re-evaluates on a subsequent keypress). `Slider.module.css` only paints the ring when `[data-suppress-focus-ring="true"]` is absent from `.sliderContainer`.
+
+## 2. Disabled Track Stayed Red
+
+**Symptom:** Once `disabled` was wired through correctly, the filled track (`.sliderBar`) still rendered the active/red color instead of the disabled grey token.
+
+**Root cause:** The base `.sliderBar` rule had `background-color: ... !important`, so the (non-`!important`) `[data-disabled="true"] .sliderBar` override could never win the cascade regardless of source order.
+
+**Fix:** Removed the unneeded `!important` flags from the base `.sliderBar` rule — `injectFirst` already makes our CSS-module class beat MUI's native `.MuiSlider-track` via source order alone (same as `.sliderTrack`/`.sliderThumb`/`.sliderMark`, none of which need `!important`).
+
+## 3. Assistive Text Rendered as `<div>` Instead of `<span>`
+
+**Root cause:** `AssistiveElement.tsx` (mui-adapter) hardcoded a `<div>` around the children text; Mantine's equivalent uses a `<span>`. Not shared via `adapter-common` — each adapter has its own `AssistiveElement`.
+
+**Fix:** Changed the inner text wrapper to a `<span>`. No CSS selector depended on the element type (`.text` is a class-only selector and remains a valid flex item as a span).
+
+## 4. Mark Label Color
+
+**Root cause:** MUI's `.sliderMarkLabel` already inherited the container text color using the min-max-label typography tokens. Mantine's equivalent class (`styles.sliderMarkLabel`) was referenced in `Slider.tsx`'s `classNames` map but was never defined in Mantine's `Slider.module.css`, so Mantine silently fell back to its own default theme grey instead of any recursica token. Fixed in `mantine-adapter` by adding the missing `.sliderMarkLabel` rule (same tokens/inherit-color approach as MUI) rather than copying Mantine's undefined behavior into MUI.

package/src/components/Slider/Slider.module.css

@@ -2,12 +2,15 @@
  * HARDCODED VALUES:
  * - display: flex; align-items: center; width: 100%; (Standard CSS flexbox layouts for bidirectional components)
  * - flex-grow: 1; flex-shrink: 0; (Layout control structures)
- * - transform: translateX(-50%); (Mantine's standard step marks positioning alignment offset)
+ * - transform: translateX(-50%); (Step marks/mark labels positioning alignment offset, matching
+ *   Mantine's own offset mechanism)
  * - outline: none; border-style: solid; (Standard focus reset and border outlines)
  * - Focus ring on thumb/input: the token schema no longer provides per-component focus
  *   colors for these (only `active` covers track/step-indicator-color). We apply the generic
  *   --recursica_brand_states_focus_* ring tokens (border-size/color/margin/blur) as a box-shadow
  *   ring instead of a color swap.
+ * - Focus ring on thumb is applied via MUI's own `Mui-focusVisible` class (not native
+ *   `:focus`/`:focus-visible`, which never match the thumb span — see inline comment).
  */
 
 /* ==========================================
@@ -79,16 +82,14 @@
 }
 
 .sliderBar {
-  height: var(
-    --recursica_ui-kit_components_slider_properties_track-height
-  ) !important;
+  height: var(--recursica_ui-kit_components_slider_properties_track-height);
   border-radius: var(
     --recursica_ui-kit_components_slider_properties_track-border-radius
-  ) !important;
+  );
   background-color: var(
     --recursica_ui-kit_components_slider_properties_colors_track-active
-  ) !important;
-  border: none !important;
+  );
+  border: none;
 }
 
 .sliderThumb {
@@ -116,8 +117,21 @@
   );
 }
 
-.sliderThumb:focus,
-.sliderThumb:focus-visible {
+/*
+ * MUI toggles its own `Mui-focusVisible` class on the thumb (for both keyboard focus and
+ * mouse-driven dragging, since MUI's slider routes real DOM focus to a hidden native input,
+ * never the visible thumb span) and pairs it with a hardcoded `theme.palette.primary.main`
+ * box-shadow ring. Native `:focus`/`:focus-visible` never match the thumb span itself, so we
+ * target MUI's own class directly to replace its default-blue ring with the recursica ring.
+ *
+ * MUI also always programmatically re-focuses that hidden input on pointer interaction, which
+ * browsers' `:focus-visible` heuristic treats as keyboard-visible — unlike Mantine's plain div
+ * thumb, where a real click correctly resolves to a non-visible focus. `data-suppress-focus-ring`
+ * (set in Slider.tsx by tracking pointer-vs-keyboard ourselves) keeps the ring keyboard-only,
+ * matching Mantine.
+ */
+.sliderContainer:not([data-suppress-focus-ring="true"])
+  .sliderThumb:global(.Mui-focusVisible) {
   outline: none;
   box-shadow:
     var(--recursica_ui-kit_components_slider_properties_thumb-elevation),
@@ -128,6 +142,14 @@
       var(--recursica_brand_states_focus_color);
 }
 
+.sliderContainer[data-suppress-focus-ring="true"]
+  .sliderThumb:global(.Mui-focusVisible) {
+  outline: none;
+  box-shadow: var(
+    --recursica_ui-kit_components_slider_properties_thumb-elevation
+  );
+}
+
 .sliderMark {
   box-sizing: border-box;
   width: var(
@@ -154,6 +176,49 @@
   );
 }
 
+/*
+ * MUI's default markLabel sits ~30-40px below the mark (`top: 30`, `top: 40` under
+ * `(pointer: coarse)`) and uses `theme.palette.text.secondary`. Mantine's equivalent label sits
+ * right under the mark (a half-step-indicator offset plus a small gap) and has no explicit color,
+ * inheriting the container's text color. Reusing the min-max-label typography tokens (the closest
+ * existing "small label near the track" token set) and inheriting color keeps this visually
+ * consistent with Mantine without a dedicated mark-label token.
+ */
+.sliderMarkLabel {
+  top: calc(
+    var(--recursica_ui-kit_components_slider_properties_step-indicator-width) /
+      2 +
+      var(--recursica_ui-kit_globals_form_properties_label-field-gap-vertical)
+  );
+  transform: translateX(-50%);
+  color: inherit;
+
+  font-family: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_slider_properties_min-max-label_text-transform
+  );
+}
+
 .sliderTooltip {
   background-color: var(--form-field-text-valued) !important;
   color: var(--form-field-background) !important;
@@ -398,14 +463,12 @@
 
 /* Focus states */
 /* The token schema's `active` state (not a separate `focus` state) now covers track/step-indicator
-   color while focus is within the slider; there is no `active` override for the filled mark. */
-.sliderRoot:has(.sliderThumb:focus) .sliderTrack,
-.sliderRoot:focus-within .sliderTrack {
-  background-color: var(
-    --recursica_ui-kit_components_slider_variants_states_active_properties_colors_track
-  );
-}
-
+   color while focus is within the slider. Unlike Mantine (whose unfilled track is painted by an
+   internal `::before` layer that this rule never actually reaches), MUI's rail element is styled
+   directly by `.sliderTrack`, so applying the active-track color here visibly repaints the rail a
+   different color for the whole duration of a drag. There is no design requirement for the rail to
+   change color while dragging, so the track is intentionally left out of this rule; only the
+   step-indicator (mark) is included, matching the token schema's remaining active-state coverage. */
 .sliderRoot:has(.sliderThumb:focus) .sliderMark,
 .sliderRoot:focus-within .sliderMark {
   background-color: var(

package/src/components/Slider/Slider.stories.tsx

@@ -92,7 +92,7 @@ export const Disabled: Story = {
     label: "Decommissioned Server Node",
     assistiveText: "Modifications to this environment are frozen.",
     defaultValue: 35,
-    disabled: false,
+    disabled: true,
   },
 };
 

package/src/components/Slider/Slider.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef, useState, useEffect } from "react";
+import React, { forwardRef, useState, useEffect, useRef } from "react";
 import {
   Slider as MuiSlider,
   type SliderProps as MuiSliderProps,
@@ -145,6 +145,36 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
     delete restRecord["color"];
     delete restRecord["wrapperProps"];
 
+    // MUI always programmatically re-focuses its hidden native input on pointer interaction,
+    // which browsers' `:focus-visible` heuristic treats as keyboard-visible — unlike Mantine's
+    // plain div thumb, where a real click correctly resolves to a non-visible focus. Track
+    // pointer-vs-keyboard ourselves so the focus ring only paints for genuine keyboard focus,
+    // matching Mantine (a later keypress while still focused reveals the ring, same as native).
+    const pointerDownRef = useRef(false);
+    const [suppressFocusRing, setSuppressFocusRing] = useState(false);
+    const externalOnMouseDown = (sanitizedProps as MuiSliderProps).onMouseDown;
+    const externalOnFocus = (sanitizedProps as MuiSliderProps).onFocus;
+    const externalOnBlur = (sanitizedProps as MuiSliderProps).onBlur;
+    const externalOnKeyDown = (sanitizedProps as MuiSliderProps).onKeyDown;
+
+    const handleThumbMouseDown = (e: React.MouseEvent<HTMLSpanElement>) => {
+      pointerDownRef.current = true;
+      externalOnMouseDown?.(e);
+    };
+    const handleThumbFocus = (e: React.FocusEvent<HTMLSpanElement>) => {
+      setSuppressFocusRing(pointerDownRef.current);
+      pointerDownRef.current = false;
+      externalOnFocus?.(e);
+    };
+    const handleThumbBlur = (e: React.FocusEvent<HTMLSpanElement>) => {
+      setSuppressFocusRing(false);
+      externalOnBlur?.(e);
+    };
+    const handleThumbKeyDown = (e: React.KeyboardEvent<HTMLSpanElement>) => {
+      setSuppressFocusRing(false);
+      externalOnKeyDown?.(e);
+    };
+
     // Securely map core native blocks down ensuring nested CSS modules map precisely
     const mergedClassNames: Partial<Record<string, string>> = {
       root: styles.sliderRoot,
@@ -226,6 +256,7 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
             data-form-layout={formLayout}
             data-disabled={disabled ? "true" : undefined}
             data-error={error ? "true" : undefined}
+            data-suppress-focus-ring={suppressFocusRing ? "true" : undefined}
           >
             {leadingIcon}
 
@@ -240,6 +271,10 @@ export const Slider = forwardRef<HTMLDivElement, SliderProps>(
                 disabled={disabled}
                 value={resolvedValue}
                 onChange={handleValueChange}
+                onMouseDown={handleThumbMouseDown}
+                onFocus={handleThumbFocus}
+                onBlur={handleThumbBlur}
+                onKeyDown={handleThumbKeyDown}
                 onChangeCommitted={
                   onChangeEnd as unknown as (
                     event: Event | React.SyntheticEvent,

package/src/components/Stepper/IMPLEMENTATION_NOTES.md

@@ -2,3 +2,57 @@
 
 - **Compositional API Dropped:** Mantine manages stepper state and content via `<Stepper.Step>` and `<Stepper.Completed>`. MUI delegates content rendering to the developer and focuses purely on the stepper visual layout using `<Step>`, `<StepLabel>`, etc.
 - **Monolithic API Adopted:** Following architectural review, we have abandoned the fabricated context wrappers for `mui-adapter`. We now natively export `Stepper`, `Step`, `StepLabel`, `StepButton`, and `StepConnector` wrapping their `@mui/material` counterparts. Developers are expected to manage the active step logic and content rendering outside the `Stepper` component, consistent with MUI patterns. Storybook tests have been updated to reflect this divergence while retaining core visual compatibility.
+
+## Layout fixes (root-caused against mantine's visual reference)
+
+Several parts of the original implementation used the correct-looking classes but wired
+them to elements that never carry those classes at runtime, or copy-pasted comments/logic
+from `mantine-adapter` that don't describe how MUI's Stepper actually works. Fixed:
+
+- **Horizontal layout uses `alternativeLabel`:** MUI's own `Stepper` prop doc says
+  `alternativeLabel` positions the label under the icon — that's exactly Recursica's
+  horizontal layout, and it's also what makes `StepConnector`'s `alternativeLabel` variant
+  absolutely-position itself relative to each `Step`, centered on the icon. The adapter
+  previously never set this prop and instead tried to force column layout via CSS on
+  `Step`'s own root, which has no effect (`StepLabel`'s row-vs-column layout is driven
+  entirely by the `alternativeLabel` context flag, not by its parent's `flex-direction`).
+  Without it, labels rendered beside the icon (row layout) and the connector used the
+  non-`alternativeLabel` inline-flex positioning, both very visibly wrong.
+- **Custom `StepIconComponent`:** MUI's default `StepIcon` draws its own self-contained
+  circle+check `CheckCircle` SVG (Material's `check_circle` glyph) whenever `completed` is
+  true, colored via `theme.palette.primary.main` (blue) — it never reads our tokens and its
+  SVG viewBox doesn't scale to `--stepper-indicator-size`. We now pass `RecursicaStepIcon`
+  (a plain span + our own inline check glyph, same convention as `Checkbox.tsx`'s `CheckIcon`)
+  so the token-driven circle (`.stepIconCircle`) is the only circle ever drawn, and the check
+  mark is sized via `--stepper-svg-size` and colored via the `completed-indicator-text` token.
+- **`classes.labelContainer` was never mapped:** all of the `.stepBody` centering/max-width
+  CSS (copied verbatim from mantine, where `stepBody` is a real classNames key) was dead code
+  for MUI — `StepLabel` calls this slot `labelContainer`, not `stepBody`. Now mapped via
+  `classes={{ labelContainer: styles.stepBody }}`.
+- **Vertical connecting line — real primitive doesn't fit, so it's drawn on `.stepIcon`:**
+  MUI's vertical `StepConnector` is a sibling with a fixed `minHeight: 24`; it can't stretch to
+  match a step's actual rendered height (e.g. a 2-line description), which is exactly why the
+  line floated disconnected from both circles. MUI's own answer to this is `StepContent`
+  (its `border-left` spans whatever height its content needs) — but Recursica intentionally
+  hides `.content` (steppers are structural-only, no per-step content in the DOM). Since
+  neither of MUI's two connecting-line primitives fits, the vertical connector is drawn as a
+  `.stepIcon::after` pseudo-element instead: `StepLabelRoot` gets `align-items: stretch` (a
+  real CSS stretch, not JS measurement) so `.stepIcon` (`iconContainer`) grows to match its
+  sibling label column's actual height, and the rail spans `top: indicator-size` down through
+  `bottom: calc(-1 * step-gap)` (the step's own padding-bottom, exactly reaching the next
+  step's icon). `Stepper.tsx` passes an empty `<></>` as the vertical `connector` since this
+  fully replaces its job. This requires zeroing MUI's own hardcoded
+  `StepLabelRoot` vertical `padding: 8px 0` (`.root.vertical .stepLabelRoot`) — leaving it in
+  place made the rail land 16px short of the next icon.
+- **`:global()` was missing everywhere `.Mui-active`/`.Mui-completed`/`.MuiStepLabel-root` was
+  referenced:** in a CSS Module, a bare `.Mui-completed` selector gets scoped/hashed like any
+  other local class, so it silently never matches the real global class MUI stamps onto the
+  DOM (same pitfall documented in `Button.module.css`/`Switch.module.css` for `.Mui-disabled`/
+  `.Mui-checked`). This affected the label/description state-color rules (already present
+  before this fix) and the new separator/rail state-color rules — all now wrapped in
+  `:global(...)`. While fixing this, the description-color selectors were also corrected to
+  use `.stepBody:has(.stepLabel:global(.Mui-completed)) .stepDescription` — the prior
+  `:has(~ .Mui-completed)` could never match because `optional`/description renders _after_
+  the label in the DOM (not before), and `.MuiStepLabel-root.Mui-completed` could never match
+  because MUI only stamps the completed/active state class onto the `label`/`iconContainer`
+  slots, never onto `StepLabel`'s own root.