feat(ui): Add warning for structural CSS customization without version pinning

[brkalow]

Summary

• Adds a development-mode console warning when users customize Clerk components using structural CSS patterns that may rely on internal DOM structure
• Detects patterns in both appearance.elements (CSS-in-JS) and external stylesheets targeting .cl- classes
• Guides users to pin their @clerk/ui version to avoid breakages

Detection Criteria

Structural patterns that trigger the warning:

• Combinators (>, +, ~) with .cl- classes
• Descendant selectors with .cl- classes
• Positional pseudo-selectors (:nth-child, :first-child, etc.)
• :has() selector
• Multiple .cl- classes in a single selector
• Tag coupled with .cl- class (e.g., div.cl-button)

Safe patterns that do NOT trigger the warning:

• Simple .cl- class styling (e.g., .cl-button { color: red })
• Pseudo-classes like :hover, :focus
• Pseudo-elements like ::before, ::after
• String className values in appearance.elements

Performance Considerations

• Only runs in development mode
• Deferred via setTimeout to avoid blocking component mount
• Uses module-level hasChecked guard to prevent rescanning on remount
• Early returns when structural patterns found in appearance.elements (skips stylesheet scan)

Test plan

• Unit tests for detectStructuralClerkCss() - 16 tests
• Unit tests for warnAboutCustomizationWithoutPinning() - 18 tests
• TypeScript compiles cleanly
• Manual verification in dev mode with structural customization

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: bb6f356

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@clerk/shared	Patch
@clerk/ui	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

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 14, 2026 3:35am

[brkalow]

!snapshot

[clerk-cookie]

Hey @brkalow - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260114034743
@clerk/astro	3.0.0-snapshot.v20260114034743
@clerk/backend	3.0.0-snapshot.v20260114034743
@clerk/chrome-extension	3.0.0-snapshot.v20260114034743
@clerk/clerk-js	6.0.0-snapshot.v20260114034743
@clerk/dev-cli	1.0.0-snapshot.v20260114034743
@clerk/expo	3.0.0-snapshot.v20260114034743
@clerk/expo-passkeys	1.0.0-snapshot.v20260114034743
@clerk/express	2.0.0-snapshot.v20260114034743
@clerk/fastify	2.6.9-snapshot.v20260114034743
@clerk/localizations	4.0.0-snapshot.v20260114034743
@clerk/msw	0.0.1-snapshot.v20260114034743
@clerk/nextjs	7.0.0-snapshot.v20260114034743
@clerk/nuxt	2.0.0-snapshot.v20260114034743
@clerk/react	6.0.0-snapshot.v20260114034743
@clerk/react-router	3.0.0-snapshot.v20260114034743
@clerk/shared	4.0.0-snapshot.v20260114034743
@clerk/tanstack-react-start	1.0.0-snapshot.v20260114034743
@clerk/testing	2.0.0-snapshot.v20260114034743
@clerk/ui	1.0.0-snapshot.v20260114034743
@clerk/upgrade	2.0.0-snapshot.v20260114034743
@clerk/vue	2.0.0-snapshot.v20260114034743

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact