From e5e6a675e5929296a7df19d4026e1c85008e6e23 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 31 Jul 2026 08:28:17 -0400
Subject: [PATCH 1/4] refactor(ui): type Mosaic render callbacks from
 MosaicComponentProps

MosaicComponentProps omitted the native color from a component's own props but
still typed render with the headless primitive's props, so a render callback
handed back a color?: string that collided with a color variant. Every call site
worked around it by destructuring the prop away.

Type render from MosaicElementProps so the omission is inherited everywhere, and
derive Menu's trigger props and Dialog's trigger from MosaicComponentProps rather
than re-deriving them from the headless types. Widening back to the primitive's
props stays safe, so the callbacks remain assignable to headless.
---
 .changeset/mosaic-render-props.md             |  2 ++
 packages/ui/src/mosaic/components/dialog.tsx  |  3 +-
 .../ui/src/mosaic/components/menu/menu.tsx    | 29 ++++++++++---------
 ...anization-profile-profile-section.view.tsx |  2 +-
 packages/ui/src/mosaic/props.ts               | 22 ++++++++++----
 5 files changed, 37 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/mosaic-render-props.md

diff --git a/.changeset/mosaic-render-props.md b/.changeset/mosaic-render-props.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-render-props.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/ui/src/mosaic/components/dialog.tsx b/packages/ui/src/mosaic/components/dialog.tsx
index 82867213791..baac978152b 100644
--- a/packages/ui/src/mosaic/components/dialog.tsx
+++ b/packages/ui/src/mosaic/components/dialog.tsx
@@ -4,6 +4,7 @@ import type { ReactNode } from 'react';
 import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
+import type { MosaicComponentProps } from '../props';
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
@@ -122,7 +123,7 @@ const Popup = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<ty
 );
 
 interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' | 'onOpenChange' | 'modal'> {
-  trigger: React.ComponentProps<typeof Primitive.Trigger>['render'];
+  trigger: MosaicComponentProps<'button'>['render'];
   children: ReactNode | ((ctx: { close: () => void }) => ReactNode);
   size?: DialogVariantProps['size'];
 }
diff --git a/packages/ui/src/mosaic/components/menu/menu.tsx b/packages/ui/src/mosaic/components/menu/menu.tsx
index 9941cccfc5b..981df196712 100644
--- a/packages/ui/src/mosaic/components/menu/menu.tsx
+++ b/packages/ui/src/mosaic/components/menu/menu.tsx
@@ -4,20 +4,22 @@ import type {
   MenuPortalProps,
   MenuProps,
   MenuSeparatorProps,
-  MenuTriggerProps,
 } from '@clerk/headless/menu';
 import { Menu as Primitive } from '@clerk/headless/menu';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
 import { iconRegistry } from '../../icons/registry';
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { Button } from '../button';
 import { styles } from './menu.styles';
 
 const EllipsisIcon = iconRegistry.ellipsis;
 
-export type { MenuProps, MenuSeparatorProps, MenuTriggerProps };
+export type { MenuProps, MenuSeparatorProps };
+
+export type MenuTriggerProps = MosaicComponentProps<'button'>;
 
 /**
  * Opens the menu. Renders a ghost `Button` holding an ellipsis glyph by default;
@@ -27,20 +29,21 @@ export const MenuTrigger = React.forwardRef<HTMLButtonElement, MenuTriggerProps>
   { render, className, style, children, ...rest },
   ref,
 ) {
+  const trigger: MenuTriggerProps['render'] =
+    render ??
+    (props => (
+      <Button
+        variant='ghost'
+        size='sm'
+        shape={children ? 'default' : 'square'}
+        {...props}
+      />
+    ));
+
   return (
     <Primitive.Trigger
       ref={ref}
-      render={
-        render ??
-        (({ color: _nativeColor, ...props }) => (
-          <Button
-            variant='ghost'
-            size='sm'
-            shape={children ? 'default' : 'square'}
-            {...props}
-          />
-        ))
-      }
+      render={trigger}
       {...mergeStyleProps(themeProps('menu-trigger'), className, style)}
       {...rest}
     >
diff --git a/packages/ui/src/mosaic/organization/organization-profile-profile-section.view.tsx b/packages/ui/src/mosaic/organization/organization-profile-profile-section.view.tsx
index b07ca69503f..d77683b2fde 100644
--- a/packages/ui/src/mosaic/organization/organization-profile-profile-section.view.tsx
+++ b/packages/ui/src/mosaic/organization/organization-profile-profile-section.view.tsx
@@ -82,7 +82,7 @@ export function OrganizationProfileProfileSectionView({
         <Dialog
           open={isOpen}
           onOpenChange={open => send({ type: open ? 'OPEN' : 'CANCEL' })}
-          trigger={({ color: _nativeColor, ...props }) => (
+          trigger={props => (
             <Button
               variant='outline'
               {...props}
diff --git a/packages/ui/src/mosaic/props.ts b/packages/ui/src/mosaic/props.ts
index ff31214b8bb..a2d4f6a60f7 100644
--- a/packages/ui/src/mosaic/props.ts
+++ b/packages/ui/src/mosaic/props.ts
@@ -1,19 +1,29 @@
-import type { RenderPropOrElement } from '@clerk/headless/utils';
+import type { RenderProp } from '@clerk/headless/utils';
 import type React from 'react';
 
 /**
- * The base props every Mosaic component accepts: the native props for its default
- * tag, plus the `render` escape hatch that swaps the rendered element.
+ * The native props for `Tag` as Mosaic exposes them.
  *
  * `color` is omitted because it is a non-standard HTML attribute typed `string`,
  * which would widen any component that exposes `color` as a variant. Omitting it
  * here rather than per component means a new component inherits the narrowing.
  */
