feat(ui): Add mosaic design systems foundations

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}

[alexcarpenter]

Description

• Mosaic design system foundations: token-driven cva(), MosaicProvider with theme context, sx prop for one-off overrides
• Token primitives: color (oklch, light-dark), spacing (multiplier fn), radius scale, fontSize scale with paired line-heights (Tailwind v4 convention)
• Theme helpers: spacing(n), alpha(color, %), mix(a, b, %), text(size) — all return literal CSS values, spreadable into style objects
• Button reference component demonstrating variant composition via cva()

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Introduced the Mosaic design system: default tokens, theme resolver, provider + hook, theme helpers (spacing, alpha, mix, text) and a theme-aware variant utility (cva).
  • Added a Mosaic Button component with customizable variants for layout, typography, color, size, and states.

• Documentation

  • Added a comprehensive Mosaic architecture guide with token details, patterns, and migration guidance.

• Tests

  • Added an extensive test suite validating the variant utility and TypeScript typings.

• Chores

  • Added a changeset declaring the new Mosaic foundations.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb0dc28

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 9, 2026 1:53pm

[coderabbitai]

Linter diff in the way? Review this PR in Change Stack to focus on meaningful changes and expand context only when needed.

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 Mosaic design-system foundations: frozen token defaults and resolver, MosaicProvider with Emotion cache and optional CSS layer wrapping, a theme-aware cva utility with tests, a reference Button component, architecture documentation, and a release changeset.

Changes

Mosaic Design System Implementation

Layer / File(s)	Summary
Token types and theme resolution packages/ui/src/mosaic/variables.ts	Defines frozen default token values and TypeScript types (MosaicTokens, MosaicVariables, MosaicTheme) and implements resolveVariables() to deep-merge overrides and provide helper functions (spacing, alpha, mix, text).
Theme provider and context delivery packages/ui/src/mosaic/MosaicProvider.tsx	MosaicProvider resolves theme variables, creates an Emotion cache with optional insertion point and nonce, and conditionally wraps generated CSS in an @layer when cssLayerName is provided. Exports useMosaicTheme() to access the resolved theme from context.
CVA variant system implementation packages/ui/src/mosaic/cva.ts	Adds cva with static and theme-aware overloads, variant resolution (including boolean coercion), base/variant/compound application, optional sx merging, and CSS-variable key sanitization.
CVA variant system test coverage packages/ui/src/mosaic/__tests__/cva.test.ts	Vitest suite validating cva behavior across base styles, variants, defaultVariants, boolean and compound variants, deep merging (including pseudo-selectors), CSS variable sanitization, theme-aware configs, handling of unknown/null props, and TypeScript VariantProps inference.
Button component example packages/ui/src/mosaic/Button.tsx	Reference Button using buttonStyles from cva, reads theme via useMosaicTheme(), applies computed css, and forwards native button props and ref.
Mosaic architecture documentation references/mosaic-architecture.md	Documentation covering token model, resolveVariables, provider delivery via context, cva design and typing, component authoring pattern, coexistence rules with Emotion theming, and migration steps.
Documentation reference AGENTS.md	Adds a reference link to references/mosaic-architecture.md in the References section.
Release changeset .changeset/mosaic-design-system-foundations.md	Adds a minor-release changeset describing the Mosaic foundations and the new UI primitives.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• jacekradko

Poem

🐰 Mosaic hops in with tokens bright and keen,
cva stitches styles where variants convene,
Provider hums themes into context's nest,
Buttons wear tokens, tests ensure the rest,
A rabbit applauds the interface scene!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): Add mosaic design systems foundations' accurately and clearly summarizes the primary change: introducing the foundational pieces of a new Mosaic design system including tokens, provider, utilities, and a reference component.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: eb0dc28

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-09T13:58:49.434Z

Summary

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

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

• @clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
• @clerk/testing ./cypress: Symbol not found for identifier: Cypress

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on eb0dc28.}