From 7c5d554324d95e6804313d017f0b208b5315d718 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 08:36:16 -0400
Subject: [PATCH 1/3] feat(ui): Stylex POC

---
 packages/ui/.gitignore                    |   2 +
 packages/ui/package.json                  |   3 +
 packages/ui/src/mosaic-x/button.tsx       | 116 ++++++
 packages/ui/src/mosaic-x/demo-live.html   | 106 ++++++
 packages/ui/src/mosaic-x/demo.html        |  64 ++++
 packages/ui/src/mosaic-x/index.ts         |   3 +
 packages/ui/src/mosaic-x/tokens.stylex.ts |  31 ++
 packages/ui/tsconfig.mosaic-x.json        |   6 +
 packages/ui/tsdown.mosaic-x.config.mts    |  29 ++
 pnpm-lock.yaml                            | 111 +++++-
 references/mosaic-stylex-migration.md     | 441 ++++++++++++++++++++++
 11 files changed, 904 insertions(+), 8 deletions(-)
 create mode 100644 packages/ui/.gitignore
 create mode 100644 packages/ui/src/mosaic-x/button.tsx
 create mode 100644 packages/ui/src/mosaic-x/demo-live.html
 create mode 100644 packages/ui/src/mosaic-x/demo.html
 create mode 100644 packages/ui/src/mosaic-x/index.ts
 create mode 100644 packages/ui/src/mosaic-x/tokens.stylex.ts
 create mode 100644 packages/ui/tsconfig.mosaic-x.json
 create mode 100644 packages/ui/tsdown.mosaic-x.config.mts
 create mode 100644 references/mosaic-stylex-migration.md

diff --git a/packages/ui/.gitignore b/packages/ui/.gitignore
new file mode 100644
index 00000000000..17ca222a57a
--- /dev/null
+++ b/packages/ui/.gitignore
@@ -0,0 +1,2 @@
+# StyleX migration POC build output (regenerate with `pnpm build:mosaic-x`)
+dist-mosaic-x
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 348c1a0f3de..6c66d912bc2 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -72,6 +72,7 @@
     "build": "pnpm build:umd && pnpm build:esm && pnpm check:no-rhc && pnpm type-check",
     "build:analyze": "rspack build --config rspack.config.js --env production --env analyze",
     "build:esm": "tsdown",
+    "build:mosaic-x": "tsdown --config tsdown.mosaic-x.config.mts",
     "build:rsdoctor": "RSDOCTOR=true rspack build --config rspack.config.js --env production",
     "build:umd": "rspack build --config rspack.config.js --env production",
     "bundlewatch": "FORCE_COLOR=1 bundlewatch --config bundlewatch.config.json",
@@ -103,6 +104,7 @@
     "@solana/wallet-adapter-base": "catalog:module-manager",
     "@solana/wallet-adapter-react": "catalog:module-manager",
     "@solana/wallet-standard": "catalog:module-manager",
+    "@stylexjs/stylex": "0.19.0",
     "@swc/helpers": "catalog:repo",
     "copy-to-clipboard": "3.3.3",
     "core-js": "catalog:repo",
@@ -119,6 +121,7 @@
     "@rspack/core": "catalog:rspack",
     "@rspack/dev-server": "catalog:rspack",
     "@rspack/plugin-react-refresh": "catalog:rspack",
+    "@stylexjs/rollup-plugin": "0.19.0",
     "@svgr/rollup": "^8.1.0",
     "@svgr/webpack": "^6.5.1",
     "@types/webpack-env": "^1.18.8",
