feat(ui): Add light-dark theme support

.changeset/seven-grapes-lay.md

@@ -0,0 +1,27 @@
+---
+'@clerk/ui': major
+---
+
+Changes provider icon rendering from `<Image>` to `<Span>` elements to support customizable icon fills via CSS variables.
+
+Provider icons for Apple, GitHub, OKX Wallet, and Vercel now use CSS `mask-image` technique with a customizable `--cl-icon-fill` CSS variable, allowing themes to control icon colors. Other provider icons (like Google) continue to render as full-color images using `background-image`.
+
+You can customize the icon fill color in your theme:
+
+```tsx
+import { createTheme } from '@clerk/ui/themes';
+
+const myTheme = createTheme({
+  name: 'myTheme',
+  elements: {
+    providerIcon__apple: {
+      '--cl-icon-fill': '#000000', // Custom fill color
+    },
+    providerIcon__github: {
+      '--cl-icon-fill': 'light-dark(#000000, #ffffff)', // Theme-aware fill
+    },
+  },
+});
+```
+
+This change enables better theme customization for monochrome provider icons while maintaining full-color support for providers that require it.

.changeset/slimy-vans-listen.md

@@ -0,0 +1,44 @@
+---
+'@clerk/ui': minor
+---
+
+Adds new `lightDark` theme.
+
+This theme uses the `light-dark()` CSS function to automatically adapt colors based on the user's system color scheme preference, eliminating the need to manually switch between light and dark themes.
+
+To enable it, within your project, you can do the following:
+
+```tsx
+import { lightDark } from '@clerk/ui/themes';
+import { ClerkProvider } from '@clerk/nextjs';
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <ClerkProvider appearance={{ theme: lightDark }}>
+      <Component {...pageProps} />
+    </ClerkProvider>
+  );
+}
+```
+
+and within your CSS file, add the following to enable automatic light/dark mode switching:
+
+```css
+:root {
+  color-scheme: light dark;
+}
+```
+
+This will automatically switch between light and dark modes based on the user's system preference. Alternatively, you can use a class-based approach:
+
+```css
+:root {
+  color-scheme: light;
+}
+
+.dark {
+  color-scheme: dark;
+}
+```
+
+**Note:** The `light-dark()` CSS function requires modern browser support (Chrome 123+, Firefox 120+, Safari 17.4+). For older browsers, consider using the `dark` theme with manual switching.

.changeset/tangy-melons-rescue.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Removes provider icon filter invert from elements for both `dark` and `shadcn` themes.

packages/ui/bundlewatch.config.json

