From ab560c812cb5a745ea3adf3c5da429ae728b4321 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Thu, 30 Jul 2026 14:22:14 -0600
Subject: [PATCH 01/13] refactor(ui): migrate Mosaic Card to StyleX

---
 .changeset/mosaic-card-stylex.md              |   2 +
 .../src/stories/card.component.stories.tsx    |  13 +-
 packages/ui/src/mosaic/components/card.tsx    | 134 ------------------
 .../src/mosaic/components/card/card.styles.ts |  46 ++++++
 .../src/mosaic/components/card/card.test.tsx  | 109 ++++++++++++++
 .../ui/src/mosaic/components/card/card.tsx    |  88 ++++++++++++
 .../ui/src/mosaic/components/card/index.ts    |   2 +
 packages/ui/src/mosaic/styles/index.ts        |   2 +
 8 files changed, 259 insertions(+), 137 deletions(-)
 create mode 100644 .changeset/mosaic-card-stylex.md
 delete mode 100644 packages/ui/src/mosaic/components/card.tsx
 create mode 100644 packages/ui/src/mosaic/components/card/card.styles.ts
 create mode 100644 packages/ui/src/mosaic/components/card/card.test.tsx
 create mode 100644 packages/ui/src/mosaic/components/card/card.tsx
 create mode 100644 packages/ui/src/mosaic/components/card/index.ts

diff --git a/.changeset/mosaic-card-stylex.md b/.changeset/mosaic-card-stylex.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-card-stylex.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/swingset/src/stories/card.component.stories.tsx b/packages/swingset/src/stories/card.component.stories.tsx
index ae72fe95628..6cb73c3bf2c 100644
--- a/packages/swingset/src/stories/card.component.stories.tsx
+++ b/packages/swingset/src/stories/card.component.stories.tsx
@@ -1,7 +1,7 @@
 /** @jsxImportSource @emotion/react */
 import { Button } from '@clerk/ui/mosaic/components/button';
 import type { CardProps } from '@clerk/ui/mosaic/components/card';
-import { Card, cardRecipe } from '@clerk/ui/mosaic/components/card';
+import { Card } from '@clerk/ui/mosaic/components/card';
 import { Heading } from '@clerk/ui/mosaic/components/heading';
 import { Text } from '@clerk/ui/mosaic/components/text';
 
