@recursica/mui-adapter 0.23.0 → 0.25.0

package/src/components/Tabs/Tabs.module.css

@@ -2,10 +2,24 @@
   Recursica Tabs CSS module natively binding to Figma variables.
 */
 
-.root {
+/* Unlike Mantine's .root (which internally wraps List+Panel and always spans its parent),
+   MUI's .root is only the tablist — it sits beside the panel in the consumer's own flex row for
+   vertical orientation. Stretching it to 100% width there fights the panel for space and drags
+   the border-right rail/indicator away from the tab content, so only horizontal gets full width;
+   vertical sizes to its content instead, same as Mantine's vertical .list does. */
+.root[data-orientation="horizontal"] {
   width: 100%;
 }
 
+/* Mantine's vertical .list stretches to the root's full height via flex align-items, so a
+   border-right divider on it spans the whole rail. MUI's scroller (the .list's parent) is a plain
+   block for vertical, not a flex container, so .list sizes to its own content (just the stacked
+   tabs) and a divider on it stops short at the last tab instead of running the full height —
+   spell the stretch out explicitly instead. */
+.root[data-orientation="vertical"] .list {
+  height: 100%;
+}
+
 /*
   Mantine Tabs Anatomy:
   .root
@@ -125,6 +139,15 @@
   --tabs-color: var(
     --recursica_ui-kit_components_tabs-item_variants_styles_outline_variants_selection-states_active_properties_colors_border-color
   ) !important;
+  --tabs-active-bg: var(
+    --recursica_ui-kit_components_tabs-item_variants_styles_outline_variants_selection-states_active_properties_colors_background-color
+  );
+  /* The active tab's own background-color token above is transparent by design (it's meant to
+     let whichever ambient Layer surface sits behind the Tabs show through). That means it can't
+     double as an opaque "eraser" for the baseline-patch trick below, which needs a real paint to
+     replace, not reveal-through. Layer 0 is the default/outermost surface a Tabs instance sits
+     on absent a wrapping <Layer>; see OUTLINE SELECTION BORDER below for why this is needed. */
+  --tabs-baseline-patch-bg: var(--recursica_brand_layer_0_properties_surface);
 }
 
 .root[data-variant="outline"][data-orientation="horizontal"] {
@@ -223,18 +246,17 @@
 
 /* ---------------------------------
    SELECTION INDICATOR & BASELINE
-   Mantine draws the active-tab underline/side-border and the full-length baseline natively off
-   the shared --tabs-color/--tabs-border-color vars above. MUI has no equivalent built-in, so we
-   drive its own indicator slot (classes.indicator, wired in Tabs.tsx) and the list's baseline
-   border explicitly from the same vars. Pills has no baseline/indicator — selection is carried
-   entirely by the pill's own background/border (see COLORS & TYPOGRAPHY below).
+   Mantine draws the active-tab underline natively off the shared --tabs-color var above. MUI has
+   no equivalent built-in, so we drive its own indicator slot (classes.indicator, wired in
+   Tabs.tsx) and the list's baseline border explicitly from the same vars. Pills has no underline
+   indicator — selection shows via the pill's own background/border (see COLORS & TYPOGRAPHY
+   below). Outline repurposes the indicator as a baseline patch rather than an underline (see
+   below).
 --------------------------------- */
-.root[data-variant="default"] .indicator,
-.root[data-variant="outline"] .indicator {
+.root[data-variant="default"] .indicator {
   background-color: var(--tabs-color) !important;
 }
-.root[data-variant="default"][data-orientation="horizontal"] .indicator,
-.root[data-variant="outline"][data-orientation="horizontal"] .indicator {
+.root[data-variant="default"][data-orientation="horizontal"] .indicator {
   height: var(--tabs-active-border-size) !important;
 }
 /* MUI's Tabs root has no border/padding of its own, so the list's margin-bottom (the
@@ -250,27 +272,52 @@
     --recursica_ui-kit_components_tabs_variants_styles_default_variants_orientation_horizontal_properties_tabs-content-gap
   ) !important;
 }
+/* width: same reasoning as the horizontal height above, rotated 90°.
+   right: same reasoning as the horizontal bottom offset above, rotated 90° — the list's
+   margin-right (this orientation's tabs-content-gap, spacing the panel to its right) inflates the
+   root's auto width past the list's own border-right edge. The indicator is absolutely positioned
+   against that wider box, so without this offset it renders content-gap pixels to the right of the
+   divider instead of flush against it. */
+.root[data-variant="default"][data-orientation="vertical"] .indicator {
+  width: var(--tabs-active-border-size) !important;
+  right: var(
+    --recursica_ui-kit_components_tabs_variants_styles_default_variants_orientation_vertical_properties_tabs-content-gap
+  ) !important;
+}
+.root[data-variant="default"][data-orientation="horizontal"][data-inverted]
+  .indicator {
+  bottom: auto !important;
+  top: 0 !important;
+}
+.root[data-variant="pills"] .indicator {
+  display: none !important;
+}
+
+/* Outline has no sliding underline of its own, but reuses the indicator element (already
+   positioned/sized by MUI to exactly track the selected tab, no matter which one) as a baseline
+   patch instead of hiding it — see OUTLINE SELECTION BORDER below for why a patch is needed at
+   all, and why it has to live here (in the scroller) rather than on the tab itself. */
+.root[data-variant="outline"] .indicator {
+  background-color: var(--tabs-baseline-patch-bg) !important;
+}
 .root[data-variant="outline"][data-orientation="horizontal"]:not(
     [data-inverted]
   )
   .indicator {
+  height: var(--tabs-inactive-border-size) !important;
   bottom: var(
     --recursica_ui-kit_components_tabs_variants_styles_outline_variants_orientation_horizontal_properties_tabs-content-gap
   ) !important;
 }
-.root[data-variant="default"][data-orientation="vertical"] .indicator,
-.root[data-variant="outline"][data-orientation="vertical"] .indicator {
-  width: var(--tabs-active-border-size) !important;
-}
-.root[data-variant="default"][data-orientation="horizontal"][data-inverted]
-  .indicator,
 .root[data-variant="outline"][data-orientation="horizontal"][data-inverted]
   .indicator {
+  height: var(--tabs-inactive-border-size) !important;
   bottom: auto !important;
-  top: 0 !important;
+  top: calc(-1 * var(--tabs-inactive-border-size)) !important;
 }
-.root[data-variant="pills"] .indicator {
-  display: none !important;
+.root[data-variant="outline"][data-orientation="vertical"] .indicator {
+  width: var(--tabs-inactive-border-size) !important;
+  right: calc(-1 * var(--tabs-inactive-border-size)) !important;
 }
 
 .root[data-variant="default"][data-orientation="horizontal"] .list,
@@ -356,6 +403,41 @@
   border-radius: var(--tabs-border-radius) 0 0 var(--tabs-border-radius);
 }
 
+/* ---------------------------------
+   OUTLINE SELECTION BORDER
+   Mantine's outline tab marks selection with a bordered box left open on the edge that touches
+   the list's own baseline, so the box visually connects to it instead of floating above it.
+   Every tab keeps the border geometry (transparent by default) so selecting a tab doesn't shift
+   layout; only the color changes on selection. The open edge here has 0 border-width, which
+   leaves the list's own baseline border showing straight through underneath — see the indicator
+   patch in SELECTION INDICATOR & BASELINE above, which covers just that segment. (A pseudo-element
+   on the tab itself can't do this: MUI clips tab content to its own bounds for ripple containment,
+   so anything extending past the tab's box to reach the list's border gets clipped away.)
+--------------------------------- */
+.root[data-variant="outline"] .tab {
+  border-style: solid;
+  border-color: transparent;
+}
+.root[data-variant="outline"][data-orientation="horizontal"]:not(
+    [data-inverted]
+  )
+  .tab {
+  border-width: var(--tabs-inactive-border-size)
+    var(--tabs-inactive-border-size) 0 var(--tabs-inactive-border-size);
+}
+.root[data-variant="outline"][data-orientation="horizontal"][data-inverted]
+  .tab {
+  border-width: 0 var(--tabs-inactive-border-size)
+    var(--tabs-inactive-border-size) var(--tabs-inactive-border-size);
+}
+.root[data-variant="outline"][data-orientation="vertical"] .tab {
+  border-width: var(--tabs-inactive-border-size) 0
+    var(--tabs-inactive-border-size) var(--tabs-inactive-border-size);
+}
+.root[data-variant="outline"] .tab:global(.Mui-selected) {
+  border-color: var(--tabs-color) !important;
+}
+
 /* ---------------------------------
    COLORS & TYPOGRAPHY
    Because colors are defined per-layer and theme via generic variable structures,
@@ -485,9 +567,7 @@
 }
 
 .root[data-variant="outline"] .tab:global(.Mui-selected) {
-  background-color: var(
-    --recursica_ui-kit_components_tabs-item_variants_styles_outline_variants_selection-states_active_properties_colors_background-color
-  ) !important;
+  background-color: var(--tabs-active-bg) !important;
   color: var(
     --recursica_ui-kit_components_tabs-item_variants_styles_outline_variants_selection-states_active_properties_colors_text-color
   ) !important;
@@ -635,8 +715,11 @@
   z-index: 0;
 }
 
-/* Ensure tab content sits above the hover background */
-.root .tab > * {
+/* Ensure tab content sits above the hover background. Excludes MuiTouchRipple-root: it relies on
+   its native position:absolute to stay out of flow, and forcing it to position:relative here
+   turns it into a real flex item — inserting an extra element-gap into the tab's flex row (and
+   growing the tab's width) the first time it's clicked, permanently shifting later siblings. */
+.root .tab > *:not(:global(.MuiTouchRipple-root)) {
   z-index: 1;
   position: relative;
 }

package/src/components/Tabs/Tabs.tsx

@@ -62,6 +62,7 @@ export const Tab = forwardRef<HTMLDivElement, TabProps>(
     return (
       <MuiTab
         ref={ref}
+        disableRipple
         className={`${styles.tab} ${className || ""}`}
         {...(sanitizedProps as MuiTabProps)}
       />

package/src/components/TextArea/TextArea.module.css

@@ -127,6 +127,19 @@
   color: inherit;
 }
 
+/* MUI always renders multiline inputs through TextareaAutosize, which sets an inline `height`
+   that otherwise wins over the min-height above. Pin the height to the same rows-based formula
+   when autosize isn't requested, so it matches the plain (non-autosizing) textarea Mantine renders. */
+.root:not([data-autosize]) .input {
+  height: calc(
+    var(--recursica_ui-kit_components_textarea_properties_rows) *
+      var(--recursica_ui-kit_components_textarea_properties_text_line-height) +
+      2 *
+      var(--recursica_ui-kit_components_textarea_properties_vertical-padding) +
+      2px
+  ) !important;
+}
+
 /* -------------------------------------
    STATE CASCADE ARCHITECTURE
 -------------------------------------- */
@@ -144,8 +157,10 @@
       var(--recursica_brand_states_focus_color);
 }
 
-/* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
-.root[data-error] .input {
+/* Error State Mapping
+   MUI only stamps the global `Mui-error` state class onto the InputBase root slot (not the
+   input element itself), so the error trigger is scoped from `.root` down to `.input`. */
+.root:global(.Mui-error) .input {
   border-color: var(
     --recursica_ui-kit_components_textarea_variants_states_error_properties_colors_border-color
   ) !important;
@@ -157,8 +172,9 @@
   ) !important;
 }
 
-/* Disabled State Mapping (Propagated strictly down from the wrapper DOM context) */
-.root[data-disabled] .input {
+/* Disabled State Mapping
+   MUI stamps `Mui-disabled` onto both the root slot and the input element directly. */
+.input:global(.Mui-disabled) {
   border-color: var(
     --recursica_ui-kit_components_textarea_variants_states_disabled_properties_colors_border-color
   ) !important;

package/src/components/TextArea/TextArea.tsx

@@ -66,6 +66,7 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
       emptyValueComponent,
       value,
       defaultValue,
+      autosize,
       ...rest
     } = props;
     const sanitizedProps = filterStylingProps(rest, overStyled);
@@ -76,27 +77,6 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
     delete restRecord["variant"];
     delete restRecord["radius"];
 
-    // Securely map core native blocks down ensuring nested CSS modules map precisely
-    const mergedClassNames: Partial<Record<string, string>> = {
-      wrapper: styles.root, // The nested Input internal relative wrapper bounding box
-      input: styles.input,
-    };
-
-    const classNamesProp = restRecord.classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Partial<Record<string, string>>;
-      mergedClassNames.wrapper = o.wrapper
-        ? `${styles.root} ${o.wrapper}`
-        : styles.root;
-      mergedClassNames.input = o.input
-        ? `${styles.input} ${o.input}`
-        : styles.input;
-    }
-
     const wrapperClass = className
       ? `${styles.layoutOverride} ${className}`
       : styles.layoutOverride;
@@ -130,15 +110,24 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
           /* Naked Input execution safely decoupled from Mui's macro Input.Wrapper DOM hooks */
           <MuiTextarea
             multiline
+            variant="standard"
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             inputRef={ref as any}
-            classes={mergedClassNames}
             disabled={disabled}
             value={value}
             defaultValue={defaultValue}
             label={undefined}
-            error={undefined}
+            error={!!error}
             required={undefined}
+            slotProps={{
+              input: {
+                disableUnderline: true,
+                classes: { root: styles.root, input: styles.input },
+                ...({
+                  "data-autosize": autosize ? "true" : undefined,
+                } as Record<string, unknown>),
+              },
+            }}
             {...(sanitizedProps as unknown as MuiTextareaProps)}
           />
         }

package/src/components/Timeline/IMPLEMENTATION_NOTES.md

@@ -1,5 +1,26 @@
 # Timeline Implementation Notes
 
-- **`TimelineItem.tsx`'s `classes` prop likely does nothing (needs follow-up):** `TimelineItem.tsx` passes `classes={{ item: styles.item, itemBody: styles.itemBody, itemContent: styles.itemContent, itemBullet: styles.itemBullet, itemTitle: styles.itemTitle }}` to `MuiTimelineItem`. But `@mui/lab`'s `TimelineItem` only defines these class slots (see `node_modules/@mui/lab/TimelineItem/timelineItemClasses.d.ts`): `root`, `positionLeft`, `positionRight`, `positionAlternate`, `positionAlternateReverse`, `missingOppositeContent`. There is no `item`/`itemBody`/`itemContent`/`itemBullet`/`itemTitle` slot — `useUtilityClasses` in `TimelineItem.js` builds its class list from a fixed `slots` object keyed only by those real slot names and passes it through `composeClasses`, which ignores any other keys on the `classes` object we pass in. So `.item`, `.itemBody`, `.itemContent`, `.itemBullet`, and `.itemTitle` in `Timeline.module.css` (lines with those selectors) are not actually attached to any rendered element today — they're dead CSS.
-  - Discovered 2026-08-06 while wiring up the `--recursica_ui-kit_components_timeline_properties_item-gap` token (see changeset `fix-mui-adapter-broken-tokens`). That specific fix didn't depend on these classes — it uses `gap` on `.root` (a real, correctly-applied slot), which spaces direct `<li>` children regardless of their own class — so it's unaffected by this bug and needed no workaround.
-  - **Needs a real fix later:** likely means auditing which of `.item`/`.itemBody`/`.itemContent`/`.itemBullet`/`.itemTitle`'s rules are actually load-bearing (vs. now-inert overrides of Mantine's naming that never carried over structurally to MUI), and either (a) finding the correct way to target those parts under MUI's actual DOM (e.g. `:global()` selectors against MUI's own internal class names, similar to the pattern used elsewhere in this adapter for `TableCell`/`TableRow`), or (b) restructuring `TimelineItem.tsx` to apply these as plain `className`s on wrapper elements it already renders internally, since `classes` won't work for slots MUI doesn't define.
+## Architecture
+
+Unlike Mantine, `@mui/lab`'s `TimelineItem` has no built-in bullet/connector — it only
+composes whatever you nest inside it. `TimelineItem.tsx` renders `TimelineSeparator` >
+`TimelineDot` (`.itemBullet`) + `TimelineConnector` (`.itemConnector`), and `TimelineContent`
+(`.itemBody`) containing the `title`/description/`timestamp` nodes, to reproduce Mantine's
+single-component bullet + connecting-line structure.
+
+- `Timeline.tsx` computes `active`/`isLast` per item (Mui has no `active` concept at all) and
+  injects them into each `Timeline.Item` as internal `__active`/`__isLast` props, mirroring
+  Mantine's own `cloneElement` pattern for propagating active state down to children.
+- `data-active` / `data-variant` are set directly on `TimelineItem`'s real `li` root and
+  consumed via plain descendant selectors (`.item[data-active] .itemBullet`, etc.) in
+  `Timeline.module.css` — Mui's `TimelineItem` only defines a `root` classes slot, so (unlike
+  Mantine) passing a `classes` object with `item`/`itemBullet`/`itemBody`/... keys is a no-op;
+  those class names must be applied as plain `className`s on the elements we render ourselves.
+- The last item omits `TimelineConnector` entirely so no trailing line renders past it.
+- `Timeline.module.css` neutralizes Mui's `TimelineItem::before` opposite-content spacer
+  (`flex: 0; padding: 0`), which otherwise pushes the separator/content right since this
+  adapter never renders `TimelineOppositeContent`.
+
+## Limitations & Missing Tokens
+
+- **Avatar Bullet Size**: There is no specific pixel variable provided for the Avatar bullet size in the UI kit tokens (`avatar-size` evaluates to `"default"`). To maintain exact mathematical centering with the connector line, the CSS falls back to inheriting the `default` bullet size (`20px`) for avatar nodes natively. If users supply a custom sized `img` tag, it must adhere to inline structural constraints or flex mappings.

