feat(ui): Add mosaic design systems foundations (#8755)

Author: alexcarpenter

.changeset/mosaic-design-system-foundations.md

@@ -0,0 +1,2 @@
+---
+---

AGENTS.md

@@ -13,4 +13,5 @@ Clerk's JavaScript SDK and library monorepo.
 ## References
 
 - For questions about theming, appearance customization, or the styled system, see `references/theming-architecture.md`.
+- For the Mosaic design system (tokens, CVA utility, `MosaicProvider`, migration from existing system), see `references/mosaic-architecture.md`.
 - For dev setup, testing, JSDoc/Typedoc, publishing, changesets, and commit conventions, see `docs/CONTRIBUTING.md`.

packages/ui/src/mosaic/MosaicProvider.tsx

@@ -0,0 +1,65 @@
+// eslint-disable-next-line no-restricted-imports
+import createCache from '@emotion/cache';
+// eslint-disable-next-line no-restricted-imports
+import { CacheProvider, type SerializedStyles } from '@emotion/react';
+import React from 'react';
+
+import { defaultMosaicVariables, resolveVariables } from './variables';
+import type { MosaicTheme, MosaicVariables } from './variables';
+
+const getInsertionPoint = (): HTMLElement | null => {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  return document.querySelector('style#cl-mosaic-style-insertion-point');
+};
+
+const MosaicThemeContext = React.createContext<MosaicTheme | null>(null);
+
+export interface MosaicProviderProps {
+  children: React.ReactNode;
+  variables?: MosaicVariables;
+  nonce?: string;
+  cssLayerName?: string;
+}
+
+export function MosaicProvider({ children, variables, nonce, cssLayerName }: MosaicProviderProps) {
+  const theme = React.useMemo(() => resolveVariables(defaultMosaicVariables, variables), [variables]);
+  const cache = React.useMemo(() => {
+    const el = getInsertionPoint();
+    const emotionCache = createCache({
+      key: 'cl-mosaic',
+      stylisPlugins: [],
+      prepend: cssLayerName ? false : !el,
+      insertionPoint: el ?? undefined,
+      nonce,
+    });
+
+    if (cssLayerName) {
+      const prevInsert = emotionCache.insert.bind(emotionCache);
+      emotionCache.insert = (selector: string, serialized: SerializedStyles, sheet: any, shouldCache: boolean) => {
+        if (serialized && typeof serialized.styles === 'string') {
+          const newSerialized = { ...serialized };
+          newSerialized.styles = `@layer ${cssLayerName} {${serialized.styles}}`;
+          return prevInsert(selector, newSerialized, sheet, shouldCache);
+        }
+        return prevInsert(selector, serialized, sheet, shouldCache);
+      };
+    }
+
+    return emotionCache;
+  }, [nonce, cssLayerName]);
+  return (
+    <MosaicThemeContext.Provider value={theme}>
+      <CacheProvider value={cache}>{children}</CacheProvider>
+    </MosaicThemeContext.Provider>
+  );
+}
+
+export function useMosaicTheme(): MosaicTheme {
+  const theme = React.useContext(MosaicThemeContext);
+  if (!theme) {
+    throw new Error('useMosaicTheme must be used within a MosaicProvider');
+  }
+  return theme;
+}