diff --git a/packages/ui/src/mosaic-x/button.tsx b/packages/ui/src/mosaic-x/button.tsx
new file mode 100644
index 00000000000..d5679c50a41
--- /dev/null
+++ b/packages/ui/src/mosaic-x/button.tsx
@@ -0,0 +1,116 @@
+import * as stylex from '@stylexjs/stylex';
+import React from 'react';
+
+import { colors, radius, space } from './tokens.stylex';
+
+// Helper to keep spacing math readable. `space['--cl-spacing']` compiles to
+// `var(--cl-spacing)`, so this yields e.g. `calc(var(--cl-spacing) * 2)`.
+const s = (n: number) => `calc(${space['--cl-spacing']} * ${n})`;
+
+const styles = stylex.create({
+  base: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: s(2),
+    borderRadius: radius['--cl-radius-md'],
+    borderWidth: '1px',
+    borderStyle: 'solid',
+    borderColor: 'transparent',
+    fontWeight: 500,
+    fontFamily: 'inherit',
+    cursor: 'pointer',
+    transitionProperty: 'background-color, border-color, color, opacity',
+    transitionDuration: '150ms',
+    outline: {
+      default: 'none',
+      ':focus-visible': `2px solid color-mix(in oklab, ${colors['--cl-primary']} 50%, transparent)`,
+    },
+    outlineOffset: '2px',
+  },
+
+  // intent × variant
+  filledPrimary: {
+    backgroundColor: {
+      default: colors['--cl-primary'],
+      ':hover': `color-mix(in oklab, ${colors['--cl-primary']}, ${colors['--cl-primary-foreground']} 12%)`,
+      ':active': `color-mix(in oklab, ${colors['--cl-primary']}, ${colors['--cl-primary-foreground']} 24%)`,
+    },
+    color: colors['--cl-primary-foreground'],
+  },
+  filledDestructive: {
+    backgroundColor: {
+      default: colors['--cl-destructive'],
+      ':hover': `color-mix(in oklab, ${colors['--cl-destructive']}, ${colors['--cl-destructive-foreground']} 12%)`,
+      ':active': `color-mix(in oklab, ${colors['--cl-destructive']}, ${colors['--cl-destructive-foreground']} 24%)`,
+    },
+    color: colors['--cl-destructive-foreground'],
+  },
+  outlinePrimary: {
+    backgroundColor: 'transparent',
+    borderColor: colors['--cl-border'],
+    color: colors['--cl-foreground'],
+  },
+
+  // size
+  sizeSm: { paddingBlock: s(1), paddingInline: s(2), fontSize: '0.75rem', lineHeight: 'calc(1 / 0.75)' },
+  sizeMd: { paddingBlock: s(2), paddingInline: s(4), fontSize: '0.875rem', lineHeight: 'calc(1.25 / 0.875)' },
+
+  // state / modifiers
+  fullWidth: { width: '100%' },
+  disabled: { opacity: 0.5, cursor: 'not-allowed', pointerEvents: 'none' },
+});
+
+export interface ButtonProps extends React.ComponentPropsWithRef<'button'> {
+  intent?: 'primary' | 'destructive';
+  variant?: 'filled' | 'outline';
+  size?: 'sm' | 'md';
+  fullWidth?: boolean;
+}
+
+// Stable, hand-authored class every consumer can target: `.cl-button { … }`.
+// StyleX never attaches rules to this class; it exists purely as a targeting
+// hook. Consumer rules on it are unlayered and therefore beat StyleX's
+// `@layer`-wrapped atomic classes (see mosaic-stylex-migration.md).
+const STABLE_CLASS = 'cl-button';
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  {
+    intent = 'primary',
+    variant = 'filled',
+    size = 'md',
+    fullWidth = false,
+    disabled = false,
+    className,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const atomic = stylex.props(
+    styles.base,
+    variant === 'filled' && intent === 'primary' && styles.filledPrimary,
+    variant === 'filled' && intent === 'destructive' && styles.filledDestructive,
+    variant === 'outline' && styles.outlinePrimary,
+    size === 'sm' ? styles.sizeSm : styles.sizeMd,
+    fullWidth && styles.fullWidth,
+    disabled && styles.disabled,
+  );
+
+  return (
+    <button
+      ref={ref}
+      type='button'
+      disabled={disabled}
+      // Order: stable class → consumer className → StyleX atomic classes.
+      className={[STABLE_CLASS, className, atomic.className].filter(Boolean).join(' ')}
+      style={atomic.style}
+      data-intent={intent}
+      data-variant={variant}
+      data-size={size}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+});
diff --git a/packages/ui/src/mosaic-x/demo-live.html b/packages/ui/src/mosaic-x/demo-live.html
new file mode 100644
index 00000000000..6ddb103163b
--- /dev/null
+++ b/packages/ui/src/mosaic-x/demo-live.html
@@ -0,0 +1,106 @@
+<!doctype html>
+<!--
+  LIVE demo — renders the actual built Button component (../../dist-mosaic-x/index.js).
+  Build first: `pnpm build:mosaic-x`, then serve the package dir over HTTP:
+    cd packages/ui && python3 -m http.server 4321
+  and open http://localhost:4321/src/mosaic-x/demo-live.html
+  (react / react-dom / @stylexjs/stylex are loaded from esm.sh via the import map,
+  so this page needs network access.)
+-->
+<html lang="en">
+
+<head>
+  <meta charset="utf-8" />
+  <title>mosaic-x — live component demo</title>
+
+  <!-- Consumer owns the layer: import our sheet into `components`, override from `overrides`. -->
+  <style>
+    @layer components, overrides;
+    @import url('../../dist-mosaic-x/mosaic.css') layer(components);
+
+    body {
+      font-family: system-ui, sans-serif;
+      margin: 2rem;
+    }
+
+    h2 {
+      font-size: 0.9rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: #666;
+      margin: 1.5rem 0 0.5rem;
+    }
+
+    .row {
+      display: flex;
+      gap: 0.75rem;
+      align-items: center;
+      flex-wrap: wrap;
+    }
+
+    /* Flip this on with the checkbox to see consumer overrides win by layer order.
+         Custom properties inherit, so setting --cl-primary on body reaches every
+         button; the rules live in `overrides` so they beat the `components` layer. */
+    @layer overrides {
+      body.overrides-on {
+        --cl-primary: rebeccapurple;
+      }
+
+      body.overrides-on .cl-button {
+        border-radius: 9999px;
+      }
+    }
+  </style>
+
+  <script type="importmap">
+      {
+        "imports": {
+          "react": "https://esm.sh/react@18.3.1",
+          "react/jsx-runtime": "https://esm.sh/react@18.3.1/jsx-runtime",
+          "react-dom/client": "https://esm.sh/react-dom@18.3.1/client",
+          "@stylexjs/stylex": "https://esm.sh/@stylexjs/stylex@0.19.0"
+        }
+      }
+    </script>
+</head>
+
+<body>
+  <label style="display: block; margin-bottom: 1rem">
+    <input id="toggle" type="checkbox" /> apply consumer overrides (purple + pill)
+  </label>
+  <div id="root"></div>
+
+  <script type="module">
+    import React from 'react';
+    import {createRoot} from 'react-dom/client';
+    import {Button} from '../../dist-mosaic-x/index.js';
+
+    const h = React.createElement;
+    const Row = (label, kids) => h('div', null, h('h2', null, label), h('div', {className: 'row'}, kids));
+
+    function App() {
+      return h(
+        React.Fragment,
+        null,
+        Row('filled', [
+          h(Button, {key: 1, intent: 'primary'}, 'Primary'),
+          h(Button, {key: 2, intent: 'destructive'}, 'Destructive'),
+        ]),
+        Row('outline', [h(Button, {key: 1, variant: 'outline'}, 'Outline')]),
+        Row('sizes', [
+          h(Button, {key: 1, size: 'sm'}, 'Small'),
+          h(Button, {key: 2, size: 'md'}, 'Medium'),
+        ]),
+        Row('state', [h(Button, {key: 1, disabled: true}, 'Disabled')]),
+      );
+    }
+
+    createRoot(document.getElementById('root')).render(h(App));
+
+    document.getElementById('toggle').addEventListener('change', e => {
+      document.body.classList.toggle('overrides-on', e.target.checked);
+    });
+  </script>
+</body>
+
+</html>
diff --git a/packages/ui/src/mosaic-x/demo.html b/packages/ui/src/mosaic-x/demo.html
new file mode 100644
index 00000000000..b46e3c8e62c
--- /dev/null
+++ b/packages/ui/src/mosaic-x/demo.html
@@ -0,0 +1,64 @@
+<!doctype html>
+<!--
+  POC demo. Build first: `pnpm build:mosaic-x`, then open this file in a browser.
+  Shows the intended consumer model: the consumer imports our stylesheet INTO A
+  LAYER THEY CONTROL, then puts their own overrides in a later layer (or
+  unlayered). Their rules win by cascade-layer order — no StyleX/JS on the
+  consumer side, and layer precedence is the consumer's concern, not ours.
+  The button markup below is copied verbatim from the server-rendered POC output.
+-->
+<html lang="en">
+
+<head>
+  <meta charset="utf-8" />
+  <title>mosaic-x StyleX POC</title>
+  <style>
+    /* ---- CONSUMER CSS (plain, no StyleX) ---- */
+
+    /* Consumer declares layer order and imports our sheet into `components`. */
+    @layer components, overrides;
+    @import url('../../dist-mosaic-x/mosaic.css') layer(components);
+
+    /* Consumer overrides live in a later layer → always win over `components`. */
+    @layer overrides {
+
+      /* 1. Override a design token globally. */
+      :root {
+        --cl-primary: rebeccapurple;
+      }
+
+      /* 2. Target the stable class directly. */
+      .cl-button {
+        border-radius: 9999px;
+      }
+
+      /* 3. Variant-scoped override via the data-* attribute the component emits. */
+      .cl-button[data-variant='outline'] {
+        border-color: rebeccapurple;
+        color: rebeccapurple;
+      }
+    }
+
+    body {
+      font-family: system-ui, sans-serif;
+      padding: 2rem;
+      display: flex;
+      gap: 1rem;
+    }
+  </style>
+</head>
+
+<body>
+  <button type="button"
+    class="cl-button x3nfvp2 x6s0dn4 xl56j7k x19rnl8h xzmjytj xmkeg23 x1y0btm7 x9r1u3d xk50ysn xjb2p0i x1ypdohk x1qsmvhx xx6bhzk x1a2a7pz xy8msr7 x1hl8ikr x1hew001 x1kdqmna x13bm0ie xlgzno x1495f9z x16lbfrg xkpwil5 xp7d87r"
+    data-intent="primary" data-variant="filled" data-size="md">
+    Primary (purple + pill)
+  </button>
+  <button type="button"
+    class="cl-button x3nfvp2 x6s0dn4 xl56j7k x19rnl8h xzmjytj xmkeg23 x1y0btm7 xk50ysn xjb2p0i x1ypdohk x1qsmvhx xx6bhzk x1a2a7pz xy8msr7 x1hl8ikr xjbqb8w x1slpqh1 x1hzhwjc x1495f9z x16lbfrg xkpwil5 xp7d87r"
+    data-intent="primary" data-variant="outline" data-size="md">
+    Outline (purple border)
+  </button>
+</body>
+
+</html>
diff --git a/packages/ui/src/mosaic-x/index.ts b/packages/ui/src/mosaic-x/index.ts
new file mode 100644
index 00000000000..15343ba8a0e
--- /dev/null
+++ b/packages/ui/src/mosaic-x/index.ts
@@ -0,0 +1,3 @@
+export { Button } from './button';
+export type { ButtonProps } from './button';
+export { colors, radius, space } from './tokens.stylex';
diff --git a/packages/ui/src/mosaic-x/tokens.stylex.ts b/packages/ui/src/mosaic-x/tokens.stylex.ts
new file mode 100644
index 00000000000..ade1f79495e
--- /dev/null
+++ b/packages/ui/src/mosaic-x/tokens.stylex.ts
@@ -0,0 +1,31 @@
+import * as stylex from '@stylexjs/stylex';
+
+// Mosaic-X design tokens.
+//
+// defineVars normally hashes variable names (e.g. `--x1a2b3c`), which consumers
+// cannot target. Keys that start with `--` are emitted verbatim, so these become
+// real, stable custom properties (`--cl-foreground`, …). A consumer can override
+// any of them in plain CSS without touching StyleX:
+//
+//   :root { --cl-foreground: red; }
+//
+// StyleX still emits `:root { --cl-foreground: black; }` as the default.
+export const colors = stylex.defineVars({
+  '--cl-foreground': 'black',
+  '--cl-background': 'white',
+  '--cl-primary': 'oklch(0.205 0 0)',
+  '--cl-primary-foreground': 'oklch(0.985 0 0)',
+  '--cl-destructive': 'oklch(0.577 0.245 27.325)',
+  '--cl-destructive-foreground': 'oklch(0.985 0 0)',
+  '--cl-border': 'oklch(0.922 0 0)',
+  '--cl-muted-foreground': 'oklch(0.556 0 0)',
+});
+
+export const radius = stylex.defineVars({
+  '--cl-radius-md': '0.375rem',
+  '--cl-radius-full': 'calc(infinity * 1px)',
+});
+
+export const space = stylex.defineVars({
+  '--cl-spacing': '0.25rem',
+});
diff --git a/packages/ui/tsconfig.mosaic-x.json b/packages/ui/tsconfig.mosaic-x.json
new file mode 100644
index 00000000000..d4b1a2302da
--- /dev/null
+++ b/packages/ui/tsconfig.mosaic-x.json
@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "jsxImportSource": "react"
+  }
+}
diff --git a/packages/ui/tsdown.mosaic-x.config.mts b/packages/ui/tsdown.mosaic-x.config.mts
new file mode 100644
index 00000000000..004756dc287
--- /dev/null
+++ b/packages/ui/tsdown.mosaic-x.config.mts
@@ -0,0 +1,29 @@
+import stylexPlugin from '@stylexjs/rollup-plugin';
+import { defineConfig } from 'tsdown';
+
+// Isolated POC build: compiles ONLY src/mosaic-x with the StyleX rollup plugin,
+// emitting transformed ESM + a single static mosaic.css stylesheet that consumers
+// import. Kept separate from the main tsdown build so the Emotion-based code is
+// untouched. `useCSSLayers` wraps StyleX's atomic rules in `@layer priorityN` for
+// correct intra-StyleX precedence; consumers import the sheet into a layer they
+// control (`@import '@clerk/ui/mosaic.css' layer(components)`) under which those
+// nest cleanly, and override from a later layer.
+export default defineConfig({
+  entry: ['./src/mosaic-x/index.ts'],
+  outDir: './dist-mosaic-x',
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  target: 'es2022',
+  platform: 'browser',
+  minify: false,
+  // Use the standard React JSX runtime, not Emotion's — mosaic-x must be Emotion-free.
+  tsconfig: './tsconfig.mosaic-x.json',
+  external: ['react', 'react-dom', '@stylexjs/stylex'],
+  plugins: [
+    stylexPlugin({
+      fileName: 'mosaic.css',
+      useCSSLayers: true,
+    }),
+  ],
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e4d6560b3da..4af7ae1e596 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -798,10 +798,10 @@ importers:
         version: 4.5.4(@types/node@25.6.0)(rollup@4.61.0)(typescript@6.0.3)(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))
       vitest:
         specifier: 4.1.6
-        version: 4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5)(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))
+        version: 4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5(vitest@4.1.5))(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))
       vitest-axe:
         specifier: ^0.1.0
