docs(repo): add headless primitives reference to mosaic skill

[alexcarpenter]

Description

Adds a reference doc for working with the @clerk/headless package components, within the mosaic skill, and fixes stale docs.

What's here

• New references/headless.md in the mosaic skill — a how-to for the shared headless conventions (the per-primitive API docs stay in each src/primitives/<name>/README.md, which this points to):
  • Consuming a primitive (namespace compound components, render function-or-element override, data-* styling, makeCustomizable from @clerk/ui).
  • Authoring a part: the useRender contract + param table, universal rules ('use client', forwardRef, ownProps satisfies DefaultProps<Tag>, mergeProps(internal, consumer) ordering), stateAttributesMapping.
  • Primitive file layout, Portal root+mounted convention, the data-* animation lifecycle, shared hooks (useControllableState, useTransition, …) and utils (cssVars, resetLayoutStyles).
• Routing row added to the mosaic SKILL.md table.
• Fixes stale renderElement references in packages/headless/README.md (renderElement was removed in feat(headless): remove renderElement, consolidate into useRender #9233 and consolidated into useRender; the dist-path in the TS2742 note is now use-render).

Changeset

Empty — docs/tooling only, and the README change is in the private @clerk/headless package. No user-facing published change.

[changeset-bot]

🦋 Changeset detected

Latest commit: a7512c0

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	Jul 24, 2026 4:04pm
swingset	Ready	Preview, Comment	Jul 24, 2026 4:04pm

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: a7512c0

[coderabbitai]

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: 71fa2f8e-cf14-4577-b2e5-4d732153a864

📥 Commits

Reviewing files that changed from the base of the PR and between 478d3dd and a7512c0.

📒 Files selected for processing (2)

• .claude/skills/mosaic/references/headless.md
• packages/headless/README.md

🔗 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/cli (auto-detected)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)

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

• .claude/skills/mosaic/references/headless.md

---

📝 Walkthrough

Walkthrough

Adds Mosaic documentation for @clerk/headless, covering primitive composition, useRender, state attributes, component structure, portals, animations, shared APIs, and testing. Links the reference from the Mosaic skill guide, adds a changeset, and updates the package README from renderElement to useRender.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a headless primitives reference to the Mosaic skill.
Description check	✅ Passed	The description is directly related to the changeset and accurately describes the new docs and stale reference updates.
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]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In @.claude/skills/mosaic/references/headless.md:
- Around line 52-62: Align the documentation’s useRender contract across both
sites: in .claude/skills/mosaic/references/headless.md, scope native props and
render behavior to each element-rendering part and state that pass-through parts
such as Root and Portal have their own APIs; in packages/headless/README.md,
change the useRender description to say that every part rendering a DOM element
calls the hook.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

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

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 29d85d06-ed0a-4ad5-9894-bafa2fa0a1b3

📥 Commits

Reviewing files that changed from the base of the PR and between 1f8d89f and 478d3dd.

📒 Files selected for processing (4)

• .changeset/mosaic-headless-reference-doc.md
• .claude/skills/mosaic/SKILL.md
• .claude/skills/mosaic/references/headless.md
• packages/headless/README.md

🔗 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/cli (auto-detected)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)