package/src/components/Timeline/Timeline.module.css

@@ -1,6 +1,6 @@
 /* EXEMPTIONS:
    - timeline-bullet_variants_types_avatar_properties_avatar-size is ignored because under the avatar timeline variant,
-     the bullet container size uses fallback bullet-size configurations to maintain vertical alignment with the 
+     the bullet container size uses fallback bullet-size configurations to maintain vertical alignment with the
      inactive/active connector line, while the nested Avatar subcomponent handles its own sizing natively. */
 /* recursica-ignore: --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_avatar-size */
 
@@ -8,74 +8,57 @@
   display: flex;
   flex-direction: column;
   gap: var(--recursica_ui-kit_components_timeline_properties_item-gap);
+  margin: 0 !important;
+  padding: 0 !important;
 }
 
 .item {
-  /* Mantine uses these vars to calculate the exact left: position of the connector line */
-  --tl-line-width: var(
-    --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_connector-size
-  ) !important;
-
-  &[data-active] {
-    --tl-line-width: var(
-      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_connector-size
-    ) !important;
-  }
-
-  &[data-variant="default"] {
-    --tl-bullet-size: var(
-      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
-    ) !important;
-  }
-  &[data-variant="icon"] {
-    --tl-bullet-size: var(
-      --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_bullet-size
-    ) !important;
-  }
-  &[data-variant="icon-alternative"] {
-    --tl-bullet-size: var(
-      --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_bullet-size
-    ) !important;
-  }
-  &[data-variant="avatar"] {
-    /* Avatar sizing fallback to default to maintain connector alignment */
-    --tl-bullet-size: var(
-      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
-    ) !important;
-  }
-
-  /* Control connector lines via the item ::before pseudo-element */
-  /* Inactive connector */
-  &::before {
-    border-left-width: var(
-      --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_connector-size
-    ) !important;
-    border-left-color: var(
-      --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_colors_connector-color
-    ) !important;
-  }
+  /* Mui gives every item a 70px min-height by default; content should drive height instead */
+  min-height: 0 !important;
+}
 