-        version: 0.1.0(vitest@4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5)(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0)))
+        version: 0.1.0(vitest@4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5(vitest@4.1.5))(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0)))
 
   packages/hono:
     dependencies:
@@ -1189,6 +1189,9 @@ importers:
       '@solana/wallet-standard':
         specifier: catalog:module-manager
         version: 1.1.4(@solana/wallet-adapter-base@0.9.27(@solana/web3.js@1.98.4(bufferutil@4.1.0)(typescript@6.0.3)(utf-8-validate@5.0.10)))(@solana/web3.js@1.98.4(bufferutil@4.1.0)(typescript@6.0.3)(utf-8-validate@5.0.10))(bs58@6.0.0)(react@18.3.1)
+      '@stylexjs/stylex':
+        specifier: 0.19.0
+        version: 0.19.0
       '@swc/helpers':
         specifier: catalog:repo
         version: 0.5.21
@@ -1238,6 +1241,9 @@ importers:
       '@rspack/plugin-react-refresh':
         specifier: catalog:rspack
         version: 2.0.1(@rspack/core@2.0.6(@swc/helpers@0.5.21))(react-refresh@0.17.0)
+      '@stylexjs/rollup-plugin':
+        specifier: 0.19.0
+        version: 0.19.0
       '@svgr/rollup':
         specifier: ^8.1.0
         version: 8.1.0(rollup@4.61.0)(typescript@6.0.3)
@@ -1519,6 +1525,10 @@ packages:
     resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/helper-string-parser@8.0.0':
