feat(repo): Add mosaic migration skill by alexcarpenter · Pull Request #9106 · clerk/javascript

alexcarpenter · 2026-07-07T22:44:50Z

Description

Adds a new skill to help with mosaic component migrations to go from the current component to an abstracted controller/machine/view approach.

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

Summary by CodeRabbit

Documentation
- Added a new Mosaic migration guide with a phased workflow, parity audit steps, and shipping guidance.
- Expanded Mosaic reference materials with clearer layer contracts for machines, controllers, views, plus testing practices for each layer.
- Added end-to-end parity audit documentation with an example mapping workflow.
- Updated Mosaic architecture notes to clarify styling-only vs full flow migration.
- Added Mosaic styling guidance for slot recipes and updated the Skills catalog with Mosaic skill docs and references.

changeset-bot · 2026-07-07T22:44:57Z

🦋 Changeset detected

Latest commit: 36130eb

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-07T22:44:58Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 8, 2026 12:02am
swingset	Ready	Preview, Comment	Jul 8, 2026 12:02am

coderabbitai · 2026-07-07T22:46:21Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: cd57d9c9-66bd-475d-8e83-d5acd2175d48

📥 Commits

Reviewing files that changed from the base of the PR and between f1568ef and 36130eb.

📒 Files selected for processing (2)

.claude/skills/mosaic/SKILL.md
.claude/skills/mosaic/references/styling.md

✅ Files skipped from review due to trivial changes (1)

.claude/skills/mosaic/references/styling.md

📝 Walkthrough

Walkthrough

This PR adds the Mosaic Claude Code skill and related reference docs for styling, machine/controller/view contracts, isolated testing, migration, and parity auditing. It also updates the skills index, architecture reference, and adds a changeset.

Changes

Mosaic Skill Documentation

Layer / File(s)	Summary
Skill overview and cross-links `.claude/skills/mosaic/SKILL.md`, `.claude/skills/README.md`, `.claude/skills/mosaic/references/machines.md`, `references/mosaic-architecture.md`, `.changeset/mighty-jars-sell.md`	Adds the Mosaic skill entry, introduces the skill overview, updates the machine intro and reference links, adds the migration note, and creates a changeset.
Styling reference and slot recipes `.claude/skills/mosaic/references/styling.md`	Documents slot recipes, single-slot and multi-slot patterns, lighter abstractions, and the authoring checklist.
Machines, controllers, and views `.claude/skills/mosaic/references/controllers.md`, `.claude/skills/mosaic/references/views.md`	Defines controller responsibilities and the view snapshot/event contract, including Clerk boundaries and testing guidance.
Testing reference `.claude/skills/mosaic/references/testing.md`	Describes isolated machine, controller, and view testing patterns, shared utilities, and example flows.
Migration workflow and parity audit `.claude/skills/mosaic/references/migration.md`, `.claude/skills/mosaic/references/parity-audit.md`	Defines the five-phase migration workflow and the Phase 4 parity audit prompt, output format, grep list, and example.

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

Suggested reviewers: wobsoriano

Poem

A rabbit hops through docs so bright,
With slots and states and tests in sight.
Machines, controllers, views align,
Migration steps and parity shine. 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: adding a new Mosaic-related skill, including migration guidance.
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.}

pkg-pr-new · 2026-07-07T22:47:27Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 36130eb

Merge the mosaic-machine and mosaic-migration skills into one `mosaic` skill with per-layer references (machines, controllers, views), the migration playbook, and the parity-audit prompt. Update the skills README table and the mosaic-architecture migration pointer.

Add a three-layer testing reference (machine/controller/view) to the mosaic skill with real snippets from the delete-organization tests. Collapse the skill's machines.md into a pointer to the in-tree machine/README.md + ADOPTION.md so the machine runtime has a single source of truth. Add the testing row to the SKILL.md router and broaden the trigger to cover testing.

Add a styling how-to to the mosaic skill covering useRecipe with single-slot and multi-slot recipes, slot registration, the variant-vs-state distinction, compoundVariants/sx, and the useSlot/slot sugar, grounded in the real button and tabs components. Add the styling row to the SKILL.md router and broaden the trigger to cover styling.

kylemac · 2026-07-08T20:02:53Z

here's what a 1-shot did when asking it to use the skill to create the members list:

https://github.com/clerk/javascript/pull/9109/changes

feat(repo): Add mosaic migration skill

ace57e3

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

add changeset

af73d58

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

vercel Bot deployed to Preview – swingset July 7, 2026 22:47 View deployment

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

vercel Bot deployed to Preview – swingset July 7, 2026 22:55 View deployment

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

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

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

vercel Bot deployed to Preview – swingset July 8, 2026 00:02 View deployment

alexcarpenter requested a review from kylemac July 8, 2026 18:47

kylemac mentioned this pull request Jul 8, 2026

feat(ui): migrate organization profile members panel to mosaic #9109

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(repo): Add mosaic migration skill#9106

feat(repo): Add mosaic migration skill#9106
alexcarpenter wants to merge 5 commits into
mainfrom
carp/mosaic-skills

alexcarpenter commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

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

edited

Loading

Uh oh!

kylemac commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

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

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Walkthrough

Changes

Uh oh!

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

Uh oh!

Uh oh!

kylemac commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexcarpenter commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Jul 7, 2026 •

edited

Loading

vercel Bot commented Jul 7, 2026 •

edited

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

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

edited

Loading