-  /* Active connector */
-  &[data-active]::before {
-    border-left-width: var(
-      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_connector-size
-    ) !important;
-    border-left-color: var(
-      --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_connector-color
-    ) !important;
-  }
+/* Mui reserves a flex:1 spacer (via ::before) for the opposite-content column even when none is
+   rendered. Recursica's Timeline never uses TimelineOppositeContent, so neutralize it to keep the
+   bullet/connector column flush against the left edge. */
+:global(.MuiTimelineItem-root)::before {
+  content: none !important;
+  flex: 0 !important;
+  padding: 0 !important;
 }
 
 .itemBody {
-  /* Space between the bullet and the content */
-  padding-left: var(
-    --recursica_ui-kit_components_timeline_properties_bullet-content-gap
+  padding: 0 0 0
+    var(--recursica_ui-kit_components_timeline_properties_bullet-content-gap) !important;
+}
+
+.itemConnector {
+  width: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_connector-size
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_colors_connector-color
+  ) !important;
+}
+.item[data-active] .itemConnector {
+  width: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_connector-size
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_connector-color
   ) !important;
 }
 
 .itemBullet {
+  display: flex !important;
+  align-items: center;
+  justify-content: center;
+  align-self: center !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  box-shadow: none !important;
+
   /* Default Variant */
-  :global(.mantine-Timeline-item)[data-variant="default"] & {
+  .item[data-variant="default"] & {
     width: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
     ) !important;
@@ -96,7 +79,7 @@
       --recursica_ui-kit_components_timeline-bullet_variants_types_default_variants_selection-states_inactive_properties_colors_border-color
     ) !important;
   }