+    resolution: {integrity: sha512-6mJgmFFFIIO82vvoLt9XtRC7/TkzXfts1t/SpRX4IHSzMgqoPYCWesVu1udUPUWioAE/2fcG6WuI8zrkE1gwrg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@babel/helper-string-parser@8.0.0-rc.6':
     resolution: {integrity: sha512-BCkFy+zN6kXQed3YOT7aJl93NfDSzQc3pBfsvTVPs9gU9X3V0aefEF5kwBT0E+mDWH9QgKaZstYUQN9VdQZT4g==}
     engines: {node: ^22.18.0 || >=24.11.0}
@@ -1531,6 +1541,10 @@ packages:
     resolution: {integrity: sha512-nVJ+1JcCgntv8d78rRo++o2wuODT0Irknx2BF8Np4Ft2CRgjLqIs4qzSZ8b66yGbBdMWGmZBO9WEZv1hhNiSpg==}
     engines: {node: ^22.18.0 || >=24.11.0}
 
+  '@babel/helper-validator-identifier@8.0.4':
+    resolution: {integrity: sha512-4wFaiLd0bVo4cIoTXI3zKI038NIWE/cr3jvBjejOVYVxV/m8Ltav1USiGzG1fmS5J2RhgEOgXNNK46cRPnRsrg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@babel/helper-validator-option@7.29.7':
     resolution: {integrity: sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==}
     engines: {node: '>=6.9.0'}
@@ -1557,6 +1571,11 @@ packages:
     engines: {node: ^22.18.0 || >=24.11.0}
     hasBin: true
 
+  '@babel/parser@8.0.4':
+    resolution: {integrity: sha512-srpptsAkEbbNIC/q8nT7o+m6CQe8CJUTV/t7MYc9NnWlgYVtHOb7JH6SorxMhN0kuRJjVqXbKClG6xSbPtzz+g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    hasBin: true
+
   '@babel/plugin-bugfix-firefox-class-in-computed-class-key@7.28.5':
     resolution: {integrity: sha512-87GDMS3tsmMSi/3bWOte1UblL+YUTFMV8SZPZ2eSEL17s74Cw/l63rR6NmGVKMYW2GYi85nE+/d6Hw5N0bEk2Q==}
     engines: {node: '>=6.9.0'}
@@ -2110,6 +2129,10 @@ packages:
     resolution: {integrity: sha512-p7/ABylAYlexb31wtRdIfH9L9A0Z2T/9H6zAqzqndkY2PLkvNNc580wGhp/gGKN4Sp9sQvSkhc6Oga8/O+wTyw==}
     engines: {node: ^22.18.0 || >=24.11.0}
 
+  '@babel/types@8.0.4':
+    resolution: {integrity: sha512-eY+Yn3dCqTGmyiq2QRU66lA5FL8lqqqvecHt0fF3uHONIa7ToYsaCiWV8lOKqAs0Rb2SjixiKFROngnulPtt2g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@base-org/account@2.0.1':
     resolution: {integrity: sha512-tySVNx+vd6XEynZL0uvB10uKiwnAfThr8AbKTwILVG86mPbLAhEOInQIk+uDnvpTvfdUhC1Bi5T/46JvFoLZQQ==}
 
@@ -2405,6 +2428,9 @@ packages:
     resolution: {integrity: sha512-KEUw/mGu+EDRhYWRTNGHIimVCs9NvMFaIXOGrHSXoCteKLE5EsJnmPjOPpYorjXVg/0xG0fbdVw720azw1z4ag==}
     hasBin: true
 
+  '@dual-bundle/import-meta-resolve@4.2.1':
+    resolution: {integrity: sha512-id+7YRUgoUX6CgV0DtuhirQWodeeA7Lf4i2x71JS/vtA5pRb/hIGWlw+G6MeXvsM+MXrz0VAydTGElX1rAfgPg==}
+
   '@dxup/nuxt@0.4.1':
     resolution: {integrity: sha512-gtYffW6OfWNvoLW+XD3Mx/K8uUq08PMGLYJoDxc92EzZAWqR0FhcR5iaLm5r/OxyGTKz+P5f5Y7Aoir9+SjYaw==}
     peerDependencies:
@@ -3014,7 +3040,7 @@ packages:
 
   '@expo/bunyan@4.0.1':
     resolution: {integrity: sha512-+Lla7nYSiHZirgK+U/uYzsLv/X+HaJienbD5AKX1UQZHYfWaP+9uuQluRB4GrEVWF0GZ7vEVp/jzaOT9k/SQlg==}
-    engines: {node: '>=0.10.0'}
+    engines: {'0': node >=0.10.0}
 
   '@expo/cli@0.22.28':
     resolution: {integrity: sha512-lvt72KNitGuixYD2l3SZmRKVu2G4zJpmg5V7WfUBNpmUU5oODBw/6qmiJ6kSLAlfDozscUk+BBGknBBzxUrwrA==}
@@ -5861,6 +5887,18 @@ packages:
     resolution: {integrity: sha512-w8CEY73X/7tw2KKlL3iOk679V9bWseE4GzNz3zlaYxcTjmcmWOathRb0emgo/QQ3eoNzmq68+2Y2gxluAv3xGw==}
     engines: {node: '>=12.16'}
 
+  '@stylexjs/babel-plugin@0.19.0':
+    resolution: {integrity: sha512-2SnVZIl047TtqKW0nRTn7Irz0kmoot1bxdGDE/HwfwfF7dJYHqwkIFg92s87v3hj7zxJobrHWwDx1p3qvQXW4g==}
+
+  '@stylexjs/rollup-plugin@0.19.0':
+    resolution: {integrity: sha512-HkPbod7x+gmQmdiPbZc3AdSBjKIknYlngAigtL3+KFNF/Yr+kd8Xke0qSaCB4P/FGbobJMofIDJrmhPZ/dWvOA==}
+
+  '@stylexjs/shared@0.19.0':
+    resolution: {integrity: sha512-7Yym70cQH5sPzJHgzJX3FkL9ZCptbC3IbiRijN9YLYU/5OywB/3c519Xv1DOzvxqjv8urSxh98/9HxLaPG7sDg==}
+
+  '@stylexjs/stylex@0.19.0':
+    resolution: {integrity: sha512-CnUFp7YMaDLDeemsWOfJgoC/gKM5P/yBNMcpJaE6ChJmXr7s0DJwSeGTTlHJcqqwN9OW1qGtmARWLFhGZN1pTA==}
+
   '@svgr/babel-plugin-add-jsx-attribute@6.5.1':
     resolution: {integrity: sha512-9PYGcXrAxitycIjRmZB+Q0JaN07GZIWaTBIGQzfaZv+qr1n8X1XUEJ5rZ/vx6OVD9RRYlrNnXWExQXcmZeD/BQ==}
     engines: {node: '>=10'}
@@ -8453,6 +8491,9 @@ packages:
     resolution: {integrity: sha512-v1plID3y9r/lPhviJ1wrXpLeyUIGAZ2SHNYTEapm7/8A9nLPoyvVp3RK/EPFqn5kEznyWgYZNsRtYYIWbuG8KA==}
     engines: {node: '>=8'}
 
+  css-mediaquery@0.1.2:
+    resolution: {integrity: sha512-COtn4EROW5dBGlE/4PiKnh6rZpAPxDeFLaEEwt4i10jpDMFt2EhQGS79QmmrO+iKCHv0PU/HrOWEhijFd1x99Q==}
+
   css-select@4.3.0:
     resolution: {integrity: sha512-wPpOYtnsVontu2mODhA19JrqWxNsfdatRKd64kmpRbQgh1KtItko5sTnEpPdpSaJszTOhEMlF/RPz28qj4HqhQ==}
 
@@ -14495,6 +14536,9 @@ packages:
     peerDependencies:
       postcss: ^8.5.14
 
+  styleq@0.2.1:
+    resolution: {integrity: sha512-L0TR0NQb+X4/ktDEKmjWyp27gla+LUYi/by5k5SjKXf6/pvZP7wbwEB5J+tqxdFVPgzbsuz+d4RTScO/QZquBw==}
+
   stylis@4.2.0:
     resolution: {integrity: sha512-Orov6g6BB1sDfYgzWfTHDOxamtX1bE/zo104Dh9e6fqJ3PooipYyfJ0pUmrZO2wAvO8YbEyeFrkV91XTsGMSrw==}
 
@@ -16338,7 +16382,7 @@ snapshots:
 
   '@babel/generator@8.0.0-rc.6':
     dependencies:
-      '@babel/parser': 8.0.0-rc.6
+      '@babel/parser': 8.0.4
       '@babel/types': 8.0.0-rc.6
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
@@ -16446,12 +16490,16 @@ snapshots:
 
   '@babel/helper-string-parser@7.29.7': {}
 
+  '@babel/helper-string-parser@8.0.0': {}
+
   '@babel/helper-string-parser@8.0.0-rc.6': {}
 
   '@babel/helper-validator-identifier@7.29.7': {}
 
   '@babel/helper-validator-identifier@8.0.0-rc.6': {}
 
+  '@babel/helper-validator-identifier@8.0.4': {}
+
   '@babel/helper-validator-option@7.29.7': {}
 
   '@babel/helper-wrap-function@7.28.3':
@@ -16482,6 +16530,10 @@ snapshots:
     dependencies:
       '@babel/types': 8.0.0-rc.6
 
+  '@babel/parser@8.0.4':
+    dependencies:
+      '@babel/types': 8.0.4
+
   '@babel/plugin-bugfix-firefox-class-in-computed-class-key@7.28.5(@babel/core@7.29.7)':
     dependencies:
       '@babel/core': 7.29.7
@@ -17172,6 +17224,11 @@ snapshots:
       '@babel/helper-string-parser': 8.0.0-rc.6
       '@babel/helper-validator-identifier': 8.0.0-rc.6
 
+  '@babel/types@8.0.4':
+    dependencies:
+      '@babel/helper-string-parser': 8.0.0
+      '@babel/helper-validator-identifier': 8.0.4
+
   '@base-org/account@2.0.1(@types/react@18.3.28)(bufferutil@4.1.0)(react@18.3.1)(typescript@6.0.3)(use-sync-external-store@1.6.0(react@18.3.1))(utf-8-validate@5.0.10)(zod@4.4.3)':
     dependencies:
       '@noble/hashes': 1.4.0
@@ -17625,6 +17682,8 @@ snapshots:
       which: 4.0.0
       yocto-spinner: 1.2.0
 
+  '@dual-bundle/import-meta-resolve@4.2.1': {}
+
   '@dxup/nuxt@0.4.1(magicast@0.5.3)(typescript@6.0.3)':
     dependencies:
       '@dxup/unimport': 0.1.2
@@ -21661,6 +21720,38 @@ snapshots:
 
   '@stripe/stripe-js@5.6.0': {}
 
+  '@stylexjs/babel-plugin@0.19.0':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+      '@dual-bundle/import-meta-resolve': 4.2.1
+      '@stylexjs/shared': 0.19.0
+      '@stylexjs/stylex': 0.19.0
+      postcss-value-parser: 4.2.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@stylexjs/rollup-plugin@0.19.0':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/plugin-syntax-flow': 7.27.1(@babel/core@7.29.7)
+      '@babel/plugin-syntax-jsx': 7.27.1(@babel/core@7.29.7)
+      '@babel/plugin-syntax-typescript': 7.29.7(@babel/core@7.29.7)
+      '@stylexjs/babel-plugin': 0.19.0
+      lightningcss: 1.32.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@stylexjs/shared@0.19.0': {}
+
+  '@stylexjs/stylex@0.19.0':
+    dependencies:
+      css-mediaquery: 0.1.2
+      invariant: 2.2.4
+      styleq: 0.2.1
+
   '@svgr/babel-plugin-add-jsx-attribute@6.5.1(@babel/core@7.29.7)':
     dependencies:
       '@babel/core': 7.29.7
@@ -23539,7 +23630,7 @@ snapshots:
 
   ast-kit@3.0.0-beta.1:
     dependencies:
-      '@babel/parser': 8.0.0-rc.6
+      '@babel/parser': 8.0.4
       estree-walker: 3.0.3
       pathe: 2.0.3
 
@@ -24753,6 +24844,8 @@ snapshots:
 
   crypto-random-string@2.0.0: {}
 
+  css-mediaquery@0.1.2: {}
+
   css-select@4.3.0:
     dependencies:
       boolbase: 1.0.0
@@ -32406,6 +32499,8 @@ snapshots:
       postcss: 8.5.15
       postcss-selector-parser: 7.1.1
 
+  styleq@0.2.1: {}
+
   stylis@4.2.0: {}
 
   sucrase@3.34.0:
@@ -33507,7 +33602,7 @@ snapshots:
     optionalDependencies:
       vite: 7.3.5(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0)
 
-  vitest-axe@0.1.0(vitest@4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5)(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))):
+  vitest-axe@0.1.0(vitest@4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5(vitest@4.1.5))(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))):
     dependencies:
       aria-query: 5.3.2
       axe-core: 4.11.4
