feat(ui): add Mosaic Badge component by alexcarpenter · Pull Request #9221 · clerk/javascript

alexcarpenter · 2026-07-22T20:35:54Z

Adds Mosaic Badge. StyleX, span root, one intent axis: primary | secondary | warning | destructive | success.

Preview: https://swingset-git-carp-mosaic-badge.clerkstage.dev/components/badge

changeset-bot · 2026-07-22T20:35:58Z

🦋 Changeset detected

Latest commit: 4ba9759

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

vercel · 2026-07-22T20:36:33Z

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

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

pkg-pr-new · 2026-07-22T20:39:12Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9221

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9221

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9221

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9221

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9221

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9221

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9221

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9221

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9221

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9221

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9221

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9221

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9221

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9221

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9221

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9221

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9221

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9221

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9221

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9221

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9221

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9221

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9221

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9221

commit: 4ba9759

github-actions · 2026-07-22T20:39:42Z

API Changes Report

Generated by Break Check on 2026-07-28T15:48:44.482Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

Report generated by Break Check

_{Last ran on 4ba9759.}

coderabbitai · 2026-07-22T20:41:06Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new Mosaic Badge component with color variants, StyleX styling and tokens, forwarded props and refs, tests, Storybook stories, and MDX documentation. Registers the component in Swingset, exposes its public exports, updates PropTable rendering, externalizes headless packages, updates button color tokens, and adds a changeset.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the Mosaic Badge component.
Description check	✅ Passed	The description is related to the Badge component work, even though some prop names are stale.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/mosaic-badge.md:
- Around line 1-2: Replace the empty frontmatter in mosaic-badge.md with a
changeset entry for `@clerk/ui` using a minor release level, preserving the
required changeset format so the new public Badge component and props API
generate a package bump and changelog entry.

In `@packages/swingset/src/stories/badge.stories.tsx`:
- Around line 1-2: Add the required top-level Emotion JSX import-source pragma
to the badge story before its imports, while preserving the existing BadgeProps
and Badge imports.

In `@packages/ui/src/mosaic/components/badge/badge.tsx`:
- Around line 18-19: Update the Badge component’s prop spread order so rest
props are applied before the component-owned themeProps result, preventing
consumers from overriding the resolved intent metadata. Preserve the existing
style and className resolution, and add a regression test covering an intent
such as success with conflicting rest metadata to verify the resolved intent
wins.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: f2fefe08-7668-4d38-97b4-36691ea6f821

📥 Commits

Reviewing files that changed from the base of the PR and between 68ae308 and e5fb0a1.

📒 Files selected for processing (11)

.changeset/mosaic-badge.md
packages/swingset/src/components/DocsViewer.tsx
packages/swingset/src/lib/registry.ts
packages/swingset/src/stories/badge.mdx
packages/swingset/src/stories/badge.stories.tsx
packages/ui/src/mosaic/components/badge/badge.styles.ts
packages/ui/src/mosaic/components/badge/badge.test.tsx
packages/ui/src/mosaic/components/badge/badge.tsx
packages/ui/src/mosaic/components/badge/index.ts
packages/ui/src/mosaic/styles/index.ts
packages/ui/src/mosaic/tokens.stylex.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)

coderabbitai · 2026-07-22T20:41:09Z

+import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
+import { Badge } from '@clerk/ui/mosaic/components/badge';


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add the required Emotion JSX pragma.

This story renders a styled Mosaic component but lacks the required top-level @jsxImportSource pragma.

+/** `@jsxImportSource` `@emotion/react` */ + import type { BadgeProps } from '`@clerk/ui/mosaic/components/badge`';

As per coding guidelines, “Use Emotion pragma /** @jsxImportSource @emotion/react */ at the top of story files that render styled Mosaic components.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';

import { Badge } from '@clerk/ui/mosaic/components/badge';

/** `@jsxImportSource` `@emotion/react` */

import type { BadgeProps } from '`@clerk/ui/mosaic/components/badge`';

import { Badge } from '`@clerk/ui/mosaic/components/badge`';

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/swingset/src/stories/badge.stories.tsx` around lines 1 - 2, Add the required top-level Emotion JSX import-source pragma to the badge story before its imports, while preserving the existing BadgeProps and Badge imports.

Source: Coding guidelines

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/ui/src/mosaic/components/badge/badge.styles.ts`:
- Around line 34-43: Update the warning and success variants in the badge styles
to meet at least 4.5:1 contrast for label-sm text in light and dark themes,
using appropriate contrast-paired foreground tokens or adjusted faded fills
while leaving destructive unchanged. Add contrast tests covering warning in
light mode and success in dark mode.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 359f20ad-7b5b-46fc-9c96-2cef54c7e062

