clerk · alexcarpenter · Jul 15, 2025 · Jul 9, 2025 · Jul 9, 2025 · Jul 9, 2025
diff --git a/.changeset/cuddly-heads-battle.md b/.changeset/cuddly-heads-battle.md
@@ -0,0 +1,37 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/themes': minor
+'@clerk/types': minor
+---
+
+Expose Clerk CSS variables as an option for theming Clerk's components. This change introduces CSS custom properties that allow developers to customize Clerk's appearance using standard CSS variables, providing a more flexible theming approach.
+
+
+```css
+:root {
+  --clerk-color-primary: #6D47FF;
+  --clerk-color-primary-foreground: #FFFFFF;
+}
+```
+
+## Deprecated variables
+
+
+| Deprecated | New |
+|--------|--------|
+| `colorText` | `colorForeground` |
+| `colorTextOnPrimaryBackground` | `colorPrimaryForeground` |
+| `colorTextSecondary` | `colorMutedForeground` |
+| `spacingUnit` | `spacing` |
+| `colorInputText` | `colorInputForeground` |
+| `colorInputBackground` | `colorInput` |
+
+Deprecated variables will continue to work but will be removed in the next major version.
+
+## 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 base shadow color used in the components.
+- `colorBorder` - The base border color used in the components.
+- `colorModalBackdrop` - The background color of the modal backdrop.
diff --git a/packages/clerk-js/bundlewatch.config.json b/packages/clerk-js/bundlewatch.config.json
@@ -1,11 +1,11 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "616kB" },
+    { "path": "./dist/clerk.js", "maxSize": "616.27KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "72.2KB" },
-    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115KB" },
+    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115.08KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "111KB" },
-    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "115KB" },
+    { "path": "./dist/ui-common*.js", "maxSize": "111.52KB" },
+    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "115.33KB" },
     { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
     { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

diff --git a/packages/clerk-js/sandbox/app.ts b/packages/clerk-js/sandbox/app.ts
@@ -156,16 +156,17 @@ function appearanceVariableOptions() {
     'colorPrimary',
     'colorNeutral',
     'colorBackground',
-    'colorTextOnPrimaryBackground',
+    'colorPrimaryForeground',
+    'colorForeground',
     'colorDanger',
     'colorSuccess',
     'colorWarning',
-    'colorText',
-    'colorTextSecondary',
-    'colorInputText',
-    'colorInputBackground',
+    'colorForeground',
+    'colorMutedForeground',
+    'colorInputForeground',
+    'colorInput',
     'colorShimmer',
-    'spacingUnit',
+    'spacing',
     'borderRadius',
   ] as const;
 

diff --git a/packages/clerk-js/sandbox/template.html b/packages/clerk-js/sandbox/template.html
@@ -216,11 +216,11 @@
           />
         </label>
         <label class="flex items-center justify-between border-t border-gray-100 py-2">
-          <span class="font-mono text-xs">colorTextOnPrimaryBackground</span>
+          <span class="font-mono text-xs">colorPrimaryForeground</span>
           <input
             class="border border-gray-200"
             type="color"
-            id="colorTextOnPrimaryBackground"
+            id="colorPrimaryForeground"
             value="#ffffff"
           />
         </label>
@@ -252,38 +252,38 @@
           />
         </label>
         <label class="flex items-center justify-between border-t border-gray-100 py-2">
-          <span class="font-mono text-xs">colorText</span>
+          <span class="font-mono text-xs">colorForeground</span>
           <input
             class="border border-gray-200"
             type="color"
-            id="colorText"
+            id="colorForeground"
             value="#212126"
           />
         </label>
         <label class="flex items-center justify-between border-t border-gray-100 py-2">
-          <span class="font-mono text-xs">colorTextSecondary</span>
+          <span class="font-mono text-xs">colorMutedForeground</span>
           <input
             class="border border-gray-200"
             type="color"
-            id="colorTextSecondary"
+            id="colorMutedForeground"
             value="#747686"
           />
         </label>
         <label class="flex items-center justify-between border-t border-gray-100 py-2">
-          <span class="font-mono text-xs">colorInputText</span>
+          <span class="font-mono text-xs">colorInputForeground</span>
           <input
             class="border border-gray-200"
             type="color"
-            id="colorInputText"
+            id="colorInputForeground"
             value="#000000"
           />
         </label>
         <label class="flex items-center justify-between border-t border-gray-100 py-2">
-          <span class="font-mono text-xs">colorInputBackground</span>
+          <span class="font-mono text-xs">colorInput</span>
           <input
             class="border border-gray-200"
             type="color"
-            id="colorInputBackground"
+            id="colorInput"
             value="#ffffff"
           />
         </label>
@@ -297,10 +297,10 @@
           />
         </label>
         <label class="flex items-center justify-between border-t border-gray-100 py-2">
-          <span class="font-mono text-xs">spacingUnit</span>
+          <span class="font-mono text-xs">spacing</span>
           <input
             type="text"
-            id="spacingUnit"
+            id="spacing"
             value="1rem"
             class="text-sm outline-none [field-sizing:content]"
           />

diff --git a/packages/clerk-js/src/ui/common/ProviderInitialIcon.tsx b/packages/clerk-js/src/ui/common/ProviderInitialIcon.tsx
@@ -22,7 +22,7 @@ export const ProviderInitialIcon = (props: ProviderInitialIconProps) => {
         width: t.space.$4,
         height: t.space.$4,
         borderRadius: t.radii.$sm,
-        color: t.colors.$colorTextOnPrimaryBackground,
+        color: t.colors.$colorPrimaryForeground,
         backgroundColor: t.colors.$primary500,
       })}
       {...rest}