@@ -14,8 +14,15 @@ export { default as __source } from './card.component.stories?raw';
 export const meta: StoryMeta = {
   group: 'Components',
   title: 'Card',
-  source: 'packages/ui/src/mosaic/components/card.tsx',
-  styles: cardRecipe,
+  source: 'packages/ui/src/mosaic/components/card/card.tsx',
+  styles: {
+    _variants: {
+      alignment: { start: {}, center: {} },
+    },
+    _defaultVariants: {
+      alignment: 'start',
+    },
+  },
 };
 
 function knobsAsProps(props: Record<string, unknown>) {
diff --git a/packages/ui/src/mosaic/components/card.tsx b/packages/ui/src/mosaic/components/card.tsx
deleted file mode 100644
index e616f6f79a9..00000000000
--- a/packages/ui/src/mosaic/components/card.tsx
+++ /dev/null
@@ -1,134 +0,0 @@
-import React from 'react';
-
-import type { RecipeVariantProps } from '../slot-recipe';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
-import { TextContext } from './text';
-
-export const cardRecipe = defineSlotRecipe(theme => ({
-  slots: {
-    root: { slot: 'card-root' },
-    header: { slot: 'card-header' },
-    content: { slot: 'card-content' },
-    footer: { slot: 'card-footer' },
-  },
-  base: {
-    root: {
-      backgroundColor: theme.color.card,
-      color: theme.color.cardForeground,
-      borderRadius: theme.rounded.lg,
-      display: 'flex',
-      flexDirection: 'column',
-      rowGap: theme.spacing(5),
-      width: '100%',
-      overflow: 'hidden',
-      border: `1px solid ${theme.color.border}`,
-    },
-    header: {
-      display: 'flex',
-      flexDirection: 'column',
-      paddingBlockStart: theme.spacing(5),
-      paddingInline: theme.spacing(4),
-    },
-    content: {
-      paddingInline: theme.spacing(4),
-      flex: '1 1 auto',
-    },
-    footer: {
-      paddingBlockEnd: theme.spacing(5),
-      paddingInline: theme.spacing(4),
-    },
-  },
-  variants: {
-    alignment: {
-      start: {
-        header: { alignItems: 'flex-start', textAlign: 'start' },
-      },
-      center: {
-        header: { alignItems: 'center', textAlign: 'center' },
-      },
-    },
-  },
-  defaultVariants: {
-    alignment: 'start',
-  },
-}));
-
-type CardVariantProps = RecipeVariantProps<typeof cardRecipe>;
-
-const CardVariantContext = React.createContext<CardVariantProps>({});
-
-declare module '../registry' {
-  interface MosaicSlotRegistry {
-    'card-root': true;
-    'card-header': true;
-    'card-content': true;
-    'card-footer': true;
-  }
-}
-
-const Root = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardRoot(props, ref) {
-  const variantProps = React.useContext(CardVariantContext);
-  const { root } = useRecipe(cardRecipe, { variants: variantProps });
-  return (
-    <div
-      ref={ref}
-      {...root}
-      {...props}
-    />
-  );
-});
-
-const Header = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardHeader(props, ref) {
-  const variantProps = React.useContext(CardVariantContext);
-  const { header } = useRecipe(cardRecipe, { variants: variantProps });
-  return (
-    <TextContext.Provider value={{ color: 'neutral' }}>
-      <div
-        ref={ref}
-        {...header}
-        {...props}
-      />
-    </TextContext.Provider>
-  );
-});
-
-const Content = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(
-  function CardContent(props, ref) {
-    const { content } = useRecipe(cardRecipe);
-    return (
-      <div
-        ref={ref}
-        {...content}
-        {...props}
-      />
-    );
-  },
-);
-
-const Footer = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardFooter(props, ref) {
-  const { footer } = useRecipe(cardRecipe);
-  return (
-    <div
-      ref={ref}
-      {...footer}
-      {...props}
-    />
-  );
-});
-
-export interface CardProps extends React.ComponentPropsWithoutRef<'div'> {
-  alignment?: CardVariantProps['alignment'];
-}
-
-export function Card({ alignment, children, ...props }: CardProps) {
-  return (
-    <CardVariantContext.Provider value={{ alignment }}>
-      <Root {...props}>{children}</Root>
-    </CardVariantContext.Provider>
-  );
-}
-
-Card.Root = Root;
-Card.Header = Header;
-Card.Content = Content;
-Card.Footer = Footer;
diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
new file mode 100644
index 00000000000..c3bd16ecd13
--- /dev/null
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -0,0 +1,46 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space } from '../../tokens.stylex';
+
+export const styles = stylex.create({
+  root: {
+    borderColor: colorVars['--cl-color-border'],
+    borderRadius: radiusVars['--cl-radius-element'],
+    borderStyle: 'solid',
+    borderWidth: '1px',
+    overflow: 'hidden',
+    backgroundColor: colorVars['--cl-color-card'],
+    color: colorVars['--cl-color-card-foreground'],
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: space['5'],
+    width: '100%',
+  },
+  header: {
+    paddingInline: space['4'],
+    display: 'flex',
+    flexDirection: 'column',
+    paddingBlockStart: space['5'],
+  },
+  content: {
+    paddingInline: space['4'],
+    flexBasis: 'auto',
+    flexGrow: '1',
+    flexShrink: '1',
+  },
+  footer: {
+    paddingInline: space['4'],
+    paddingBlockEnd: space['5'],
+  },
+});
+
+export const headerAlignments = stylex.create({
+  start: {
+    alignItems: 'flex-start',
+    textAlign: 'start',
+  },
+  center: {
+    alignItems: 'center',
+    textAlign: 'center',
+  },
+});
diff --git a/packages/ui/src/mosaic/components/card/card.test.tsx b/packages/ui/src/mosaic/components/card/card.test.tsx
new file mode 100644
index 00000000000..e6a31d13284
--- /dev/null
+++ b/packages/ui/src/mosaic/components/card/card.test.tsx
@@ -0,0 +1,109 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { Text } from '../text';
+import { Card } from './card';
+
+describe('Mosaic Card', () => {
+  it('renders each compound slot with the default alignment', () => {
+    render(
+      <Card data-testid='root'>
+        <Card.Header data-testid='header'>Header</Card.Header>
+        <Card.Content data-testid='content'>Content</Card.Content>
+        <Card.Footer data-testid='footer'>Footer</Card.Footer>
+      </Card>,
+    );
+
+    expect(screen.getByTestId('root')).toHaveClass('cl-card-root');
+    expect(screen.getByTestId('root')).toHaveAttribute('data-alignment', 'start');
+    expect(screen.getByTestId('header')).toHaveClass('cl-card-header');
+    expect(screen.getByTestId('header')).toHaveAttribute('data-alignment', 'start');
+    expect(screen.getByTestId('content')).toHaveClass('cl-card-content');
+    expect(screen.getByTestId('footer')).toHaveClass('cl-card-footer');
+  });
+
+  it('reflects centered alignment on the root and header', () => {
+    render(
+      <Card
+        alignment='center'
+        data-testid='root'
+      >
+        <Card.Header data-testid='header'>Header</Card.Header>
+      </Card>,
+    );
+
+    expect(screen.getByTestId('root')).toHaveAttribute('data-alignment', 'center');
+    expect(screen.getByTestId('header')).toHaveAttribute('data-alignment', 'center');
+  });
+
+  it('provides the neutral text color to header copy', () => {
+    render(
+      <Card>
+        <Card.Header>
+          <Text>Supporting copy</Text>
+        </Card.Header>
+      </Card>,
+    );
+
+    expect(screen.getByText('Supporting copy')).toHaveAttribute('data-color', 'neutral');
+  });
+
+  it('lets consumer className and style win on every slot', () => {
+    render(
+      <Card
+        className='my-card'
+        style={{ width: '20rem' }}
+        data-testid='root'
+      >
+        <Card.Header
+          className='my-header'
+          style={{ textAlign: 'right' }}
+          data-testid='header'
+        />
+        <Card.Content
+          className='my-content'
+          style={{ paddingInline: 0 }}
+          data-testid='content'
+        />
+        <Card.Footer
+          className='my-footer'
+          style={{ paddingBlockEnd: 0 }}
+          data-testid='footer'
+        />
+      </Card>,
+    );
+
+    expect(screen.getByTestId('root')).toHaveClass('cl-card-root', 'my-card');
+    expect(screen.getByTestId('root')).toHaveStyle({ width: '20rem' });
+    expect(screen.getByTestId('header')).toHaveClass('cl-card-header', 'my-header');
+    expect(screen.getByTestId('header')).toHaveStyle({ textAlign: 'right' });
+    expect(screen.getByTestId('content')).toHaveClass('cl-card-content', 'my-content');
+    expect(screen.getByTestId('content')).toHaveStyle({ paddingInline: 0 });
+    expect(screen.getByTestId('footer')).toHaveClass('cl-card-footer', 'my-footer');
+    expect(screen.getByTestId('footer')).toHaveStyle({ paddingBlockEnd: 0 });
+  });
+
+  it('forwards refs and arbitrary props from compound slots', () => {
+    const rootRef = React.createRef<HTMLDivElement>();
+    const headerRef = React.createRef<HTMLDivElement>();
+    const contentRef = React.createRef<HTMLDivElement>();
+    const footerRef = React.createRef<HTMLDivElement>();
+
+    render(
+      <Card.Root
+        ref={rootRef}
+        aria-label='Card'
+      >
+        <Card.Header ref={headerRef} />
+        <Card.Content ref={contentRef} />
+        <Card.Footer ref={footerRef} />
+      </Card.Root>,
+    );
+
+    expect(rootRef.current).toBe(screen.getByLabelText('Card'));
+    expect(headerRef.current).toHaveClass('cl-card-header');
+    expect(contentRef.current).toHaveClass('cl-card-content');
+    expect(footerRef.current).toHaveClass('cl-card-footer');
+  });
+});
diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
new file mode 100644
index 00000000000..01d7eec987e
--- /dev/null
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -0,0 +1,88 @@
+import * as stylex from '@stylexjs/stylex';
+import React from 'react';
+
+import { mergeStyleProps, themeProps } from '../../props';
+import { TextContext } from '../text';
+import { headerAlignments, styles } from './card.styles';
+
+type CardAlignment = 'start' | 'center';
+
+const CardVariantContext = React.createContext<{ alignment: CardAlignment }>({ alignment: 'start' });
+
+const Root = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardRoot(
+  { className, style, ...props },
+  ref,
+) {
+  const { alignment } = React.useContext(CardVariantContext);
+  return (
+    <div
+      ref={ref}
+      {...mergeStyleProps(themeProps('card-root', { alignment }), stylex.props(styles.root), className, style)}
+      {...props}
+    />
+  );
+});
+
+const Header = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardHeader(
+  { className, style, ...props },
+  ref,
+) {
+  const { alignment } = React.useContext(CardVariantContext);
+  return (
+    <TextContext.Provider value={{ color: 'neutral' }}>
+      <div
+        ref={ref}
+        {...mergeStyleProps(
+          themeProps('card-header', { alignment }),
+          stylex.props(styles.header, headerAlignments[alignment]),
+          className,
+          style,
+        )}
+        {...props}
+      />
+    </TextContext.Provider>
+  );
+});
+
+const Content = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardContent(
+  { className, style, ...props },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      {...mergeStyleProps(themeProps('card-content'), stylex.props(styles.content), className, style)}
+      {...props}
+    />
+  );
+});
+
+const Footer = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardFooter(
+  { className, style, ...props },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      {...mergeStyleProps(themeProps('card-footer'), stylex.props(styles.footer), className, style)}
+      {...props}
+    />
+  );
+});
+
+export interface CardProps extends React.ComponentPropsWithoutRef<'div'> {
+  alignment?: CardAlignment;
+}
+
+export function Card({ alignment = 'start', children, ...props }: CardProps) {
+  return (
+    <CardVariantContext.Provider value={{ alignment }}>
+      <Root {...props}>{children}</Root>
+    </CardVariantContext.Provider>
+  );
+}
+
+Card.Root = Root;
+Card.Header = Header;
+Card.Content = Content;
+Card.Footer = Footer;
diff --git a/packages/ui/src/mosaic/components/card/index.ts b/packages/ui/src/mosaic/components/card/index.ts
new file mode 100644
index 00000000000..659228ff6fd
--- /dev/null
+++ b/packages/ui/src/mosaic/components/card/index.ts
@@ -0,0 +1,2 @@
+export { Card } from './card';
+export type { CardProps } from './card';
diff --git a/packages/ui/src/mosaic/styles/index.ts b/packages/ui/src/mosaic/styles/index.ts
index 643906b40b4..d341aaa1770 100644
--- a/packages/ui/src/mosaic/styles/index.ts
+++ b/packages/ui/src/mosaic/styles/index.ts
@@ -10,6 +10,8 @@ export { Badge } from '../components/badge';
 export type { BadgeProps } from '../components/badge';
 export { Button } from '../components/button';
 export type { ButtonProps } from '../components/button';
