feat(clerk-js): Introduce Clerk CSS variables for theming

[alexcarpenter]

Description

This PR exposes the ability to theme Clerk components using CSS custom properties, avoiding the need to pass variables into the appearance variables prop.

All of the variables support an accompanying clerk prefixed CSS custom property. The CSS custom property is using kebab casing.

e.g. colorPrimary = --clerk-color-primary.

:root {
  --clerk-color-primary: #6D47FF;
  --clerk-color-muted-foreground: #999999;
}

The equivalent using the appearance prop would be:

<ClerkProvider
  appearance={{
    variables: {
      colorPrimary: '#6D47FF',
      colorMutedForeground: '#999999',
    }
  }}
/>

Deprecated variables

This PR also makes some updates to current variable names, with deprecation notices to migrate to the updated keys.

Deprecated	New
colorText	colorForeground
colorTextOnPrimaryBackground	colorPrimaryForeground
colorTextSecondary	colorMutedForeground
spacingUnit	spacing
colorInputText	colorInputForeground
colorInputBackground	colorInput

New variables

• colorRing - The color of the ring when an interactive element is focused.
• colorMuted - The background color for elements of lower importance, eg: a muted background.
• colorShadow - The color used as the base for all shadows.

Resolves USER-2202

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:

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9d7f66c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 11, 2025 7:24pm

[alexcarpenter]

!snapshot

[clerk-cookie]

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

Package	Version
@clerk/agent-toolkit	0.1.7-snapshot.v20250711170548
@clerk/astro	2.10.4-snapshot.v20250711170548
@clerk/backend	2.4.2-snapshot.v20250711170548
@clerk/chrome-extension	2.5.5-snapshot.v20250711170548
@clerk/clerk-js	5.71.1-snapshot.v20250711170548
@clerk/elements	0.23.39-snapshot.v20250711170548
@clerk/clerk-expo	2.14.4-snapshot.v20250711170548
@clerk/expo-passkeys	0.3.16-snapshot.v20250711170548
@clerk/express	1.7.6-snapshot.v20250711170548
@clerk/fastify	2.4.6-snapshot.v20250711170548
@clerk/localizations	3.18.1-snapshot.v20250711170548
@clerk/nextjs	6.24.1-snapshot.v20250711170548
@clerk/nuxt	1.7.7-snapshot.v20250711170548
@clerk/clerk-react	5.33.1-snapshot.v20250711170548
@clerk/react-router	1.7.1-snapshot.v20250711170548
@clerk/remix	4.9.1-snapshot.v20250711170548
@clerk/shared	3.11.1-snapshot.v20250711170548
@clerk/tanstack-react-start	0.19.1-snapshot.v20250711170548
@clerk/testing	1.10.0-snapshot.v20250711170548
@clerk/themes	2.2.56-snapshot.v20250711170548
@clerk/types	4.64.1-snapshot.v20250711170548
@clerk/vue	1.8.14-snapshot.v20250711170548

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/elements

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

@clerk/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/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

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/themes

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

@clerk/types

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

@clerk/vue

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