-  :global(.mantine-Timeline-item)[data-variant="default"][data-active] & {
+  .item[data-variant="default"][data-active] & {
     background-color: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_default_variants_selection-states_active_properties_colors_background-color
     ) !important;
@@ -106,7 +89,7 @@
   }
 
   /* Icon Variant */
-  :global(.mantine-Timeline-item)[data-variant="icon"] & {
+  .item[data-variant="icon"] & {
     width: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_icon_properties_bullet-size
     ) !important;
@@ -143,7 +126,7 @@
       );
     }
   }
-  :global(.mantine-Timeline-item)[data-variant="icon"][data-active] & {
+  .item[data-variant="icon"][data-active] & {
     background-color: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_icon_variants_selection-states_active_properties_colors_background-color
     ) !important;
@@ -156,7 +139,7 @@
   }
 
   /* Icon Alternative Variant */
-  :global(.mantine-Timeline-item)[data-variant="icon-alternative"] & {
+  .item[data-variant="icon-alternative"] & {
     width: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_properties_bullet-size
     ) !important;
@@ -192,8 +175,7 @@
       );
     }
   }
-  :global(.mantine-Timeline-item)[data-variant="icon-alternative"][data-active]
-    & {
+  .item[data-variant="icon-alternative"][data-active] & {
     background-color: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_icon-alternative_variants_selection-states_active_properties_colors_background-color
     ) !important;
@@ -206,8 +188,14 @@
   }
 
   /* Avatar Variant */