@@ -4,7 +4,7 @@
     { "path": "./dist/ui.legacy.browser.js", "maxSize": "54KB" },
     { "path": "./dist/framework*.js", "maxSize": "44KB" },
     { "path": "./dist/vendors*.js", "maxSize": "73KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "129KB" },
+    { "path": "./dist/ui-common*.js", "maxSize": "130KB" },
     { "path": "./dist/signin*.js", "maxSize": "16KB" },
     { "path": "./dist/signup*.js", "maxSize": "11KB" },
     { "path": "./dist/userprofile*.js", "maxSize": "16KB" },

packages/ui/src/elements/SocialButtons.tsx

@@ -12,9 +12,9 @@ import {
   Flex,
   Grid,
   Icon,
-  Image,
   localizationKeys,
   SimpleButton,
+  Span,
   Spinner,
   Text,
   useAppearance,
@@ -30,6 +30,13 @@ import { distributeStrategiesIntoRows } from './utils';
 const SOCIAL_BUTTON_BLOCK_THRESHOLD = 2;
 const SOCIAL_BUTTON_PRE_TEXT_THRESHOLD = 1;
 const MAX_STRATEGIES_PER_ROW = 5;
+const SUPPORTS_MASK_IMAGE = ['apple', 'github', 'okx_wallet', 'vercel'] as const;
+
+type SupportsMaskImageProvider = (typeof SUPPORTS_MASK_IMAGE)[number];
+
+const supportsMaskImage = (id: OAuthProvider | Web3Provider | PhoneCodeChannel): id is SupportsMaskImageProvider => {
+  return (SUPPORTS_MASK_IMAGE as readonly string[]).includes(id);
+};
 
 export type SocialButtonsProps = React.PropsWithChildren<{
   enableOAuthProviders: boolean;
@@ -189,14 +196,31 @@ export const SocialButtons = React.memo((props: SocialButtonsRootProps) => {
                 });
 
             const imageOrInitial = strategyToDisplayData[strategy].iconUrl ? (
-              <Image
+              <Span
                 elementDescriptor={[descriptors.providerIcon, descriptors.socialButtonsProviderIcon]}
                 elementId={descriptors.socialButtonsProviderIcon.setId(strategyToDisplayData[strategy].id)}
-                isLoading={card.loadingMetadata === strategy}
-                isDisabled={card.isLoading}
-                src={strategyToDisplayData[strategy].iconUrl}
-                alt={`Sign in with ${strategyToDisplayData[strategy].name}`}
-                sx={theme => ({ width: theme.sizes.$4, height: 'auto', maxWidth: '100%' })}
+                aria-label={`Sign in with ${strategyToDisplayData[strategy].name}`}
+                sx={theme => ({
+                  display: 'inline-block',
+                  width: theme.sizes.$4,
+                  height: theme.sizes.$4,
+                  maxWidth: '100%',
+                  ...(supportsMaskImage(strategyToDisplayData[strategy].id)
+                    ? {
+                        '--cl-icon-fill': theme.colors.$colorForeground,
+                        backgroundColor: 'var(--cl-icon-fill)',
+                        maskImage: `url(${strategyToDisplayData[strategy].iconUrl})`,
+                        maskSize: 'cover',
+                        maskPosition: 'center',
+                        maskRepeat: 'no-repeat',
+                      }
+                    : {
+                        backgroundImage: `url(${strategyToDisplayData[strategy].iconUrl})`,
+                        backgroundSize: 'cover',
+                        backgroundPosition: 'center',
+                        backgroundRepeat: 'no-repeat',
+                      }),
+                })}
               />
             ) : (
               <ProviderInitialIcon

packages/ui/src/foundations/colors.ts

@@ -1,6 +1,7 @@
 import { colors as colorUtils } from '../utils/colors';
 import { colorOptionToThemedAlphaScale, colorOptionToThemedLightnessScale } from '../utils/colors/scales';
 import { clerkCssVar } from '../utils/cssVariables';
+import { lightDark } from '../utils/lightDark';
 
 const whiteAlpha = Object.freeze({
   whiteAlpha25: 'hsla(0, 0%, 100%, 0.02)',
@@ -34,14 +35,14 @@ type AlphaScale<T extends string> = NonNullable<ReturnType<typeof colorOptionToT
  * Therefore, it's safe to assert these as NonNullable.
  */
 
-const defaultColorNeutral = clerkCssVar('color-neutral', '#000000');
+const defaultColorNeutral = clerkCssVar('color-neutral', lightDark('#000000', '#ffffff'));
 
 const dangerScale = colorOptionToThemedLightnessScale(
   clerkCssVar('color-danger', '#EF4444'),
   'danger',
 ) as LightnessScale<'danger'>;
 const primaryScale = colorOptionToThemedLightnessScale(
-  clerkCssVar('color-primary', '#2F3037'),
+  clerkCssVar('color-primary', lightDark('#2F3037', '#ffffff')),
   'primary',
 ) as LightnessScale<'primary'>;
 const successScale = colorOptionToThemedLightnessScale(
@@ -62,7 +63,7 @@ const neutralAlphaScale = colorOptionToThemedAlphaScale(
   'neutralAlpha',
 ) as AlphaScale<'neutralAlpha'>;
 const primaryAlphaScale = colorOptionToThemedAlphaScale(
-  clerkCssVar('color-primary', '#2F3037'),
+  clerkCssVar('color-primary', lightDark('#2F3037', '#ffffff')),
   'primaryAlpha',
 ) as AlphaScale<'primaryAlpha'>;
 const successAlphaScale = colorOptionToThemedAlphaScale(
@@ -79,7 +80,7 @@ const borderAlphaScale = colorOptionToThemedAlphaScale(
   'borderAlpha',
 ) as AlphaScale<'borderAlpha'>;
 
-const colorForeground = clerkCssVar('color-foreground', '#212126');
+const colorForeground = clerkCssVar('color-foreground', lightDark('#212126', 'white'));
 const colorMutedForeground = clerkCssVar(
   'color-muted-foreground',
   colorUtils.makeTransparent(colorForeground, 0.35) || '#747686',
@@ -92,17 +93,17 @@ const colors = Object.freeze({
     'color-modal-backdrop',
     colorUtils.makeTransparent(defaultColorNeutral, 0.27) || neutralAlphaScale.neutralAlpha700,
   ),
-  colorBackground: clerkCssVar('color-background', 'white'),
-  colorInput: clerkCssVar('color-input', 'white'),
+  colorBackground: clerkCssVar('color-background', lightDark('#ffffff', '#212126')),
+  colorInput: clerkCssVar('color-input', lightDark('white', '#26262B')),
   colorForeground,
   colorMutedForeground,
   colorMuted: undefined,
   colorRing: clerkCssVar(
     'color-ring',
     colorUtils.makeTransparent(defaultColorNeutral, 0.85) || neutralAlphaScale.neutralAlpha200,
   ),
-  colorInputForeground: clerkCssVar('color-input-foreground', '#131316'),
-  colorPrimaryForeground: clerkCssVar('color-primary-foreground', 'white'),
+  colorInputForeground: clerkCssVar('color-input-foreground', lightDark('#131316', 'white')),
+  colorPrimaryForeground: clerkCssVar('color-primary-foreground', lightDark('white', 'black')),
   colorShimmer: clerkCssVar('color-shimmer', 'rgba(255, 255, 255, 0.36)'),
   transparent: 'transparent',
   white: 'white',

packages/ui/src/themes/dark.ts

@@ -12,10 +12,6 @@ export const dark = createTheme({
     colorInput: '#26262B',
   },
   elements: {
-    providerIcon__apple: { filter: 'invert(1)' },
-    providerIcon__github: { filter: 'invert(1)' },
-    providerIcon__okx_wallet: { filter: 'invert(1)' },
-    providerIcon__vercel: { filter: 'invert(1)' },
     activeDeviceIcon: {
       '--cl-chassis-bottom': '#d2d2d2',
       '--cl-chassis-back': '#e6e6e6',

packages/ui/src/themes/shadcn.ts

@@ -32,9 +32,5 @@ export const shadcn = createTheme({
         display: 'none',
       },
     },
-    providerIcon__apple: 'dark:invert',
-    providerIcon__github: 'dark:invert',
-    providerIcon__okx_wallet: 'dark:invert',
-    providerIcon__vercel: 'dark:invert',
   },
 });

packages/ui/src/utils/__tests__/cssSupports.test.ts

@@ -1,29 +1,54 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
 
 import { clearCache, cssSupports } from '../cssSupports';
+import { lightDark } from '../lightDark';
 
-// Mock CSS.supports
-const originalCSSSupports = CSS.supports;
+// Store original CSS if it exists
+const originalCSS = globalThis.CSS;
 
 beforeAll(() => {
-  CSS.supports = vi.fn(feature => {
-    if (feature === 'color: hsl(from white h s l)') {
-      return true;
-    }
-    if (feature === 'color: color-mix(in srgb, white, black)') {
+  // Create mock CSS global for Node.js environment
+  globalThis.CSS = {
+    supports: vi.fn((feature: string) => {
+      if (feature === 'color: hsl(from white h s l)') {
+        return true;
+      }
+      if (feature === 'color: color-mix(in srgb, white, black)') {
+        return false;
+      }
+      if (feature === 'color: light-dark(white, black)') {
+        return true;
+      }
       return false;
-    }
-    return false;
-  });
+    }),
+  } as unknown as typeof CSS;
 });
 
 afterAll(() => {
-  CSS.supports = originalCSSSupports;
+  // Restore original CSS or remove if it didn't exist
+  if (originalCSS) {
+    globalThis.CSS = originalCSS;
+  } else {
+    // @ts-expect-error - cleaning up mock
+    delete globalThis.CSS;
+  }
 });
 
 beforeEach(() => {
   clearCache();
-  vi.mocked(CSS.supports).mockClear();
+  // Reset mock to default behavior
+  vi.mocked(globalThis.CSS.supports).mockImplementation((feature: string) => {
+    if (feature === 'color: hsl(from white h s l)') {
+      return true;
+    }
+    if (feature === 'color: color-mix(in srgb, white, black)') {
+      return false;
+    }
+    if (feature === 'color: light-dark(white, black)') {
+      return true;
+    }
+    return false;
+  });
 });
 
 describe('cssSupports', () => {
@@ -39,10 +64,68 @@ describe('cssSupports', () => {
     expect(cssSupports.modernColor()).toBe(true);
   });
 
+  test('lightDark should return true when supported', () => {
+    expect(cssSupports.lightDark()).toBe(true);
+  });
+
   test('caching works correctly', () => {
+    const initialCallCount = vi.mocked(globalThis.CSS.supports).mock.calls.length;
     cssSupports.relativeColorSyntax();
-    expect(CSS.supports).toHaveBeenCalledTimes(1);
+    expect(globalThis.CSS.supports).toHaveBeenCalledTimes(initialCallCount + 1);
     cssSupports.relativeColorSyntax();
-    expect(CSS.supports).toHaveBeenCalledTimes(1); // Should not call again due to caching
+    expect(globalThis.CSS.supports).toHaveBeenCalledTimes(initialCallCount + 1); // Should not call again due to caching
+  });
+
+  test('lightDark caching works correctly', () => {
+    const initialCallCount = vi.mocked(globalThis.CSS.supports).mock.calls.length;
+    cssSupports.lightDark();
+    expect(globalThis.CSS.supports).toHaveBeenCalledTimes(initialCallCount + 1);
+    cssSupports.lightDark();
+    expect(globalThis.CSS.supports).toHaveBeenCalledTimes(initialCallCount + 1); // Should not call again due to caching
+  });
+});
+
+describe('lightDark utility', () => {
+  test('returns light-dark() when both lightDark and modernColor are supported', () => {
+    // In this test setup: lightDark=true, relativeColorSyntax=true (so modernColor=true)
+    const result = lightDark('#ffffff', '#000000');
+    expect(result).toBe('light-dark(#ffffff, #000000)');
+  });
+
+  test('returns light value when lightDark is not supported', () => {
+    // Override mock to return false for lightDark
+    vi.mocked(globalThis.CSS.supports).mockImplementation((feature: string) => {
+      if (feature === 'color: light-dark(white, black)') {
+        return false;
+      }
+      if (feature === 'color: hsl(from white h s l)') {
+        return true;
+      }
+      return false;
+    });
+    clearCache();
+
+    const result = lightDark('#ffffff', '#000000');
+    expect(result).toBe('#ffffff');
+  });
+
+  test('returns light value when modernColor is not supported', () => {
+    // Override mock to return true for lightDark but false for modern color features
+    vi.mocked(globalThis.CSS.supports).mockImplementation((feature: string) => {
+      if (feature === 'color: light-dark(white, black)') {
+        return true;
+      }
+      // Both relativeColorSyntax and colorMix return false
+      return false;
+    });
+    clearCache();
+
+    const result = lightDark('#ffffff', '#000000');
+    expect(result).toBe('#ffffff');
+  });
+
+  test('works with named colors', () => {
+    const result = lightDark('white', 'black');
+    expect(result).toBe('light-dark(white, black)');
   });
 });