-export type MosaicComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = Omit<
+export type MosaicElementProps<Tag extends keyof React.JSX.IntrinsicElements> = Omit<
   React.ComponentPropsWithRef<Tag>,
   'color'
-> & {
-  render?: RenderPropOrElement<Tag>;
+>;
+
+/**
+ * The base props every Mosaic component accepts: the native props for its default
+ * tag, plus the `render` escape hatch that swaps the rendered element.
+ *
+ * `render` hands back `MosaicElementProps` rather than the headless primitive's
+ * props, so a callback can spread them onto a Mosaic component without the native
+ * `color` colliding with a `color` variant. Widening back to the primitive's props
+ * is safe: dropping an optional prop leaves the callback assignable to headless.
+ */
+export type MosaicComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = MosaicElementProps<Tag> & {
+  render?: RenderProp<MosaicElementProps<Tag>> | React.ReactElement;
 };
 
 // The public styling contract, emitted onto a component's root element:

From f6c3791e500f915ba94d8305c47eeba99e214d98 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 31 Jul 2026 15:35:31 -0400
Subject: [PATCH 2/4] refactor(ui): route Tabs, Dialog, and Item props through
 MosaicComponentProps

Tabs and Dialog took their parts' props straight from the headless primitives, so
their render callbacks still handed back the native color?: string that collides
with a color variant. Add MosaicPartProps to re-expose a headless part's props the
Mosaic way: the part's own additions kept, color and render swapped for Mosaic's.

Item redeclared render as RenderProp<React.HTMLAttributes<HTMLElement>> after
omitting the inherited one. Nothing depended on the widening: the inherited render
types the link case its docblock and tests already cover, so drop the override.
---
 packages/ui/src/mosaic/components/dialog.tsx  |  74 ++++++-----
 .../ui/src/mosaic/components/item/item.tsx    |   6 +-
 packages/ui/src/mosaic/components/tabs.tsx    | 117 +++++++++---------
 packages/ui/src/mosaic/props.ts               |   9 ++
 4 files changed, 104 insertions(+), 102 deletions(-)

diff --git a/packages/ui/src/mosaic/components/dialog.tsx b/packages/ui/src/mosaic/components/dialog.tsx
index baac978152b..30e6d315aee 100644
--- a/packages/ui/src/mosaic/components/dialog.tsx
+++ b/packages/ui/src/mosaic/components/dialog.tsx
@@ -4,7 +4,7 @@ import type { ReactNode } from 'react';
 import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import type { MosaicComponentProps } from '../props';
+import type { MosaicComponentProps, MosaicPartProps } from '../props';
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
@@ -82,45 +82,43 @@ declare module '../registry' {
   }
 }
 
-const Backdrop = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.Backdrop>>(
-  function DialogBackdrop(props, ref) {
-    const { backdrop } = useRecipe(dialogRecipe);
-    return (
-      <Primitive.Backdrop
-        ref={ref}
-        {...props}
-        {...backdrop}
-      />
-    );
-  },
-);
+export type DialogBackdropProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Backdrop>, 'div'>;
+export type DialogViewportProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Viewport>, 'div'>;
+export type DialogPopupProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Popup>, 'div'>;
 
-const Viewport = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.Viewport>>(
-  function DialogViewport(props, ref) {
-    const { viewport } = useRecipe(dialogRecipe);
-    return (
-      <Primitive.Viewport
-        ref={ref}
-        {...props}
-        {...viewport}
-      />
-    );
-  },
-);
+const Backdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(function DialogBackdrop(props, ref) {
+  const { backdrop } = useRecipe(dialogRecipe);
+  return (
+    <Primitive.Backdrop
+      ref={ref}
+      {...props}
+      {...backdrop}
+    />
+  );
+});
 
