refactor(ui): migrate Mosaic Card to StyleX by austincalvelage · Pull Request #9292 · clerk/javascript

austincalvelage · 2026-07-30T20:27:52Z

Description

https://swingset-git-austin-mosaic-card-component.clerkstage.dev/components/card

Updates the Mosaic Card to match the current Figma:

Migrates Card styling from Emotion to StyleX.
Aligns the Card root, elevation, shadow, radius, and footer treatment with the design.
Updates the API to use the compound Card.Root, Card.Header, Card.Content, and Card.Footer structure.
Adds raised, flush, and overlay elevation options.

import { Card } from '@clerk/ui/mosaic/components/card';

<Card.Root elevation='raised'>
  <Card.Header>Heading</Card.Header>
  <Card.Content>Body content.</Card.Content>
  <Card.Footer>Footer actions</Card.Footer>
</Card.Root>;

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-30T20:27:59Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Jul 31, 2026 6:49pm
swingset	Ready	Preview	Jul 31, 2026 6:49pm

changeset-bot · 2026-07-30T20:28:08Z

🦋 Changeset detected

Latest commit: f70d3bc

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

pkg-pr-new · 2026-07-30T20:31:23Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: f70d3bc

github-actions · 2026-07-31T16:13:56Z

API Changes Report

Generated by Break Check on 2026-07-31T18:51:22.394Z

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 f70d3bc.}

coderabbitai · 2026-07-31T16:19:32Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: bf49b6d5-90e5-4f90-9b4b-87d169ea2dab

📥 Commits

Reviewing files that changed from the base of the PR and between 3546d65 and f70d3bc.

📒 Files selected for processing (1)

packages/ui/src/mosaic/components/card/card.styles.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/clerk-android (auto-detected)
clerk/cli (auto-detected)

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

packages/ui/src/mosaic/components/card/card.styles.ts

📝 Walkthrough

Walkthrough

The PR replaces the previous Card implementation with a StyleX-based compound component. It adds Card.Root, Card.Header, Card.Content, and Card.Footer, with alignment and elevation variants, context propagation, custom rendering, ref forwarding, and public exports. It adds tests and updates Card and Popover stories and documentation to use Card.Root. A Changeset file is also added.

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

Possibly related PRs

clerk/javascript#9295: Updates Popover stories and documentation that use the Card surface.
clerk/javascript#9296: Migrates Mosaic surfaces to compound components and updates Popover examples.
clerk/javascript#9244: Applies a similar Mosaic StyleX migration pattern.

Suggested reviewers: alexcarpenter, maxyinger

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: migrating the Mosaic Card implementation to StyleX.
Description check	✅ Passed	The description directly explains the StyleX migration, compound Card API, visual updates, and new elevation options.
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.

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

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.changeset/mosaic-card-stylex.md (1)
1-3: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Add release metadata for the Card API change.

This changeset has no package entry, version bump, or release note. The PR changes the published @clerk/ui Card API to the compound Card.Root structure and adds elevation options. Add the affected package with the appropriate semver bump and a migration note. If the direct Card API is removed, document the breaking migration explicitly.

As per coding guidelines, use Changesets for managing releases. Based on learnings, empty changesets are acceptable only for documentation-only or non-published changes; this PR changes a published UI API.
🤖 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 @.changeset/mosaic-card-stylex.md around lines 1 - 3, Populate the changeset
with the affected `@clerk/ui` package, using a major semver bump for the breaking
Card API migration, and add a release note describing the move to Card.Root and
new elevation options. Explicitly document how consumers should migrate from the
direct Card API if it was removed.
Sources: Coding guidelines, Learnings

🤖 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.

Outside diff comments:
In @.changeset/mosaic-card-stylex.md:
- Around line 1-3: Populate the changeset with the affected `@clerk/ui` package,
using a major semver bump for the breaking Card API migration, and add a release
note describing the move to Card.Root and new elevation options. Explicitly
document how consumers should migrate from the direct Card API if it was
removed.

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 5e7f328d-d2fb-451d-9eea-bd677d5f1162

📥 Commits

Reviewing files that changed from the base of the PR and between 38f347c and 60221b8.

📒 Files selected for processing (11)

.changeset/mosaic-card-stylex.md
packages/swingset/src/stories/card.component.mdx
packages/swingset/src/stories/card.component.stories.tsx
packages/swingset/src/stories/popover.component.mdx
packages/swingset/src/stories/popover.component.stories.tsx
packages/ui/src/mosaic/components/card.tsx
packages/ui/src/mosaic/components/card/card.styles.ts
packages/ui/src/mosaic/components/card/card.test.tsx
packages/ui/src/mosaic/components/card/card.tsx
packages/ui/src/mosaic/components/card/index.ts
packages/ui/src/mosaic/styles/index.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/clerk-android (auto-detected)
clerk/cli (auto-detected)

💤 Files with no reviewable changes (1)

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

maxyinger