-  :global(.mantine-Timeline-item)[data-variant="avatar"] & {
+  .item[data-variant="avatar"] & {
     /* Avatar sizing is often governed by the avatar itself, but we'll apply the radius and opacity */
+    width: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
+    ) !important;
+    height: var(
+      --recursica_ui-kit_components_timeline-bullet_variants_types_default_properties_bullet-size
+    ) !important;
     border-radius: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_properties_border-radius
     ) !important;
@@ -225,7 +213,7 @@
       --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_variants_selection-states_inactive_properties_colors_border-color
     ) !important;
   }
-  :global(.mantine-Timeline-item)[data-variant="avatar"][data-active] & {
+  .item[data-variant="avatar"][data-active] & {
     opacity: var(
       --recursica_ui-kit_components_timeline-bullet_variants_types_avatar_variants_selection-states_active_properties_avatar-opacity
     ) !important;
@@ -275,7 +263,7 @@
   ) !important;
 
   /* Active Title Color */
-  :global(.mantine-Timeline-item)[data-active] & {
+  .item[data-active] & {
     color: var(
       --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_title-color
     ) !important;
@@ -323,7 +311,7 @@
     --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_colors_description-color
   );
 
-  :global(.mantine-Timeline-item)[data-active] & {
+  .item[data-active] & {
     color: var(
       --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_description-color
     );
@@ -360,7 +348,7 @@
     --recursica_ui-kit_components_timeline_variants_selection-states_inactive_properties_colors_timestamp-color
   );
 
-  :global(.mantine-Timeline-item)[data-active] & {
+  .item[data-active] & {
     color: var(
       --recursica_ui-kit_components_timeline_variants_selection-states_active_properties_colors_timestamp-color
     );

package/src/components/Timeline/Timeline.tsx

@@ -7,7 +7,7 @@ import {
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
 import styles from "./Timeline.module.css";
-import { TimelineItem } from "./TimelineItem";
+import { TimelineItem, type TimelineItemProps } from "./TimelineItem";
 
 import { type RecursicaTimelineProps } from "@recursica/adapter-common";
 
@@ -23,7 +23,7 @@ export type TimelineProps = RecursicaOverStyled<
 
 interface TimelineComponent
   extends React.ForwardRefExoticComponent<
-    TimelineProps & React.RefAttributes<HTMLDivElement>
+    TimelineProps & React.RefAttributes<HTMLUListElement>
   > {
   Item: typeof TimelineItem;
 }
@@ -32,8 +32,10 @@ interface TimelineComponent
  * The `Timeline` component displays a list of events in chronological order.
  *
  * **Recursica Abstract:**
- * This component acts as a structural wrapper around Mui's `<Timeline>`.
- * It forces alignment and geometry strictly via the UI Kit's `.itemBullet` and connector definitions.
+ * This component acts as a structural wrapper around Mui's `<Timeline>`, composing
+ * `TimelineSeparator`/`TimelineDot`/`TimelineConnector`/`TimelineContent` per item
+ * (via `Timeline.Item`) so the bullet marker and connecting line render the same way
+ * they do in the Mantine adapter.
  *
  * @example
  * ```tsx
@@ -43,29 +45,21 @@ interface TimelineComponent
  * ```
  */
 const TimelineInner = React.forwardRef<HTMLUListElement, TimelineProps>(
-  function Timeline({ overStyled = false, ...rest }, ref) {
+  function Timeline(
+    { overStyled = false, active = -1, children, ...rest },
+    ref,
+  ) {
     const sanitizedProps = filterStylingProps(rest, overStyled);
 
-    const mergedClassNames: Partial<Record<string, string>> = {
-      root: styles.root,
-    };
-
-    const classNamesProp = (sanitizedProps as Record<string, unknown>)
-      .classNames;
-    if (
-      classNamesProp &&
-      typeof classNamesProp === "object" &&
-      !Array.isArray(classNamesProp)
-    ) {
-      const o = classNamesProp as Record<string, string>;
-      Object.keys(o).forEach((key) => {
-        if (mergedClassNames[key]) {
-          mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
-        } else {
-          mergedClassNames[key] = o[key];
-        }
-      });
-    }
+    const items = React.Children.toArray(children);
+    const decoratedItems = items.map((item, index) =>
+      React.isValidElement(item)
+        ? React.cloneElement(item as React.ReactElement<TimelineItemProps>, {
+            __active: active >= index,
+            __isLast: index === items.length - 1,
+          })
+        : item,
+    );
 
     return (
       <MuiTimeline
@@ -74,8 +68,10 @@ const TimelineInner = React.forwardRef<HTMLUListElement, TimelineProps>(
           MuiTimelineProps,
           "color" | "radius" | "bulletSize" | "lineWidth"
         >)}
-        classes={mergedClassNames}
-      />
+        classes={{ root: styles.root }}
+      >
+        {decoratedItems}
+      </MuiTimeline>
     );
   },
 );