fix(ui): Improve structural CSS warning message format, warn for appearance usage on components

[brkalow]

Description

• Improve the warning message for structural CSS detection based on feedback.
• Trigger detection on appearance objects passed directly to components

BEFORE

🔒 Clerk:
[CLERK_W001] Structural CSS detected

Found: 
  -
  -

May break on updates. Pin your version:
  npm install @clerk/ui && import { ui } from '@clerk/ui'
  <ClerkProvider ui={ui} />

https://clerk.com/docs/customization/versioning
(This notice only appears in development)

AFTER

Clerk: Structural CSS detected that may break on updates.

Found:
  -
  -

These selectors depend on the internal DOM structure of Clerk's components, which may change when Clerk deploys component updates.
To prevent breaking changes, install @clerk/ui and pass it to ClerkProvider:

  import { ui } from '@clerk/ui'
  <ClerkProvider ui={ui}>

Learn more: https://clerk.com/docs/reference/components/versioning
(code=structural_css_pin_clerk_ui)

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

  • Components now emit a development-only warning when structural CSS customizations are detected without UI pinning.
  • Added a lightweight check that warns about component-level appearance patterns and presents them as organized bullet lists.

• Tests

  • Added tests covering development vs production, pinned vs unpinned UI, missing provider context, and the new warning formatting/behavior.

• Chores

  • Minor changelog entry added.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 9f7563c

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	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 21, 2026 5:04pm

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7628

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3dd0d17

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces a development-only structural CSS warning flow: adds hook useWarnAboutCustomizationWithoutPinning and calls it from the Appearance provider with appearance to run a deferred check. The hook reads Clerk and options contexts, defers work via requestIdleCallback (with a timeout fallback), skips in production or when contexts are absent, and cleans up on unmount. Adds warnAboutComponentAppearance(appearance, uiPinned) to format up to five detected element patterns as bullet points and emit a one-time warning. Tests cover hook and utility behavior.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: improving structural CSS warning message format and adding warnings for appearance usage on components, which are the core objectives of this PR.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

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

---

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