feat(ui): migrate Mosaic Icon to StyleX by alexcarpenter · Pull Request #9245 · clerk/javascript

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

alexcarpenter · 2026-07-24T20:14:19Z

Description

Stacked on #9244 (base branch carp/mosaic-typography-stylex) — Icon's story needs the meta.styleEngine field that PR adds. Retarget to main once it merges.

Moves Icon off the Emotion slot-recipe engine onto StyleX. Same contract as the components migrated before it: a stable .cl-icon class plus a data-size attribute, with the consumer's className/style merged last.

The appearance.icons override path loses a layer. It only wrapped itself in Emotion's ClassNames to serialize the recipe's css into a real class — an override is authored in a consumer file with no jsx pragma, so its own css prop would be ignored. stylex.props() already returns a className, so the override is now cloned with the same merged props the built-in glyph gets:

constprops=mergeStyleProps(themeProps('icon',{ size }),stylex.props(styles.base,sizes[size]),className,style);if(override){constoverrideClassName=(override.propsas{className?: string}).className;returnReact.cloneElement(override,{ ...rest, ...mergeStyleProps(props,overrideClassName)});}

Everything the override path guaranteed is unchanged: overrides stay plain elements (so they serialize across the RSC boundary), Mosaic's sizing applies to them exactly as to the built-in glyph, the element's own className survives, call-site svg props are forwarded, and ref is still deliberately not forwarded to an override.

Consumers target .cl-icon + data-size instead of data-cl-slot="icon" and appearance.elements.icon, matching Button, Heading, and Text.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

vercel · 2026-07-24T20:14:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 27, 2026 3:51pm
swingset	Ready	Preview, Comment	Jul 27, 2026 3:51pm

changeset-bot · 2026-07-24T20:14:25Z

🦋 Changeset detected

Latest commit: a15162e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Same contract as the other migrated components: a stable `.cl-icon` class plus a `data-size` attr, with the consumer's `className`/`style` merged last. The `appearance.icons` override path loses a layer. It only wrapped itself in Emotion's `ClassNames` to serialize the recipe's `css` into a real class, since an override authored in a consumer file has no jsx pragma to process a `css` prop. `stylex.props()` already returns a className, so the override is now cloned directly with the same merged props the built-in glyph gets.

Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

github-actionsBot added the ui label Jul 24, 2026

vercelBotdeployed to Preview – clerk-js-sandbox July 24, 2026 20:14 View deployment

vercelBotdeployed to Preview – swingset July 24, 2026 20:16 View deployment

vercelBotdeployed to Preview – clerk-js-sandbox July 24, 2026 20:19 View deployment

alexcarpenter added 2 commits July 24, 2026 16:20

refactor(ui): drop redundant comments from the Icon migration
3643f2a

alexcarpenter force-pushed the carp/mosaic-icon-stylex branch from 7f6ce20 to 3643f2aCompare July 24, 2026 20:20

vercelBotdeployed to Preview – clerk-js-sandbox July 24, 2026 20:21 View deployment

vercelBotdeployed to Preview – swingset July 24, 2026 20:23 View deployment

feat(ui): add placement prop to Mosaic Icon
a15162e
Reflects data-icon="inline-start|inline-end" so a container can tighten padding on the side the icon sits.

vercelBotdeployed to Preview – clerk-js-sandbox July 27, 2026 15:49 View deployment

vercelBotdeployed to Preview – swingset July 27, 2026 15:51 View deployment

maxyinger approved these changes Jul 28, 2026
View reviewed changes

alexcarpenter merged commit 21eb391 into carp/mosaic-typography-stylexJul 28, 2026
10 checks passed

alexcarpenter deleted the carp/mosaic-icon-stylex branch July 28, 2026 18:01

alexcarpenter added a commit that referenced this pull request Jul 28, 2026
feat(ui): migrate Mosaic Icon to StyleX (#9245)
e21b9f2

alexcarpenter added a commit that referenced this pull request Jul 28, 2026
feat(ui): migrate Mosaic Icon to StyleX (#9245)
e33a29e