@@ -33515,7 +33610,7 @@ snapshots:
       dom-accessibility-api: 0.5.16
       lodash-es: 4.18.1
       redent: 3.0.0
-      vitest: 4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5)(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))
+      vitest: 4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5(vitest@4.1.5))(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))
 
   vitest-chrome@0.1.0:
     dependencies:
@@ -33598,7 +33693,7 @@ snapshots:
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5)(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0)):
+  vitest@4.1.6(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@25.6.0)(@vitest/coverage-v8@4.1.5(vitest@4.1.5))(happy-dom@20.10.2(bufferutil@4.1.0)(utf-8-validate@5.0.10))(jsdom@27.0.0(bufferutil@4.1.0)(utf-8-validate@5.0.10))(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.6
       '@vitest/mocker': 4.1.6(msw@2.14.2(@types/node@25.6.0)(typescript@6.0.3))(vite@6.4.2(@types/node@25.6.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.20.6)(yaml@2.9.0))
diff --git a/references/mosaic-stylex-migration.md b/references/mosaic-stylex-migration.md
new file mode 100644
index 00000000000..eedb5250435
--- /dev/null
+++ b/references/mosaic-stylex-migration.md
@@ -0,0 +1,441 @@
+# Mosaic → StyleX migration: findings + POC
+
+Status: **spike / proof-of-concept complete.** This documents an evaluation of
+migrating Mosaic off Emotion (runtime CSS-in-JS) onto
+[StyleX](https://stylexjs.com) (compile-time atomic CSS), including a real,
+build-verified POC in `packages/ui/src/mosaic-x/`. Nothing here is shipped;
+Mosaic is still Emotion-based and greenfield/unused, so we can change the model
+freely.
+
+## Context — why consider this
+
+Today Mosaic authors styles with Emotion. `useRecipe`/`useSlot` merge plain
+style objects and Emotion serializes them to `<style>` tags at runtime inside a
+`MosaicProvider`-owned cache. Consumers customize via the `appearance` prop
+(`variables` for tokens, `elements` for per-slot overrides), targeted through
+`data-cl-*` attributes. See `references/mosaic-architecture.md`.
+
+The goal of this spike is a different consumer contract:
+
+1. **Drop the `appearance` prop** (no `variables`/`elements` props). Consumers
+   style Mosaic from **their own CSS** instead.
+2. **Ship a static stylesheet** consumers import once.
+3. **Stable CSS variables** — e.g. `--cl-foreground` defaults to `black`, and a
+   consumer overrides it with plain `:root { --cl-foreground: red; }`.
+4. **Stable class names** — e.g. every button carries `.cl-button` that a
+   consumer can target in their CSS to override styles.
+
+StyleX is a compile-time engine: `stylex.create(...)` becomes atomic classes and
+`stylex.defineVars(...)` becomes CSS custom properties, both extracted to a
+static `.css` file at build time. The only runtime is a tiny `stylex.props()`
+class-joiner. That matches goals 1–3 cleanly. Goal 4 (stable classes) needs a
+specific technique, covered below.
+
+## TL;DR verdict
+
+All four requirements are achievable and were verified against real compiler
+output. The linchpins:
+
+- **Stable CSS vars:** `defineVars` keys that begin with `--` are emitted
+  verbatim (not hashed). `--cl-foreground: black` lands in `:root` and is
+  overridable from plain consumer CSS. ✅
+- **Stable classes:** StyleX will **not** give you a stable atomic class. You
+  attach your own plain class (`cl-button`) alongside the StyleX classes as a
+  targeting hook. ✅
+- **Override precedence is the consumer's concern.** We ship a plain stylesheet;
+  the consumer imports it into a cascade layer they control and puts their
+  overrides in a later layer:
+
+  ```css
+  @layer components, overrides;
+  @import '@clerk/ui/mosaic.css' layer(components);
+  @layer overrides {
+    .cl-button {
+      border-radius: 9999px;
+    }
+  }
+  ```
+
+  Their `overrides` layer wins over `components` by cascade-layer order. We keep
+  StyleX's `useCSSLayers: true` (its `@layer priorityN` handles intra-StyleX
+  precedence and nests cleanly under whatever layer the consumer imports into), so
+  we don't engineer consumer precedence at all — it's the consumer's job to place
+  our sheet in a layer. ✅
+
+- **Build:** the `@stylexjs/rollup-plugin` composes with our existing `tsdown`
+  (rolldown) build and emits a single `mosaic.css`. ✅
+
+The real cost is not feasibility — it's that StyleX's model is materially
+different from Emotion's, and the whole Mosaic recipe/appearance engine
+(`slot-recipe.ts`, `appearance.ts`, `resolveSlot.ts`, `conditions.ts`,
+`MosaicProvider`'s Emotion cache) goes away and is replaced by a much simpler
+but less dynamic model. See Trade-offs.
+
+---
+
+## The POC (what actually got built and verified)
+
+Location: `packages/ui/src/mosaic-x/`
+
+| File               | What it shows                                                              |
+| ------------------ | -------------------------------------------------------------------------- |
+| `tokens.stylex.ts` | `defineVars` with stable `--cl-*` custom properties (foreground, primary…) |
+| `button.tsx`       | A Button authored in StyleX: base + intent/variant/size/state variants     |
+| `index.ts`         | Entry that re-exports Button + token groups                                |
+| `demo.html`        | Runnable consumer-override demo (token + `.cl-button` + `data-*`)          |
+
+Build wiring (isolated from the main Emotion build so nothing else is touched):
+
+- `packages/ui/tsdown.mosaic-x.config.mts` — a dedicated tsdown build for
+  `src/mosaic-x` with the StyleX rollup plugin (`useCSSLayers: true`; the consumer
+  still owns the outer layer via `@import … layer(components)`).
+- `packages/ui/tsconfig.mosaic-x.json` — overrides `jsxImportSource` back to
+  `react` (the package default is `@emotion/react`), so the output is truly
+  Emotion-free.
+- `package.json` script: `pnpm build:mosaic-x`.
+- Deps added: `@stylexjs/stylex` (dependency), `@stylexjs/rollup-plugin`
+  (devDependency). The rollup plugin bundles its own TS/JSX Babel syntax
+  plugins, so no `@babel/preset-*` is needed on this path.
+
+Run it:
+
+```bash
+cd packages/ui
+pnpm build:mosaic-x           # → dist-mosaic-x/{index.js, index.d.ts, mosaic.css}
+open src/mosaic-x/demo.html   # visual proof of the override paths
+```
+
+### Evidence 1 — stable, overridable CSS variables
+
+Authoring (`tokens.stylex.ts`):
+
+```ts
+export const colors = stylex.defineVars({
+  '--cl-foreground': 'black',
+  '--cl-primary': 'oklch(0.205 0 0)',
+  // …
+});
+```
+
+Compiled `dist-mosaic-x/mosaic.css` (excerpt):
+
+```css
+@layer priority1, priority2, priority3, priority4;
+@layer priority1 {
+  :root,
+  .xzhe2oz {
+    --cl-foreground: black;
+    --cl-primary: #171717; /* lightningcss resolved the oklch default */
+    /* … */
+  }
+}
+```
+
+Compiled `tokens.stylex.js` — references are readable `var(--cl-*)`:
+
+```js
+export const colors = {
+  '--cl-foreground': 'var(--cl-foreground)',
+  '--cl-primary': 'var(--cl-primary)',
+  __varGroupHash__: 'xzhe2oz',
+};
+```
+
+So a consumer overrides a token with nothing but CSS:
+
+```css
+:root {
+  --cl-foreground: red;
+} /* unlayered → beats the layered default */
+```
+
+> Note: lightningcss (inside the plugin) resolved the `oklch()` _defaults_ to hex
+>
+> - `@supports (color: lab())` fallbacks. `color-mix()` expressions used inside
+>   rules are preserved as-is. This affects only the emitted default values, not
+>   the override mechanism.
+
+### Evidence 2 — stable class + `@layer` override
+
+`button.tsx` attaches a hand-authored class and merges StyleX's classes after it:
+
+```tsx
+const STABLE_CLASS = 'cl-button';
+const atomic = stylex.props(styles.base /* …conditional variants… */);
+return (
+  <button
+    className={[STABLE_CLASS, className, atomic.className].filter(Boolean).join(' ')}
+    style={atomic.style}
+    data-intent={intent}
+    data-variant={variant}
+    data-size={size}
+    {...rest}
+  />
+);
+```
+
+Server-rendered output (real, from `renderToStaticMarkup`):
+
+```html
+<button
+  type="button"
+  class="cl-button x3nfvp2 x6s0dn4 x1hew001 … …"
+  data-intent="primary"
+  data-variant="filled"
+  data-size="md"
+>
+  Primary
+</button>
+
+<!-- consumer className is preserved too: -->
+<button
+  class="cl-button my-cta x3nfvp2 …"
+  data-variant="outline"
+  …
+>
+  Danger
+</button>
+```
+
+The consumer imports our sheet into a layer they own and overrides from a later
+layer — no StyleX, no build step on their side:
+
+```css
+@layer components, overrides;
+@import '@clerk/ui/mosaic.css' layer(components);
+
+@layer overrides {
+  :root {
+    --cl-primary: rebeccapurple;
+  } /* token override */
+  .cl-button {
+    border-radius: 9999px;
+  } /* stable-class override */
+  .cl-button[data-variant='outline'] {
+    color: rebeccapurple;
+  } /* variant scope */
+}
+```
+
+`overrides` ranks above `components`, so the consumer always wins by cascade-layer
+order (an unlayered rule works too — unlayered outranks any layer). Verified in
+`demo.html`. StyleX's own `@layer priorityN` (from `useCSSLayers`) simply nests
+under `components` when imported this way; it exists only for intra-StyleX
+property precedence and does not compete with the consumer's layers.
+
+---
+
+## The stable-className nuance (important)
+
+StyleX's maintainer addresses exactly this "merge my own className" pattern in
+[discussion #442](https://github.com/facebook/stylex/discussions/442). The
+blessed merge helper:
+
+```ts
+function merge(xstyle: ReturnType<typeof stylex.props>, className?: string) {
+  return { className: classnames(className, xstyle.className), style: xstyle.style };
+}
+```
+
+His guidance is two-part:
+
+- For **styling** customization he discourages accepting arbitrary `className`
+  strings, because **mixing StyleX atomic classes and non-StyleX styles on the
+  same element is "unpredictable."**
+- For **non-styling** markers (analytics, session-replay masking, privacy tools)
+  the merge pattern "should be fine."
+
+Our requirement is _styling_ via `.cl-button`, which is the discouraged case —
+**but his "unpredictable" caveat assumes no cascade layers.** Cascade layers make
+the outcome deterministic: because the consumer imports our sheet into a layer
+they control (`@import … layer(components)`) and overrides from a later layer,
+their rule always wins by layer order. This converts "unpredictable" into
+"reliable" and makes goal #4 safe. StyleX's own `useCSSLayers` is orthogonal —
+it only orders StyleX's atomic rules among themselves.
+
+Consequences to accept:
+
+- Consumers target our **stable class + `data-*` attributes**, never the atomic
+  `x…` hashes (those are unstable across builds — never document them).
+- Layer precedence is the consumer's responsibility. We only need to ship plain
+  CSS and document the recommended `@import … layer(components)` pattern; we do
+  not have to engineer the override precedence ourselves.
+
+---
+
+## Proposed architecture
+
+### Tokens
+
+One or more `*.stylex.ts` files calling `defineVars`, keyed with `--cl-*` so the
+names are stable and public. Group by concern (`colors`, `radius`, `space`,
+`text`). Reference them in components as `colors['--cl-foreground']` → compiles
+to `var(--cl-foreground)`.
+
+Prebuilt themes (today's `dark`, `shadcn`, …) become either:
+
+- a plain CSS file that sets the `--cl-*` variables (shippable, zero-JS), or
+- a `stylex.createTheme(...)` object applied via a wrapper element.
+
+The plain-CSS route fits the "consumers own their CSS" goal best and is trivial
+to publish next to `mosaic.css`.
+
+### Components
+
+Each styled part:
+
+1. `stylex.create({...})` for base + each variant value as a separate style
+   object.
+2. A stable `cl-<slot>` class constant.
+3. Compose conditionally in `stylex.props(...)` from props, merge the stable
+   class first, spread `data-*` for attribute targeting.
+
+Variants (size/intent/variant) → conditional composition. Pseudo-states
+(`:hover`, `:focus-visible`, `:active`) and media/`prefers-reduced-motion` →
+StyleX's object-value syntax (`{ default, ':hover', '@media …' }`). `color-mix`
+and `calc` work inside values (verified).
+
+### Public contract shift
+
+| Concern           | Emotion Mosaic (today)                   | StyleX Mosaic (proposed)                        |
+| ----------------- | ---------------------------------------- | ----------------------------------------------- |
+| Token override    | `appearance.variables`                   | `:root { --cl-*: … }` in consumer CSS           |
+| Element override  | `appearance.elements[slot]`              | `.cl-<slot> { … }` in consumer CSS (unlayered)  |
+| Variant targeting | `data-cl-<axis>` attr selectors          | `data-<axis>` attrs + stable class              |
+| State targeting   | `data-cl-<state>` + `_hover`/`_disabled` | `:hover` etc. compiled in; `.cl-*` for override |
+| Per-flow scoping  | `appearance.elements[scope][slot]`       | consumer scopes with their own selectors        |
+| Delivery          | runtime `<style>` via Emotion cache      | static `mosaic.css` imported once               |
+
+---
+
+## Build & distribution
+
+**Build:** `@stylexjs/rollup-plugin` works inside `tsdown` (rolldown 1.x). It
+transforms `stylex.*` calls (its own TS/JSX syntax plugins parse the source; the
+tsdown/oxc pass strips types + lowers JSX) and emits one CSS asset. `useCSSLayers`
+must be on.
+
+**Distribution — the key question.** A consumer app must get the compiled CSS
+_and_ the transformed JS without running StyleX themselves. Two models:
+
+1. **Precompiled (recommended for Clerk).** We run StyleX at _our_ build and
+   publish transformed JS + a static `mosaic.css`. Consumers import components
+   normally and import the stylesheet once — into a cascade layer they control,
+   so their own styles can override ours by layer order:
+
+   ```css
+   @layer components, overrides;
+   @import '@clerk/ui/mosaic.css' layer(components);
+   ```
+
+   This fits how `@clerk/ui` is consumed (framework SDKs + injected into clerk-js)
+   and requires **zero** StyleX config downstream. The POC proves this output.
+
+   > Caveat: because `useCSSLayers` puts our rules in low-priority layers, the
+   > `layer()` import is the _recommended_ form. If a consumer imports the sheet
+   > with no layer wrapper, our styles become weak against their unlayered global
+   > CSS (e.g. a `button {}` reset could clobber components). Document the
+   > `@import … layer(components)` pattern as the expected usage.
+
+2. **Source distribution.** Ship `.stylex.ts` source and require every consumer
+   to run the StyleX plugin. Not viable for Clerk — consumers are arbitrary
+   Next.js/Vite/etc. apps we don't control.
+
+For clerk-js specifically (rspack UMD, runtime-injected, not an npm import for
+the app), the `mosaic.css` would be injected the same way other styles are, or
+inlined. This needs a follow-up: today Mosaic styles are injected at runtime by
+Emotion; a static stylesheet needs an explicit load path in the clerk-js runtime.
+
+**Caveat — double atomization.** If a _consumer_ also uses StyleX, our
+precompiled atomic classes and theirs won't merge/dedupe across the boundary
+(two separate StyleX outputs). With layers this is harmless (no visual bug), just
+slightly larger CSS. Document it.
+
+---
+
+## Trade-offs
+
+### What StyleX buys us
+
+- **Zero runtime styling.** No Emotion cache, no serialize-on-render, no
+  `MosaicProvider` style plumbing, no SSR hydration dance
+  (`MosaicProvider.tsx`'s insertion-point + `<Global>` workarounds all go away).
+- **Static, cacheable CSS.** One file, atomic, deduped, tree-shaken to imported
+  components. Smaller and faster than runtime injection.
+- **Deterministic cascade** via layers — the override story is a spec guarantee,
+  not specificity roulette.
+- **Native stable CSS variables** for theming — exactly the requested model.
+- **React 19 / RSC friendly** — build-time CSS sidesteps the runtime-CSS-in-JS
+  SSR problems Emotion has in modern Next.js.
+
+### What it costs
+
+- **Whole engine replaced.** `slot-recipe.ts`, `useRecipe`, `useSlot`,
+  `appearance.ts`, `resolveSlot.ts`, `conditions.ts`, `registry.ts`, and the
+  Emotion cache in `MosaicProvider` are removed or rebuilt. The `appearance` prop
+  API disappears (intended, but it's a real public-surface change — and
+  `packages/ui` non-major changes load into older SDKs in the wild, so the
+  removal must be coordinated as breaking).
+- **No runtime `appearance.elements`.** Consumers lose JS-object overrides and
+  the per-flow `scope` cascade; they move to CSS. That's the point, but it's less
+  ergonomic for programmatic theming and for prebuilt-theme composition.
+- **No arbitrary runtime styles.** StyleX dynamic styles are constrained: style
+  functions must be simple `(param) => ({...})` object literals, no logic, no
+  destructuring. Anything Mosaic computes at runtime (e.g. `theme.mix(...)`,
+  `theme.alpha(...)`, arbitrary `sx`) must become a token, a precompiled variant,
+  or a CSS `var()`/`color-mix()` expression. The `sx` escape hatch as a
+  free-form object is gone; a StyleX `sx` would only accept StyleX styles.
+- **No descendant/child selectors.** StyleX styles only the element they're on —
+  no `& > div`, no styling a child from a parent. Emotion Mosaic occasionally
+  uses nested/attribute selectors (e.g. `tabs.tsx`'s `'&[data-cl-selected]'`).
+  Those patterns must be restructured (style each part on its own element, drive
+  state by composing style objects from props). Self attribute-selectors like
+  `&[data-cl-selected]` are also unsupported — state must be a composed variant.
+- **`.stylex.ts` file constraint + build coupling.** `defineVars`/`defineConsts`
+  must live in `*.stylex.ts` files; the whole thing depends on the compiler
+  running. Debugging is "read the emitted CSS," not "inspect a JS object."
+- **Maturity.** StyleX is v0.19 (pre-1.0). API churn is possible; ecosystem is
+  smaller than Emotion's.
+- **Two systems during migration.** Emotion Mosaic and StyleX Mosaic would
+  coexist for a while; the shared reset (`:where([data-cl-slot])`) and layer
+  ordering need to be reconciled so neither stomps the other.
+
+---
+
+## Open questions / follow-ups
+
+1. **clerk-js load path** for a static `mosaic.css` (runtime-injected UMD, not an
+   npm import). Biggest unknown.
+2. **Naming contract**: lock a documented `--cl-*` token list and `.cl-<slot>`
+   class list as the public API (with a stability guarantee), since consumers
+   pin to it.
+3. **Theme delivery**: prebuilt themes as plain CSS files vs `createTheme`.
+4. **Layer story is consumer-owned** (`@import … layer(components)`), so our only
+   job is to document the recommended pattern. Still worth confirming how it
+   interacts with any legacy Emotion styles present during the migration window.
+5. **State model**: re-express the `data-cl-*` + conditions model as StyleX
+   variants + `:pseudo` while keeping `.cl-*`/`data-*` targeting for consumers.
+6. **Migration sequencing**: component-by-component behind the isolated build, or
+   a single cutover once the engine is ported.
+
+## Recommendation
+
+The requested model (CSS-var theming + stable classes + a shipped stylesheet + no
+`appearance` prop) is a **natural fit for StyleX and was proven end-to-end.** The
+decision is not "can we" but "do we accept trading Mosaic's runtime override
+engine for a static, CSS-first, zero-runtime model." Given Mosaic is greenfield
+and the explicit goal is to push customization into consumer CSS, the trade is
+favorable.
+
+Suggested next step: extend the POC to a second, harder component (a multi-part
+one like `tabs`, to exercise the no-child-selector / state-as-variant
+constraints), and resolve the clerk-js stylesheet load path — those two retire
+the remaining real risk before committing to the engine rewrite.
+
+## Reproduction / artifacts
+
+- Source: `packages/ui/src/mosaic-x/`
+- Build: `cd packages/ui && pnpm build:mosaic-x` → `packages/ui/dist-mosaic-x/`
+- Demo: open `packages/ui/src/mosaic-x/demo.html` after building
+- Configs: `packages/ui/tsdown.mosaic-x.config.mts`,
+  `packages/ui/tsconfig.mosaic-x.json`

From 29d9d57918491af41cd7b0a46e93345f3c40f13e Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 08:53:21 -0400
Subject: [PATCH 2/3] add stable class lint script

---
 eslint.config.mjs                   | 56 +++++++++++++++++++++++++++++
 packages/ui/src/mosaic-x/button.tsx | 34 ++++++++----------
 packages/ui/src/mosaic-x/index.ts   |  1 +
 packages/ui/src/mosaic-x/props.ts   | 31 ++++++++++++++++
 4 files changed, 103 insertions(+), 19 deletions(-)
 create mode 100644 packages/ui/src/mosaic-x/props.ts

diff --git a/eslint.config.mjs b/eslint.config.mjs
index 5598e5426cf..b1e5d863bf5 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -249,6 +249,54 @@ const noPhysicalCssProperties = {
   },
 };
 
+// Mosaic components expose a stable, consumer-facing class (e.g. `.cl-button`)
+// as the first argument to the `cx()` styling helper. Consumers target that
+// class in their own CSS, so it is a public contract: it must be an explicit
+// string literal in `cl-<name>` kebab-case, never derived from a variable or
+// identifier that could be renamed/minified out from under consumers.
+const mosaicStableClass = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require cx() to receive a stable cl-* class literal as its first argument',
+      recommended: false,
+    },
+    messages: {
+      missing: 'cx() must receive a stable class literal (e.g. cx("cl-button", ...)) as its first argument.',
+      notLiteral:
+        'The first argument to cx() must be a string literal (e.g. "cl-button"), not {{ got }}. Consumers target this class in their CSS, so it must stay stable and greppable rather than derived from a variable.',
+      badFormat: 'Stable class "{{ value }}" must be cl-<name> in lowercase kebab-case (e.g. "cl-button").',
+    },
+    schema: [],
+  },
+  create(context) {
+    const STABLE_CLASS = /^cl-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'Identifier' || node.callee.name !== 'cx') {
+          return;
+        }
+        const first = node.arguments[0];
+        if (!first) {
+          context.report({ node, messageId: 'missing' });
+          return;
+        }
+        if (first.type !== 'Literal' || typeof first.value !== 'string') {
+          context.report({
+            node: first,
+            messageId: 'notLiteral',
+            data: { got: first.type === 'SpreadElement' ? 'a spread' : 'a non-literal expression' },
+          });
+          return;
+        }
+        if (!STABLE_CLASS.test(first.value)) {
+          context.report({ node: first, messageId: 'badFormat', data: { value: first.value } });
+        }
+      },
+    };
+  },
+};
+
 export default tseslint.config([
   {
     name: 'repo/ignores',
@@ -325,6 +373,7 @@ export default tseslint.config([
           'no-global-object': noGlobalObject,
           'no-unstable-methods': noUnstableMethods,
           'no-physical-css-properties': noPhysicalCssProperties,
+          'mosaic-stable-class': mosaicStableClass,
         },
       },
       'simple-import-sort': pluginSimpleImportSort,
@@ -561,6 +610,13 @@ export default tseslint.config([
       ],
     },
   },
+  {
+    name: 'packages/ui/mosaic-x',
+    files: ['packages/ui/src/mosaic-x/**/*.{ts,tsx}'],
+    rules: {
+      'custom-rules/mosaic-stable-class': 'error',
+    },
+  },
   {
     name: 'packages - vitest',
     files: ['packages/*/src/**/*.test.{ts,tsx}'],
diff --git a/packages/ui/src/mosaic-x/button.tsx b/packages/ui/src/mosaic-x/button.tsx
index d5679c50a41..413b8c27777 100644
--- a/packages/ui/src/mosaic-x/button.tsx
+++ b/packages/ui/src/mosaic-x/button.tsx
@@ -1,6 +1,7 @@
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import { cx } from './props';
 import { colors, radius, space } from './tokens.stylex';
 
 // Helper to keep spacing math readable. `space['--cl-spacing']` compiles to
@@ -68,12 +69,6 @@ export interface ButtonProps extends React.ComponentPropsWithRef<'button'> {
   fullWidth?: boolean;
 }
 
-// Stable, hand-authored class every consumer can target: `.cl-button { … }`.
-// StyleX never attaches rules to this class; it exists purely as a targeting
-// hook. Consumer rules on it are unlayered and therefore beat StyleX's
-// `@layer`-wrapped atomic classes (see mosaic-stylex-migration.md).
-const STABLE_CLASS = 'cl-button';
-
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function Button(
   {
     intent = 'primary',
@@ -87,27 +82,28 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function
   },
   ref,
 ) {
-  const atomic = stylex.props(
-    styles.base,
-    variant === 'filled' && intent === 'primary' && styles.filledPrimary,
-    variant === 'filled' && intent === 'destructive' && styles.filledDestructive,
-    variant === 'outline' && styles.outlinePrimary,
-    size === 'sm' ? styles.sizeSm : styles.sizeMd,
-    fullWidth && styles.fullWidth,
-    disabled && styles.disabled,
-  );
-
   return (
     <button
       ref={ref}
       type='button'
       disabled={disabled}
-      // Order: stable class → consumer className → StyleX atomic classes.
-      className={[STABLE_CLASS, className, atomic.className].filter(Boolean).join(' ')}
-      style={atomic.style}
       data-intent={intent}
       data-variant={variant}
       data-size={size}
+      {...cx(
+        // Stable, consumer-facing targeting class: `.cl-button { … }`. Keep this a
+        // literal (enforced by the custom-rules/mosaic-stable-class lint rule) — it
+        // is a public styling contract, not an internal identifier.
+        'cl-button',
+        className,
+        styles.base,
+        variant === 'filled' && intent === 'primary' && styles.filledPrimary,
+        variant === 'filled' && intent === 'destructive' && styles.filledDestructive,
+        variant === 'outline' && styles.outlinePrimary,
+        size === 'sm' ? styles.sizeSm : styles.sizeMd,
+        fullWidth && styles.fullWidth,
+        disabled && styles.disabled,
+      )}
       {...rest}
     >
       {children}
diff --git a/packages/ui/src/mosaic-x/index.ts b/packages/ui/src/mosaic-x/index.ts
index 15343ba8a0e..6910799bb7a 100644
--- a/packages/ui/src/mosaic-x/index.ts
+++ b/packages/ui/src/mosaic-x/index.ts
@@ -1,3 +1,4 @@
 export { Button } from './button';
 export type { ButtonProps } from './button';
+export { cx } from './props';
 export { colors, radius, space } from './tokens.stylex';
diff --git a/packages/ui/src/mosaic-x/props.ts b/packages/ui/src/mosaic-x/props.ts
new file mode 100644
index 00000000000..31da83a35e3
--- /dev/null
+++ b/packages/ui/src/mosaic-x/props.ts
@@ -0,0 +1,31 @@
+import type { CompiledStyles, InlineStyles, StyleXArray } from '@stylexjs/stylex';
+import * as stylex from '@stylexjs/stylex';
+
+// Mirrors the argument type of `stylex.props`. Deriving it via
+// `Parameters<typeof stylex.props>` collapses to `never`, so we reference the
+// public style types StyleX re-exports from its root.
+type StyleArg = StyleXArray<(null | undefined | CompiledStyles) | boolean | Readonly<[CompiledStyles, InlineStyles]>>;
+
+/**
+ * Resolve a component's styling into spreadable `{ className, style }`.
+ *
+ * Folds three things into one call so components don't hand-roll the merge:
+ *   1. `stable`    — the hand-authored targeting class (e.g. `cl-button`)
+ *   2. `className` — the consumer's incoming className (may be undefined)
+ *   3. `...styles` — the StyleX style objects to compose for this render
+ *
+ * Order is deliberate: stable → consumer → StyleX atoms. The atoms live in
+ * `@layer priorityN`, so keeping the stable/consumer classes ahead of them is
+ * cosmetic (layer order decides precedence), but it keeps the emitted class
+ * list readable and predictable.
+ *
+ * Runtime note: `stylex.props` runs per render because variant selection
+ * depends on props. That is inherent to StyleX, not to this helper.
+ */
+export function cx(stable: string, className: string | undefined, ...styles: StyleArg[]) {
+  const atomic = stylex.props(...styles);
+  return {
+    className: [stable, className, atomic.className].filter(Boolean).join(' '),
+    style: atomic.style,
+  };
+}

From 190a8dd9f10549bb5edc0bbcaf104c15893cb6dc Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 17 Jul 2026 08:53:22 -0400
Subject: [PATCH 3/3] chore(ui): add cx styling helper and stable-class lint
 rule for stylex poc

Introduce a cx() helper that folds the stable targeting class, consumer
className, and StyleX atomic styles into spreadable { className, style },
and a custom-rules/mosaic-stable-class ESLint rule that requires cx()'s
first argument to be an explicit cl-* class literal (the public styling
contract). Button now inlines 'cl-button' at the call site.
---
 .changeset/mosaic-x-cx-helper.md | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 .changeset/mosaic-x-cx-helper.md

diff --git a/.changeset/mosaic-x-cx-helper.md b/.changeset/mosaic-x-cx-helper.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-x-cx-helper.md
@@ -0,0 +1,2 @@
+---
+---