feat(ui): Mosaic <Card /> component scaffolding

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });

.changeset/some-towns-study.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -25,6 +25,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
  },
  components: {
  button: dynamic(() => import('../stories/button.mdx')),
+ card: dynamic(() => import('../stories/card.component.mdx')),
  input: dynamic(() => import('../stories/input.mdx')),
  dialog: dynamic(() => import('../stories/dialog.component.mdx')),
  heading: dynamic(() => import('../stories/heading.mdx')),

packages/swingset/src/lib/registry.ts

@@ -2,6 +2,11 @@
 import { meta as accordionMeta } from '../stories/accordion.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
+import {
+ Centered as CardCentered,
+ Default as CardDefault,
+ meta as cardComponentMeta,
+} from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import {
  Default as DeleteOrganizationDefault,
@@ -66,6 +71,8 @@ const organizationProfileGeneralModule: StoryModule = {
  Default: OrganizationProfileGeneralDefault,
 };
 
+const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
+
 const buttonModule: StoryModule = { meta: buttonMeta, Primary, Sizes, Disabled };
 
 const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes, Disabled: InputDisabled, Invalid };
@@ -116,6 +123,7 @@ export const registry: StoryModule[] = [
  destructiveModule,
  // Components
  buttonModule,
+ cardComponentModule,
  inputModule,
  dialogComponentModule,
  headingModule,

packages/swingset/src/stories/card.component.mdx

@@ -0,0 +1,39 @@
+import * as CardStories from './card.component.stories';
+
+# Card
+
+A styled surface container that groups related content into Header, Content, and Footer zones. Use it to visually separate distinct sections of a page or flow.
+
+## Playground
+
+<Preview
+ name='Default'
+ storyModule={CardStories}
+/>
+
+## Props
+
+<PropTable meta={CardStories.meta} />
+
+## Usage
+
+```tsx
+import { Card } from '@clerk/ui/mosaic/components/card';
+
+<Card>
+ <Card.Header>Heading</Card.Header>
+ <Card.Content>Body content.</Card.Content>
+ <Card.Footer>Footer actions</Card.Footer>
+</Card>
+```
+
+---
+
+## Examples
+
+### Centered
+
+<Story
+ name='Centered'
+ storyModule={CardStories}
+/>

packages/swingset/src/stories/card.component.stories.tsx

@@ -0,0 +1,59 @@
+/** @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 { Heading } from '@clerk/ui/mosaic/components/heading';
+import { Text } from '@clerk/ui/mosaic/components/text';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+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,
+};
+
+function knobsAsProps(props: Record<string, unknown>) {
+ return props as unknown as CardProps;
+}
+
+export function Default(props: Record<string, unknown>) {
+ return (
+ <Card
+ {...knobsAsProps(props)}
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Login to your account</Heading>
+ <Text>Enter your email below to login to your account</Text>
+ </Card.Header>
+ <Card.Content>Card body content goes here.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Continue</Button>
+ </Card.Footer>
+ </Card>
+ );
+}
+
+export function Centered() {
+ return (
+ <Card
+ alignment='center'
+ style={{ maxWidth: 400 }}
+ >
+ <Card.Header>
+ <Heading>Verify your email</Heading>
+ <Text>We sent a verification code to your email address</Text>
+ </Card.Header>
+ <Card.Content>Enter the code below to continue.</Card.Content>
+ <Card.Footer>
+ <Button fullWidth>Verify</Button>
+ </Card.Footer>
+ </Card>
+ );
+}

packages/ui/src/mosaic/components/button.tsx

@@ -53,6 +53,12 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  borderRadius: theme.rounded.full,
  },
  },
+ fullWidth: {
+ true: {
+ width: '100%',
+ },
+ false: {},
+ },
  },
  compoundVariants: [
  {
@@ -126,7 +132,7 @@ export const buttonRecipe = defineSlotRecipe(theme => ({
  { shape: 'circle', size: 'sm', css: { width: theme.spacing(6), height: theme.spacing(6) } },
  { shape: 'circle', size: 'md', css: { width: theme.spacing(9), height: theme.spacing(9) } },
  ],
- defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default' },
+ defaultVariants: { intent: 'primary', size: 'md', variant: 'filled', shape: 'default', fullWidth: false },
 }));
 
 declare module '../registry' {
@@ -138,9 +144,9 @@ declare module '../registry' {
 export type ButtonProps = React.ComponentPropsWithRef<'button'> & RecipeVariantProps<typeof buttonRecipe>;
 
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function MosaicButton(props, ref) {
- const { intent, variant, size, shape, disabled, sx, children, ...rest } = props;
+ const { intent, variant, size, shape, fullWidth, disabled, sx, children, ...rest } = props;
  const { root } = useRecipe(buttonRecipe, {
- variants: { intent, variant, size, shape },
+ variants: { intent, variant, size, shape, fullWidth },
  state: { disabled: !!disabled },
  sx,
  });

packages/ui/src/mosaic/components/card.tsx

@@ -0,0 +1,134 @@
+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={{ intent: 'mutedForeground' }}>
+ <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;

packages/ui/src/mosaic/components/dialog.tsx

@@ -1,12 +1,11 @@
-import React from 'react';
-import type { ReactNode } from 'react';
-
-import { useDialogContext } from '@clerk/headless/dialog';
 import type { DialogProps as HeadlessDialogProps } from '@clerk/headless/dialog';
+import { useDialogContext } from '@clerk/headless/dialog';
+import type { ReactNode } from 'react';
+import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
-import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 import type { RecipeVariantProps } from '../slot-recipe';
+import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
 /**
  * One multi-slot recipe owns every dialog part: slot identity (`data-cl-slot`),
@@ -130,7 +129,9 @@ interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' |
 
 function DialogContent({ children }: { children: DialogProps['children'] }) {
  const { setOpen } = useDialogContext();
- if (typeof children !== 'function') return <>{children}</>;
+ if (typeof children !== 'function') {
+ return <>{children}</>;
+ }
  return <>{children({ close: () => setOpen(false) })}</>;
 }
 

packages/ui/src/mosaic/components/heading.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic heading slot recipe.
@@ -46,13 +47,15 @@ declare module '../registry' {
 /** Props for the Heading component combining h2 attributes with recipe variants. */
 export type HeadingProps = ComponentProps<'h2'> & RecipeVariantProps<typeof headingRecipe>;
 
+export const HeadingContext = React.createContext<Partial<HeadingProps> | null>(null);
+
 /**
  * Themeable heading component.
  * Renders as an h2 element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(function MosaicHeading(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, HeadingContext);
  const { root } = useRecipe(headingRecipe, { variants: { size, intent }, sx });
  if (render) {
  // renderElement handles the cast; Emotion processes `css` inside the callback's own JSX.

packages/ui/src/mosaic/components/text.tsx

@@ -5,6 +5,7 @@ import { renderElement } from '@clerk/headless/utils';
 
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
+import { useContextProps } from '../utils/context';
 
 /**
  * Mosaic text slot recipe.
@@ -44,13 +45,15 @@ declare module '../registry' {
 /** Props for the Text component combining p element attributes with recipe variants. */
 export type TextProps = ComponentProps<'p'> & RecipeVariantProps<typeof textRecipe>;
 
+export const TextContext = React.createContext<Partial<TextProps> | null>(null);
+
 /**
  * Themeable text component.
  * Renders as a p element by default, forwards refs, and supports
  * size and intent variants plus Mosaic styling (sx prop and render callback).
  */
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(props, ref) {
- const { size, intent, sx, render, ...rest } = props;
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(function MosaicText(rawProps, ref) {
+ const { size, intent, sx, render, ...rest } = useContextProps(rawProps, TextContext);
  const { root } = useRecipe(textRecipe, { variants: { size, intent }, sx });
  if (render) {
  return renderElement({ defaultTagName: 'p', render, props: { ref, ...root, ...rest } as Record<string, unknown> });