-const Popup = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.Popup>>(
-  function DialogPopup(props, ref) {
-    const variantProps = React.useContext(DialogVariantContext);
-    const { popup } = useRecipe(dialogRecipe, { variants: variantProps });
-    return (
-      <Primitive.Popup
-        ref={ref}
-        {...props}
-        {...popup}
-      />
-    );
-  },
-);
+const Viewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(function DialogViewport(props, ref) {
+  const { viewport } = useRecipe(dialogRecipe);
+  return (
+    <Primitive.Viewport
+      ref={ref}
+      {...props}
+      {...viewport}
+    />
+  );
+});
+
+const Popup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
+  const variantProps = React.useContext(DialogVariantContext);
+  const { popup } = useRecipe(dialogRecipe, { variants: variantProps });
+  return (
+    <Primitive.Popup
+      ref={ref}
+      {...props}
+      {...popup}
+    />
+  );
+});
 
 interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' | 'onOpenChange' | 'modal'> {
   trigger: MosaicComponentProps<'button'>['render'];
diff --git a/packages/ui/src/mosaic/components/item/item.tsx b/packages/ui/src/mosaic/components/item/item.tsx
index d79cc885538..2b93ccc66e7 100644
--- a/packages/ui/src/mosaic/components/item/item.tsx
+++ b/packages/ui/src/mosaic/components/item/item.tsx
@@ -1,4 +1,4 @@
-import { type RenderProp, useRender } from '@clerk/headless/utils';
+import { useRender } from '@clerk/headless/utils';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
@@ -16,7 +16,7 @@ const DEFAULT_SIZE: Size = 'md';
 /** Carries `Item.Root`'s size down to the parts it scales (`Item.Media`). */
 const ItemContext = React.createContext<Size>(DEFAULT_SIZE);
 
