chore(repo): Add theming architecture reference

[alexcarpenter]

Description

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:

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 20, 2026 2:34pm

[changeset-bot]

🦋 Changeset detected

Latest commit: d35b15a

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

[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

Run ID: 27a19ba0-4be8-41a6-90c8-b4c3398e5142

📥 Commits

Reviewing files that changed from the base of the PR and between 6a58966 and 67c2802.

📒 Files selected for processing (1)

• .changeset/empty-oigyvq.md

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

• .changeset/empty-oigyvq.md

---

📝 Walkthrough

Walkthrough

Adds a new theming architecture reference at references/theming-architecture.md and updates AGENTS.md with a "## References" pointer to it. The documentation explains appearance configuration, the cascade and variable-resolution pipeline, provider flow (StyleCacheProvider/AppearanceProvider/InternalThemeProvider), the makeCustomizable merge and classname generation, element descriptor targeting and theme composition, optional cssLayerName behavior, a data-flow diagram, and a key-files reference. Also adds a small changeset file.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Possibly related PRs

• clerk/javascript#8566: Also modifies AGENTS.md; related because both touch the agent documentation and navigation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description contains only the standard contribution template without any actual details about the changes being made. It does not meaningfully describe the theming architecture reference being added.	Provide a brief description of what theming architecture reference was added, why it was needed, and how reviewers can verify the changes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'chore(repo): Add theming architecture reference' clearly and concisely describes the main change: adding documentation about theming architecture to the repository.
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.

_{✏️ 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@8596

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8596

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 6ace42d

[Ephem]

Nice, TIL! 🙏