What do we want to do with darkmode here? my gut says to move all shadows to just a 1px spread white shadow so users are not dealing with dark shadows on potentially black bgs.

Only thing is we want to explicitly move away from the 1px spread shadows acting as outer borders right?

idk. any thoughts?

maxyinger · 2026-07-31T17:10:26Z

+  overlay: {
+    borderRadius: radiusVars['--cl-radius-container'],
+    overflow: 'hidden',
+    backgroundColor: colorVars['--cl-color-card'],
+    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
+                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
+                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
+  },


this a placeholder for now? or a backwards compatibility thing? (noticing it mirrors raised)

So in the Figma, these currently mirror each other. I'd assume these eventually would differ?

cool cool. yea I'm guessing so too 🤷 . so basically just a placeholder for now I guess while a shadowing system is still tbd

I think we want to move away from that 0 0 0 1px oklch(0.2046 0 0 / 4%) shadow tho.. maybe worth syncing up with @stvhayes here

austincalvelage · 2026-07-31T18:49:50Z

What do we want to do with darkmode here? my gut says to move all shadows to just a 1px spread white shadow so users are not dealing with dark shadows on potentially black bgs.

Only thing is we want to explicitly move away from the 1px spread shadows acting as outer borders right?

idk. any thoughts?

What do we want to do with darkmode here? my gut says to move all shadows to just a 1px spread white shadow so users are not dealing with dark shadows on potentially black bgs.

Yeah that's fair I removed the shadows on dark mode and just kept the ring.

Only thing is we want to explicitly move away from the 1px spread shadows acting as outer borders right?

Do we have the shadows figured out yet? Yesterday Alex mentioned just build to the Figma spec as shadows weren't set in stone yet. (Totally down to switch to borders If we are ready for that)

austincalvelage force-pushed the austin/mosaic-card-component branch from db7ac81 to 686e72d Compare July 30, 2026 20:28

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

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

vercel Bot deployed to Preview – swingset July 30, 2026 20:31 View deployment

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

vercel Bot deployed to Preview – swingset July 30, 2026 21:11 View deployment

austincalvelage added 2 commits July 30, 2026 15:11

refactor(ui): migrate Mosaic Card to StyleX

ab560c8

feat(ui): align Mosaic Card with updated design

4ff280b

austincalvelage force-pushed the austin/mosaic-card-component branch from bbe7602 to 4ff280b Compare July 30, 2026 21:12

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

vercel Bot deployed to Preview – swingset July 30, 2026 21:15 View deployment

austincalvelage added 3 commits July 30, 2026 19:37

refactor(ui): align Card compound API

a45fc86

feat(ui): add Card elevation variants

3e5d932

docs(ui): expose Card elevation controls

c53b67c

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 02:38 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 02:40 View deployment

feat(ui): align Card elevation variants

39a52e8

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 04:17 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 04:19 View deployment

Merge branch 'main' into austin/mosaic-card-component

7575e06

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 04:53 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 04:55 View deployment

refactor(ui): separate Card elevation styles

acd3bdd

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

Merge branch 'main' into austin/mosaic-card-component

bcec0e5

vercel Bot temporarily deployed to Preview – clerk-js-sandbox July 31, 2026 15:48 Inactive

vercel Bot had a problem deploying to Preview – swingset July 31, 2026 15:51 Failure

austincalvelage added 2 commits July 31, 2026 10:03

refactor(ui): align Card with Mosaic component props

6bdcfda

docs(swingset): use Card compound API in Popover examples

60221b8

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 16:04 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 16:06 View deployment

austincalvelage marked this pull request as ready for review July 31, 2026 16:10

austincalvelage requested review from alexcarpenter and maxyinger and removed request for alexcarpenter July 31, 2026 16:10

coderabbitai Bot reviewed Jul 31, 2026

View reviewed changes

maxyinger reviewed Jul 31, 2026

View reviewed changes

refactor: Move ‘rest’ spread after ‘mergeStyleProps’

bc43056

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 18:04 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 18:06 View deployment

austincalvelage added 2 commits July 31, 2026 12:15

refactor(ui): align Card elevation names with Figma

1248e1f

fix(ui): inherit Card footer background

3546d65

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

vercel Bot deployed to Preview – swingset July 31, 2026 18:30 View deployment

fix(ui): adapt Card shadows for dark mode

f70d3bc

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 18:48 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 18:49 View deployment

Uh oh!

Conversation

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

Uh oh!

Description

Checklist

Type of change

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Jul 31, 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 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

maxyinger left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

austincalvelage Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

maxyinger Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

maxyinger Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

austincalvelage commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

austincalvelage commented Jul 30, 2026 •

edited

Loading

vercel Bot commented Jul 30, 2026 •

edited

Loading

changeset-bot Bot commented Jul 30, 2026 •

edited

Loading

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

edited

Loading

github-actions Bot commented Jul 31, 2026 •

edited

Loading

coderabbitai Bot commented Jul 31, 2026 •

edited

Loading

maxyinger Jul 31, 2026 •

edited

Loading