From 93ee54801067a8192a69c706350a3f0b6479f32d Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 1 Apr 2026 11:42:38 -0400
Subject: [PATCH 1/2] feat(ui): Add composite, button, and text components

---
 .../ui/src/ceramic/{button.ts => button.tsx}  | 39 +++++++++++++---
 packages/ui/src/ceramic/composite.tsx         | 46 +++++++++++++++++++
 packages/ui/src/ceramic/{text.ts => text.tsx} | 32 ++++++++++++-
 packages/ui/src/ceramic/variants.ts           |  6 +--
 4 files changed, 113 insertions(+), 10 deletions(-)
 rename packages/ui/src/ceramic/{button.ts => button.tsx} (72%)
 create mode 100644 packages/ui/src/ceramic/composite.tsx
 rename packages/ui/src/ceramic/{text.ts => text.tsx} (68%)

diff --git a/packages/ui/src/ceramic/button.ts b/packages/ui/src/ceramic/button.tsx
similarity index 72%
rename from packages/ui/src/ceramic/button.ts
rename to packages/ui/src/ceramic/button.tsx
index 21326c01cfe..7247499a922 100644
--- a/packages/ui/src/ceramic/button.ts
+++ b/packages/ui/src/ceramic/button.tsx
@@ -1,9 +1,11 @@
-import { style, variants } from './variants';
+import * as React from 'react';
+
+import { Composite, type RenderProp } from './composite';
+import { type StyleRule, type VariantProps, style, variants } from './variants';
 
 export const buttonStyles = variants({
   base: style(theme => ({
     appearance: 'none',
-    boxSizing: 'border-box',
     position: 'relative',
     display: 'inline-flex',
     alignItems: 'center',
@@ -16,8 +18,6 @@ export const buttonStyles = variants({
     fontFamily: theme.fontFamilies.sans,
     border: 'none',
     outline: 'none',
-    margin: 0,
-    paddingBlock: 0,
     paddingInline: theme.spacing[3],
     cursor: 'pointer',
     textDecoration: 'none',
@@ -55,7 +55,7 @@ export const buttonStyles = variants({
     },
   })),
   variants: {
-    variant: {
+    color: {
       primary: style(theme => ({
         background: theme.colors.purple[700],
         color: theme.colors.white,
@@ -73,7 +73,34 @@ export const buttonStyles = variants({
     },
   },
   defaultVariants: {
-    variant: 'primary',
+    color: 'primary',
     fullWidth: false,
   },
 });
+
+type ButtonVariantProps = VariantProps<typeof buttonStyles>;
+
+type ButtonProps = ButtonVariantProps & {
+  render?: RenderProp;
+  sx?: StyleRule;
+};
+
+export const Button = React.forwardRef<HTMLElement, React.HTMLProps<HTMLElement> & ButtonProps>(
+  function Button(props, forwardedRef) {
+    const { render = <button type='button' />, color, fullWidth, sx, ...domProps } = props;
+
+    const combinedSx: StyleRule = theme => ({
+      ...(buttonStyles({ color, fullWidth }) as any)(theme),
+      ...(typeof sx === 'function' ? sx(theme) : sx),
+    });
+
+    return (
+      <Composite
+        render={render}
+        sx={combinedSx}
+        ref={forwardedRef}
+        {...domProps}
+      />
+    );
+  },
+);
diff --git a/packages/ui/src/ceramic/composite.tsx b/packages/ui/src/ceramic/composite.tsx
new file mode 100644
index 00000000000..382ecbefdce
--- /dev/null
+++ b/packages/ui/src/ceramic/composite.tsx
@@ -0,0 +1,46 @@
+// eslint-disable-next-line no-restricted-imports
+import { type Interpolation, type Theme, jsx } from '@emotion/react';
+import * as React from 'react';
+
+import { type StyleRule, style, variants } from './variants';
+
+const compositeStyles = variants({
+  base: style(() => ({
+    boxSizing: 'border-box',
+    margin: 0,
+    padding: 0,
+  })),
+});
+
+export type RenderProp = React.JSX.Element | ((props: React.HTMLAttributes<HTMLElement>) => React.JSX.Element);
+
+function renderJsx(render: RenderProp | undefined, computedProps: React.HTMLAttributes<HTMLElement>) {
+  if (typeof render === 'function') {
+    return render(computedProps);
+  }
+  if (render) {
+    return jsx(render.type, { ...render.props, ...computedProps });
+  }
+  return jsx('div', computedProps);
+}
+
+interface CompositeProps {
+  render?: RenderProp;
+  sx?: StyleRule;
+}
+
+export const Composite = React.forwardRef<HTMLElement, React.HTMLProps<HTMLElement> & CompositeProps>(
+  function Composite(props, forwardedRef) {
+    const { render, sx, ...domProps } = props;
+    const renderElementProps = render && typeof render !== 'function' ? render.props : {};
+
+    const computedProps = {
+      ...domProps,
+      ...renderElementProps,
+      ref: forwardedRef,
+      css: [compositeStyles({}), sx as Interpolation<Theme>],
+    };
+
+    return renderJsx(render, computedProps);
+  },
+);
diff --git a/packages/ui/src/ceramic/text.ts b/packages/ui/src/ceramic/text.tsx
similarity index 68%
rename from packages/ui/src/ceramic/text.ts
rename to packages/ui/src/ceramic/text.tsx
index f7442050ba5..98d9d50d7c4 100644
--- a/packages/ui/src/ceramic/text.ts
+++ b/packages/ui/src/ceramic/text.tsx
@@ -1,4 +1,7 @@
-import { style, variants } from './variants';
+import * as React from 'react';
+
+import { Composite, type RenderProp } from './composite';
+import { type StyleRule, type VariantProps, style, variants } from './variants';
 
 export const textStyles = variants({
   base: style(theme => ({
@@ -46,3 +49,30 @@ export const textStyles = variants({
     font: 'sans',
   },
 });
+
+type TextVariantProps = VariantProps<typeof textStyles>;
+
+type TextProps = TextVariantProps & {
+  render?: RenderProp;
+  sx?: StyleRule;
+};
+
+export const Text = React.forwardRef<HTMLElement, Omit<React.HTMLProps<HTMLElement>, 'color'> & TextProps>(
+  function Text(props, forwardedRef) {
+    const { render = <p />, variant, color, font, sx, ...domProps } = props;
+
+    const combinedSx: StyleRule = theme => ({
+      ...(textStyles({ variant, color, font }) as any)(theme),
+      ...(typeof sx === 'function' ? sx(theme) : sx),
+    });
+
+    return (
+      <Composite
+        render={render}
+        sx={combinedSx}
+        ref={forwardedRef}
+        {...domProps}
+      />
+    );
+  },
+);
diff --git a/packages/ui/src/ceramic/variants.ts b/packages/ui/src/ceramic/variants.ts
index 99a75721dc7..c6106a7507a 100644
--- a/packages/ui/src/ceramic/variants.ts
+++ b/packages/ui/src/ceramic/variants.ts
@@ -4,10 +4,10 @@ import type { Interpolation, Theme } from '@emotion/react';
 
 import { type CeramicTheme } from './theme';
 
-type CSSObject = Record<string, any>;
+export type CSSObject = Record<string, any>;
 // StyleFunction uses CeramicTheme to provide proper typing for theme parameter
-type StyleFunction = (theme: CeramicTheme) => CSSObject;
-type StyleRule = CSSObject | StyleFunction;
+export type StyleFunction = (theme: CeramicTheme) => CSSObject;
+export type StyleRule = CSSObject | StyleFunction;
 
 // Convert string literal "true" | "false" to boolean (CVA's StringToBoolean)
 type StringToBoolean<T> = T extends 'true' | 'false' ? boolean : T;

From 543cba66045540608e454905f3329cb2d4754493 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 1 Apr 2026 11:59:47 -0400
Subject: [PATCH 2/2] cleanup

---
 packages/ui/src/ceramic/button.tsx    | 7 +------
 packages/ui/src/ceramic/composite.tsx | 7 +++++--
 packages/ui/src/ceramic/text.tsx      | 7 +------
 packages/ui/src/ceramic/variants.ts   | 9 +++------
 4 files changed, 10 insertions(+), 20 deletions(-)

diff --git a/packages/ui/src/ceramic/button.tsx b/packages/ui/src/ceramic/button.tsx
index 7247499a922..98e9330193b 100644
--- a/packages/ui/src/ceramic/button.tsx
+++ b/packages/ui/src/ceramic/button.tsx
@@ -89,15 +89,10 @@ export const Button = React.forwardRef<HTMLElement, React.HTMLProps<HTMLElement>
   function Button(props, forwardedRef) {
     const { render = <button type='button' />, color, fullWidth, sx, ...domProps } = props;
 
-    const combinedSx: StyleRule = theme => ({
-      ...(buttonStyles({ color, fullWidth }) as any)(theme),
-      ...(typeof sx === 'function' ? sx(theme) : sx),
-    });
-
     return (
       <Composite
         render={render}
-        sx={combinedSx}
+        sx={[buttonStyles({ color, fullWidth }), sx]}
         ref={forwardedRef}
         {...domProps}
       />
diff --git a/packages/ui/src/ceramic/composite.tsx b/packages/ui/src/ceramic/composite.tsx
index 382ecbefdce..8ef864a9450 100644
--- a/packages/ui/src/ceramic/composite.tsx
+++ b/packages/ui/src/ceramic/composite.tsx
@@ -14,6 +14,8 @@ const compositeStyles = variants({
 
 export type RenderProp = React.JSX.Element | ((props: React.HTMLAttributes<HTMLElement>) => React.JSX.Element);
 
+type SxArray = (StyleRule | undefined | null | false)[];
+
 function renderJsx(render: RenderProp | undefined, computedProps: React.HTMLAttributes<HTMLElement>) {
   if (typeof render === 'function') {
     return render(computedProps);
@@ -26,19 +28,20 @@ function renderJsx(render: RenderProp | undefined, computedProps: React.HTMLAttr
 
 interface CompositeProps {
   render?: RenderProp;
-  sx?: StyleRule;
+  sx?: StyleRule | SxArray;
 }
 
 export const Composite = React.forwardRef<HTMLElement, React.HTMLProps<HTMLElement> & CompositeProps>(
   function Composite(props, forwardedRef) {
     const { render, sx, ...domProps } = props;
     const renderElementProps = render && typeof render !== 'function' ? render.props : {};
+    const sxEntries = Array.isArray(sx) ? sx : [sx];
 
     const computedProps = {
       ...domProps,
       ...renderElementProps,
       ref: forwardedRef,
-      css: [compositeStyles({}), sx as Interpolation<Theme>],
+      css: [compositeStyles({}), ...sxEntries] as Interpolation<Theme>[],
     };
 
     return renderJsx(render, computedProps);
diff --git a/packages/ui/src/ceramic/text.tsx b/packages/ui/src/ceramic/text.tsx
index 98d9d50d7c4..1fa6a6e8947 100644
--- a/packages/ui/src/ceramic/text.tsx
+++ b/packages/ui/src/ceramic/text.tsx
@@ -61,15 +61,10 @@ export const Text = React.forwardRef<HTMLElement, Omit<React.HTMLProps<HTMLEleme
   function Text(props, forwardedRef) {
     const { render = <p />, variant, color, font, sx, ...domProps } = props;
 
-    const combinedSx: StyleRule = theme => ({
-      ...(textStyles({ variant, color, font }) as any)(theme),
-      ...(typeof sx === 'function' ? sx(theme) : sx),
-    });
-
     return (
       <Composite
         render={render}
-        sx={combinedSx}
+        sx={[textStyles({ variant, color, font }), sx]}
         ref={forwardedRef}
         {...domProps}
       />
diff --git a/packages/ui/src/ceramic/variants.ts b/packages/ui/src/ceramic/variants.ts
index c6106a7507a..7058d20221e 100644
--- a/packages/ui/src/ceramic/variants.ts
+++ b/packages/ui/src/ceramic/variants.ts
@@ -1,6 +1,4 @@
 import { fastDeepMergeAndReplace } from '@clerk/shared/utils';
-// eslint-disable-next-line no-restricted-imports
-import type { Interpolation, Theme } from '@emotion/react';
 
 import { type CeramicTheme } from './theme';
 
@@ -143,9 +141,8 @@ function conditionMatches(
 export function variants<T>(config: VariantsConfig<T>) {
   const { base, variants: variantDefinitions = {} as T, defaultVariants = {}, compoundVariants = [] } = config;
 
-  return (props: ConfigVariants<T> = {}): Interpolation<Theme> => {
-    return ((theme: Theme) => {
-      const ceramicTheme = theme as unknown as CeramicTheme;
+  return (props: ConfigVariants<T> = {}): StyleFunction => {
+    return (ceramicTheme: CeramicTheme) => {
       const computedStyles: CSSObject = {};
       const variantDefs = variantDefinitions as Record<string, Record<string, StyleRule>>;
 
@@ -178,6 +175,6 @@ export function variants<T>(config: VariantsConfig<T>) {
       }
 
       return computedStyles;
-    }) as unknown as Interpolation<Theme>;
+    };
   };
 }