-export type ItemProps = Omit<MosaicComponentProps<'div'>, 'render'> & {
+export type ItemProps = MosaicComponentProps<'div'> & {
   /**
    * Row height and gap. Also sizes a nested `Item.Media`, which reads this from
    * context rather than taking its own prop, so a row scales as one unit.
@@ -24,8 +24,6 @@ export type ItemProps = Omit<MosaicComponentProps<'div'>, 'render'> & {
    * @default 'md'
    */
   size?: Size;
-  /** Render a custom element (e.g. a link or button) in place of the default `div`. */
-  render?: RenderProp<React.HTMLAttributes<HTMLElement>>;
 };
 
 /**
diff --git a/packages/ui/src/mosaic/components/tabs.tsx b/packages/ui/src/mosaic/components/tabs.tsx
index bf9a76728a5..a599113040f 100644
--- a/packages/ui/src/mosaic/components/tabs.tsx
+++ b/packages/ui/src/mosaic/components/tabs.tsx
@@ -1,6 +1,7 @@
 import React from 'react';
 
 import { Tabs as Primitive } from '../primitives/tabs';
+import type { MosaicPartProps } from '../props';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
@@ -98,70 +99,66 @@ declare module '../registry' {
   }
 }
 
-const List = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.List>>(
-  function TabsList(props, ref) {
-    const { list } = useRecipe(tabsRecipe);
-    return (
-      <Primitive.List
-        ref={ref}
-        {...props}
-        {...list}
-      />
-    );
-  },
-);
+export type TabsListProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.List>, 'div'>;
+export type TabsTabProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Tab>, 'button'>;
+export type TabsTriggerProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Trigger>, 'button'>;
+export type TabsPanelProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Panel>, 'div'>;
+export type TabsIndicatorProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Indicator>, 'span'>;
 
-const Tab = React.forwardRef<HTMLButtonElement, React.ComponentPropsWithoutRef<typeof Primitive.Tab>>(
-  function TabsTab(props, ref) {
-    const { tab } = useRecipe(tabsRecipe);
-    return (
-      <Primitive.Tab
-        ref={ref}
-        {...props}
-        {...tab}
-      />
-    );
-  },
-);
+const List = React.forwardRef<HTMLDivElement, TabsListProps>(function TabsList(props, ref) {
+  const { list } = useRecipe(tabsRecipe);
+  return (
+    <Primitive.List
+      ref={ref}
+      {...props}
+      {...list}
+    />
+  );
+});
 
-const Trigger = React.forwardRef<HTMLButtonElement, React.ComponentPropsWithoutRef<typeof Primitive.Trigger>>(
-  function TabsTrigger(props, ref) {
-    const { trigger } = useRecipe(tabsRecipe);
-    return (
-      <Primitive.Trigger
-        ref={ref}
-        {...props}
-        {...trigger}
-      />
-    );
-  },
-);
+const Tab = React.forwardRef<HTMLButtonElement, TabsTabProps>(function TabsTab(props, ref) {
+  const { tab } = useRecipe(tabsRecipe);
+  return (
+    <Primitive.Tab
+      ref={ref}
+      {...props}
+      {...tab}
+    />
+  );
+});
 
-const Panel = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.Panel>>(
-  function TabsPanel(props, ref) {
-    const { panel } = useRecipe(tabsRecipe);
-    return (
-      <Primitive.Panel
-        ref={ref}
-        {...props}
-        {...panel}
-      />
-    );
-  },
-);
+const Trigger = React.forwardRef<HTMLButtonElement, TabsTriggerProps>(function TabsTrigger(props, ref) {
+  const { trigger } = useRecipe(tabsRecipe);
+  return (
+    <Primitive.Trigger
+      ref={ref}
+      {...props}
+      {...trigger}
+    />
+  );
+});
 
-const Indicator = React.forwardRef<HTMLSpanElement, React.ComponentPropsWithoutRef<typeof Primitive.Indicator>>(
-  function TabsIndicator(props, ref) {
-    const { indicator } = useRecipe(tabsRecipe);
-    return (
-      <Primitive.Indicator
-        ref={ref}
-        {...props}
-        {...indicator}
-      />
-    );
-  },
-);
+const Panel = React.forwardRef<HTMLDivElement, TabsPanelProps>(function TabsPanel(props, ref) {
+  const { panel } = useRecipe(tabsRecipe);
+  return (
+    <Primitive.Panel
+      ref={ref}
+      {...props}
+      {...panel}
+    />
+  );
+});
+
+const Indicator = React.forwardRef<HTMLSpanElement, TabsIndicatorProps>(function TabsIndicator(props, ref) {
+  const { indicator } = useRecipe(tabsRecipe);
+  return (
+    <Primitive.Indicator
+      ref={ref}
+      {...props}
+      {...indicator}
+    />
+  );
+});
 
 /** Styled mosaic Tabs components built on headless Tabs primitives. */
 export const Tabs: {
diff --git a/packages/ui/src/mosaic/props.ts b/packages/ui/src/mosaic/props.ts
index 75d8e88248c..196371823b5 100644
--- a/packages/ui/src/mosaic/props.ts
+++ b/packages/ui/src/mosaic/props.ts
@@ -24,6 +24,15 @@ export type MosaicComponentProps<Tag extends keyof React.JSX.IntrinsicElements>
   render?: RenderProp<MosaicElementProps<Tag>> | React.ReactElement;
 };
 
+/**
+ * A headless part's props as Mosaic re-exposes them: the part's own additions
+ * (`value`, `disabled`, …) kept, with `color` and `render` swapped for Mosaic's.
+ * Use this when wrapping a part whose props are more than its tag's — otherwise
+ * `MosaicComponentProps<Tag>` says the same thing more directly.
+ */
+export type MosaicPartProps<Props, Tag extends keyof React.JSX.IntrinsicElements> = Omit<Props, 'color' | 'render'> &
+  Pick<MosaicComponentProps<Tag>, 'render'>;
+
 // The public styling contract, emitted onto a component's root element:
 //   1. `--cl-*` vars      — from `tokens.stylex.ts` (`:root { --cl-color-primary: … }`)
 //   2. `.cl-<slot>` class — from `themeProps` (`.cl-button { … }`)

From 57f1ce778e4b14083cf7317f75ab0da682850e25 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 31 Jul 2026 16:05:37 -0400
Subject: [PATCH 3/4] fix(ui): restore Item's ref-less render prop

The inherited render pins ref to the default tag's HTMLDivElement, which a callback
cannot spread onto the <a> or <button> a row renders. Restore the override and say
why it exists, so the next reader doesn't take it for redundant.
---
 packages/ui/src/mosaic/components/item/item.tsx | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/mosaic/components/item/item.tsx b/packages/ui/src/mosaic/components/item/item.tsx
index 2b93ccc66e7..479298c50f3 100644
--- a/packages/ui/src/mosaic/components/item/item.tsx
+++ b/packages/ui/src/mosaic/components/item/item.tsx
@@ -1,4 +1,4 @@
-import { useRender } from '@clerk/headless/utils';
+import { type RenderProp, useRender } from '@clerk/headless/utils';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
@@ -16,7 +16,7 @@ const DEFAULT_SIZE: Size = 'md';
 /** Carries `Item.Root`'s size down to the parts it scales (`Item.Media`). */
 const ItemContext = React.createContext<Size>(DEFAULT_SIZE);
 
-export type ItemProps = MosaicComponentProps<'div'> & {
+export type ItemProps = Omit<MosaicComponentProps<'div'>, 'render'> & {
   /**
    * Row height and gap. Also sizes a nested `Item.Media`, which reads this from
    * context rather than taking its own prop, so a row scales as one unit.
@@ -24,6 +24,14 @@ export type ItemProps = MosaicComponentProps<'div'> & {
    * @default 'md'
    */
   size?: Size;
+  /**
+   * Render a custom element (e.g. a link or button) in place of the default `div`.
+   *
+   * Typed without a `ref`, unlike the inherited `render`: that one pins `ref` to
+   * the default tag's `HTMLDivElement`, which a callback cannot spread onto the
+   * `<a>` or `<button>` this row exists to render.
+   */
+  render?: RenderProp<React.HTMLAttributes<HTMLElement>>;
 };
 
 /**

From 716a4ee24f7fe55c1656a77fe86db9be486778fd Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 31 Jul 2026 16:40:09 -0400
Subject: [PATCH 4/4] refactor(headless): give render props their own
 tag-agnostic type

`RenderPropOrElement<Tag>` pinned a `render` callback's props to the part's
default tag, so every Mosaic component worked around the same two problems:
a `ref` that would not spread onto a different element, and the non-standard
`color` attribute colliding with a `color` variant.

Splits the two contracts at the source. `ComponentProps<Tag>` stays pinned to
the tag for the component's own props; the new `RenderProps` is tag-agnostic,
matching Base UI's `HTMLProps`. Both drop `color`.

Deletes the workarounds this made unnecessary: `MosaicPartProps`, Item's
redeclared `render`, box's hand-rolled render prop, and the last `color`
destructure in swingset.
---
 packages/headless/src/utils/index.ts          |  1 +
 .../headless/src/utils/use-render.test-d.ts   | 34 ++++++++++---
 packages/headless/src/utils/use-render.tsx    | 49 +++++++++++++------
 .../src/stories/dialog.component.stories.tsx  |  5 +-
 .../src/mosaic/components/button/button.tsx   |  4 +-
 packages/ui/src/mosaic/components/dialog.tsx  |  8 +--
 .../ui/src/mosaic/components/item/item.tsx    | 12 +----
 packages/ui/src/mosaic/components/tabs.tsx    | 11 ++---
 packages/ui/src/mosaic/primitives/box.tsx     |  6 +--
 packages/ui/src/mosaic/props.ts               | 24 +++------
 10 files changed, 86 insertions(+), 68 deletions(-)

diff --git a/packages/headless/src/utils/index.ts b/packages/headless/src/utils/index.ts
index f2a2d4c17c4..cafe09fe0a2 100644
--- a/packages/headless/src/utils/index.ts
+++ b/packages/headless/src/utils/index.ts
@@ -6,5 +6,6 @@ export {
   mergeProps,
   type RenderProp,
   type RenderPropOrElement,
+  type RenderProps,
   useRender,
 } from './use-render';
diff --git a/packages/headless/src/utils/use-render.test-d.ts b/packages/headless/src/utils/use-render.test-d.ts
index 91701264962..051fe2eaad4 100644
--- a/packages/headless/src/utils/use-render.test-d.ts
+++ b/packages/headless/src/utils/use-render.test-d.ts
@@ -1,14 +1,36 @@
 import type React from 'react';
 import { describe, expectTypeOf, test } from 'vitest';
 
-import type { ComponentProps } from './use-render';
+import type { ComponentProps, RenderProps } from './use-render';
+
+type RenderFn<Tag extends keyof React.JSX.IntrinsicElements> = Extract<
+  NonNullable<ComponentProps<Tag>['render']>,
+  (...args: never[]) => unknown
+>;
+type RenderArg<Tag extends keyof React.JSX.IntrinsicElements> =
+  RenderFn<Tag> extends (props: infer P) => React.ReactElement ? P : never;
+type HasColor<P> = 'color' extends keyof P ? true : false;
 
 describe('use-render', () => {
-  test('render prop arg is narrowed to the element tag props, not the generic HTMLAttributes<HTMLElement>', () => {
-    type Props = ComponentProps<'button'>;
-    type RenderFn = Extract<NonNullable<Props['render']>, (...args: never[]) => unknown>;
-    type RenderArg = RenderFn extends (props: infer P) => React.ReactElement ? P : never;
-    expectTypeOf<RenderArg>().toEqualTypeOf<React.ComponentPropsWithRef<'button'>>();
+  test('a part keeps its own tag props', () => {
+    expectTypeOf<ComponentProps<'button'>>().toExtend<{ type?: 'button' | 'submit' | 'reset' }>();
+  });
+
+  test('the legacy `color` attribute is dropped, so it cannot widen a `color` variant', () => {
+    expectTypeOf<HasColor<ComponentProps<'button'>>>().toEqualTypeOf<false>();
+    expectTypeOf<HasColor<RenderArg<'button'>>>().toEqualTypeOf<false>();
+  });
+
+  test('the render arg is the tag-agnostic RenderProps, not the default tag props', () => {
+    expectTypeOf<RenderArg<'button'>>().toEqualTypeOf<RenderProps>();
+    expectTypeOf<RenderArg<'div'>>().toEqualTypeOf<RenderProps>();
+  });
+
+  test('render props spread onto an element other than the default tag', () => {
+    // The point of `render`: a `div` part rendering an `<a>`. A tag-pinned `ref`
+    // would make this fail, which is what every call site used to work around.
+    expectTypeOf<RenderProps>().toExtend<React.ComponentPropsWithRef<'a'>>();
+    expectTypeOf<RenderProps>().toExtend<React.ComponentPropsWithRef<'button'>>();
   });
 
   test('render also accepts an element to clone', () => {
diff --git a/packages/headless/src/utils/use-render.tsx b/packages/headless/src/utils/use-render.tsx
index 8a58fd224d1..b314ea49396 100644
--- a/packages/headless/src/utils/use-render.tsx
+++ b/packages/headless/src/utils/use-render.tsx
@@ -5,27 +5,48 @@ import * as React from 'react';
 // Types
 // ---------------------------------------------------------------------------
 
+/**
+ * The props a `render` callback receives, deliberately *not* the default tag's props.
+ *
+ * `render` exists to swap the rendered element, so the element's type is unknown at
+ * the point this is declared. Two things follow, and both were previously worked
+ * around at each call site instead of here:
+ *
+ * - `ref` is not pinned to the default tag. A `div` part rendering an `<a>` could
+ *   not spread its props, because `Ref<HTMLDivElement>` is not a `Ref<HTMLAnchorElement>`.
+ * - `color` is dropped. It is a non-standard HTML attribute typed `string`, so it
+ *   collides with the `color` variant a styled component spreads these props into.
+ */
+export type RenderProps = Omit<React.HTMLAttributes<HTMLElement>, 'color'> & {
+  // SAFETY: the rendered element is chosen by the callback, after this type is fixed, so
+  // no concrete element type is correct here. `Ref<Element>` does not work: `RefObject<Element>`
+  // is not a `RefObject<HTMLAnchorElement>`. `any` is what makes the ref spreadable onto
+  // whatever the callback returns, which is the whole point of `render`. Base UI's
+  // `HTMLProps` resolves this the same way.
+  ref?: React.Ref<any>;
+};
+
 /**
  * A render prop: a function that receives computed HTML props and returns a JSX element.
  */
-export type RenderProp<Props = React.HTMLAttributes<HTMLElement>> = (props: Props) => React.ReactElement;
+export type RenderProp<Props = RenderProps> = (props: Props) => React.ReactElement;
 
 /**
  * A `render` prop: a render function receiving the part's computed props, or a
- * React element to clone with them (`render={<Link/>}`). The element form lets a
- * part render a component whose own props diverge from the tag's, which a render
- * function cannot express — it is typed to receive the tag's props verbatim.
+ * React element to clone with them (`render={<Link/>}`).
  */
-export type RenderPropOrElement<Tag extends keyof React.JSX.IntrinsicElements> =
-  | RenderProp<React.ComponentPropsWithRef<Tag>>
-  | React.ReactElement;
+export type RenderPropOrElement = RenderProp | React.ReactElement;
 
 /**
- * Props accepted by any primitive part. Extends the native props for `Tag`
- * and adds the optional `render` escape hatch, narrowed to that tag's props.
+ * Props accepted by any primitive part: the native props for `Tag` plus the
+ * optional `render` escape hatch. `color` is dropped for the reason given on
+ * `RenderProps` — a part and its render callback expose the same contract.
  */
-export type ComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = React.ComponentPropsWithRef<Tag> & {
-  render?: RenderPropOrElement<Tag>;
+export type ComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = Omit<
+  React.ComponentPropsWithRef<Tag>,
+  'color'
+> & {
+  render?: RenderPropOrElement;
 };
 
 /**
@@ -125,7 +146,7 @@ interface UseRenderParamsBase<
   /** Fallback HTML tag when `render` is not provided. */
   defaultTagName: Tag;
   /** Render prop or element from the consumer. */
-  render?: RenderPropOrElement<Tag>;
+  render?: RenderPropOrElement;
   /** Ref(s) to merge onto the rendered element. Merged with the element's own ref. */
   ref?: React.Ref<unknown> | Array<React.Ref<unknown> | undefined>;
   /** State object. Keys are mapped to data attributes via `stateAttributesMapping`. */
@@ -197,9 +218,7 @@ export function useRender<
   const computedProps = { ...props, ...dataAttrs };
 
   if (typeof render === 'function') {
-    // SAFETY: computedProps is the tag's props widened with data-* attrs; the render
-    // function is declared to receive this tag's props.
-    return render({ ...computedProps, ref: mergedRef } as React.ComponentPropsWithRef<Tag>);
+    return render({ ...computedProps, ref: mergedRef });
   }
 
   if (React.isValidElement(render)) {
diff --git a/packages/swingset/src/stories/dialog.component.stories.tsx b/packages/swingset/src/stories/dialog.component.stories.tsx
index afe4b77b335..051d810540c 100644
--- a/packages/swingset/src/stories/dialog.component.stories.tsx
+++ b/packages/swingset/src/stories/dialog.component.stories.tsx
@@ -1,4 +1,5 @@
 /** @jsxImportSource @emotion/react */
+import type { RenderProps } from '@clerk/headless/utils';
 import { Button } from '@clerk/ui/mosaic/components/button';
 import { Dialog, dialogRecipe } from '@clerk/ui/mosaic/components/dialog';
 
@@ -15,9 +16,7 @@ export const meta: StoryMeta = {
   styles: dialogRecipe,
 };
 
-const dialogTrigger = ({ color: _nativeColor, ...props }: React.HTMLAttributes<HTMLElement>) => (
-  <Button {...props}>Open dialog</Button>
-);
+const dialogTrigger = (props: RenderProps) => <Button {...props}>Open dialog</Button>;
 
 export function Default(args: Record<string, unknown>) {
   const { size } = args as { size?: 'md' | 'lg' };
diff --git a/packages/ui/src/mosaic/components/button/button.tsx b/packages/ui/src/mosaic/components/button/button.tsx
index df42713e57d..7906e9554b7 100644
--- a/packages/ui/src/mosaic/components/button/button.tsx
+++ b/packages/ui/src/mosaic/components/button/button.tsx
@@ -1,12 +1,12 @@
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import type { MosaicComponentProps } from '../../props';
+import type { MosaicElementProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { truncationStyles } from '../typography.styles';
 import { iconSizes, sizes, styles, variants } from './button.styles';
 
-export interface ButtonProps extends Omit<MosaicComponentProps<'button'>, 'render'> {
+export interface ButtonProps extends MosaicElementProps<'button'> {
   color?: 'primary' | 'neutral' | 'negative';
   variant?: 'filled' | 'outline' | 'ghost' | 'link';
   size?: 'sm' | 'md' | 'lg';
diff --git a/packages/ui/src/mosaic/components/dialog.tsx b/packages/ui/src/mosaic/components/dialog.tsx
index 30e6d315aee..45927daf298 100644
--- a/packages/ui/src/mosaic/components/dialog.tsx
+++ b/packages/ui/src/mosaic/components/dialog.tsx
@@ -4,7 +4,7 @@ import type { ReactNode } from 'react';
 import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import type { MosaicComponentProps, MosaicPartProps } from '../props';
+import type { MosaicComponentProps } from '../props';
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
@@ -82,9 +82,9 @@ declare module '../registry' {
   }
 }
 
-export type DialogBackdropProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Backdrop>, 'div'>;
-export type DialogViewportProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Viewport>, 'div'>;
-export type DialogPopupProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Popup>, 'div'>;
+export type DialogBackdropProps = React.ComponentPropsWithoutRef<typeof Primitive.Backdrop>;
+export type DialogViewportProps = React.ComponentPropsWithoutRef<typeof Primitive.Viewport>;
+export type DialogPopupProps = React.ComponentPropsWithoutRef<typeof Primitive.Popup>;
 
 const Backdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(function DialogBackdrop(props, ref) {
   const { backdrop } = useRecipe(dialogRecipe);
diff --git a/packages/ui/src/mosaic/components/item/item.tsx b/packages/ui/src/mosaic/components/item/item.tsx
index 479298c50f3..2b93ccc66e7 100644
--- a/packages/ui/src/mosaic/components/item/item.tsx
+++ b/packages/ui/src/mosaic/components/item/item.tsx
@@ -1,4 +1,4 @@
-import { type RenderProp, useRender } from '@clerk/headless/utils';
+import { useRender } from '@clerk/headless/utils';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
@@ -16,7 +16,7 @@ const DEFAULT_SIZE: Size = 'md';
 /** Carries `Item.Root`'s size down to the parts it scales (`Item.Media`). */
 const ItemContext = React.createContext<Size>(DEFAULT_SIZE);
 
-export type ItemProps = Omit<MosaicComponentProps<'div'>, 'render'> & {
+export type ItemProps = MosaicComponentProps<'div'> & {
   /**
    * Row height and gap. Also sizes a nested `Item.Media`, which reads this from
    * context rather than taking its own prop, so a row scales as one unit.
@@ -24,14 +24,6 @@ export type ItemProps = Omit<MosaicComponentProps<'div'>, 'render'> & {
    * @default 'md'
    */
   size?: Size;
-  /**
-   * Render a custom element (e.g. a link or button) in place of the default `div`.
-   *
-   * Typed without a `ref`, unlike the inherited `render`: that one pins `ref` to
-   * the default tag's `HTMLDivElement`, which a callback cannot spread onto the
-   * `<a>` or `<button>` this row exists to render.
-   */
-  render?: RenderProp<React.HTMLAttributes<HTMLElement>>;
 };
 
 /**
diff --git a/packages/ui/src/mosaic/components/tabs.tsx b/packages/ui/src/mosaic/components/tabs.tsx
index a599113040f..6c4d428cd65 100644
--- a/packages/ui/src/mosaic/components/tabs.tsx
+++ b/packages/ui/src/mosaic/components/tabs.tsx
@@ -1,7 +1,6 @@
 import React from 'react';
 
 import { Tabs as Primitive } from '../primitives/tabs';
-import type { MosaicPartProps } from '../props';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
@@ -99,11 +98,11 @@ declare module '../registry' {
   }
 }
 
-export type TabsListProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.List>, 'div'>;
-export type TabsTabProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Tab>, 'button'>;
-export type TabsTriggerProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Trigger>, 'button'>;
-export type TabsPanelProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Panel>, 'div'>;
-export type TabsIndicatorProps = MosaicPartProps<React.ComponentPropsWithoutRef<typeof Primitive.Indicator>, 'span'>;
+export type TabsListProps = React.ComponentPropsWithoutRef<typeof Primitive.List>;
+export type TabsTabProps = React.ComponentPropsWithoutRef<typeof Primitive.Tab>;
+export type TabsTriggerProps = React.ComponentPropsWithoutRef<typeof Primitive.Trigger>;
+export type TabsPanelProps = React.ComponentPropsWithoutRef<typeof Primitive.Panel>;
+export type TabsIndicatorProps = React.ComponentPropsWithoutRef<typeof Primitive.Indicator>;
 
 const List = React.forwardRef<HTMLDivElement, TabsListProps>(function TabsList(props, ref) {
   const { list } = useRecipe(tabsRecipe);
diff --git a/packages/ui/src/mosaic/primitives/box.tsx b/packages/ui/src/mosaic/primitives/box.tsx
index b5269bf93f7..6ef439c2e60 100644
--- a/packages/ui/src/mosaic/primitives/box.tsx
+++ b/packages/ui/src/mosaic/primitives/box.tsx
@@ -1,4 +1,4 @@
-import { type ComponentProps, type RenderProp, useRender } from '@clerk/headless/utils';
+import { type ComponentProps, useRender } from '@clerk/headless/utils';
 import React from 'react';
 
 /**
@@ -9,9 +9,7 @@ import React from 'react';
  *
  * Accepts render prop with any element type — styling passes along regardless of what's rendered.
  */
-export type BoxProps = Omit<ComponentProps<'div'>, 'render'> & {
-  render?: RenderProp<React.HTMLAttributes<HTMLElement>> | React.ReactElement;
-};
+export type BoxProps = ComponentProps<'div'>;
 
 export const Box = React.forwardRef<HTMLElement, BoxProps>(function Box(props, ref) {
   const { render, ...rest } = props;
diff --git a/packages/ui/src/mosaic/props.ts b/packages/ui/src/mosaic/props.ts
index 196371823b5..8289cfea83b 100644
--- a/packages/ui/src/mosaic/props.ts
+++ b/packages/ui/src/mosaic/props.ts
@@ -1,10 +1,10 @@
-import type { RenderProp } from '@clerk/headless/utils';
+import type { ComponentProps } from '@clerk/headless/utils';
 import type React from 'react';
 
 /**
  * The native props for a tag, minus the non-standard HTML `color` attribute. That
  * attribute is typed `string`, so leaving it in widens any component that exposes
- * `color` as a variant union.
+ * `color` as a variant union. Use for a component that has no `render`.
  */
 export type MosaicElementProps<Tag extends keyof React.JSX.IntrinsicElements> = Omit<
   React.ComponentPropsWithRef<Tag>,
@@ -15,23 +15,11 @@ export type MosaicElementProps<Tag extends keyof React.JSX.IntrinsicElements> =
  * The base props every Mosaic component accepts: the native props for its default
  * tag, plus the `render` escape hatch that swaps the rendered element.
  *
- * `color` is dropped from both the props and the `render` callback's argument, so
- * the props a `render` callback receives spread straight into another Mosaic
- * component. Doing it here rather than per component means a new component
- * inherits the narrowing.
+ * Mosaic's name for the headless part contract, which already drops `color` and
+ * hands `render` callbacks tag-agnostic props. Aliased rather than rebuilt so the
+ * two layers cannot drift, and so `@clerk/ui` consumers have a name to import.
  */
-export type MosaicComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = MosaicElementProps<Tag> & {
-  render?: RenderProp<MosaicElementProps<Tag>> | React.ReactElement;
-};
-
-/**
- * A headless part's props as Mosaic re-exposes them: the part's own additions
- * (`value`, `disabled`, …) kept, with `color` and `render` swapped for Mosaic's.
- * Use this when wrapping a part whose props are more than its tag's — otherwise
- * `MosaicComponentProps<Tag>` says the same thing more directly.
- */
-export type MosaicPartProps<Props, Tag extends keyof React.JSX.IntrinsicElements> = Omit<Props, 'color' | 'render'> &
-  Pick<MosaicComponentProps<Tag>, 'render'>;
+export type MosaicComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = ComponentProps<Tag>;
 
 // The public styling contract, emitted onto a component's root element:
 //   1. `--cl-*` vars      — from `tokens.stylex.ts` (`:root { --cl-color-primary: … }`)