diff --git a/packages/clerk-js/src/ui/components/ApiKeys/ApiKeysTable.tsx b/packages/clerk-js/src/ui/components/ApiKeys/ApiKeysTable.tsx
@@ -99,7 +99,7 @@ const SecretInputWithToggle = ({ apiKeyID }: { apiKeyID: string }) => {
       >
         <Icon
           icon={revealed ? EyeSlash : Eye}
-          sx={t => ({ color: t.colors.$colorTextSecondary })}
+          sx={t => ({ color: t.colors.$colorMutedForeground })}
         />
       </Button>
     </Flex>

diff --git a/packages/clerk-js/src/ui/components/ApiKeys/CreateApiKeyForm.tsx b/packages/clerk-js/src/ui/components/ApiKeys/CreateApiKeyForm.tsx
@@ -110,7 +110,7 @@ const ExpirationSelector: React.FC<ExpirationSelectorProps> = ({ selectedExpirat
       <SelectOptionList
         sx={t => ({
           paddingBlock: t.space.$1,
-          color: t.colors.$colorText,
+          color: t.colors.$colorForeground,
         })}
       />
     </Select>
@@ -236,7 +236,7 @@ export const CreateApiKeyForm: React.FC<CreateApiKeyFormProps> = ({ onCreate, is
             sx={t => ({
               borderTopWidth: t.borderWidths.$normal,
               borderTopStyle: t.borderStyles.$solid,
-              borderTopColor: t.colors.$neutralAlpha100,
+              borderTopColor: t.colors.$borderAlpha100,
               paddingTop: t.space.$4,
               paddingBottom: t.space.$4,
             })}

diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
@@ -246,7 +246,7 @@ export const CheckoutComplete = () => {
               borderRadius: t.radii.$circle,
               backgroundImage: `linear-gradient(180deg, rgba(255, 255, 255, 0.30) 0%, rgba(0, 0, 0, 0.12) 50%, rgba(0, 0, 0, 0.30) 95.31%)`,
               boxShadow: '0px 4px 12px 0px rgba(0, 0, 0, 0.35), 0px 1px 0px 0px rgba(255, 255, 255, 0.05) inset',
-              color: canHover ? t.colors.$success500 : t.colors.$colorText,
+              color: canHover ? t.colors.$success500 : t.colors.$colorForeground,
               ':before': {
                 content: '""',
                 position: 'absolute',
@@ -320,7 +320,7 @@ export const CheckoutComplete = () => {
                 animationDuration: `${transitionDurationValues.slowest}ms`,
                 animationTimingFunction: transitionTiming.bezier,
                 animationFillMode: 'forwards',
-                color: t.colors.$colorText,
+                color: t.colors.$colorForeground,
                 '@keyframes slideUp': {
                   '0%': {
                     transform: 'translateY(30px)',

diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx
@@ -43,7 +43,7 @@ export const CheckoutForm = withCardStateProvider(() => {
           padding: t.space.$4,
           borderBottomWidth: t.borderWidths.$normal,
           borderBottomStyle: t.borderStyles.$solid,
-          borderBottomColor: t.colors.$neutralAlpha100,
+          borderBottomColor: t.colors.$borderAlpha100,
         })}
       >
         <LineItems.Root>
@@ -230,7 +230,7 @@ export const PayWithTestPaymentSource = () => {
         borderRadius: t.radii.$md,
         borderWidth: t.borderWidths.$normal,
         borderStyle: t.borderStyles.$solid,
-        borderColor: t.colors.$neutralAlpha100,
+        borderColor: t.colors.$borderAlpha100,
         display: 'flex',
         flexDirection: 'column',
         rowGap: t.space.$2,
@@ -375,7 +375,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
             <SelectOptionList
               sx={t => ({
                 paddingBlock: t.space.$1,
-                color: t.colors.$colorText,
+                color: t.colors.$colorForeground,
               })}
             />
           </Select>

diff --git a/packages/clerk-js/src/ui/components/Checkout/parts.tsx b/packages/clerk-js/src/ui/components/Checkout/parts.tsx
@@ -64,7 +64,7 @@ export const InvalidPlanScreen = () => {
             padding: t.space.$4,
             borderBottomWidth: t.borderWidths.$normal,
             borderBottomStyle: t.borderStyles.$solid,
-            borderBottomColor: t.colors.$neutralAlpha100,
+            borderBottomColor: t.colors.$borderAlpha100,
           })}
         >
           <LineItems.Root>

diff --git a/packages/clerk-js/src/ui/components/CreateOrganization/CreateOrganizationForm.tsx b/packages/clerk-js/src/ui/components/CreateOrganization/CreateOrganizationForm.tsx
@@ -162,7 +162,7 @@ export const CreateOrganizationForm = withCardStateProvider((props: CreateOrgani
                       size='md'
                       icon={Upload}
                       sx={t => ({
-                        color: t.colors.$colorTextSecondary,
+                        color: t.colors.$colorMutedForeground,
                         transitionDuration: t.transitionDuration.$controls,
                       })}
                     />
@@ -173,7 +173,7 @@ export const CreateOrganizationForm = withCardStateProvider((props: CreateOrgani
                     borderRadius: t.radii.$md,
                     borderWidth: t.borderWidths.$normal,
                     borderStyle: t.borderStyles.$dashed,
-                    borderColor: t.colors.$neutralAlpha200,
+                    borderColor: t.colors.$borderAlpha200,
                     backgroundColor: t.colors.$neutralAlpha50,
                     ':hover': {
                       backgroundColor: t.colors.$neutralAlpha50,

diff --git a/packages/clerk-js/src/ui/components/OAuthConsent/OAuthConsent.tsx b/packages/clerk-js/src/ui/components/OAuthConsent/OAuthConsent.tsx
@@ -113,7 +113,7 @@ export function OAuthConsentInternal() {
               textAlign: 'left',
               borderWidth: t.borderWidths.$normal,
               borderStyle: t.borderStyles.$solid,
-              borderColor: t.colors.$neutralAlpha100,
+              borderColor: t.colors.$borderAlpha100,
               borderRadius: t.radii.$lg,
               overflow: 'hidden',
             })}
@@ -146,13 +146,13 @@ export function OAuthConsentInternal() {
                     paddingBlock: t.space.$2,
                     borderTopWidth: t.borderWidths.$normal,
                     borderTopStyle: t.borderStyles.$solid,
-                    borderTopColor: t.colors.$neutralAlpha100,
+                    borderTopColor: t.colors.$borderAlpha100,
                     '&::before': {
                       content: '""',
                       display: 'inline-block',
                       width: t.space.$1,
                       height: t.space.$1,
-                      background: t.colors.$colorTextSecondary,
+                      background: t.colors.$colorMutedForeground,
                       borderRadius: t.radii.$circle,
                       transform: 'translateY(-0.1875rem)',
                       marginRight: t.space.$2,
@@ -340,7 +340,7 @@ function ConnectionIcon({ size = 'md', sx }: { size?: 'sm' | 'md'; sx?: Themable
           borderRadius: t.radii.$circle,
           borderWidth: t.borderWidths.$normal,
           borderStyle: t.borderStyles.$solid,
-          borderColor: t.colors.$neutralAlpha100,
+          borderColor: t.colors.$borderAlpha100,
           display: 'flex',
           alignItems: 'center',
           justifyContent: 'center',
@@ -369,7 +369,7 @@ function ConnectionSeparator() {
       height={2}
       aria-hidden
       sx={t => ({
-        color: t.colors.$colorTextSecondary,
+        color: t.colors.$colorMutedForeground,
       })}
     >
       <path

diff --git a/packages/clerk-js/src/ui/components/OrganizationList/OrganizationListPage.tsx b/packages/clerk-js/src/ui/components/OrganizationList/OrganizationListPage.tsx
@@ -64,7 +64,7 @@ const CreateOrganizationButton = ({
       sx={t => ({
         borderTopWidth: t.borderWidths.$normal,
         borderTopStyle: t.borderStyles.$solid,
-        borderTopColor: t.colors.$neutralAlpha100,
+        borderTopColor: t.colors.$borderAlpha100,
         padding: `${t.space.$5} ${t.space.$5}`,
       })}
       iconSx={t => ({

diff --git a/packages/clerk-js/src/ui/components/OrganizationList/shared.tsx b/packages/clerk-js/src/ui/components/OrganizationList/shared.tsx
@@ -19,7 +19,7 @@ export const PreviewListItems = (props: PropsWithChildren) => {
         overflowY: 'auto',
         borderTopWidth: t.borderWidths.$normal,
         borderTopStyle: t.borderStyles.$solid,
-        borderTopColor: t.colors.$neutralAlpha100,
+        borderTopColor: t.colors.$borderAlpha100,
         ...common.unstyledScrollbar(t),
       })}
     >
@@ -33,9 +33,9 @@ const sharedStyles: ThemableCssProp = t => ({
 });
 
 export const sharedMainIdentifierSx: ThemableCssProp = t => ({
-  color: t.colors.$colorText,
+  color: t.colors.$colorForeground,
   ':hover': {
-    color: t.colors.$colorText,
+    color: t.colors.$colorForeground,
   },
 });
 
@@ -54,7 +54,7 @@ export const PreviewListItem = (
           justifyContent: 'space-between',
           borderTopWidth: t.borderWidths.$normal,
           borderTopStyle: t.borderStyles.$solid,
-          borderTopColor: t.colors.$neutralAlpha100,
+          borderTopColor: t.colors.$borderAlpha100,
         }),
         sharedStyles,
       ]}

diff --git a/packages/clerk-js/src/ui/components/OrganizationProfile/MemberListTable.tsx b/packages/clerk-js/src/ui/components/OrganizationProfile/MemberListTable.tsx
@@ -193,7 +193,7 @@ export const RoleSelect = (props: {
         sx={
           triggerSx ||
           (t => ({
-            color: t.colors.$colorText,
+            color: t.colors.$colorForeground,
             backgroundColor: 'transparent',
             textWrap: 'nowrap',
           }))

diff --git a/packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationBillingPage.tsx b/packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationBillingPage.tsx
@@ -26,7 +26,7 @@ const OrganizationBillingPageInternal = withCardStateProvider(() => {
   return (
     <Col
       elementDescriptor={descriptors.page}
-      sx={t => ({ gap: t.space.$8, color: t.colors.$colorText })}
+      sx={t => ({ gap: t.space.$8, color: t.colors.$colorForeground })}
     >
       <Col
         elementDescriptor={descriptors.profilePage}

diff --git a/...ages/clerk-js/src/ui/components/OrganizationProfile/OrganizationMembersTabInvitations.tsx b/...ages/clerk-js/src/ui/components/OrganizationProfile/OrganizationMembersTabInvitations.tsx
@@ -38,7 +38,7 @@ export const OrganizationMembersTabInvitations = withCardStateProvider(() => {
               paddingRight: t.space.$1,
               borderBottomWidth: t.borderWidths.$normal,
               borderBottomStyle: t.borderStyles.$solid,
-              borderBottomColor: t.colors.$neutralAlpha100,
+              borderBottomColor: t.colors.$borderAlpha100,
               [mqu.md]: {
                 flexDirection: 'column',
                 gap: t.space.$2,
@@ -73,7 +73,7 @@ export const OrganizationMembersTabInvitations = withCardStateProvider(() => {
                       )}
                       sx={t => ({
                         paddingLeft: t.space.$10,
-                        color: t.colors.$colorTextSecondary,
+                        color: t.colors.$colorMutedForeground,
                         [mqu.md]: {
                           paddingLeft: 0,
                         },

diff --git a/packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationMembersTabRequests.tsx b/packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationMembersTabRequests.tsx
@@ -37,7 +37,7 @@ export const OrganizationMembersTabRequests = () => {
               paddingRight: t.space.$1,
               borderBottomWidth: t.borderWidths.$normal,
               borderBottomStyle: t.borderStyles.$solid,
-              borderBottomColor: t.colors.$neutralAlpha100,
+              borderBottomColor: t.colors.$borderAlpha100,
               [mqu.md]: {
                 flexDirection: 'column',
                 gap: t.space.$2,
@@ -72,7 +72,7 @@ export const OrganizationMembersTabRequests = () => {
                       )}
                       sx={t => ({
                         paddingLeft: t.space.$10,
-                        color: t.colors.$colorTextSecondary,
+                        color: t.colors.$colorMutedForeground,
                         [mqu.md]: {
                           paddingLeft: 0,
                         },