feat(clerk-js): Update color logic utils to support CSS variable usage

.changeset/chubby-parts-try.md

@@ -0,0 +1,9 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Add modern CSS color manipulation utilities with progressive enhancement support. This update introduces:
+
+- CSS variable support in `appearance.variables` object (e.g., `colorPrimary: 'var(--brand-color)'`)
+- Modern CSS features like `color-mix()` and relative color syntax when supported by browser
+- Automatic fallback to legacy HSLA-based color manipulation for older browsers

packages/clerk-js/bundlewatch.config.json

@@ -5,7 +5,7 @@
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "115KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "55KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "111.8KB" },
-    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "112.1KB" },
+    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "113.67KB" },
     { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
     { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },
@@ -23,7 +23,7 @@
     { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
     { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
     { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
-    { "path": "./dist/checkout*.js", "maxSize": "8.34KB" },
+    { "path": "./dist/checkout*.js", "maxSize": "8.4KB" },
     { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/src/ui/components/OrganizationSwitcher/OrganizationSwitcherTrigger.tsx

@@ -113,8 +113,8 @@ const NotificationCountBadgeSwitcherTrigger = () => {
     <NotificationCountBadge
       containerSx={t => ({
         position: 'absolute',
-        top: `-${t.space.$2}`,
-        right: `-${t.space.$2}`,
+        top: `calc(${t.space.$2} * -1)`,
+        right: `calc(${t.space.$2} * -1)`,
       })}
       notificationCount={notificationCount}
     />

packages/clerk-js/src/ui/components/PaymentSources/AddPaymentSource.tsx

@@ -13,37 +13,40 @@ import { useCardState } from '@/ui/elements/contexts';
 import { Form } from '@/ui/elements/Form';
 import { FormButtons } from '@/ui/elements/FormButtons';
 import { FormContainer } from '@/ui/elements/FormContainer';
+import { resolveComputedCSSColor, resolveComputedCSSProperty } from '@/ui/utils/cssVariables';
 import { handleError } from '@/ui/utils/errorHandler';
-import { normalizeColorString } from '@/ui/utils/normalizeColorString';
 
 import { useSubscriberTypeContext, useSubscriberTypeLocalizationRoot } from '../../contexts';
 import { descriptors, Flex, localizationKeys, Spinner, useAppearance, useLocalizations } from '../../customizables';
 import type { LocalizationKey } from '../../localization';
 
-const useStripeAppearance = () => {
+const useStripeAppearance = (node: HTMLElement | null) => {
   const theme = useAppearance().parsedInternalTheme;
 
   return useMemo(() => {
+    if (!node) {
+      return undefined;
+    }
     const { colors, fontWeights, fontSizes, radii, space } = theme;
     return {
-      colorPrimary: normalizeColorString(colors.$primary500),
-      colorBackground: normalizeColorString(colors.$colorInputBackground),
-      colorText: normalizeColorString(colors.$colorText),
-      colorTextSecondary: normalizeColorString(colors.$colorTextSecondary),
-      colorSuccess: normalizeColorString(colors.$success500),
-      colorDanger: normalizeColorString(colors.$danger500),
-      colorWarning: normalizeColorString(colors.$warning500),
-      fontWeightNormal: fontWeights.$normal.toString(),
-      fontWeightMedium: fontWeights.$medium.toString(),
-      fontWeightBold: fontWeights.$bold.toString(),
-      fontSizeXl: fontSizes.$xl,
-      fontSizeLg: fontSizes.$lg,
-      fontSizeSm: fontSizes.$md,
-      fontSizeXs: fontSizes.$sm,
-      borderRadius: radii.$md,
-      spacingUnit: space.$1,
+      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),
+      colorSuccess: resolveComputedCSSColor(node, colors.$success500, colors.$colorBackground),
+      colorDanger: resolveComputedCSSColor(node, colors.$danger500, colors.$colorBackground),
+      colorWarning: resolveComputedCSSColor(node, colors.$warning500, colors.$colorBackground),
+      fontWeightNormal: resolveComputedCSSProperty(node, 'font-weight', fontWeights.$normal.toString()),
+      fontWeightMedium: resolveComputedCSSProperty(node, 'font-weight', fontWeights.$medium.toString()),
+      fontWeightBold: resolveComputedCSSProperty(node, 'font-weight', fontWeights.$bold.toString()),
+      fontSizeXl: resolveComputedCSSProperty(node, 'font-size', fontSizes.$xl),
+      fontSizeLg: resolveComputedCSSProperty(node, 'font-size', fontSizes.$lg),
+      fontSizeSm: resolveComputedCSSProperty(node, 'font-size', fontSizes.$md),
+      fontSizeXs: resolveComputedCSSProperty(node, 'font-size', fontSizes.$sm),
+      borderRadius: resolveComputedCSSProperty(node, 'border-radius', radii.$lg),
+      spacingUnit: resolveComputedCSSProperty(node, 'padding', space.$1),
     };
-  }, [theme]);
+  }, [theme, node]);
 };
 
 type AddPaymentSourceProps = {
@@ -66,11 +69,12 @@ const [AddPaymentSourceContext, useAddPaymentSourceContext] = createContextAndHo
 
 const AddPaymentSourceRoot = ({ children, checkout, ...rest }: PropsWithChildren<AddPaymentSourceProps>) => {
   const subscriberType = useSubscriberTypeContext();
+  const stripeAppearanceNode = useRef<HTMLDivElement | null>(null);
   const { t } = useLocalizations();
   const [headerTitle, setHeaderTitle] = useState<LocalizationKey | undefined>(undefined);
   const [headerSubtitle, setHeaderSubtitle] = useState<LocalizationKey | undefined>(undefined);
   const [submitLabel, setSubmitLabel] = useState<LocalizationKey | undefined>(undefined);
-  const stripeAppearance = useStripeAppearance();
+  const stripeAppearance = useStripeAppearance(stripeAppearanceNode.current);
 
   return (
     <AddPaymentSourceContext.Provider
@@ -87,6 +91,10 @@ const AddPaymentSourceRoot = ({ children, checkout, ...rest }: PropsWithChildren
         },
       }}
     >
+      <div
+        ref={stripeAppearanceNode}
+        style={{ display: 'none' }}
+      />
       <PaymentElementProvider
         checkout={checkout}
         for={subscriberType}

packages/clerk-js/src/ui/customizables/__tests__/parseVariables.spec.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mock cssSupports
+vi.mock('../../utils/cssSupports', () => ({
+  cssSupports: {
+    modernColor: vi.fn(),
+  },
+}));
+
+import { cssSupports } from '@/ui/utils/cssSupports';
+
+import { removeInvalidValues } from '../parseVariables';
+
+const mockModernColorSupport = vi.mocked(cssSupports.modernColor);
+
+describe('removeInvalidValues', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockModernColorSupport.mockReturnValue(false);
+  });
+
+  it('should return the variables as-is if modern color support is present', () => {
+    mockModernColorSupport.mockReturnValue(true);
+    const variables = {
+      colorPrimary: 'var(--color-primary)',
+    };
+
+    const result = removeInvalidValues(variables);
+    expect(result).toEqual({ colorPrimary: 'var(--color-primary)' });
+  });
+
+  it('should remove invalid string values if modern color support is not present', () => {
+    mockModernColorSupport.mockReturnValue(false);
+    const variables = {
+      colorPrimary: 'var(--color-primary)',
+      colorDanger: '#ff0000',
+    };
+
+    const result = removeInvalidValues(variables);
+    expect(result).toEqual({ colorDanger: '#ff0000' });
+  });
+
+  it('should remove invalid object values if modern color support is not present', () => {
+    mockModernColorSupport.mockReturnValue(false);
+    const variables = {
+      colorPrimary: {
+        400: 'var(--color-primary-500)',
+        500: '#fff',
+      },
+      colorDanger: {
+        500: '#ff0000',
+      },
+    };
+
+    const result = removeInvalidValues(variables);
+    expect(result).toEqual({ colorDanger: { 500: '#ff0000' } });
+  });
+});

packages/clerk-js/src/ui/customizables/parseVariables.ts

@@ -2,46 +2,89 @@ import type { Theme } from '@clerk/types';
 
 import { spaceScaleKeys } from '../foundations/sizes';
 import type { fontSizes, fontWeights } from '../foundations/typography';
-import { colorOptionToHslaAlphaScale, colorOptionToHslaLightnessScale } from '../utils/colorOptionToHslaScale';
 import { colors } from '../utils/colors';
+import { colorOptionToThemedAlphaScale, colorOptionToThemedLightnessScale } from '../utils/colors/scales';
+import { cssSupports } from '../utils/cssSupports';
 import { fromEntries } from '../utils/fromEntries';
 import { removeUndefinedProps } from '../utils/removeUndefinedProps';
 
 export const createColorScales = (theme: Theme) => {
-  const variables = theme.variables || {};
+  const variables = removeInvalidValues(theme.variables || {});
 
-  const primaryScale = colorOptionToHslaLightnessScale(variables.colorPrimary, 'primary');
-  const primaryAlphaScale = colorOptionToHslaAlphaScale(primaryScale?.primary500, 'primaryAlpha');
-  const dangerScale = colorOptionToHslaLightnessScale(variables.colorDanger, 'danger');
-  const dangerAlphaScale = colorOptionToHslaAlphaScale(dangerScale?.danger500, 'dangerAlpha');
-  const successScale = colorOptionToHslaLightnessScale(variables.colorSuccess, 'success');
-  const successAlphaScale = colorOptionToHslaAlphaScale(successScale?.success500, 'successAlpha');
-  const warningScale = colorOptionToHslaLightnessScale(variables.colorWarning, 'warning');
-  const warningAlphaScale = colorOptionToHslaAlphaScale(warningScale?.warning500, 'warningAlpha');
+  const dangerScale = colorOptionToThemedLightnessScale(variables.colorDanger, 'danger');
+  const primaryScale = colorOptionToThemedLightnessScale(variables.colorPrimary, 'primary');
+  const successScale = colorOptionToThemedLightnessScale(variables.colorSuccess, 'success');
+  const warningScale = colorOptionToThemedLightnessScale(variables.colorWarning, 'warning');
+
+  const dangerAlphaScale = colorOptionToThemedAlphaScale(dangerScale?.danger500, 'dangerAlpha');
+  const neutralAlphaScale = colorOptionToThemedAlphaScale(variables.colorNeutral, 'neutralAlpha');
+  const primaryAlphaScale = colorOptionToThemedAlphaScale(primaryScale?.primary500, 'primaryAlpha');
+  const successAlphaScale = colorOptionToThemedAlphaScale(successScale?.success500, 'successAlpha');
+  const warningAlphaScale = colorOptionToThemedAlphaScale(warningScale?.warning500, 'warningAlpha');
 
   return removeUndefinedProps({
-    ...primaryScale,
-    ...primaryAlphaScale,
     ...dangerScale,
-    ...dangerAlphaScale,
+    ...primaryScale,
     ...successScale,
-    ...successAlphaScale,
     ...warningScale,
+    ...dangerAlphaScale,
+    ...neutralAlphaScale,
+    ...primaryAlphaScale,
+    ...successAlphaScale,
     ...warningAlphaScale,
-    ...colorOptionToHslaAlphaScale(variables.colorNeutral, 'neutralAlpha'),
     primaryHover: colors.adjustForLightness(primaryScale?.primary500),
-    colorTextOnPrimaryBackground: toHSLA(variables.colorTextOnPrimaryBackground),
-    colorText: toHSLA(variables.colorText),
-    colorTextSecondary: toHSLA(variables.colorTextSecondary) || colors.makeTransparent(variables.colorText, 0.35),
-    colorInputText: toHSLA(variables.colorInputText),
-    colorBackground: toHSLA(variables.colorBackground),
-    colorInputBackground: toHSLA(variables.colorInputBackground),
-    colorShimmer: toHSLA(variables.colorShimmer),
+    colorTextOnPrimaryBackground: colors.toHslaString(variables.colorTextOnPrimaryBackground),
+    colorText: colors.toHslaString(variables.colorText),
+    colorTextSecondary:
+      colors.toHslaString(variables.colorTextSecondary) || colors.makeTransparent(variables.colorText, 0.35),
+    colorInputText: colors.toHslaString(variables.colorInputText),
+    colorBackground: colors.toHslaString(variables.colorBackground),
+    colorInputBackground: colors.toHslaString(variables.colorInputBackground),
+    colorShimmer: colors.toHslaString(variables.colorShimmer),
   });
 };
 
-export const toHSLA = (str: string | undefined) => {
-  return str ? colors.toHslaString(str) : undefined;
+export const removeInvalidValues = (variables: NonNullable<Theme['variables']>): NonNullable<Theme['variables']> => {
+  // Check for modern color support. If present, we can simply return the variables as-is since we support everything
+  // CSS supports.
+  if (cssSupports.modernColor()) {
+    return variables;
+  }
+
+  // If not, we need to remove any values that are specified with CSS variables, as our color scale generation only
+  // supports CSS variables using modern CSS functionality.
+  const validVariables: Theme['variables'] = Object.fromEntries(
+    Object.entries(variables).filter(([key, value]) => {
+      if (typeof value === 'string') {
+        const isValid = !value.startsWith('var(');
+        if (!isValid) {
+          console.warn(
+            `Invalid color value: ${value} for key: ${key}, using default value instead. Using CSS variables is not supported in this browser.`,
+          );
+        }
+        return isValid;
+      }
+
+      if (typeof value === 'object') {
+        return Object.entries(value).every(([key, value]) => {
+          if (typeof value !== 'string') return true;
+
+          const isValid = !value.startsWith('var(');
+          if (!isValid) {
+            console.warn(
+              `Invalid color value: ${value} for key: ${key}, using default value instead. Using CSS variables is not supported in this browser.`,
+            );
+          }
+
+          return isValid;
+        });
+      }
+
+      return false;
+    }),
+  );
+
+  return validVariables;
 };
 
 export const createRadiiUnits = (theme: Theme) => {
@@ -51,12 +94,11 @@ export const createRadiiUnits = (theme: Theme) => {
   }
 
   const md = borderRadius === 'none' ? '0' : borderRadius;
-  const { numericValue, unit = 'rem' } = splitCssUnit(md);
   return {
-    sm: (numericValue * 0.66).toString() + unit,
+    sm: `calc(${md} * 0.66)`,
     md,
-    lg: (numericValue * 1.33).toString() + unit,
-    xl: (numericValue * 2).toString() + unit,
+    lg: `calc(${md} * 1.33)`,
+    xl: `calc(${md} * 2)`,
   };
 };
 
@@ -65,12 +107,11 @@ export const createSpaceScale = (theme: Theme) => {
   if (spacingUnit === undefined) {
     return;
   }
-  const { numericValue, unit } = splitCssUnit(spacingUnit);
   return fromEntries(
     spaceScaleKeys.map(k => {
       const num = Number.parseFloat(k.replace('x', '.'));
       const percentage = (num / 0.5) * 0.125;
-      return [k, `${numericValue * percentage}${unit}`];
+      return [k, `calc(${spacingUnit} * ${percentage})`];
     }),
   );
 };
@@ -83,13 +124,12 @@ export const createFontSizeScale = (theme: Theme): Record<keyof typeof fontSizes
   if (fontSize === undefined) {
     return;
   }
-  const { numericValue, unit = 'rem' } = splitCssUnit(fontSize);
   return {
-    xs: (numericValue * 0.8).toString() + unit,
-    sm: (numericValue * 0.9).toString() + unit,
+    xs: `calc(${fontSize} * 0.8)`,
+    sm: `calc(${fontSize} * 0.9)`,
     md: fontSize,
-    lg: (numericValue * 1.3).toString() + unit,
-    xl: (numericValue * 1.85).toString() + unit,
+    lg: `calc(${fontSize} * 1.3)`,
+    xl: `calc(${fontSize} * 1.85)`,
   };
 };
 
@@ -102,9 +142,3 @@ export const createFonts = (theme: Theme) => {
   const { fontFamily, fontFamilyButtons } = theme.variables || {};
   return removeUndefinedProps({ main: fontFamily, buttons: fontFamilyButtons });
 };
-
-const splitCssUnit = (str: string) => {
-  const numericValue = Number.parseFloat(str);
-  const unit = str.replace(numericValue.toString(), '') || undefined;
-  return { numericValue, unit };
-};

packages/clerk-js/src/ui/elements/Card/CardFooter.tsx

@@ -49,7 +49,7 @@ export const CardFooter = React.forwardRef<HTMLDivElement, CardFooterProps>((pro
       elementDescriptor={descriptors.footer}
       sx={[
         t => ({
-          marginTop: `-${t.space.$2}`,
+          marginTop: `calc(${t.space.$2} * -1)`,
           paddingTop: t.space.$2,
           background: common.mergedColorsBackground(
             colors.setAlpha(t.colors.$colorBackground, 1),

packages/clerk-js/src/ui/elements/CodeControl.tsx

@@ -336,7 +336,7 @@ export const OTPCodeControl = React.forwardRef<{ reset: any }>((_, ref) => {
         hasError={feedbackType === 'error'}
         elementDescriptor={descriptors.otpCodeFieldInputs}
         gap={2}
-        sx={t => ({ direction: 'ltr', padding: t.space.$1, marginLeft: `-${t.space.$1}`, ...centerSx })}
+        sx={t => ({ direction: 'ltr', padding: t.space.$1, marginLeft: `calc(${t.space.$1} * -1)`, ...centerSx })}
         role='group'
         aria-label='Verification code input'
       >

packages/clerk-js/src/ui/elements/Navbar.tsx

@@ -159,7 +159,7 @@ const NavbarContainer = (
           t.colors.$neutralAlpha50,
         ),
         padding: `${t.space.$6} ${t.space.$5} ${t.space.$4} ${t.space.$3}`,
-        marginRight: `-${t.space.$2}`,
+        marginRight: `calc(${t.space.$2} * -1)`,
         color: t.colors.$colorText,
         justifyContent: 'space-between',
       })}
@@ -332,7 +332,7 @@ export const NavbarMenuButtonRow = ({ navbarTitleLocalizationKey, ...props }: Na
           t.colors.$neutralAlpha50,
         ),
         padding: `${t.space.$2} ${t.space.$3} ${t.space.$4} ${t.space.$3}`,
-        marginBottom: `-${t.space.$2}`,
+        marginBottom: `calc(${t.space.$2} * -1)`,
         [mqu.md]: {
           display: 'flex',
         },

packages/clerk-js/src/ui/elements/PopoverCard.tsx

@@ -85,7 +85,7 @@ const PopoverCardFooter = (props: PropsOfComponent<typeof Flex>) => {
             colors.setAlpha(t.colors.$colorBackground, 1),
             t.colors.$neutralAlpha50,
           ),
-          marginTop: `-${t.space.$2}`,
+          marginTop: `calc(${t.space.$2} * -1)`,
           paddingTop: t.space.$2,
           '&:empty': {
             padding: 0,