📥 Commits

Reviewing files that changed from the base of the PR and between e5fb0a1 and 173b95d.

📒 Files selected for processing (2)

packages/ui/src/mosaic/components/badge/badge.styles.ts
packages/ui/src/mosaic/tokens.stylex.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/clerk-ios (auto-detected)
clerk/cli (auto-detected)
clerk/clerk-android (auto-detected)

- values: secondary→neutral, destructive→negative, success→positive - swingset PropTable: sx row now opt-out (Badge is StyleX, no sx) - docs: document render prop

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/ui/src/mosaic/tokens.stylex.ts`:
- Around line 29-44: Restore the deprecated --cl-color-destructive* and
--cl-color-muted* aliases in the exported colorVars alongside the replacement
negative and neutral tokens. Map each alias to its corresponding current token,
preserving compatibility for existing SDK styles and consumer customizations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: d6a66e4b-7245-437c-97f3-09c71b4ce92f

📥 Commits

Reviewing files that changed from the base of the PR and between 173b95d and 5406ee6.

📒 Files selected for processing (13)

.changeset/mosaic-badge.md
packages/swingset/src/components/DocsViewer.tsx
packages/swingset/src/components/PropTable.tsx
packages/swingset/src/lib/registry.ts
packages/swingset/src/stories/badge.mdx
packages/swingset/src/stories/badge.stories.tsx
packages/ui/src/mosaic/components/badge/badge.styles.ts
packages/ui/src/mosaic/components/badge/badge.test.tsx
packages/ui/src/mosaic/components/badge/badge.tsx
packages/ui/src/mosaic/components/badge/index.ts
packages/ui/src/mosaic/styles/index.ts
packages/ui/src/mosaic/tokens.stylex.ts
packages/ui/tsdown.mosaic.config.mts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)

🚧 Files skipped from review as they are similar to previous changes (5)

packages/ui/src/mosaic/components/badge/index.ts
packages/ui/src/mosaic/styles/index.ts
packages/swingset/src/components/DocsViewer.tsx
packages/swingset/src/stories/badge.mdx
packages/swingset/src/lib/registry.ts

Dev now injects StyleX at runtime (unplugin runtimeInjection) instead of the build-time globals.css extraction, which Next never re-ran on .styles.ts edits. Prod keeps static extraction.

…ross-module defineConsts emits no CSS across module boundaries, so every consumer of the space scale (Badge, Button, ...) got dangling var(--hash) references with no :root default and collapsed spacing. Switch space to defineVars (like astryx's spacingVars), keeping the calc(var(--cl-spacing) * n) values so --cl-spacing still rescales the whole scale and the steps stay hashed (only --cl-spacing is publicly targetable). Call sites are unchanged.

…esolve defineVars token :root defaults are compile-time only (the runtime export throws), so runtimeInjection alone left every var(--cl-*) unresolved. Keep the postcss extraction on in dev for the static :root defaults and keep runtimeInjection for fresh atoms on edit; drop the treeshakeCompensation experiment that didn't help.

github-actions Bot added the ui label Jul 22, 2026

vercel Bot deployed to Preview – clerk-js-sandbox July 22, 2026 20:36 View deployment

vercel Bot deployed to Preview – swingset July 22, 2026 20:38 View deployment

coderabbitai Bot reviewed Jul 22, 2026

View reviewed changes

vercel Bot deployed to Preview – clerk-js-sandbox July 23, 2026 21:08 View deployment

vercel Bot deployed to Preview – swingset July 23, 2026 21:10 View deployment

coderabbitai Bot reviewed Jul 23, 2026

View reviewed changes

Comment thread packages/ui/src/mosaic/components/badge/badge.styles.ts Outdated

coderabbitai Bot mentioned this pull request Jul 23, 2026

feat(ui): add Mosaic Avatar component #9230

Merged

4 tasks

alexcarpenter added 3 commits July 23, 2026 19:49

feat(ui): add Mosaic Badge component

2f24dfe

adjust colors/sizing

d0a3fcd

refactor(ui): rename mergeProps to mergeStyleProps in Badge

ba4d13a

alexcarpenter force-pushed the carp/mosaic-badge branch from 173b95d to ba4d13a Compare July 23, 2026 23:51

vercel Bot deployed to Preview – clerk-js-sandbox July 23, 2026 23:52 View deployment

vercel Bot deployed to Preview – swingset July 23, 2026 23:54 View deployment

feat(ui): support custom rendering in Badge via useRender

dfb8912

vercel Bot deployed to Preview – clerk-js-sandbox July 23, 2026 23:56 View deployment

vercel Bot deployed to Preview – swingset July 23, 2026 23:58 View deployment

refactor(ui): rename Badge intent prop to color

5406ee6

- values: secondary→neutral, destructive→negative, success→positive - swingset PropTable: sx row now opt-out (Badge is StyleX, no sx) - docs: document render prop

vercel Bot deployed to Preview – clerk-js-sandbox July 27, 2026 19:40 View deployment

vercel Bot had a problem deploying to Preview – swingset July 27, 2026 19:40 Failure

coderabbitai Bot reviewed Jul 27, 2026

View reviewed changes

Comment thread packages/ui/src/mosaic/tokens.stylex.ts

fix(ui): point Button destructive intent at renamed negative color token

8e4e83b

vercel Bot deployed to Preview – clerk-js-sandbox July 27, 2026 19:47 View deployment

vercel Bot had a problem deploying to Preview – swingset July 27, 2026 19:49 Failure

fix(ui): update swingset registry for renamed Badge Colors story

49c80c2

vercel Bot temporarily deployed to Preview – clerk-js-sandbox July 27, 2026 19:55 Inactive

docs(ui): fix stale intent references in Badge prose and comment

890fc06

vercel Bot deployed to Preview – clerk-js-sandbox July 27, 2026 19:57 View deployment

vercel Bot deployed to Preview – swingset July 27, 2026 19:58 View deployment

fix(repo): hot-reload Mosaic StyleX edits in swingset dev

3401708

Dev now injects StyleX at runtime (unplugin runtimeInjection) instead of the build-time globals.css extraction, which Next never re-ran on .styles.ts edits. Prod keeps static extraction.

vercel Bot temporarily deployed to Preview – clerk-js-sandbox July 28, 2026 14:24 Inactive

vercel Bot deployed to Preview – swingset July 28, 2026 14:27 View deployment

alexcarpenter added 3 commits July 28, 2026 10:57

extract colors from styles

3a910e0

vercel Bot deployed to Preview – clerk-js-sandbox July 28, 2026 15:01 View deployment

vercel Bot deployed to Preview – swingset July 28, 2026 15:04 View deployment

docs(ui): add @example JSDoc to Mosaic Badge and Button

4ba9759

vercel Bot deployed to Preview – clerk-js-sandbox July 28, 2026 15:45 View deployment

vercel Bot deployed to Preview – swingset July 28, 2026 15:47 View deployment

maxyinger approved these changes Jul 28, 2026

View reviewed changes

alexcarpenter merged commit d8407c9 into main Jul 28, 2026
84 of 85 checks passed

alexcarpenter deleted the carp/mosaic-badge branch July 28, 2026 16:35

This was referenced Jul 28, 2026

feat(ui): migrate Mosaic Heading and Text to StyleX #9244

Merged

feat(ui): add Mosaic Item component #9234

Open

refactor(ui): share one base props type across Mosaic components #9267

Merged

		import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
		import { Badge } from '@clerk/ui/mosaic/components/badge';

-import type { BadgeProps } from '@clerk/ui/mosaic/components/badge';
-import { Badge } from '@clerk/ui/mosaic/components/badge';
+/** `@jsxImportSource` `@emotion/react` */
+import type { BadgeProps } from '`@clerk/ui/mosaic/components/badge`';
+import { Badge } from '`@clerk/ui/mosaic/components/badge`';

Uh oh!

Conversation

alexcarpenter commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

No API Changes Detected

Uh oh!

coderabbitai Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexcarpenter commented Jul 22, 2026 •

edited

Loading

changeset-bot Bot commented Jul 22, 2026 •

edited

Loading

vercel Bot commented Jul 22, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 22, 2026 •

edited

Loading

github-actions Bot commented Jul 22, 2026 •

edited

Loading

coderabbitai Bot commented Jul 22, 2026 •

edited

Loading