+export { Card } from '../components/card';
+export type { CardProps } from '../components/card';
 export { Heading, HeadingContext } from '../components/heading';
 export type { HeadingProps } from '../components/heading';
 export { Icon } from '../components/icon';

From 4ff280b933f18ff99cda89349a288a77e0ce6ccd Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Thu, 30 Jul 2026 15:05:40 -0600
Subject: [PATCH 02/13] feat(ui): align Mosaic Card with updated design

---
 .../src/mosaic/components/card/card.styles.ts | 24 +++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index c3bd16ecd13..6b45ca7022d 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -4,16 +4,15 @@ import { colorVars, radiusVars, space } from '../../tokens.stylex';
 
 export const styles = stylex.create({
   root: {
-    borderColor: colorVars['--cl-color-border'],
-    borderRadius: radiusVars['--cl-radius-element'],
-    borderStyle: 'solid',
-    borderWidth: '1px',
+    borderRadius: radiusVars['--cl-radius-container'],
     overflow: 'hidden',
     backgroundColor: colorVars['--cl-color-card'],
+    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
+                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
+                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
     color: colorVars['--cl-color-card-foreground'],
     display: 'flex',
     flexDirection: 'column',
-    rowGap: space['5'],
     width: '100%',
   },
   header: {
@@ -29,8 +28,19 @@ export const styles = stylex.create({
     flexShrink: '1',
   },
   footer: {
-    paddingInline: space['4'],
-    paddingBlockEnd: space['5'],
+    gap: space['2'],
+    paddingBlock: space['4'],
+    paddingInline: space['6'],
+    alignItems: 'center',
+    backgroundColor: `color-mix(in oklab, ${colorVars['--cl-color-card-foreground']} 4%, ${colorVars['--cl-color-card']})`,
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexShrink: 0,
+    justifyContent: 'space-between',
+    borderTopColor: colorVars['--cl-color-border'],
+    borderTopStyle: 'solid',
+    borderTopWidth: '1px',
+    width: '100%',
   },
 });
 

From a45fc86917fc821fa624174dd8009f3a1b85eb41 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Thu, 30 Jul 2026 19:37:54 -0600
Subject: [PATCH 03/13] refactor(ui): align Card compound API

---
 .../swingset/src/stories/card.component.mdx   |  4 +-
 .../src/stories/card.component.stories.tsx    |  9 +++--
 .../src/mosaic/components/card/card.styles.ts |  1 +
 .../src/mosaic/components/card/card.test.tsx  | 16 ++++----
 .../ui/src/mosaic/components/card/card.tsx    | 40 ++++++++-----------
 5 files changed, 32 insertions(+), 38 deletions(-)

diff --git a/packages/swingset/src/stories/card.component.mdx b/packages/swingset/src/stories/card.component.mdx
index 5f282a30ea2..38444cd4842 100644
--- a/packages/swingset/src/stories/card.component.mdx
+++ b/packages/swingset/src/stories/card.component.mdx
@@ -20,11 +20,11 @@ A styled surface container that groups related content into Header, Content, and
 ```tsx
 import { Card } from '@clerk/ui/mosaic/components/card';
 
-<Card>
+<Card.Root>
   <Card.Header>Heading</Card.Header>
   <Card.Content>Body content.</Card.Content>
   <Card.Footer>Footer actions</Card.Footer>
-</Card>
+</Card.Root>
 ```
 
 ---
diff --git a/packages/swingset/src/stories/card.component.stories.tsx b/packages/swingset/src/stories/card.component.stories.tsx
index 6cb73c3bf2c..6d2ab58714e 100644
--- a/packages/swingset/src/stories/card.component.stories.tsx
+++ b/packages/swingset/src/stories/card.component.stories.tsx
@@ -15,6 +15,7 @@ export const meta: StoryMeta = {
   group: 'Components',
   title: 'Card',
   source: 'packages/ui/src/mosaic/components/card/card.tsx',
+  styleEngine: 'stylex',
   styles: {
     _variants: {
       alignment: { start: {}, center: {} },
@@ -31,7 +32,7 @@ function knobsAsProps(props: Record<string, unknown>) {
 
 export function Default(props: Record<string, unknown>) {
   return (
-    <Card
+    <Card.Root
       {...knobsAsProps(props)}
       style={{ maxWidth: 400 }}
     >
@@ -43,13 +44,13 @@ export function Default(props: Record<string, unknown>) {
       <Card.Footer>
         <Button fullWidth>Continue</Button>
       </Card.Footer>
-    </Card>
+    </Card.Root>
   );
 }
 
 export function Centered() {
   return (
-    <Card
+    <Card.Root
       alignment='center'
       style={{ maxWidth: 400 }}
     >
@@ -61,6 +62,6 @@ export function Centered() {
       <Card.Footer>
         <Button fullWidth>Verify</Button>
       </Card.Footer>
-    </Card>
+    </Card.Root>
   );
 }
diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index 6b45ca7022d..869c250c5f9 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -13,6 +13,7 @@ export const styles = stylex.create({
     color: colorVars['--cl-color-card-foreground'],
     display: 'flex',
     flexDirection: 'column',
+    rowGap: space['5'],
     width: '100%',
   },
   header: {
diff --git a/packages/ui/src/mosaic/components/card/card.test.tsx b/packages/ui/src/mosaic/components/card/card.test.tsx
index e6a31d13284..ec8db918d43 100644
--- a/packages/ui/src/mosaic/components/card/card.test.tsx
+++ b/packages/ui/src/mosaic/components/card/card.test.tsx
@@ -8,11 +8,11 @@ import { Card } from './card';
 describe('Mosaic Card', () => {
   it('renders each compound slot with the default alignment', () => {
     render(
-      <Card data-testid='root'>
+      <Card.Root data-testid='root'>
         <Card.Header data-testid='header'>Header</Card.Header>
         <Card.Content data-testid='content'>Content</Card.Content>
         <Card.Footer data-testid='footer'>Footer</Card.Footer>
-      </Card>,
+      </Card.Root>,
     );
 
     expect(screen.getByTestId('root')).toHaveClass('cl-card-root');
@@ -25,12 +25,12 @@ describe('Mosaic Card', () => {
 
   it('reflects centered alignment on the root and header', () => {
     render(
-      <Card
+      <Card.Root
         alignment='center'
         data-testid='root'
       >
         <Card.Header data-testid='header'>Header</Card.Header>
-      </Card>,
+      </Card.Root>,
     );
 
     expect(screen.getByTestId('root')).toHaveAttribute('data-alignment', 'center');
@@ -39,11 +39,11 @@ describe('Mosaic Card', () => {
 
   it('provides the neutral text color to header copy', () => {
     render(
-      <Card>
+      <Card.Root>
         <Card.Header>
           <Text>Supporting copy</Text>
         </Card.Header>
-      </Card>,
+      </Card.Root>,
     );
 
     expect(screen.getByText('Supporting copy')).toHaveAttribute('data-color', 'neutral');
@@ -51,7 +51,7 @@ describe('Mosaic Card', () => {
 
   it('lets consumer className and style win on every slot', () => {
     render(
-      <Card
+      <Card.Root
         className='my-card'
         style={{ width: '20rem' }}
         data-testid='root'
@@ -71,7 +71,7 @@ describe('Mosaic Card', () => {
           style={{ paddingBlockEnd: 0 }}
           data-testid='footer'
         />
-      </Card>,
+      </Card.Root>,
     );
 
     expect(screen.getByTestId('root')).toHaveClass('cl-card-root', 'my-card');
diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
index 01d7eec987e..d6d55015a3b 100644
--- a/packages/ui/src/mosaic/components/card/card.tsx
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -9,17 +9,24 @@ type CardAlignment = 'start' | 'center';
 
 const CardVariantContext = React.createContext<{ alignment: CardAlignment }>({ alignment: 'start' });
 
-const Root = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardRoot(
-  { className, style, ...props },
+export interface CardProps extends React.ComponentPropsWithoutRef<'div'> {
+  alignment?: CardAlignment;
+}
+
+const Root = React.forwardRef<HTMLDivElement, CardProps>(function CardRoot(
+  { alignment = 'start', children, className, style, ...props },
   ref,
 ) {
-  const { alignment } = React.useContext(CardVariantContext);
   return (
-    <div
-      ref={ref}
-      {...mergeStyleProps(themeProps('card-root', { alignment }), stylex.props(styles.root), className, style)}
-      {...props}
-    />
+    <CardVariantContext.Provider value={{ alignment }}>
+      <div
+        ref={ref}
+        {...mergeStyleProps(themeProps('card-root', { alignment }), stylex.props(styles.root), className, style)}
+        {...props}
+      >
+        {children}
+      </div>
+    </CardVariantContext.Provider>
   );
 });
 
@@ -70,19 +77,4 @@ const Footer = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'
   );
 });
 
-export interface CardProps extends React.ComponentPropsWithoutRef<'div'> {
-  alignment?: CardAlignment;
-}
-
-export function Card({ alignment = 'start', children, ...props }: CardProps) {
-  return (
-    <CardVariantContext.Provider value={{ alignment }}>
-      <Root {...props}>{children}</Root>
-    </CardVariantContext.Provider>
-  );
-}
-
-Card.Root = Root;
-Card.Header = Header;
-Card.Content = Content;
-Card.Footer = Footer;
+export const Card = { Root, Header, Content, Footer };

From 3e5d932675aad8750c09714e548d110a0cec2879 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Thu, 30 Jul 2026 20:23:49 -0600
Subject: [PATCH 04/13] feat(ui): add Card elevation variants

---
 .../src/mosaic/components/card/card.styles.ts | 28 ++++++++++++++-----
 .../src/mosaic/components/card/card.test.tsx  | 16 +++++++++++
 .../ui/src/mosaic/components/card/card.tsx    | 26 +++++++++++++----
 3 files changed, 58 insertions(+), 12 deletions(-)

diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index 869c250c5f9..1cc286a4fbc 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -4,17 +4,25 @@ import { colorVars, radiusVars, space } from '../../tokens.stylex';
 
 export const styles = stylex.create({
   root: {
+    color: colorVars['--cl-color-card-foreground'],
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: space['5'],
+    width: '100%',
+  },
+  raised: {
     borderRadius: radiusVars['--cl-radius-container'],
     overflow: 'hidden',
     backgroundColor: colorVars['--cl-color-card'],
     boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
                 0 24px 24px -10px oklch(0.2046 0 0 / 4%),
                 0 0 0 1px oklch(0.2046 0 0 / 4%)`,
-    color: colorVars['--cl-color-card-foreground'],
-    display: 'flex',
-    flexDirection: 'column',
-    rowGap: space['5'],
-    width: '100%',
+  },
+  flush: {
+    borderRadius: 0,
+    overflow: 'visible',
+    backgroundColor: 'transparent',
+    boxShadow: 'none',
   },
   header: {
     paddingInline: space['4'],
@@ -33,15 +41,21 @@ export const styles = stylex.create({
     paddingBlock: space['4'],
     paddingInline: space['6'],
     alignItems: 'center',
-    backgroundColor: `color-mix(in oklab, ${colorVars['--cl-color-card-foreground']} 4%, ${colorVars['--cl-color-card']})`,
     boxSizing: 'border-box',
     display: 'flex',
     flexShrink: 0,
     justifyContent: 'space-between',
+    width: '100%',
+  },
+  'footer-raised': {
+    backgroundColor: `color-mix(in oklab, ${colorVars['--cl-color-card-foreground']} 4%, ${colorVars['--cl-color-card']})`,
     borderTopColor: colorVars['--cl-color-border'],
     borderTopStyle: 'solid',
     borderTopWidth: '1px',
-    width: '100%',
+  },
+  'footer-flush': {
+    backgroundColor: 'transparent',
+    borderTopWidth: 0,
   },
 });
 
diff --git a/packages/ui/src/mosaic/components/card/card.test.tsx b/packages/ui/src/mosaic/components/card/card.test.tsx
index ec8db918d43..855ad493f9f 100644
--- a/packages/ui/src/mosaic/components/card/card.test.tsx
+++ b/packages/ui/src/mosaic/components/card/card.test.tsx
@@ -17,10 +17,12 @@ describe('Mosaic Card', () => {
 
     expect(screen.getByTestId('root')).toHaveClass('cl-card-root');
     expect(screen.getByTestId('root')).toHaveAttribute('data-alignment', 'start');
+    expect(screen.getByTestId('root')).toHaveAttribute('data-elevation', 'raised');
     expect(screen.getByTestId('header')).toHaveClass('cl-card-header');
     expect(screen.getByTestId('header')).toHaveAttribute('data-alignment', 'start');
     expect(screen.getByTestId('content')).toHaveClass('cl-card-content');
     expect(screen.getByTestId('footer')).toHaveClass('cl-card-footer');
+    expect(screen.getByTestId('footer')).toHaveAttribute('data-elevation', 'raised');
   });
 
   it('reflects centered alignment on the root and header', () => {
@@ -37,6 +39,20 @@ describe('Mosaic Card', () => {
     expect(screen.getByTestId('header')).toHaveAttribute('data-alignment', 'center');
   });
 
+  it('reflects flush elevation on the root and footer', () => {
+    render(
+      <Card.Root
+        elevation='flush'
+        data-testid='root'
+      >
+        <Card.Footer data-testid='footer' />
+      </Card.Root>,
+    );
+
+    expect(screen.getByTestId('root')).toHaveAttribute('data-elevation', 'flush');
+    expect(screen.getByTestId('footer')).toHaveAttribute('data-elevation', 'flush');
+  });
+
   it('provides the neutral text color to header copy', () => {
     render(
       <Card.Root>
diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
index d6d55015a3b..d3d8265757a 100644
--- a/packages/ui/src/mosaic/components/card/card.tsx
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -6,22 +6,32 @@ import { TextContext } from '../text';
 import { headerAlignments, styles } from './card.styles';
 
 type CardAlignment = 'start' | 'center';
+type CardElevation = 'raised' | 'flush';
 
-const CardVariantContext = React.createContext<{ alignment: CardAlignment }>({ alignment: 'start' });
+const CardVariantContext = React.createContext<{ alignment: CardAlignment; elevation: CardElevation }>({
+  alignment: 'start',
+  elevation: 'raised',
+});
 
 export interface CardProps extends React.ComponentPropsWithoutRef<'div'> {
   alignment?: CardAlignment;
+  elevation?: CardElevation;
 }
 
 const Root = React.forwardRef<HTMLDivElement, CardProps>(function CardRoot(
-  { alignment = 'start', children, className, style, ...props },
+  { alignment = 'start', elevation = 'raised', children, className, style, ...props },
   ref,
 ) {
   return (
-    <CardVariantContext.Provider value={{ alignment }}>
+    <CardVariantContext.Provider value={{ alignment, elevation }}>
       <div
         ref={ref}
-        {...mergeStyleProps(themeProps('card-root', { alignment }), stylex.props(styles.root), className, style)}
+        {...mergeStyleProps(
+          themeProps('card-root', { alignment, elevation }),
+          stylex.props(styles.root, styles[elevation]),
+          className,
+          style,
+        )}
         {...props}
       >
         {children}
@@ -68,10 +78,16 @@ const Footer = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'
   { className, style, ...props },
   ref,
 ) {
+  const { elevation } = React.useContext(CardVariantContext);
   return (
     <div
       ref={ref}
-      {...mergeStyleProps(themeProps('card-footer'), stylex.props(styles.footer), className, style)}
+      {...mergeStyleProps(
+        themeProps('card-footer', { elevation }),
+        stylex.props(styles.footer, styles[`footer-${elevation}`]),
+        className,
+        style,
+      )}
       {...props}
     />
   );

From c53b67ce09b910c89cd404e81bdcf90adc958306 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Thu, 30 Jul 2026 20:24:10 -0600
Subject: [PATCH 05/13] docs(ui): expose Card elevation controls

---
 packages/swingset/src/stories/card.component.stories.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/swingset/src/stories/card.component.stories.tsx b/packages/swingset/src/stories/card.component.stories.tsx
index 6d2ab58714e..43ec9dc6d7f 100644
--- a/packages/swingset/src/stories/card.component.stories.tsx
+++ b/packages/swingset/src/stories/card.component.stories.tsx
@@ -19,9 +19,11 @@ export const meta: StoryMeta = {
   styles: {
     _variants: {
       alignment: { start: {}, center: {} },
+      elevation: { raised: {}, flush: {} },
     },
     _defaultVariants: {
       alignment: 'start',
+      elevation: 'raised',
     },
   },
 };

From 39a52e8f4f56b5a33cd5fbb4b169c1de2a39bc51 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Thu, 30 Jul 2026 21:59:09 -0600
Subject: [PATCH 06/13] feat(ui): align Card elevation variants

---
 .../src/stories/card.component.stories.tsx         |  2 +-
 .../ui/src/mosaic/components/card/card.styles.ts   | 12 +++---------
 .../ui/src/mosaic/components/card/card.test.tsx    | 14 ++++++++++++++
 packages/ui/src/mosaic/components/card/card.tsx    | 11 +++--------
 4 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/packages/swingset/src/stories/card.component.stories.tsx b/packages/swingset/src/stories/card.component.stories.tsx
index 43ec9dc6d7f..eca6fe484de 100644
--- a/packages/swingset/src/stories/card.component.stories.tsx
+++ b/packages/swingset/src/stories/card.component.stories.tsx
@@ -19,7 +19,7 @@ export const meta: StoryMeta = {
   styles: {
     _variants: {
       alignment: { start: {}, center: {} },
-      elevation: { raised: {}, flush: {} },
+      elevation: { raised: {}, flush: {}, overlay: {} },
     },
     _defaultVariants: {
       alignment: 'start',
diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index 1cc286a4fbc..a01cf384e8d 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -19,7 +19,7 @@ export const styles = stylex.create({
                 0 0 0 1px oklch(0.2046 0 0 / 4%)`,
   },
   flush: {
-    borderRadius: 0,
+    borderRadius: radiusVars['--cl-radius-container'],
     overflow: 'visible',
     backgroundColor: 'transparent',
     boxShadow: 'none',
@@ -41,21 +41,15 @@ export const styles = stylex.create({
     paddingBlock: space['4'],
     paddingInline: space['6'],
     alignItems: 'center',
+    backgroundColor: `color-mix(in oklab, ${colorVars['--cl-color-card-foreground']} 4%, ${colorVars['--cl-color-card']})`,
     boxSizing: 'border-box',
     display: 'flex',
     flexShrink: 0,
     justifyContent: 'space-between',
-    width: '100%',
-  },
-  'footer-raised': {
-    backgroundColor: `color-mix(in oklab, ${colorVars['--cl-color-card-foreground']} 4%, ${colorVars['--cl-color-card']})`,
     borderTopColor: colorVars['--cl-color-border'],
     borderTopStyle: 'solid',
     borderTopWidth: '1px',
-  },
-  'footer-flush': {
-    backgroundColor: 'transparent',
-    borderTopWidth: 0,
+    width: '100%',
   },
 });
 
diff --git a/packages/ui/src/mosaic/components/card/card.test.tsx b/packages/ui/src/mosaic/components/card/card.test.tsx
index 855ad493f9f..30db2d1c09d 100644
--- a/packages/ui/src/mosaic/components/card/card.test.tsx
+++ b/packages/ui/src/mosaic/components/card/card.test.tsx
@@ -53,6 +53,20 @@ describe('Mosaic Card', () => {
     expect(screen.getByTestId('footer')).toHaveAttribute('data-elevation', 'flush');
   });
 
+  it('reflects overlay elevation on the root and footer', () => {
+    render(
+      <Card.Root
+        elevation='overlay'
+        data-testid='root'
+      >
+        <Card.Footer data-testid='footer' />
+      </Card.Root>,
+    );
+
+    expect(screen.getByTestId('root')).toHaveAttribute('data-elevation', 'overlay');
+    expect(screen.getByTestId('footer')).toHaveAttribute('data-elevation', 'overlay');
+  });
+
   it('provides the neutral text color to header copy', () => {
     render(
       <Card.Root>
diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
index d3d8265757a..6b9f9e1652b 100644
--- a/packages/ui/src/mosaic/components/card/card.tsx
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -6,7 +6,7 @@ import { TextContext } from '../text';
 import { headerAlignments, styles } from './card.styles';
 
 type CardAlignment = 'start' | 'center';
-type CardElevation = 'raised' | 'flush';
+type CardElevation = 'raised' | 'flush' | 'overlay';
 
 const CardVariantContext = React.createContext<{ alignment: CardAlignment; elevation: CardElevation }>({
   alignment: 'start',
@@ -28,7 +28,7 @@ const Root = React.forwardRef<HTMLDivElement, CardProps>(function CardRoot(
         ref={ref}
         {...mergeStyleProps(
           themeProps('card-root', { alignment, elevation }),
-          stylex.props(styles.root, styles[elevation]),
+          stylex.props(styles.root, elevation === 'flush' ? styles.flush : styles.raised),
           className,
           style,
         )}
@@ -82,12 +82,7 @@ const Footer = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'
   return (
     <div
       ref={ref}
-      {...mergeStyleProps(
-        themeProps('card-footer', { elevation }),
-        stylex.props(styles.footer, styles[`footer-${elevation}`]),
-        className,
-        style,
-      )}
+      {...mergeStyleProps(themeProps('card-footer', { elevation }), stylex.props(styles.footer), className, style)}
       {...props}
     />
   );

From acd3bdd81c7509190e581cd49d409754fcfdf295 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Fri, 31 Jul 2026 09:46:58 -0600
Subject: [PATCH 07/13] refactor(ui): separate Card elevation styles

---
 .../src/mosaic/components/card/card.styles.ts | 39 ++++++++++++-------
 .../ui/src/mosaic/components/card/card.tsx    |  4 +-
 2 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index a01cf384e8d..1e51ca25f46 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -10,20 +10,6 @@ export const styles = stylex.create({
     rowGap: space['5'],
     width: '100%',
   },
-  raised: {
-    borderRadius: radiusVars['--cl-radius-container'],
-    overflow: 'hidden',
-    backgroundColor: colorVars['--cl-color-card'],
-    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
-                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
-                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
-  },
-  flush: {
-    borderRadius: radiusVars['--cl-radius-container'],
-    overflow: 'visible',
-    backgroundColor: 'transparent',
-    boxShadow: 'none',
-  },
   header: {
     paddingInline: space['4'],
     display: 'flex',
@@ -53,6 +39,31 @@ export const styles = stylex.create({
   },
 });
 
+export const elevations = stylex.create({
+  raised: {
+    borderRadius: radiusVars['--cl-radius-container'],
+    overflow: 'hidden',
+    backgroundColor: colorVars['--cl-color-card'],
+    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
+                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
+                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
+  },
+  flush: {
+    borderRadius: radiusVars['--cl-radius-container'],
+    overflow: 'visible',
+    backgroundColor: 'transparent',
+    boxShadow: 'none',
+  },
+  overlay: {
+    borderRadius: radiusVars['--cl-radius-container'],
+    overflow: 'hidden',
+    backgroundColor: colorVars['--cl-color-card'],
+    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
+                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
+                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
+  },
+});
+
 export const headerAlignments = stylex.create({
   start: {
     alignItems: 'flex-start',
diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
index 6b9f9e1652b..391e2d4387a 100644
--- a/packages/ui/src/mosaic/components/card/card.tsx
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -3,7 +3,7 @@ import React from 'react';
 
 import { mergeStyleProps, themeProps } from '../../props';
 import { TextContext } from '../text';
-import { headerAlignments, styles } from './card.styles';
+import { elevations, headerAlignments, styles } from './card.styles';
 
 type CardAlignment = 'start' | 'center';
 type CardElevation = 'raised' | 'flush' | 'overlay';
@@ -28,7 +28,7 @@ const Root = React.forwardRef<HTMLDivElement, CardProps>(function CardRoot(
         ref={ref}
         {...mergeStyleProps(
           themeProps('card-root', { alignment, elevation }),
-          stylex.props(styles.root, elevation === 'flush' ? styles.flush : styles.raised),
+          stylex.props(styles.root, elevations[elevation]),
           className,
           style,
         )}

From 6bdcfda13a8a077af7de34b5610544dc8cdc1d16 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Fri, 31 Jul 2026 10:03:16 -0600
Subject: [PATCH 08/13] refactor(ui): align Card with Mosaic component props

---
 .../src/mosaic/components/card/card.test.tsx  |  15 +++
 .../ui/src/mosaic/components/card/card.tsx    | 126 ++++++++++--------
 2 files changed, 87 insertions(+), 54 deletions(-)

diff --git a/packages/ui/src/mosaic/components/card/card.test.tsx b/packages/ui/src/mosaic/components/card/card.test.tsx
index 30db2d1c09d..6455a57e940 100644
--- a/packages/ui/src/mosaic/components/card/card.test.tsx
+++ b/packages/ui/src/mosaic/components/card/card.test.tsx
@@ -136,4 +136,19 @@ describe('Mosaic Card', () => {
     expect(contentRef.current).toHaveClass('cl-card-content');
     expect(footerRef.current).toHaveClass('cl-card-footer');
   });
+
+  it('supports custom elements through render on every slot', () => {
+    render(
+      <Card.Root render={props => <section {...props} />}>
+        <Card.Header render={props => <header {...props}>Header</header>} />
+        <Card.Content render={props => <main {...props}>Content</main>} />
+        <Card.Footer render={props => <footer {...props}>Footer</footer>} />
+      </Card.Root>,
+    );
+
+    expect(screen.getByText('Header').tagName).toBe('HEADER');
+    expect(screen.getByText('Content').tagName).toBe('MAIN');
+    expect(screen.getByText('Footer').tagName).toBe('FOOTER');
+    expect(screen.getByText('Header').closest('section')).toHaveClass('cl-card-root');
+  });
 });
diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
index 391e2d4387a..3338486440d 100644
--- a/packages/ui/src/mosaic/components/card/card.tsx
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -1,6 +1,8 @@
+import { useRender } from '@clerk/headless/utils';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { TextContext } from '../text';
 import { elevations, headerAlignments, styles } from './card.styles';
@@ -8,84 +10,100 @@ import { elevations, headerAlignments, styles } from './card.styles';
 type CardAlignment = 'start' | 'center';
 type CardElevation = 'raised' | 'flush' | 'overlay';
 
+const DEFAULT_ALIGNMENT: CardAlignment = 'start';
+const DEFAULT_ELEVATION: CardElevation = 'raised';
+
 const CardVariantContext = React.createContext<{ alignment: CardAlignment; elevation: CardElevation }>({
-  alignment: 'start',
-  elevation: 'raised',
+  alignment: DEFAULT_ALIGNMENT,
+  elevation: DEFAULT_ELEVATION,
 });
 
-export interface CardProps extends React.ComponentPropsWithoutRef<'div'> {
+/** Props for `Card.Root`, including native `div` props and the Mosaic `render` escape hatch. */
+export interface CardProps extends MosaicComponentProps<'div'> {
+  /** Alignment applied to `Card.Header`. @default 'start' */
   alignment?: CardAlignment;
+  /** Surface treatment applied to the card. @default 'raised' */
   elevation?: CardElevation;
 }
 
 const Root = React.forwardRef<HTMLDivElement, CardProps>(function CardRoot(
-  { alignment = 'start', elevation = 'raised', children, className, style, ...props },
+  { alignment = DEFAULT_ALIGNMENT, elevation = DEFAULT_ELEVATION, render, className, style, ...rest },
   ref,
 ) {
-  return (
-    <CardVariantContext.Provider value={{ alignment, elevation }}>
-      <div
-        ref={ref}
-        {...mergeStyleProps(
-          themeProps('card-root', { alignment, elevation }),
-          stylex.props(styles.root, elevations[elevation]),
-          className,
-          style,
-        )}
-        {...props}
-      >
-        {children}
-      </div>
-    </CardVariantContext.Provider>
-  );
+  const element = useRender({
+    defaultTagName: 'div',
+    render,
+    ref,
+    props: {
+      ...rest,
+      ...mergeStyleProps(
+        themeProps('card-root', { alignment, elevation }),
+        stylex.props(styles.root, elevations[elevation]),
+        className,
+        style,
+      ),
+    },
+  });
+
+  return <CardVariantContext.Provider value={{ alignment, elevation }}>{element}</CardVariantContext.Provider>;
 });
 
-const Header = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardHeader(
-  { className, style, ...props },
+const Header = React.forwardRef<HTMLDivElement, MosaicComponentProps<'div'>>(function CardHeader(
+  { render, className, style, ...rest },
   ref,
 ) {
   const { alignment } = React.useContext(CardVariantContext);
-  return (
-    <TextContext.Provider value={{ color: 'neutral' }}>
-      <div
-        ref={ref}
-        {...mergeStyleProps(
-          themeProps('card-header', { alignment }),
-          stylex.props(styles.header, headerAlignments[alignment]),
-          className,
-          style,
-        )}
-        {...props}
-      />
-    </TextContext.Provider>
-  );
+  const element = useRender({
+    defaultTagName: 'div',
+    render,
+    ref,
+    props: {
+      ...rest,
+      ...mergeStyleProps(
+        themeProps('card-header', { alignment }),
+        stylex.props(styles.header, headerAlignments[alignment]),
+        className,
+        style,
+      ),
+    },
+  });
+
+  return <TextContext.Provider value={{ color: 'neutral' }}>{element}</TextContext.Provider>;
 });
 
-const Content = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardContent(
-  { className, style, ...props },
+const Content = React.forwardRef<HTMLDivElement, MosaicComponentProps<'div'>>(function CardContent(
+  { render, className, style, ...rest },
   ref,
 ) {
-  return (
-    <div
-      ref={ref}
-      {...mergeStyleProps(themeProps('card-content'), stylex.props(styles.content), className, style)}
-      {...props}
-    />
-  );
+  return useRender({
+    defaultTagName: 'div',
+    render,
+    ref,
+    props: {
+      ...rest,
+      ...mergeStyleProps(themeProps('card-content'), stylex.props(styles.content), className, style),
+    },
+  });
 });
 
-const Footer = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<'div'>>(function CardFooter(
-  { className, style, ...props },
+const Footer = React.forwardRef<HTMLDivElement, MosaicComponentProps<'div'>>(function CardFooter(
+  { render, className, style, ...rest },
   ref,
 ) {
   const { elevation } = React.useContext(CardVariantContext);
-  return (
-    <div
-      ref={ref}
-      {...mergeStyleProps(themeProps('card-footer', { elevation }), stylex.props(styles.footer), className, style)}
-      {...props}
-    />
-  );
+  return useRender({
+    defaultTagName: 'div',
+    render,
+    ref,
+    props: {
+      ...rest,
+      ...mergeStyleProps(themeProps('card-footer', { elevation }), stylex.props(styles.footer), className, style),
+    },
+  });
 });
 
+/**
+ * A styled surface composed through `Card.Root`, `Card.Header`, `Card.Content`, and `Card.Footer`.
+ * Every part accepts the Mosaic `render` prop and forwards its ref.
+ */
 export const Card = { Root, Header, Content, Footer };

From 60221b8c5947750bc6d7721d9b6ad4ca3407da6f Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Fri, 31 Jul 2026 10:03:23 -0600
Subject: [PATCH 09/13] docs(swingset): use Card compound API in Popover
 examples

---
 .../src/stories/popover.component.mdx         | 20 +++++++++----------
 .../src/stories/popover.component.stories.tsx |  8 ++++----
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/packages/swingset/src/stories/popover.component.mdx b/packages/swingset/src/stories/popover.component.mdx
index 08dc13b078a..9ce80bcbbb2 100644
--- a/packages/swingset/src/stories/popover.component.mdx
+++ b/packages/swingset/src/stories/popover.component.mdx
@@ -29,7 +29,7 @@ import { Popover } from '@clerk/ui/mosaic/components/popover';
 <Popover.Root>
   <Popover.Trigger render={props => <Button {...props}>Open popover</Button>} />
   <Popover.Popup aria-label='Account'>
-    <Card>
+    <Card.Root>
       <Card.Content>Flexible inner content.</Card.Content>
       <Card.Footer>
         <Button
@@ -39,7 +39,7 @@ import { Popover } from '@clerk/ui/mosaic/components/popover';
           Sign out of all accounts
         </Button>
       </Card.Footer>
-    </Card>
+    </Card.Root>
   </Popover.Popup>
 </Popover.Root>;
 ```
@@ -61,9 +61,9 @@ neither logs a development warning.
 <Popover.Root>
   <Popover.Trigger>Open</Popover.Trigger>
   <Popover.Popup aria-label='Account'>
-    <Card>
+    <Card.Root>
       <Card.Content>Flexible inner content.</Card.Content>
-    </Card>
+    </Card.Root>
   </Popover.Popup>
 </Popover.Root>;
 ```
@@ -79,9 +79,9 @@ const [open, setOpen] = useState(false);
 >
   <Popover.Trigger>Open</Popover.Trigger>
   <Popover.Popup aria-label='Account'>
-    <Card>
+    <Card.Root>
       <Card.Content>Flexible inner content.</Card.Content>
-    </Card>
+    </Card.Root>
   </Popover.Popup>
 </Popover.Root>;
 ```
@@ -97,9 +97,9 @@ region.
 <Popover.Root>
   <Popover.Trigger>Open</Popover.Trigger>
   <Popover.Popup size='lg'>
-    <Card>
+    <Card.Root>
       <Card.Content>A wider panel.</Card.Content>
-    </Card>
+    </Card.Root>
   </Popover.Popup>
 </Popover.Root>;
 ```
@@ -135,9 +135,9 @@ centering on it.
 >
   <Popover.Trigger>Open</Popover.Trigger>
   <Popover.Popup aria-label='Account'>
-    <Card>
+    <Card.Root>
       <Card.Content>Aligned to the trigger's end edge.</Card.Content>
-    </Card>
+    </Card.Root>
   </Popover.Popup>
 </Popover.Root>;
 ```
diff --git a/packages/swingset/src/stories/popover.component.stories.tsx b/packages/swingset/src/stories/popover.component.stories.tsx
index 1e923360fb3..b775dbc7f64 100644
--- a/packages/swingset/src/stories/popover.component.stories.tsx
+++ b/packages/swingset/src/stories/popover.component.stories.tsx
@@ -23,7 +23,7 @@ export function Default() {
     <Popover.Root>
       <Popover.Trigger render={props => <Button {...props}>Open popover</Button>} />
       <Popover.Popup aria-label='Account'>
-        <Card>
+        <Card.Root>
           <Card.Header>
             <Heading size='sm'>Ada Lovelace</Heading>
             <Text>ada@example.com</Text>
@@ -36,7 +36,7 @@ export function Default() {
               Sign out of all accounts
             </Button>
           </Card.Footer>
-        </Card>
+        </Card.Root>
       </Popover.Popup>
     </Popover.Root>
   );
@@ -48,11 +48,11 @@ export function Default() {
 const labelledTrigger = (label: string) => <Button variant='outline'>{label}</Button>;
 
 const panel = (label: string) => (
-  <Card>
+  <Card.Root>
     <Card.Content style={{ paddingBlock: '1rem' }}>
       <Text>{label}</Text>
     </Card.Content>
-  </Card>
+  </Card.Root>
 );
 
 export function Placement() {

From bc43056a57ecbd590f21e11fd0b71a5e41c49263 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Fri, 31 Jul 2026 11:59:32 -0600
Subject: [PATCH 10/13] =?UTF-8?q?refactor:=20Move=20=E2=80=98rest=E2=80=99?=
 =?UTF-8?q?=20spread=20after=20=E2=80=98mergeStyleProps=E2=80=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/ui/src/mosaic/components/card/card.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
index 3338486440d..73e9a64c803 100644
--- a/packages/ui/src/mosaic/components/card/card.tsx
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -35,13 +35,13 @@ const Root = React.forwardRef<HTMLDivElement, CardProps>(function CardRoot(
     render,
     ref,
     props: {
-      ...rest,
       ...mergeStyleProps(
         themeProps('card-root', { alignment, elevation }),
         stylex.props(styles.root, elevations[elevation]),
         className,
         style,
       ),
+      ...rest,
     },
   });
 
@@ -58,13 +58,13 @@ const Header = React.forwardRef<HTMLDivElement, MosaicComponentProps<'div'>>(fun
     render,
     ref,
     props: {
-      ...rest,
       ...mergeStyleProps(
         themeProps('card-header', { alignment }),
         stylex.props(styles.header, headerAlignments[alignment]),
         className,
         style,
       ),
+      ...rest,
     },
   });
 
@@ -80,8 +80,8 @@ const Content = React.forwardRef<HTMLDivElement, MosaicComponentProps<'div'>>(fu
     render,
     ref,
     props: {
-      ...rest,
       ...mergeStyleProps(themeProps('card-content'), stylex.props(styles.content), className, style),
+      ...rest,
     },
   });
 });
@@ -96,8 +96,8 @@ const Footer = React.forwardRef<HTMLDivElement, MosaicComponentProps<'div'>>(fun
     render,
     ref,
     props: {
-      ...rest,
       ...mergeStyleProps(themeProps('card-footer', { elevation }), stylex.props(styles.footer), className, style),
+      ...rest,
     },
   });
 });

From 1248e1fba75c42d1e1fd5513a5adec158968642f Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Fri, 31 Jul 2026 12:15:41 -0600
Subject: [PATCH 11/13] refactor(ui): align Card elevation names with Figma

---
 packages/swingset/src/stories/card.component.stories.tsx | 4 ++--
 packages/ui/src/mosaic/components/card/card.styles.ts    | 2 +-
 packages/ui/src/mosaic/components/card/card.test.tsx     | 4 ++--
 packages/ui/src/mosaic/components/card/card.tsx          | 6 +++---
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/swingset/src/stories/card.component.stories.tsx b/packages/swingset/src/stories/card.component.stories.tsx
index eca6fe484de..201fd081626 100644
--- a/packages/swingset/src/stories/card.component.stories.tsx
+++ b/packages/swingset/src/stories/card.component.stories.tsx
@@ -19,11 +19,11 @@ export const meta: StoryMeta = {
   styles: {
     _variants: {
       alignment: { start: {}, center: {} },
-      elevation: { raised: {}, flush: {}, overlay: {} },
+      elevation: { card: {}, flush: {}, overlay: {} },
     },
     _defaultVariants: {
       alignment: 'start',
-      elevation: 'raised',
+      elevation: 'card',
     },
   },
 };
diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index 1e51ca25f46..7e57d4ee8e9 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -40,7 +40,7 @@ export const styles = stylex.create({
 });
 
 export const elevations = stylex.create({
-  raised: {
+  card: {
     borderRadius: radiusVars['--cl-radius-container'],
     overflow: 'hidden',
     backgroundColor: colorVars['--cl-color-card'],
diff --git a/packages/ui/src/mosaic/components/card/card.test.tsx b/packages/ui/src/mosaic/components/card/card.test.tsx
index 6455a57e940..2561a816d6e 100644
--- a/packages/ui/src/mosaic/components/card/card.test.tsx
+++ b/packages/ui/src/mosaic/components/card/card.test.tsx
@@ -17,12 +17,12 @@ describe('Mosaic Card', () => {
 
     expect(screen.getByTestId('root')).toHaveClass('cl-card-root');
     expect(screen.getByTestId('root')).toHaveAttribute('data-alignment', 'start');
-    expect(screen.getByTestId('root')).toHaveAttribute('data-elevation', 'raised');
+    expect(screen.getByTestId('root')).toHaveAttribute('data-elevation', 'card');
     expect(screen.getByTestId('header')).toHaveClass('cl-card-header');
     expect(screen.getByTestId('header')).toHaveAttribute('data-alignment', 'start');
     expect(screen.getByTestId('content')).toHaveClass('cl-card-content');
     expect(screen.getByTestId('footer')).toHaveClass('cl-card-footer');
-    expect(screen.getByTestId('footer')).toHaveAttribute('data-elevation', 'raised');
+    expect(screen.getByTestId('footer')).toHaveAttribute('data-elevation', 'card');
   });
 
   it('reflects centered alignment on the root and header', () => {
diff --git a/packages/ui/src/mosaic/components/card/card.tsx b/packages/ui/src/mosaic/components/card/card.tsx
index 73e9a64c803..134aca83714 100644
--- a/packages/ui/src/mosaic/components/card/card.tsx
+++ b/packages/ui/src/mosaic/components/card/card.tsx
@@ -8,10 +8,10 @@ import { TextContext } from '../text';
 import { elevations, headerAlignments, styles } from './card.styles';
 
 type CardAlignment = 'start' | 'center';
-type CardElevation = 'raised' | 'flush' | 'overlay';
+type CardElevation = 'card' | 'flush' | 'overlay';
 
 const DEFAULT_ALIGNMENT: CardAlignment = 'start';
-const DEFAULT_ELEVATION: CardElevation = 'raised';
+const DEFAULT_ELEVATION: CardElevation = 'card';
 
 const CardVariantContext = React.createContext<{ alignment: CardAlignment; elevation: CardElevation }>({
   alignment: DEFAULT_ALIGNMENT,
@@ -22,7 +22,7 @@ const CardVariantContext = React.createContext<{ alignment: CardAlignment; eleva
 export interface CardProps extends MosaicComponentProps<'div'> {
   /** Alignment applied to `Card.Header`. @default 'start' */
   alignment?: CardAlignment;
-  /** Surface treatment applied to the card. @default 'raised' */
+  /** Surface treatment applied to the card. @default 'card' */
   elevation?: CardElevation;
 }
 

From 3546d65350990309bbd5505a7ada612831ff6e1e Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Fri, 31 Jul 2026 12:26:58 -0600
Subject: [PATCH 12/13] fix(ui): inherit Card footer background

---
 packages/ui/src/mosaic/components/card/card.styles.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index 7e57d4ee8e9..ac7eb3210bb 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -27,7 +27,6 @@ export const styles = stylex.create({
     paddingBlock: space['4'],
     paddingInline: space['6'],
     alignItems: 'center',
-    backgroundColor: `color-mix(in oklab, ${colorVars['--cl-color-card-foreground']} 4%, ${colorVars['--cl-color-card']})`,
     boxSizing: 'border-box',
     display: 'flex',
     flexShrink: 0,

From f70d3bcdd3e7a97d39629df2b4a80dc7ee1ca237 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Fri, 31 Jul 2026 12:43:35 -0600
Subject: [PATCH 13/13] fix(ui): adapt Card shadows for dark mode

---
 .../ui/src/mosaic/components/card/card.styles.ts     | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/ui/src/mosaic/components/card/card.styles.ts b/packages/ui/src/mosaic/components/card/card.styles.ts
index ac7eb3210bb..035231712d8 100644
--- a/packages/ui/src/mosaic/components/card/card.styles.ts
+++ b/packages/ui/src/mosaic/components/card/card.styles.ts
@@ -43,9 +43,9 @@ export const elevations = stylex.create({
     borderRadius: radiusVars['--cl-radius-container'],
     overflow: 'hidden',
     backgroundColor: colorVars['--cl-color-card'],
-    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
-                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
-                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
+    boxShadow: `0 12px 12px -7px light-dark(oklch(0.2046 0 0 / 12%), transparent),
+                0 24px 24px -10px light-dark(oklch(0.2046 0 0 / 4%), transparent),
+                0 0 0 1px light-dark(oklch(0.2046 0 0 / 4%), oklch(1 0 0 / 10%))`,
   },
   flush: {
     borderRadius: radiusVars['--cl-radius-container'],
@@ -57,9 +57,9 @@ export const elevations = stylex.create({
     borderRadius: radiusVars['--cl-radius-container'],
     overflow: 'hidden',
     backgroundColor: colorVars['--cl-color-card'],
-    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
-                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
-                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
+    boxShadow: `0 12px 12px -7px light-dark(oklch(0.2046 0 0 / 12%), transparent),
+                0 24px 24px -10px light-dark(oklch(0.2046 0 0 / 4%), transparent),
+                0 0 0 1px light-dark(oklch(0.2046 0 0 / 4%), oklch(1 0 0 / 10%))`,
   },
 });