clerk · alexcarpenter · Jul 11, 2025 · Jul 10, 2025 · Jul 10, 2025 · Jul 10, 2025
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>

diff --git a/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx b/packages/clerk-js/src/ui/components/Checkout/CheckoutComplete.tsx
@@ -245,7 +245,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',
@@ -319,7 +319,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
@@ -383,7 +383,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/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,
                       })}
                     />

diff --git a/packages/clerk-js/src/ui/components/OAuthConsent/OAuthConsent.tsx b/packages/clerk-js/src/ui/components/OAuthConsent/OAuthConsent.tsx
@@ -152,7 +152,7 @@ export function OAuthConsentInternal() {
                       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,
@@ -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/shared.tsx b/packages/clerk-js/src/ui/components/OrganizationList/shared.tsx
@@ -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,
   },
 });
 

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
@@ -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
@@ -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,
                         },

diff --git a/packages/clerk-js/src/ui/components/OrganizationSwitcher/OrganizationSwitcherTrigger.tsx b/packages/clerk-js/src/ui/components/OrganizationSwitcher/OrganizationSwitcherTrigger.tsx
@@ -67,7 +67,7 @@ export const OrganizationSwitcherTrigger = withAvatarShimmer(
             gap={3}
             user={userWithoutIdentifiers}
             showAvatar={!hidePersonal}
-            sx={t => ({ color: t.colors.$colorTextSecondary })}
+            sx={t => ({ color: t.colors.$colorMutedForeground })}
             title={
               hidePersonal
                 ? localizationKeys('organizationSwitcher.notSelected')

diff --git a/packages/clerk-js/src/ui/components/OrganizationSwitcher/UserInvitationSuggestionList.tsx b/packages/clerk-js/src/ui/components/OrganizationSwitcher/UserInvitationSuggestionList.tsx
@@ -120,9 +120,9 @@ const Preview = (
         elementId='organizationSwitcherListedOrganization'
         organization={publicOrganizationData}
         sx={t => ({
-          color: t.colors.$colorTextSecondary,
+          color: t.colors.$colorMutedForeground,
           ':hover': {
-            color: t.colors.$colorTextSecondary,
+            color: t.colors.$colorMutedForeground,
           },
         })}
       />
@@ -186,9 +186,9 @@ const InvitationPreview = withCardStateProvider(
             elementId='organizationSwitcherListedOrganization'
             organization={publicOrganizationData}
             sx={t => ({
-              color: t.colors.$colorTextSecondary,
+              color: t.colors.$colorMutedForeground,
               ':hover': {
-                color: t.colors.$colorTextSecondary,
+                color: t.colors.$colorMutedForeground,
               },
             })}
           />

diff --git a/packages/clerk-js/src/ui/components/PaymentAttempts/PaymentAttemptPage.tsx b/packages/clerk-js/src/ui/components/PaymentAttempts/PaymentAttemptPage.tsx
@@ -102,7 +102,7 @@ export const PaymentAttemptPage = () => {
                   display: 'flex',
                   alignItems: 'center',
                   gap: t.space.$0x25,
-                  color: t.colors.$colorTextSecondary,
+                  color: t.colors.$colorMutedForeground,
                 })}
               >
                 <CopyButton

diff --git a/packages/clerk-js/src/ui/components/PaymentSources/AddPaymentSource.tsx b/packages/clerk-js/src/ui/components/PaymentSources/AddPaymentSource.tsx
@@ -30,9 +30,9 @@ const useStripeAppearance = (node: HTMLElement | null) => {
     const { colors, fontWeights, fontSizes, radii, space } = theme;
     return {
       colorPrimary: resolveComputedCSSColor(node, colors.$primary500, colors.$colorBackground),
-      colorBackground: resolveComputedCSSColor(node, colors.$colorInputBackground, colors.$colorBackground),
-      colorText: resolveComputedCSSColor(node, colors.$colorText, colors.$colorBackground),
-      colorTextSecondary: resolveComputedCSSColor(node, colors.$colorTextSecondary, colors.$colorBackground),
+      colorBackground: resolveComputedCSSColor(node, colors.$colorInput, colors.$colorBackground),
+      colorText: resolveComputedCSSColor(node, colors.$colorForeground, colors.$colorBackground),
+      colorTextSecondary: resolveComputedCSSColor(node, colors.$colorMutedForeground, colors.$colorBackground),
       colorSuccess: resolveComputedCSSColor(node, colors.$success500, colors.$colorBackground),
       colorDanger: resolveComputedCSSColor(node, colors.$danger500, colors.$colorBackground),
       colorWarning: resolveComputedCSSColor(node, colors.$warning500, colors.$colorBackground),

diff --git a/packages/clerk-js/src/ui/components/PaymentSources/PaymentSourceRow.tsx b/packages/clerk-js/src/ui/components/PaymentSources/PaymentSourceRow.tsx
@@ -17,14 +17,14 @@ export const PaymentSourceRow = ({ paymentSource }: { paymentSource: CommercePay
         elementDescriptor={descriptors.paymentSourceRowIcon}
       />
       <Text
-        sx={t => ({ color: t.colors.$colorText, textTransform: 'capitalize' })}
+        sx={t => ({ color: t.colors.$colorForeground, textTransform: 'capitalize' })}
         truncate
         elementDescriptor={descriptors.paymentSourceRowType}
       >
         {paymentSource.paymentMethod === 'card' ? paymentSource.cardType : paymentSource.paymentMethod}
       </Text>
       <Text
-        sx={t => ({ color: t.colors.$colorTextSecondary })}
+        sx={t => ({ color: t.colors.$colorMutedForeground })}
         variant='caption'
         truncate
         elementDescriptor={descriptors.paymentSourceRowValue}

diff --git a/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx b/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx
@@ -4,7 +4,6 @@ import * as React from 'react';
 
 import { Switch } from '@/ui/elements/Switch';
 import { Tooltip } from '@/ui/elements/Tooltip';
-import { colors } from '@/ui/utils/colors';
 import { getClosestProfileScrollBox } from '@/ui/utils/getClosestProfileScrollBox';
 
 import { useProtect } from '../../common';
@@ -168,10 +167,7 @@ function Card(props: CardProps) {
         gap: 0,
         gridTemplateRows: 'subgrid',
         gridRow: 'span 5',
-        background: common.mergedColorsBackground(
-          colors.setAlpha(t.colors.$colorBackground, 1),
-          t.colors.$neutralAlpha50,
-        ),
+        background: common.mutedBackground(t),
         borderWidth: t.borderWidths.$normal,
         borderStyle: t.borderStyles.$solid,
         borderColor: t.colors.$neutralAlpha100,

diff --git a/packages/clerk-js/src/ui/components/Statements/Statement.tsx b/packages/clerk-js/src/ui/components/Statements/Statement.tsx
@@ -54,7 +54,7 @@ function Header({ title, id, status }: { title: string | LocalizationKey; id: st
             display: 'flex',
             alignItems: 'center',
             gap: t.space.$0x25,
-            color: t.colors.$colorTextSecondary,
+            color: t.colors.$colorMutedForeground,
           })}
         >
           <CopyButton
@@ -329,7 +329,7 @@ function SectionContentDetailsListItem({
           display: 'flex',
           alignItems: 'center',
           gap: t.space.$0x25,
-          color: t.colors.$colorTextSecondary,
+          color: t.colors.$colorMutedForeground,
         })}
       >
         {typeof value === 'string' ? (

diff --git a/packages/clerk-js/src/ui/components/Subscriptions/SubscriptionsList.tsx b/packages/clerk-js/src/ui/components/Subscriptions/SubscriptionsList.tsx
@@ -158,7 +158,7 @@ export function SubscriptionsList({
                     {(subscription.plan.amount > 0 || subscription.plan.annualAmount > 0) && (
                       <Span
                         sx={t => ({
-                          color: t.colors.$colorTextSecondary,
+                          color: t.colors.$colorMutedForeground,
                           textTransform: 'lowercase',
                           ':before': {
                             content: '"/"',

diff --git a/packages/clerk-js/src/ui/components/UserButton/UserButtonTrigger.tsx b/packages/clerk-js/src/ui/components/UserButton/UserButtonTrigger.tsx
@@ -23,7 +23,7 @@ export const UserButtonTrigger = withAvatarShimmer(
       <Button
         elementDescriptor={descriptors.userButtonTrigger}
         variant='roundWrapper'
-        sx={[t => ({ borderRadius: showName ? t.radii.$md : t.radii.$circle, color: t.colors.$colorText }), sx]}
+        sx={[t => ({ borderRadius: showName ? t.radii.$md : t.radii.$circle, color: t.colors.$colorForeground }), sx]}
         ref={ref}
         aria-label={`${props.isOpen ? 'Close' : 'Open'} user button`}
         aria-expanded={props.isOpen}

diff --git a/packages/clerk-js/src/ui/components/UserProfile/AccountPage.tsx b/packages/clerk-js/src/ui/components/UserProfile/AccountPage.tsx
@@ -36,7 +36,7 @@ export const AccountPage = 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/packages/clerk-js/src/ui/components/UserProfile/BillingPage.tsx b/packages/clerk-js/src/ui/components/UserProfile/BillingPage.tsx
@@ -24,7 +24,7 @@ const BillingPageInternal = 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/packages/clerk-js/src/ui/components/UserProfile/ConnectedAccountsSection.tsx b/packages/clerk-js/src/ui/components/UserProfile/ConnectedAccountsSection.tsx
@@ -179,7 +179,7 @@ const ConnectedAccount = ({ account }: { account: ExternalAccountResource }) =>
               gap={1}
               center
             >
-              <Text sx={t => ({ color: t.colors.$colorText })}>{`${
+              <Text sx={t => ({ color: t.colors.$colorForeground })}>{`${
                 providerToDisplayData[account.provider].name
               }`}</Text>
               <Text

diff --git a/packages/clerk-js/src/ui/components/UserProfile/EmailsSection.tsx b/packages/clerk-js/src/ui/components/UserProfile/EmailsSection.tsx
@@ -57,7 +57,7 @@ export const EmailsSection = ({ shouldAllowCreation = true }) => {
                 <ProfileSection.Item id='emailAddresses'>
                   <Flex sx={t => ({ overflow: 'hidden', gap: t.space.$1 })}>
                     <Text
-                      sx={t => ({ color: t.colors.$colorText })}
+                      sx={t => ({ color: t.colors.$colorForeground })}
                       truncate
                     >
                       {email.emailAddress}

diff --git a/packages/clerk-js/src/ui/components/UserProfile/PhoneSection.tsx b/packages/clerk-js/src/ui/components/UserProfile/PhoneSection.tsx
@@ -66,7 +66,7 @@ export const PhoneSection = ({ shouldAllowCreation = true }: { shouldAllowCreati
                       gap={2}
                       center
                     >
-                      <Text sx={t => ({ color: t.colors.$colorText })}>
+                      <Text sx={t => ({ color: t.colors.$colorForeground })}>
                         {stringToFormattedPhoneString(phone.phoneNumber)}
                       </Text>
                       {user?.primaryPhoneNumberId === phoneId && (