From b76a9afe5b4c393a5f63943e9d20e9ae315390f0 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 12:59:59 -0400
Subject: [PATCH 01/15] feat(ui): Add experimental mosaic components export

---
 packages/ui/package.json                      |  5 ++
 packages/ui/src/experimental.ts               | 13 +++++
 packages/ui/src/mosaic/MosaicProvider.tsx     | 38 +++++++++++--
 .../mosaic/__tests__/MosaicProvider.test.tsx  | 50 ++++++++++++++++-
 .../organization-profile.controller.test.tsx  | 53 +++++++++++++++++++
 .../__tests__/organization-profile.test.tsx   | 20 +++++++
 .../aio/organization-profile.controller.tsx   | 17 ++++++
 .../src/mosaic/aio/organization-profile.tsx   | 15 ++++++
 .../src/mosaic/hooks/useMosaicEnvironment.ts  | 21 ++++++++
 .../ui/src/mosaic/hooks/useMosaicRouter.ts    | 18 +++++++
 .../delete-organization.controller.test.tsx   | 23 ++++++++
 .../leave-organization.controller.test.tsx    | 38 ++++++++++---
 .../delete-organization.controller.tsx        | 11 +++-
 .../sections/delete-organization.view.tsx     |  1 +
 .../leave-organization.controller.tsx         | 22 ++++++--
 packages/ui/src/mosaic/slot-recipe.ts         |  4 +-
 packages/ui/tsdown.config.mts                 |  1 +
 17 files changed, 328 insertions(+), 22 deletions(-)
 create mode 100644 packages/ui/src/experimental.ts
 create mode 100644 packages/ui/src/mosaic/aio/__tests__/organization-profile.controller.test.tsx
 create mode 100644 packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
 create mode 100644 packages/ui/src/mosaic/aio/organization-profile.controller.tsx
 create mode 100644 packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts
 create mode 100644 packages/ui/src/mosaic/hooks/useMosaicRouter.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index a3341049609..1df36da3e0a 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -35,6 +35,11 @@
       "import": "./dist/entry.js",
       "default": "./dist/entry.js"
     },
+    "./experimental": {
+      "types": "./dist/experimental.d.ts",
+      "import": "./dist/experimental.js",
+      "default": "./dist/experimental.js"
+    },
     "./internal": {
       "types": "./dist/internal/index.d.ts",
       "import": "./dist/internal/index.js",
diff --git a/packages/ui/src/experimental.ts b/packages/ui/src/experimental.ts
new file mode 100644
index 00000000000..d06e6736c2b
--- /dev/null
+++ b/packages/ui/src/experimental.ts
@@ -0,0 +1,13 @@
+/**
+ * Experimental entrypoint for the Mosaic design system.
+ *
+ * No semver guarantees: anything exported here may change or be removed in a minor
+ * release. Render `OrganizationProfile` under a `ClerkProvider` (for data) and a
+ * `MosaicProvider` (for styling/appearance). The profile's parts can also be rendered
+ * standalone via `OrganizationProfile.GeneralPanel`, `OrganizationProfile.LeaveSection`,
+ * and `OrganizationProfile.DeleteSection`.
+ */
+export { MosaicProvider } from './mosaic/MosaicProvider';
+export type { MosaicProviderProps } from './mosaic/MosaicProvider';
+export { OrganizationProfile } from './mosaic/aio/organization-profile';
+export type { MosaicAppearance } from './mosaic/appearance';
diff --git a/packages/ui/src/mosaic/MosaicProvider.tsx b/packages/ui/src/mosaic/MosaicProvider.tsx
index 5ed16f7ef4b..1ccc848b87d 100644
--- a/packages/ui/src/mosaic/MosaicProvider.tsx
+++ b/packages/ui/src/mosaic/MosaicProvider.tsx
@@ -1,7 +1,7 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider } from '@emotion/react';
+import { CacheProvider, Global } from '@emotion/react';
 import React from 'react';
 
 import type { MosaicAppearance } from './appearance';
@@ -9,13 +9,38 @@ import { MosaicAppearanceProvider, MosaicIconsProvider, parseMosaicAppearance }
 import type { MosaicTheme } from './variables';
 import { defaultMosaicVariables, resolveVariables } from './variables';
 
-const getInsertionPoint = (): HTMLElement | null => {
+const INSERTION_POINT_ID = 'cl-mosaic-style-insertion-point';
+
+// Anchor Emotion's <style> insertion at a known point so Mosaic's styles land in a
+// deterministic spot relative to any host styles. A host may pre-place the node; if
+// it hasn't, create it once so the consumer contract is just "wrap with MosaicProvider".
+// querySelector-first keeps this idempotent across StrictMode double-renders and
+// multiple providers.
+const ensureInsertionPoint = (): HTMLElement | null => {
   if (typeof document === 'undefined') {
     return null;
   }
-  return document.querySelector('style#cl-mosaic-style-insertion-point');
+  const existing = document.querySelector<HTMLElement>(`style#${INSERTION_POINT_ID}`);
+  if (existing) {
+    return existing;
+  }
+  const node = document.createElement('style');
+  node.id = INSERTION_POINT_ID;
+  document.head.appendChild(node);
+  return node;
 };
 
+// A single zero-specificity reset for every Mosaic part. Keyed on `data-cl-slot` — the one
+// attribute that every part emits (via useRecipe / useSlot / slot) — so it covers all authoring
+// tiers with one rule instead of bloating each element's generated css. Scoped to the attribute
+// (never a bare `*`) so it can't stomp host-app or legacy-system styles. Wrapped in `:where()` so
+// it has 0 specificity: any component class (recipe / sx / appearance) wins regardless of
+// stylesheet insertion order — a plain `[data-cl-slot]` selector (0,1,0) ties with the generated
+// class and would override it on insertion order, undoing component padding/margin.
+const mosaicReset = {
+  ':where([data-cl-slot])': { boxSizing: 'border-box', margin: 0, padding: 0, fontFamily: 'inherit' },
+} as const;
+
 const MosaicThemeContext = React.createContext<MosaicTheme | null>(null);
 
 export interface MosaicProviderProps {
@@ -33,7 +58,7 @@ export function MosaicProvider({ children, nonce, cssLayerName, appearance, scop
   const parsedElements = React.useMemo(() => parseMosaicAppearance(appearance, scope), [appearance, scope]);
   const icons = React.useMemo(() => appearance?.icons ?? {}, [appearance]);
   const cache = React.useMemo(() => {
-    const el = getInsertionPoint();
+    const el = ensureInsertionPoint();
     const emotionCache = createCache({
       key: 'cl-mosaic',
       stylisPlugins: [],
@@ -49,7 +74,10 @@ export function MosaicProvider({ children, nonce, cssLayerName, appearance, scop
     <MosaicThemeContext.Provider value={theme}>
       <MosaicAppearanceProvider value={parsedElements}>
         <MosaicIconsProvider value={icons}>
-          <CacheProvider value={cache}>{children}</CacheProvider>
+          <CacheProvider value={cache}>
+            <Global styles={mosaicReset} />
+            {children}
+          </CacheProvider>
         </MosaicIconsProvider>
       </MosaicAppearanceProvider>
     </MosaicThemeContext.Provider>
diff --git a/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx b/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx
index 1e8958c7718..d1db9db4176 100644
--- a/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx
+++ b/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx
@@ -1,6 +1,6 @@
-import { renderHook } from '@testing-library/react';
+import { render, renderHook } from '@testing-library/react';
 import React from 'react';
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 
 import type { MosaicAppearance } from '../appearance';
 import { parseMosaicAppearance, useMosaicAppearance } from '../appearance';
@@ -13,6 +13,12 @@ const appearance: MosaicAppearance = {
   },
 };
 
+// Every MosaicProvider render now self-creates the Emotion insertion-point node, so
+// clean it up after each test to keep the document fresh across the whole file.
+afterEach(() => {
+  document.querySelectorAll('style#cl-mosaic-style-insertion-point').forEach(node => node.remove());
+});
+
 describe('parseMosaicAppearance', () => {
   it('returns [] with no appearance', () => {
     expect(parseMosaicAppearance(undefined, 'signIn')).toEqual([]);
@@ -69,3 +75,43 @@ describe('MosaicProvider theme from appearance.variables', () => {
     expect(result.current.rounded.md).toBe('0.375rem');
   });
 });
+
+describe('MosaicProvider global reset', () => {
+  const styleText = () =>
+    Array.from(document.querySelectorAll('style'))
+      .map(node => node.textContent ?? '')
+      .join('');
+
+  it('emits a zero-specificity box-sizing/margin/padding reset scoped to [data-cl-slot]', () => {
+    render(React.createElement(MosaicProvider, {}, React.createElement('div')));
+
+    const css = styleText();
+    // `:where()` keeps the reset at 0 specificity so component classes always win on insertion-order ties.
+    expect(css).toContain(':where([data-cl-slot])');
+    expect(css).toContain('box-sizing:border-box');
+    expect(css).toContain('margin:0');
+    expect(css).toContain('padding:0');
+  });
+});
+
+describe('MosaicProvider Emotion insertion point', () => {
+  it('creates the insertion-point node when the host has not supplied one', () => {
+    expect(document.querySelector('style#cl-mosaic-style-insertion-point')).toBeNull();
+
+    render(React.createElement(MosaicProvider, {}, React.createElement('div')));
+
+    expect(document.querySelectorAll('style#cl-mosaic-style-insertion-point')).toHaveLength(1);
+  });
+
+  it('reuses a host-supplied node instead of creating a second one', () => {
+    const existing = document.createElement('style');
+    existing.id = 'cl-mosaic-style-insertion-point';
+    document.head.appendChild(existing);
+
+    render(React.createElement(MosaicProvider, {}, React.createElement('div')));
+
+    const nodes = document.querySelectorAll('style#cl-mosaic-style-insertion-point');
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]).toBe(existing);
+  });
+});
diff --git a/packages/ui/src/mosaic/aio/__tests__/organization-profile.controller.test.tsx b/packages/ui/src/mosaic/aio/__tests__/organization-profile.controller.test.tsx
new file mode 100644
index 00000000000..8b95be3810d
--- /dev/null
+++ b/packages/ui/src/mosaic/aio/__tests__/organization-profile.controller.test.tsx
@@ -0,0 +1,53 @@
+import { render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useOrganizationProfileController } from '../organization-profile.controller';
+
+let isLoaded: boolean;
+let organization: { id: string; name: string } | null;
+
+vi.mock('@clerk/shared/react', async importOriginal => {
+  const actual = await importOriginal<typeof import('@clerk/shared/react')>();
+  return {
+    ...actual,
+    useOrganization: () => ({ isLoaded, organization, membership: null }),
+  };
+});
+
+beforeEach(() => {
+  isLoaded = true;
+  organization = { id: 'org_1', name: 'Acme Inc' };
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+function Harness() {
+  const controller = useOrganizationProfileController();
+  return <output data-testid='state'>{controller.status}</output>;
+}
+
+describe('useOrganizationProfileController', () => {
+  it('is loading until useOrganization is loaded', () => {
+    isLoaded = false;
+
+    render(<Harness />);
+
+    expect(screen.getByTestId('state')).toHaveTextContent('loading');
+  });
+
+  it('is hidden when there is no active organization', () => {
+    organization = null;
+
+    render(<Harness />);
+
+    expect(screen.getByTestId('state')).toHaveTextContent('hidden');
+  });
+
+  it('is ready when an organization is loaded', () => {
+    render(<Harness />);
+
+    expect(screen.getByTestId('state')).toHaveTextContent('ready');
+  });
+});
diff --git a/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx b/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
new file mode 100644
index 00000000000..78c6ab42cab
--- /dev/null
+++ b/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+
+import { OrganizationProfileGeneral } from '../../panels/organization-profile-general';
+import { DeleteOrganization } from '../../sections/delete-organization';
+import { LeaveOrganization } from '../../sections/leave-organization';
+import { OrganizationProfile } from '../organization-profile';
+
+describe('OrganizationProfile compound parts', () => {
+  it('exposes the general panel as a standalone part', () => {
+    expect(OrganizationProfile.GeneralPanel).toBe(OrganizationProfileGeneral);
+  });
+
+  it('exposes the leave section as a standalone part', () => {
+    expect(OrganizationProfile.LeaveSection).toBe(LeaveOrganization);
+  });
+
+  it('exposes the delete section as a standalone part', () => {
+    expect(OrganizationProfile.DeleteSection).toBe(DeleteOrganization);
+  });
+});
diff --git a/packages/ui/src/mosaic/aio/organization-profile.controller.tsx b/packages/ui/src/mosaic/aio/organization-profile.controller.tsx
new file mode 100644
index 00000000000..dce75be08e6
--- /dev/null
+++ b/packages/ui/src/mosaic/aio/organization-profile.controller.tsx
@@ -0,0 +1,17 @@
+import { useOrganization } from '@clerk/shared/react';
+
+type OrganizationProfileController = { status: 'loading' } | { status: 'hidden' } | { status: 'ready' };
+
+export function useOrganizationProfileController(): OrganizationProfileController {
+  const { isLoaded, organization } = useOrganization();
+
+  if (!isLoaded) {
+    return { status: 'loading' };
+  }
+
+  if (!organization) {
+    return { status: 'hidden' };
+  }
+
+  return { status: 'ready' };
+}
diff --git a/packages/ui/src/mosaic/aio/organization-profile.tsx b/packages/ui/src/mosaic/aio/organization-profile.tsx
index 01f59620361..1c5668a57d9 100644
--- a/packages/ui/src/mosaic/aio/organization-profile.tsx
+++ b/packages/ui/src/mosaic/aio/organization-profile.tsx
@@ -1,6 +1,21 @@
 import { OrganizationProfileGeneral } from '../panels/organization-profile-general';
+import { DeleteOrganization } from '../sections/delete-organization';
+import { LeaveOrganization } from '../sections/leave-organization';
+import { useOrganizationProfileController } from './organization-profile.controller';
 import { OrganizationProfileView } from './organization-profile-view';
 
 export function OrganizationProfile() {
+  const controller = useOrganizationProfileController();
+  if (controller.status !== 'ready') {
+    return null;
+  }
   return <OrganizationProfileView general={<OrganizationProfileGeneral />} />;
 }
+
+// Standalone parts of the profile, exposed via the compound namespace (mirrors the
+// Card.Root/Tabs.Root convention). Each part is self-gating and only needs a
+// MosaicProvider ancestor, so consumers can render any of them on their own — there
+// is no shared Root context to host.
+OrganizationProfile.GeneralPanel = OrganizationProfileGeneral;
+OrganizationProfile.LeaveSection = LeaveOrganization;
+OrganizationProfile.DeleteSection = DeleteOrganization;
diff --git a/packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts b/packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts
new file mode 100644
index 00000000000..f5712716ec4
--- /dev/null
+++ b/packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts
@@ -0,0 +1,21 @@
+import { useClerk } from '@clerk/shared/react';
+import type { EnvironmentResource } from '@clerk/shared/types';
+
+/**
+ * The single seam through which Mosaic reads the active Clerk environment.
+ *
+ * In the app-direct model (`ClerkProvider` → `MosaicProvider` → component) clerk-js's
+ * own `useEnvironment()` context is not mounted, so the only host-agnostic way to reach
+ * the environment is `clerk.__internal_environment`. Quarantining that one private
+ * access here keeps the `@ts-expect-error` out of every caller: read whatever field you
+ * need (`displayConfig`, `authConfig`, …) off the returned resource.
+ *
+ * Returns `undefined` until the environment hydrates; callers should handle that.
+ */
+export function useMosaicEnvironment(): EnvironmentResource | undefined {
+  const clerk = useClerk();
+  // @ts-expect-error -- `__internal_environment` is a private Clerk surface for now.
+  // SAFETY: read-only access to the loaded environment resource, mirroring
+  // components/devPrompts/KeylessPrompt/use-revalidate-environment.ts.
+  return clerk.__internal_environment ?? undefined;
+}
diff --git a/packages/ui/src/mosaic/hooks/useMosaicRouter.ts b/packages/ui/src/mosaic/hooks/useMosaicRouter.ts
new file mode 100644
index 00000000000..2a5d3e2f0c2
--- /dev/null
+++ b/packages/ui/src/mosaic/hooks/useMosaicRouter.ts
@@ -0,0 +1,18 @@
+import { useClerk } from '@clerk/shared/react';
+
+export interface MosaicRouter {
+  navigate: (to: string) => void | Promise<unknown>;
+}
+
+/**
+ * Host-agnostic navigation seam for Mosaic.
+ *
+ * Delegates to `clerk.navigate`, which already routes through the host app's
+ * `routerPush`/`routerReplace`. Controllers depend on this hook rather than on
+ * Clerk internals, so a future clerk-js mount path or a dedicated Mosaic router
+ * only has to change this one file.
+ */
+export function useMosaicRouter(): MosaicRouter {
+  const clerk = useClerk();
+  return { navigate: to => clerk.navigate(to) };
+}
diff --git a/packages/ui/src/mosaic/sections/__tests__/delete-organization.controller.test.tsx b/packages/ui/src/mosaic/sections/__tests__/delete-organization.controller.test.tsx
index 0270e0dd9ca..7c46d47520e 100644
--- a/packages/ui/src/mosaic/sections/__tests__/delete-organization.controller.test.tsx
+++ b/packages/ui/src/mosaic/sections/__tests__/delete-organization.controller.test.tsx
@@ -8,6 +8,8 @@ const ORG_NAME = 'Acme Inc';
 
 let destroy: ReturnType<typeof vi.fn>;
 let revalidate: ReturnType<typeof vi.fn>;
+let navigate: ReturnType<typeof vi.fn>;
+let afterLeaveUrl: string;
 let checkAuthorization: ReturnType<typeof vi.fn>;
 let isLoaded: boolean;
 let isSessionLoaded: boolean;
@@ -23,12 +25,18 @@ vi.mock('@clerk/shared/react', async importOriginal => {
       isLoaded: isSessionLoaded,
       session: isSessionLoaded ? { id: 'sess_1', checkAuthorization } : undefined,
     }),
+    useClerk: () => ({
+      navigate,
+      __internal_environment: { displayConfig: { afterLeaveOrganizationUrl: afterLeaveUrl } },
+    }),
   };
 });
 
 beforeEach(() => {
   destroy = vi.fn();
   revalidate = vi.fn().mockResolvedValue(undefined);
+  navigate = vi.fn().mockResolvedValue(undefined);
+  afterLeaveUrl = '/after-leave';
   checkAuthorization = vi.fn().mockReturnValue(true);
   isLoaded = true;
   isSessionLoaded = true;
@@ -121,6 +129,20 @@ describe('useDeleteOrganizationController', () => {
     expect(revalidate).toHaveBeenCalledTimes(1);
   });
 
+  it('navigates to afterLeaveOrganizationUrl after a successful delete', async () => {
+    const gate = deferred<void>();
+    destroy.mockReturnValue(gate.promise);
+
+    render(<Harness />);
+    openAndConfirm();
+
+    await act(async () => {
+      gate.resolve();
+    });
+
+    expect(navigate).toHaveBeenCalledWith('/after-leave');
+  });
+
   it('returns to confirming with an error message when deleting rejects', async () => {
     const gate = deferred<void>();
     destroy.mockReturnValue(gate.promise);
@@ -136,5 +158,6 @@ describe('useDeleteOrganizationController', () => {
     expect(screen.getByTestId('state')).toHaveTextContent('confirming');
     expect(screen.getByTestId('error')).toHaveTextContent('nope');
     expect(revalidate).not.toHaveBeenCalled();
+    expect(navigate).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/ui/src/mosaic/sections/__tests__/leave-organization.controller.test.tsx b/packages/ui/src/mosaic/sections/__tests__/leave-organization.controller.test.tsx
index c9bac90ea88..4c1242cc7a4 100644
--- a/packages/ui/src/mosaic/sections/__tests__/leave-organization.controller.test.tsx
+++ b/packages/ui/src/mosaic/sections/__tests__/leave-organization.controller.test.tsx
@@ -6,11 +6,13 @@ import { useLeaveOrganizationController } from '../leave-organization.controller
 
 const ORG_NAME = 'Acme Inc';
 
-let destroy: ReturnType<typeof vi.fn>;
+let leaveOrganization: ReturnType<typeof vi.fn>;
 let revalidate: ReturnType<typeof vi.fn>;
+let navigate: ReturnType<typeof vi.fn>;
+let afterLeaveUrl: string;
 let isLoaded: boolean;
 let organization: { id: string; name: string } | null;
-let membership: { id: string; destroy: () => Promise<void> } | null | undefined;
+let membership: { id: string } | null | undefined;
 
 vi.mock('@clerk/shared/react', async importOriginal => {
   const actual = await importOriginal<typeof import('@clerk/shared/react')>();
@@ -18,15 +20,22 @@ vi.mock('@clerk/shared/react', async importOriginal => {
     ...actual,
     useOrganization: () => ({ isLoaded, organization, membership }),
     useOrganizationList: () => ({ userMemberships: { revalidate } }),
+    useUser: () => ({ user: { leaveOrganization } }),
+    useClerk: () => ({
+      navigate,
+      __internal_environment: { displayConfig: { afterLeaveOrganizationUrl: afterLeaveUrl } },
+    }),
   };
 });
 
 beforeEach(() => {
-  destroy = vi.fn();
+  leaveOrganization = vi.fn();
   revalidate = vi.fn().mockResolvedValue(undefined);
+  navigate = vi.fn().mockResolvedValue(undefined);
+  afterLeaveUrl = '/after-leave';
   isLoaded = true;
   organization = { id: 'org_1', name: ORG_NAME };
-  membership = { id: 'mem_1', destroy };
+  membership = { id: 'mem_1' };
 });
 
 afterEach(() => {
@@ -90,7 +99,7 @@ describe('useLeaveOrganizationController', () => {
 
   it('drives CONFIRM → leaving → resolve → left', async () => {
     const gate = deferred<void>();
-    destroy.mockReturnValue(gate.promise);
+    leaveOrganization.mockReturnValue(gate.promise);
 
     render(<Harness />);
     expect(screen.getByTestId('state')).toHaveTextContent('idle');
@@ -103,13 +112,27 @@ describe('useLeaveOrganizationController', () => {
     });
 
     expect(screen.getByTestId('state')).toHaveTextContent('left');
-    expect(destroy).toHaveBeenCalledTimes(1);
+    expect(leaveOrganization).toHaveBeenCalledWith('org_1');
     expect(revalidate).toHaveBeenCalledTimes(1);
   });
 
+  it('navigates to afterLeaveOrganizationUrl after a successful leave', async () => {
+    const gate = deferred<void>();
+    leaveOrganization.mockReturnValue(gate.promise);
+
+    render(<Harness />);
+    openAndConfirm();
+
+    await act(async () => {
+      gate.resolve();
+    });
+
+    expect(navigate).toHaveBeenCalledWith('/after-leave');
+  });
+
   it('returns to confirming with an error message when leaving rejects', async () => {
     const gate = deferred<void>();
-    destroy.mockReturnValue(gate.promise);
+    leaveOrganization.mockReturnValue(gate.promise);
 
     render(<Harness />);
     openAndConfirm();
@@ -122,5 +145,6 @@ describe('useLeaveOrganizationController', () => {
     expect(screen.getByTestId('state')).toHaveTextContent('confirming');
     expect(screen.getByTestId('error')).toHaveTextContent('nope');
     expect(revalidate).not.toHaveBeenCalled();
+    expect(navigate).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/ui/src/mosaic/sections/delete-organization.controller.tsx b/packages/ui/src/mosaic/sections/delete-organization.controller.tsx
index 3a1b17843a8..454069c3fd5 100644
--- a/packages/ui/src/mosaic/sections/delete-organization.controller.tsx
+++ b/packages/ui/src/mosaic/sections/delete-organization.controller.tsx
@@ -1,5 +1,7 @@
 import { useOrganization, useOrganizationList, useSession } from '@clerk/shared/react';
 
+import { useMosaicEnvironment } from '../hooks/useMosaicEnvironment';
+import { useMosaicRouter } from '../hooks/useMosaicRouter';
 import type { Snapshot } from '../machine/types';
 import { useMachine } from '../machine/useMachine';
 import type { DeleteOrgContext, DeleteOrgEvent } from './delete-organization.machine';
@@ -19,6 +21,8 @@ export function useDeleteOrganizationController(): DeleteOrganizationController
   const { isLoaded: isOrganizationLoaded, organization } = useOrganization();
   const { isLoaded: isSessionLoaded, session } = useSession();
   const { userMemberships } = useOrganizationList({ userMemberships: true });
+  const router = useMosaicRouter();
+  const afterLeaveUrl = useMosaicEnvironment()?.displayConfig.afterLeaveOrganizationUrl;
 
   const [snapshot, send, actor] = useMachine(deleteOrgMachine, {
     context: {
@@ -28,8 +32,11 @@ export function useDeleteOrganizationController(): DeleteOrganizationController
         // Refresh org lists elsewhere (e.g. the switcher). Not awaited: a stale
         // list must not make a successful delete look like it failed.
         void userMemberships.revalidate?.();
-        // TODO(mosaic): navigate away from the deleted org's profile once the flow
-        // has router context, mirroring legacy navigateAfterLeaveOrganization.
+        // Navigate away from the deleted org's profile, mirroring legacy
+        // navigateAfterLeaveOrganization. Fire-and-forget for the same reason.
+        if (afterLeaveUrl) {
+          void router.navigate(afterLeaveUrl);
+        }
       },
     },
   });
diff --git a/packages/ui/src/mosaic/sections/delete-organization.view.tsx b/packages/ui/src/mosaic/sections/delete-organization.view.tsx
index 74e95812a24..46fdc1353fe 100644
--- a/packages/ui/src/mosaic/sections/delete-organization.view.tsx
+++ b/packages/ui/src/mosaic/sections/delete-organization.view.tsx
@@ -62,6 +62,7 @@ export function DeleteOrganizationView({ snapshot, send, canSubmit }: DeleteOrga
               sx={{
                 flexShrink: 0,
               }}
+              type='button'
             >
               Delete organization
             </Button>
diff --git a/packages/ui/src/mosaic/sections/leave-organization.controller.tsx b/packages/ui/src/mosaic/sections/leave-organization.controller.tsx
index b5e1a28d1a1..58eb3d512a2 100644
--- a/packages/ui/src/mosaic/sections/leave-organization.controller.tsx
+++ b/packages/ui/src/mosaic/sections/leave-organization.controller.tsx
@@ -1,5 +1,7 @@
-import { useOrganization, useOrganizationList } from '@clerk/shared/react';
+import { useOrganization, useOrganizationList, useUser } from '@clerk/shared/react';
 
+import { useMosaicEnvironment } from '../hooks/useMosaicEnvironment';
+import { useMosaicRouter } from '../hooks/useMosaicRouter';
 import type { Snapshot } from '../machine/types';
 import { useMachine } from '../machine/useMachine';
 import type { LeaveOrgContext, LeaveOrgEvent } from './leave-organization.machine';
@@ -17,18 +19,30 @@ type LeaveOrganizationController =
 
 export function useLeaveOrganizationController(): LeaveOrganizationController {
   const { isLoaded, organization, membership } = useOrganization();
+  const { user } = useUser();
   const { userMemberships } = useOrganizationList({ userMemberships: true });
+  const router = useMosaicRouter();
+  const afterLeaveUrl = useMosaicEnvironment()?.displayConfig.afterLeaveOrganizationUrl;
 
   const [snapshot, send, actor] = useMachine(leaveOrgMachine, {
     context: {
       organizationName: organization?.name ?? '',
       leaveOrganization: async () => {
-        await membership?.destroy();
+        // Self-leave hits `/me/organization_memberships/{orgId}`. `membership.destroy()`
+        // is the admin remove-member endpoint (needs publicUserData.userId, which the
+        // current user's own membership lacks), so it 404s — mirror legacy and use
+        // `user.leaveOrganization`.
+        if (organization) {
+          await user?.leaveOrganization(organization.id);
+        }
         // Refresh org lists elsewhere (e.g. the switcher). Not awaited: a stale
         // list must not make a successful leave look like it failed.
         void userMemberships.revalidate?.();
-        // TODO(mosaic): navigate away from the left org's profile once the flow
-        // has router context, mirroring legacy navigateAfterLeaveOrganization.
+        // Navigate away from the left org's profile, mirroring legacy
+        // navigateAfterLeaveOrganization. Fire-and-forget for the same reason.
+        if (afterLeaveUrl) {
+          void router.navigate(afterLeaveUrl);
+        }
       },
     },
   });
diff --git a/packages/ui/src/mosaic/slot-recipe.ts b/packages/ui/src/mosaic/slot-recipe.ts
index 33c4797ae09..74880262085 100644
--- a/packages/ui/src/mosaic/slot-recipe.ts
+++ b/packages/ui/src/mosaic/slot-recipe.ts
@@ -2,12 +2,12 @@ import { fastDeepMergeAndReplace } from '@clerk/shared/utils';
 import type * as CSS from 'csstype';
 
 import { useMosaicAppearance } from './appearance';
-import { expandConditions } from './conditions';
 import type { MosaicConditionKey } from './conditions';
+import { expandConditions } from './conditions';
 import { useMosaicTheme } from './MosaicProvider';
 import { resolveSlotClassName, resolveSlotCss } from './resolveSlot';
-import { defaultMosaicVariables, resolveVariables } from './variables';
 import type { MosaicTheme } from './variables';
+import { defaultMosaicVariables, resolveVariables } from './variables';
 
 // ─── Public Types ─────────────────────────────────────────────────────────────
 
diff --git a/packages/ui/tsdown.config.mts b/packages/ui/tsdown.config.mts
index fcf7e5e089e..49d6400c0f2 100644
--- a/packages/ui/tsdown.config.mts
+++ b/packages/ui/tsdown.config.mts
@@ -37,6 +37,7 @@ export default defineConfig(({ watch }) => {
       entry: [
         './src/index.ts',
         './src/entry.ts',
+        './src/experimental.ts',
         './src/server.ts',
         './src/internal/index.ts',
         './src/themes/index.ts',

From ce12ff32a6078c0c4fbb3ded300e2d5e0b08e019 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 13:33:58 -0400
Subject: [PATCH 02/15] add changeset

---
 .changeset/open-heads-brush.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/open-heads-brush.md

diff --git a/.changeset/open-heads-brush.md b/.changeset/open-heads-brush.md
new file mode 100644
index 00000000000..96f7dd95ba7
--- /dev/null
+++ b/.changeset/open-heads-brush.md
@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Export experimental mosaic components.

From 82fddc85fd6353d1efce35fa308bf02b7648c6d8 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 14:22:41 -0400
Subject: [PATCH 03/15] add explicit return types

---
 packages/ui/src/mosaic/MosaicProvider.tsx             | 11 ++++++++++-
 packages/ui/src/mosaic/aio/organization-profile.tsx   |  4 +++-
 .../mosaic/panels/organization-profile-general.tsx    |  4 +++-
 .../ui/src/mosaic/sections/delete-organization.tsx    |  4 +++-
 .../ui/src/mosaic/sections/leave-organization.tsx     |  4 +++-
 5 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/mosaic/MosaicProvider.tsx b/packages/ui/src/mosaic/MosaicProvider.tsx
index 1ccc848b87d..8a6d8256ca4 100644
--- a/packages/ui/src/mosaic/MosaicProvider.tsx
+++ b/packages/ui/src/mosaic/MosaicProvider.tsx
@@ -53,7 +53,16 @@ export interface MosaicProviderProps {
   scope?: string;
 }
 
-export function MosaicProvider({ children, nonce, cssLayerName, appearance, scope }: MosaicProviderProps) {
+// Exported Mosaic components annotate a React return type on purpose. The package sets
+// `jsxImportSource: '@emotion/react'`, so an inferred return leaks Emotion's `JSX.Element` into the
+// published `.d.ts`, which React 19 consumers reject as a JSX element type.
+export function MosaicProvider({
+  children,
+  nonce,
+  cssLayerName,
+  appearance,
+  scope,
+}: MosaicProviderProps): React.ReactElement {
   const theme = React.useMemo(() => resolveVariables(defaultMosaicVariables, appearance?.variables), [appearance]);
   const parsedElements = React.useMemo(() => parseMosaicAppearance(appearance, scope), [appearance, scope]);
   const icons = React.useMemo(() => appearance?.icons ?? {}, [appearance]);
diff --git a/packages/ui/src/mosaic/aio/organization-profile.tsx b/packages/ui/src/mosaic/aio/organization-profile.tsx
index 1c5668a57d9..329b5e33164 100644
--- a/packages/ui/src/mosaic/aio/organization-profile.tsx
+++ b/packages/ui/src/mosaic/aio/organization-profile.tsx
@@ -1,10 +1,12 @@
+import type { ReactElement } from 'react';
+
 import { OrganizationProfileGeneral } from '../panels/organization-profile-general';
 import { DeleteOrganization } from '../sections/delete-organization';
 import { LeaveOrganization } from '../sections/leave-organization';
 import { useOrganizationProfileController } from './organization-profile.controller';
 import { OrganizationProfileView } from './organization-profile-view';
 
-export function OrganizationProfile() {
+export function OrganizationProfile(): ReactElement | null {
   const controller = useOrganizationProfileController();
   if (controller.status !== 'ready') {
     return null;
diff --git a/packages/ui/src/mosaic/panels/organization-profile-general.tsx b/packages/ui/src/mosaic/panels/organization-profile-general.tsx
index 7aca4421094..80f894609b1 100644
--- a/packages/ui/src/mosaic/panels/organization-profile-general.tsx
+++ b/packages/ui/src/mosaic/panels/organization-profile-general.tsx
@@ -1,8 +1,10 @@
+import type { ReactElement } from 'react';
+
 import { DeleteOrganization } from '../sections/delete-organization';
 import { LeaveOrganization } from '../sections/leave-organization';
 import { OrganizationProfileGeneralView } from './organization-profile-general-view';
 
-export function OrganizationProfileGeneral() {
+export function OrganizationProfileGeneral(): ReactElement {
   return (
     <OrganizationProfileGeneralView
       leaveOrganization={<LeaveOrganization />}
diff --git a/packages/ui/src/mosaic/sections/delete-organization.tsx b/packages/ui/src/mosaic/sections/delete-organization.tsx
index 208ff061765..66be0a8bb36 100644
--- a/packages/ui/src/mosaic/sections/delete-organization.tsx
+++ b/packages/ui/src/mosaic/sections/delete-organization.tsx
@@ -1,7 +1,9 @@
+import type { ReactElement } from 'react';
+
 import { useDeleteOrganizationController } from './delete-organization.controller';
 import { DeleteOrganizationView } from './delete-organization.view';
 
-export function DeleteOrganization() {
+export function DeleteOrganization(): ReactElement | null {
   const controller = useDeleteOrganizationController();
   if (controller.status !== 'ready') {
     return null;
diff --git a/packages/ui/src/mosaic/sections/leave-organization.tsx b/packages/ui/src/mosaic/sections/leave-organization.tsx
index 4b1147c2617..28f0c8a08bf 100644
--- a/packages/ui/src/mosaic/sections/leave-organization.tsx
+++ b/packages/ui/src/mosaic/sections/leave-organization.tsx
@@ -1,7 +1,9 @@
+import type { ReactElement } from 'react';
+
 import { useLeaveOrganizationController } from './leave-organization.controller';
 import { LeaveOrganizationView } from './leave-organization.view';
 
-export function LeaveOrganization() {
+export function LeaveOrganization(): ReactElement | null {
   const controller = useLeaveOrganizationController();
   if (controller.status !== 'ready') {
     return null;

From e25d14ee5fe3459abb50c07c858427d2c3f3557d Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 14:42:31 -0400
Subject: [PATCH 04/15] update comment

---
 packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts b/packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts
index f5712716ec4..0bfcd90e055 100644
--- a/packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts
+++ b/packages/ui/src/mosaic/hooks/useMosaicEnvironment.ts
@@ -7,8 +7,14 @@ import type { EnvironmentResource } from '@clerk/shared/types';
  * In the app-direct model (`ClerkProvider` → `MosaicProvider` → component) clerk-js's
  * own `useEnvironment()` context is not mounted, so the only host-agnostic way to reach
  * the environment is `clerk.__internal_environment`. Quarantining that one private
- * access here keeps the `@ts-expect-error` out of every caller: read whatever field you
- * need (`displayConfig`, `authConfig`, …) off the returned resource.
+ * access here keeps the `@ts-expect-error` out of every caller.
+ *
+ * This is a one-shot read off the Clerk singleton, NOT a reactive subscription: unlike
+ * clerk-js's `EnvironmentProvider`, `useClerk()` does not re-render when the environment
+ * mutates. So only read fields that are set once at hydration and never change at runtime
+ * (e.g. static `displayConfig` URLs). Anything that can mutate post-hydration
+ * (`authConfig.claimedAt`, live config toggles) will render stale through this hook and
+ * needs a real reactive subscription instead (see `use-revalidate-environment.ts`).
  *
  * Returns `undefined` until the environment hydrates; callers should handle that.
  */

From fe45e3d404454798c3ee48258a81c84545d56acc Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 14:49:31 -0400
Subject: [PATCH 05/15] Update experimental.ts

---
 packages/ui/src/experimental.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/ui/src/experimental.ts b/packages/ui/src/experimental.ts
index d06e6736c2b..32c3266e36a 100644
--- a/packages/ui/src/experimental.ts
+++ b/packages/ui/src/experimental.ts
@@ -1,3 +1,5 @@
+'use client';
+
 /**
  * Experimental entrypoint for the Mosaic design system.
  *

From 41842dc6f108394796f340b0049c37cdf1e7aa8f Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 14:56:49 -0400
Subject: [PATCH 06/15] move exports to /experimental/mosaic

---
 packages/ui/package.json               |  8 ++++----
 packages/ui/src/experimental.ts        | 15 ---------------
 packages/ui/src/experimental/mosaic.ts | 20 ++++++++++++++++++++
 packages/ui/tsdown.config.mts          |  2 +-
 4 files changed, 25 insertions(+), 20 deletions(-)
 delete mode 100644 packages/ui/src/experimental.ts
 create mode 100644 packages/ui/src/experimental/mosaic.ts

diff --git a/packages/ui/package.json b/packages/ui/package.json
index 1df36da3e0a..c48e5195156 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -35,10 +35,10 @@
       "import": "./dist/entry.js",
       "default": "./dist/entry.js"
     },
-    "./experimental": {
-      "types": "./dist/experimental.d.ts",
-      "import": "./dist/experimental.js",
-      "default": "./dist/experimental.js"
+    "./experimental/mosaic": {
+      "types": "./dist/experimental/mosaic.d.ts",
+      "import": "./dist/experimental/mosaic.js",
+      "default": "./dist/experimental/mosaic.js"
     },
     "./internal": {
       "types": "./dist/internal/index.d.ts",
diff --git a/packages/ui/src/experimental.ts b/packages/ui/src/experimental.ts
deleted file mode 100644
index 32c3266e36a..00000000000
--- a/packages/ui/src/experimental.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-'use client';
-
-/**
- * Experimental entrypoint for the Mosaic design system.
- *
- * No semver guarantees: anything exported here may change or be removed in a minor
- * release. Render `OrganizationProfile` under a `ClerkProvider` (for data) and a
- * `MosaicProvider` (for styling/appearance). The profile's parts can also be rendered
- * standalone via `OrganizationProfile.GeneralPanel`, `OrganizationProfile.LeaveSection`,
- * and `OrganizationProfile.DeleteSection`.
- */
-export { MosaicProvider } from './mosaic/MosaicProvider';
-export type { MosaicProviderProps } from './mosaic/MosaicProvider';
-export { OrganizationProfile } from './mosaic/aio/organization-profile';
-export type { MosaicAppearance } from './mosaic/appearance';
diff --git a/packages/ui/src/experimental/mosaic.ts b/packages/ui/src/experimental/mosaic.ts
new file mode 100644
index 00000000000..af8d842e6fd
--- /dev/null
+++ b/packages/ui/src/experimental/mosaic.ts
@@ -0,0 +1,20 @@
+'use client';
+
+/**
+ * Experimental entrypoint for the Mosaic design system.
+ *
+ * No semver guarantees: anything exported here may change or be removed in a minor
+ * release. Render `OrganizationProfile` under a `ClerkProvider` (for data) and a
+ * `MosaicProvider` (for styling/appearance). The profile's parts can also be rendered
+ * standalone via `OrganizationProfile.GeneralPanel`, `OrganizationProfile.LeaveSection`,
+ * and `OrganizationProfile.DeleteSection`.
+ *
+ * This entry carries a `'use client'` boundary because every Mosaic component is
+ * client-only (React context, hooks, emotion). It lives under `experimental/mosaic`
+ * rather than the generic `experimental` so that boundary stays scoped to Mosaic and
+ * does not force a client directive onto unrelated experimental exports.
+ */
+export { MosaicProvider } from '../mosaic/MosaicProvider';
+export type { MosaicProviderProps } from '../mosaic/MosaicProvider';
+export { OrganizationProfile } from '../mosaic/aio/organization-profile';
+export type { MosaicAppearance } from '../mosaic/appearance';
diff --git a/packages/ui/tsdown.config.mts b/packages/ui/tsdown.config.mts
index 49d6400c0f2..26582cdc482 100644
--- a/packages/ui/tsdown.config.mts
+++ b/packages/ui/tsdown.config.mts
@@ -37,7 +37,7 @@ export default defineConfig(({ watch }) => {
       entry: [
         './src/index.ts',
         './src/entry.ts',
-        './src/experimental.ts',
+        './src/experimental/mosaic.ts',
         './src/server.ts',
         './src/internal/index.ts',
         './src/themes/index.ts',

From 83ba74a05ed46e723306e69a21e23e278e4e08dd Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 15:09:18 -0400
Subject: [PATCH 07/15] fix exports

---
 .../src/mosaic/aio/organization-profile.tsx   | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/packages/ui/src/mosaic/aio/organization-profile.tsx b/packages/ui/src/mosaic/aio/organization-profile.tsx
index 329b5e33164..7fc75f2ab8a 100644
--- a/packages/ui/src/mosaic/aio/organization-profile.tsx
+++ b/packages/ui/src/mosaic/aio/organization-profile.tsx
@@ -6,7 +6,7 @@ import { LeaveOrganization } from '../sections/leave-organization';
 import { useOrganizationProfileController } from './organization-profile.controller';
 import { OrganizationProfileView } from './organization-profile-view';
 
-export function OrganizationProfile(): ReactElement | null {
+function OrganizationProfileRoot(): ReactElement | null {
   const controller = useOrganizationProfileController();
   if (controller.status !== 'ready') {
     return null;
@@ -14,10 +14,17 @@ export function OrganizationProfile(): ReactElement | null {
   return <OrganizationProfileView general={<OrganizationProfileGeneral />} />;
 }
 
-// Standalone parts of the profile, exposed via the compound namespace (mirrors the
-// Card.Root/Tabs.Root convention). Each part is self-gating and only needs a
-// MosaicProvider ancestor, so consumers can render any of them on their own — there
-// is no shared Root context to host.
-OrganizationProfile.GeneralPanel = OrganizationProfileGeneral;
-OrganizationProfile.LeaveSection = LeaveOrganization;
-OrganizationProfile.DeleteSection = DeleteOrganization;
+// Standalone parts of the profile, exposed via the compound namespace. Each part is
+// self-gating and only needs a MosaicProvider ancestor, so consumers can render any of
+// them on their own — there is no shared Root context to host.
+//
+// Attached with Object.assign rather than the in-repo `Card.Root = Root` statement form on
+// purpose: this package ships `sideEffects` restricted to two files, so a consumer's
+// tree-shaking bundler treats this module as side-effect-free and drops bare
+// `OrganizationProfile.X = ...` statements, leaving the parts `undefined` at runtime. Folding
+// them into the exported binding's initializer keeps them attached across that boundary.
+export const OrganizationProfile = Object.assign(OrganizationProfileRoot, {
+  GeneralPanel: OrganizationProfileGeneral,
+  LeaveSection: LeaveOrganization,
+  DeleteSection: DeleteOrganization,
+});

From 858ca82efcca9337d482420e98bc21d865843e1e Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 15:49:38 -0400
Subject: [PATCH 08/15] export flat exports

---
 .../experimental/__tests__/mosaic.test.tsx    | 34 +++++++++++++++++++
 packages/ui/src/experimental/mosaic.ts        | 21 ++++++++++--
 2 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100644 packages/ui/src/experimental/__tests__/mosaic.test.tsx

diff --git a/packages/ui/src/experimental/__tests__/mosaic.test.tsx b/packages/ui/src/experimental/__tests__/mosaic.test.tsx
new file mode 100644
index 00000000000..b6b50097689
--- /dev/null
+++ b/packages/ui/src/experimental/__tests__/mosaic.test.tsx
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { OrganizationProfileGeneral } from '../../mosaic/panels/organization-profile-general';
+import { DeleteOrganization } from '../../mosaic/sections/delete-organization';
+import { LeaveOrganization } from '../../mosaic/sections/leave-organization';
+import {
+  OrganizationProfile,
+  OrganizationProfileDeleteSection,
+  OrganizationProfileGeneralPanel,
+  OrganizationProfileLeaveSection,
+} from '../mosaic';
+
+// The parts are exposed two ways: as a compound namespace (`OrganizationProfile.GeneralPanel`,
+// ergonomic inside a client component) and as flat top-level exports (RSC-safe — each is its own
+// client reference, so a React Server Component can render it without a `'use client'` boundary).
+// Property access on a client reference is impossible across the RSC boundary, so the flat exports
+// are the only form reachable from a server component. Both forms must resolve to the same
+// component object.
+describe('experimental/mosaic flat part exports', () => {
+  it('exports the general panel as a top-level export equal to the compound part', () => {
+    expect(OrganizationProfileGeneralPanel).toBe(OrganizationProfileGeneral);
+    expect(OrganizationProfileGeneralPanel).toBe(OrganizationProfile.GeneralPanel);
+  });
+
+  it('exports the leave section as a top-level export equal to the compound part', () => {
+    expect(OrganizationProfileLeaveSection).toBe(LeaveOrganization);
+    expect(OrganizationProfileLeaveSection).toBe(OrganizationProfile.LeaveSection);
+  });
+
+  it('exports the delete section as a top-level export equal to the compound part', () => {
+    expect(OrganizationProfileDeleteSection).toBe(DeleteOrganization);
+    expect(OrganizationProfileDeleteSection).toBe(OrganizationProfile.DeleteSection);
+  });
+});
diff --git a/packages/ui/src/experimental/mosaic.ts b/packages/ui/src/experimental/mosaic.ts
index af8d842e6fd..0c2a709d957 100644
--- a/packages/ui/src/experimental/mosaic.ts
+++ b/packages/ui/src/experimental/mosaic.ts
@@ -5,16 +5,31 @@
  *
  * No semver guarantees: anything exported here may change or be removed in a minor
  * release. Render `OrganizationProfile` under a `ClerkProvider` (for data) and a
- * `MosaicProvider` (for styling/appearance). The profile's parts can also be rendered
- * standalone via `OrganizationProfile.GeneralPanel`, `OrganizationProfile.LeaveSection`,
- * and `OrganizationProfile.DeleteSection`.
+ * `MosaicProvider` (for styling/appearance).
  *
  * This entry carries a `'use client'` boundary because every Mosaic component is
  * client-only (React context, hooks, emotion). It lives under `experimental/mosaic`
  * rather than the generic `experimental` so that boundary stays scoped to Mosaic and
  * does not force a client directive onto unrelated experimental exports.
+ *
+ * The profile's parts are exposed two ways:
+ *
+ * - As flat top-level exports (`OrganizationProfileGeneralPanel`,
+ *   `OrganizationProfileLeaveSection`, `OrganizationProfileDeleteSection`). Each is its
+ *   own named export, so React treats it as an individual client reference and a React
+ *   Server Component can render it directly — no `'use client'` needed in the consumer.
+ * - As a compound namespace (`OrganizationProfile.GeneralPanel`, `.LeaveSection`,
+ *   `.DeleteSection`), which is more ergonomic but only works inside a client component:
+ *   property access on a client reference is not possible across the RSC boundary, so
+ *   `OrganizationProfile.GeneralPanel` reads as `undefined` in a server component. Server
+ *   components must use the flat exports.
+ *
+ * Both forms resolve to the same component object.
  */
 export { MosaicProvider } from '../mosaic/MosaicProvider';
 export type { MosaicProviderProps } from '../mosaic/MosaicProvider';
 export { OrganizationProfile } from '../mosaic/aio/organization-profile';
+export { OrganizationProfileGeneral as OrganizationProfileGeneralPanel } from '../mosaic/panels/organization-profile-general';
+export { DeleteOrganization as OrganizationProfileDeleteSection } from '../mosaic/sections/delete-organization';
+export { LeaveOrganization as OrganizationProfileLeaveSection } from '../mosaic/sections/leave-organization';
 export type { MosaicAppearance } from '../mosaic/appearance';

From 1da16c91de6ea0ab94cd1fb4c16fb138782b7c14 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 16:37:05 -0400
Subject: [PATCH 09/15] fix global style

---
 packages/ui/src/mosaic/MosaicProvider.tsx | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/mosaic/MosaicProvider.tsx b/packages/ui/src/mosaic/MosaicProvider.tsx
index 8a6d8256ca4..ae2db8060ad 100644
--- a/packages/ui/src/mosaic/MosaicProvider.tsx
+++ b/packages/ui/src/mosaic/MosaicProvider.tsx
@@ -1,7 +1,7 @@
 // eslint-disable-next-line no-restricted-imports
 import createCache from '@emotion/cache';
 // eslint-disable-next-line no-restricted-imports
-import { CacheProvider, Global } from '@emotion/react';
+import { CacheProvider } from '@emotion/react';
 import React from 'react';
 
 import type { MosaicAppearance } from './appearance';
@@ -37,9 +37,12 @@ const ensureInsertionPoint = (): HTMLElement | null => {
 // it has 0 specificity: any component class (recipe / sx / appearance) wins regardless of
 // stylesheet insertion order — a plain `[data-cl-slot]` selector (0,1,0) ties with the generated
 // class and would override it on insertion order, undoing component padding/margin.
-const mosaicReset = {
-  ':where([data-cl-slot])': { boxSizing: 'border-box', margin: 0, padding: 0, fontFamily: 'inherit' },
-} as const;
+//
+// Rendered as a plain <style>, not Emotion's <Global>: <Global> emits an inline <style> during SSR
+// but injects via an insertion effect (rendering null) on the client, so the two trees never match
+// and hydration throws. A static <style> is byte-identical on server and client, so it hydrates
+// cleanly. Order doesn't matter thanks to `:where()`, so it needn't live in the Emotion cache.
+const MOSAIC_RESET_CSS = ':where([data-cl-slot]){box-sizing:border-box;margin:0;padding:0;font-family:inherit;}';
 
 const MosaicThemeContext = React.createContext<MosaicTheme | null>(null);
 
@@ -84,7 +87,12 @@ export function MosaicProvider({
       <MosaicAppearanceProvider value={parsedElements}>
         <MosaicIconsProvider value={icons}>
           <CacheProvider value={cache}>
-            <Global styles={mosaicReset} />
+            <style
+              nonce={nonce}
+              dangerouslySetInnerHTML={{
+                __html: cssLayerName ? `@layer ${cssLayerName}{${MOSAIC_RESET_CSS}}` : MOSAIC_RESET_CSS,
+              }}
+            />
             {children}
           </CacheProvider>
         </MosaicIconsProvider>

From 8cff5b404e9145f520c4214bac3752247cbb6d41 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Tue, 30 Jun 2026 19:21:18 -0400
Subject: [PATCH 10/15] Update mosaic.ts

---
 packages/ui/src/experimental/mosaic.ts | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/packages/ui/src/experimental/mosaic.ts b/packages/ui/src/experimental/mosaic.ts
index 0c2a709d957..fe9a96dbdce 100644
--- a/packages/ui/src/experimental/mosaic.ts
+++ b/packages/ui/src/experimental/mosaic.ts
@@ -7,10 +7,15 @@
  * release. Render `OrganizationProfile` under a `ClerkProvider` (for data) and a
  * `MosaicProvider` (for styling/appearance).
  *
- * This entry carries a `'use client'` boundary because every Mosaic component is
- * client-only (React context, hooks, emotion). It lives under `experimental/mosaic`
- * rather than the generic `experimental` so that boundary stays scoped to Mosaic and
- * does not force a client directive onto unrelated experimental exports.
+ * This entry carries a `'use client'` boundary because every Mosaic component needs one
+ * (React context, hooks, emotion can't run in a Server Component). The directive marks a
+ * client boundary — it does not opt out of SSR; React still invokes these components during
+ * the server render. In practice they emit no server markup anyway, because their controllers
+ * gate on Clerk being loaded (`!isLoaded` → render `null`) and Clerk only loads client-side,
+ * so the UI appears after hydration. What the directive actually buys is letting the flat
+ * exports below drop straight into a Server Component with no consumer setup. It lives under
+ * `experimental/mosaic` rather than the generic `experimental` so that boundary stays scoped
+ * to Mosaic and does not force a client directive onto unrelated experimental exports.
  *
  * The profile's parts are exposed two ways:
  *

From d4e6a30e71d8f545d6c2064b33ab96b7a87117a6 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 1 Jul 2026 10:57:03 -0400
Subject: [PATCH 11/15] refactor(ui): rename mosaic organization profile parts
 to match experimental exports

Rename the experimental Mosaic parts and their files so the source symbols match how they are exported from @clerk/ui/experimental/mosaic:

- DeleteOrganization -> OrganizationProfileDeleteSection
- LeaveOrganization -> OrganizationProfileLeaveSection
- OrganizationProfileGeneral -> OrganizationProfileGeneralPanel
- OrganizationProfile unchanged

The rename cascades through each part's view, controller, and machine symbols and their co-located tests. The experimental entry no longer needs to alias on re-export.

In @clerk/swingset, flatten the AIO/Panels/Sections sidebar groups into a single Organization group, and render each entry by its export name (components as <Name />, hooks as useName()), wrapping long names instead of overflowing.

Public export names from @clerk/ui/experimental/mosaic are unchanged, so there is no user-facing impact.
---
 .changeset/public-mangos-join.md              |  2 +
 .../swingset/src/components/Composition.tsx   |  4 +-
 .../swingset/src/components/DocsViewer.tsx    | 12 ++---
 .../swingset/src/components/app-sidebar.tsx   | 11 +++--
 packages/swingset/src/lib/registry.ts         | 48 ++++++++++---------
 .../stories/delete-organization.stories.tsx   | 30 ------------
 .../stories/leave-organization.stories.tsx    | 30 ------------
 ...> organization-profile-delete-section.mdx} |  6 +--
 ...ization-profile-delete-section.stories.tsx | 29 +++++++++++
 .../organization-profile-general-panel.mdx    | 22 +++++++++
 ...nization-profile-general-panel.stories.tsx | 22 +++++++++
 .../stories/organization-profile-general.mdx  | 14 ------
 .../organization-profile-general.stories.tsx  | 23 ---------
 ...=> organization-profile-leave-section.mdx} |  8 ++--
 ...nization-profile-leave-section.stories.tsx | 29 +++++++++++
 .../src/stories/organization-profile.mdx      |  6 ++-
 .../stories/organization-profile.stories.tsx  |  7 ++-
 .../experimental/__tests__/mosaic.test.tsx    | 12 ++---
 packages/ui/src/experimental/mosaic.ts        |  6 +--
 .../__tests__/organization-profile.test.tsx   | 12 ++---
 .../src/mosaic/aio/organization-profile.tsx   | 14 +++---
 .../__tests__/delete-organization-machine.ts  |  2 +-
 ...ganization-profile-general-panel-view.tsx} | 10 ++--
 .../organization-profile-general-panel.tsx    | 14 ++++++
 .../panels/organization-profile-general.tsx   | 14 ------
 ...rofile-delete-section.controller.test.tsx} |  6 +--
 ...on-profile-delete-section.machine.test.ts} | 10 ++--
 ...tion-profile-delete-section.view.test.tsx} | 14 +++---
 ...profile-leave-section.controller.test.tsx} |  6 +--
 ...ion-profile-leave-section.machine.test.ts} | 10 ++--
 ...ation-profile-leave-section.view.test.tsx} | 14 +++---
 .../mosaic/sections/delete-organization.tsx   | 18 -------
 .../mosaic/sections/leave-organization.tsx    | 18 -------
 ...ion-profile-delete-section.controller.tsx} | 17 ++++---
 ...ization-profile-delete-section.machine.ts} | 11 +++--
 .../organization-profile-delete-section.tsx   | 18 +++++++
 ...anization-profile-delete-section.view.tsx} | 17 +++++--
 ...tion-profile-leave-section.controller.tsx} | 17 ++++---
 ...nization-profile-leave-section.machine.ts} | 11 +++--
 .../organization-profile-leave-section.tsx    | 18 +++++++
 ...ganization-profile-leave-section.view.tsx} | 17 +++++--
 41 files changed, 326 insertions(+), 283 deletions(-)
 create mode 100644 .changeset/public-mangos-join.md
 delete mode 100644 packages/swingset/src/stories/delete-organization.stories.tsx
 delete mode 100644 packages/swingset/src/stories/leave-organization.stories.tsx
 rename packages/swingset/src/stories/{delete-organization.mdx => organization-profile-delete-section.mdx} (69%)
 create mode 100644 packages/swingset/src/stories/organization-profile-delete-section.stories.tsx
 create mode 100644 packages/swingset/src/stories/organization-profile-general-panel.mdx
 create mode 100644 packages/swingset/src/stories/organization-profile-general-panel.stories.tsx
 delete mode 100644 packages/swingset/src/stories/organization-profile-general.mdx
 delete mode 100644 packages/swingset/src/stories/organization-profile-general.stories.tsx
 rename packages/swingset/src/stories/{leave-organization.mdx => organization-profile-leave-section.mdx} (53%)
 create mode 100644 packages/swingset/src/stories/organization-profile-leave-section.stories.tsx
 rename packages/ui/src/mosaic/panels/{organization-profile-general-view.tsx => organization-profile-general-panel-view.tsx} (64%)
 create mode 100644 packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx
 delete mode 100644 packages/ui/src/mosaic/panels/organization-profile-general.tsx
 rename packages/ui/src/mosaic/sections/__tests__/{delete-organization.controller.test.tsx => organization-profile-delete-section.controller.test.tsx} (95%)
 rename packages/ui/src/mosaic/sections/__tests__/{delete-organization.machine.test.ts => organization-profile-delete-section.machine.test.ts} (82%)
 rename packages/ui/src/mosaic/sections/__tests__/{delete-organization.view.test.tsx => organization-profile-delete-section.view.test.tsx} (79%)
 rename packages/ui/src/mosaic/sections/__tests__/{leave-organization.controller.test.tsx => organization-profile-leave-section.controller.test.tsx} (94%)
 rename packages/ui/src/mosaic/sections/__tests__/{leave-organization.machine.test.ts => organization-profile-leave-section.machine.test.ts} (82%)
 rename packages/ui/src/mosaic/sections/__tests__/{leave-organization.view.test.tsx => organization-profile-leave-section.view.test.tsx} (79%)
 delete mode 100644 packages/ui/src/mosaic/sections/delete-organization.tsx
 delete mode 100644 packages/ui/src/mosaic/sections/leave-organization.tsx
 rename packages/ui/src/mosaic/sections/{delete-organization.controller.tsx => organization-profile-delete-section.controller.tsx} (75%)
 rename packages/ui/src/mosaic/sections/{delete-organization.machine.ts => organization-profile-delete-section.machine.ts} (80%)
 create mode 100644 packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx
 rename packages/ui/src/mosaic/sections/{delete-organization.view.tsx => organization-profile-delete-section.view.tsx} (83%)
 rename packages/ui/src/mosaic/sections/{leave-organization.controller.tsx => organization-profile-leave-section.controller.tsx} (77%)
 rename packages/ui/src/mosaic/sections/{leave-organization.machine.ts => organization-profile-leave-section.machine.ts} (80%)
 create mode 100644 packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx
 rename packages/ui/src/mosaic/sections/{leave-organization.view.tsx => organization-profile-leave-section.view.tsx} (83%)

diff --git a/.changeset/public-mangos-join.md b/.changeset/public-mangos-join.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/public-mangos-join.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/swingset/src/components/Composition.tsx b/packages/swingset/src/components/Composition.tsx
index 9edacfe3ef5..3724b72d61b 100644
--- a/packages/swingset/src/components/Composition.tsx
+++ b/packages/swingset/src/components/Composition.tsx
@@ -12,8 +12,8 @@ export interface CompositionPiece {
 }
 
 // Mosaic layers, high → low. Drives the order the composition groups render in.
-// Plural to match the sidebar group names.
-const LAYER_ORDER = ['AIO', 'Panels', 'Sections', 'Blocks', 'Components', 'Primitives'];
+// Matches the sidebar group names.
+const LAYER_ORDER = ['Organization', 'Blocks', 'Components', 'Primitives'];
 
 function layerRank(layer: string): number {
   const i = LAYER_ORDER.indexOf(layer);
diff --git a/packages/swingset/src/components/DocsViewer.tsx b/packages/swingset/src/components/DocsViewer.tsx
index 66c8423ae2a..ddf1d779db0 100644
--- a/packages/swingset/src/components/DocsViewer.tsx
+++ b/packages/swingset/src/components/DocsViewer.tsx
@@ -10,15 +10,11 @@ import { ViewSource } from './ViewSource';
 // MDX docs keyed by `group` slug → `component` slug. Group-aware so identically-named
 // entries (the headless `Dialog` primitive vs. the styled `Dialog` component) stay distinct.
 const docModules: Record<string, Record<string, React.ComponentType>> = {
-  aio: {
+  organization: {
     'organization-profile': dynamic(() => import('../stories/organization-profile.mdx')),
-  },
-  panels: {
-    'organization-profile-general': dynamic(() => import('../stories/organization-profile-general.mdx')),
-  },
-  sections: {
-    'leave-organization': dynamic(() => import('../stories/leave-organization.mdx')),
-    'delete-organization': dynamic(() => import('../stories/delete-organization.mdx')),
+    'organization-profile-general-panel': dynamic(() => import('../stories/organization-profile-general-panel.mdx')),
+    'organization-profile-leave-section': dynamic(() => import('../stories/organization-profile-leave-section.mdx')),
+    'organization-profile-delete-section': dynamic(() => import('../stories/organization-profile-delete-section.mdx')),
   },
   blocks: {
     destructive: dynamic(() => import('../stories/destructive.mdx')),
diff --git a/packages/swingset/src/components/app-sidebar.tsx b/packages/swingset/src/components/app-sidebar.tsx
index ef76475fba8..35cd5ef3ad8 100644
--- a/packages/swingset/src/components/app-sidebar.tsx
+++ b/packages/swingset/src/components/app-sidebar.tsx
@@ -71,16 +71,19 @@ export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
               <SidebarMenu>
                 {components.map(({ mod, componentSlug }) => {
                   const href = `/${groupSlug}/${componentSlug}`;
+                  // Hooks (e.g. `useDataTable`) are called, not rendered — show `useX()` rather
+                  // than JSX `<useX />`. Everything else is a component.
+                  const isHook = /^use[A-Z]/.test(mod.meta.title);
+                  const usage = isHook ? `${mod.meta.title}()` : `<${mod.meta.title} />`;
                   return (
                     <SidebarMenuItem key={mod.meta.title}>
                       <SidebarMenuButton
-                        className='h-auto justify-between py-1 text-xs leading-relaxed'
+                        className='h-auto items-start py-1 text-xs leading-relaxed'
                         isActive={pathname === href}
                         render={<Link href={href} />}
                       >
-                        <span className='truncate'>{mod.meta.label ?? mod.meta.title}</span>
-                        <span className='text-sidebar-foreground/50 shrink-0 font-mono text-[10px] leading-none'>
-                          {`<${mod.meta.title} />`}
+                        <span className='whitespace-normal! break-all font-mono text-[10px] leading-relaxed'>
+                          {usage}
                         </span>
                       </SidebarMenuButton>
                     </SidebarMenuItem>
diff --git a/packages/swingset/src/lib/registry.ts b/packages/swingset/src/lib/registry.ts
index ff0ee8b6f6a..0c97e0d7ec8 100644
--- a/packages/swingset/src/lib/registry.ts
+++ b/packages/swingset/src/lib/registry.ts
@@ -8,10 +8,6 @@ import {
   meta as cardComponentMeta,
 } from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
-import {
-  Default as DeleteOrganizationDefault,
-  meta as deleteOrganizationMeta,
-} from '../stories/delete-organization.stories';
 import { Default as DestructiveDefault, meta as destructiveMeta } from '../stories/destructive.stories';
 import { Default as DialogDefault, meta as dialogComponentMeta } from '../stories/dialog.component.stories';
 import { meta as dialogMeta } from '../stories/dialog.stories';
@@ -35,19 +31,23 @@ import {
   meta as inputMeta,
   Sizes as InputSizes,
 } from '../stories/input.stories';
-import {
-  Default as LeaveOrganizationDefault,
-  meta as leaveOrganizationMeta,
-} from '../stories/leave-organization.stories';
 import { meta as menuMeta } from '../stories/menu.stories';
 import {
   Default as OrganizationProfileDefault,
   meta as organizationProfileMeta,
 } from '../stories/organization-profile.stories';
 import {
-  Default as OrganizationProfileGeneralDefault,
-  meta as organizationProfileGeneralMeta,
-} from '../stories/organization-profile-general.stories';
+  Default as OrganizationProfileDeleteSectionDefault,
+  meta as organizationProfileDeleteSectionMeta,
+} from '../stories/organization-profile-delete-section.stories';
+import {
+  Default as OrganizationProfileGeneralPanelDefault,
+  meta as organizationProfileGeneralPanelMeta,
+} from '../stories/organization-profile-general-panel.stories';
+import {
+  Default as OrganizationProfileLeaveSectionDefault,
+  meta as organizationProfileLeaveSectionMeta,
+} from '../stories/organization-profile-leave-section.stories';
 import { meta as popoverMeta } from '../stories/popover.stories';
 import { meta as selectMeta } from '../stories/select.stories';
 import { Default as TabsComponentDefault, meta as tabsComponentMeta } from '../stories/tabs.component.stories';
@@ -64,12 +64,18 @@ import { toSlug } from './slug';
 import type { StoryModule } from './types';
 
 const destructiveModule: StoryModule = { meta: destructiveMeta, Default: DestructiveDefault };
-const leaveOrganizationModule: StoryModule = { meta: leaveOrganizationMeta, Default: LeaveOrganizationDefault };
-const deleteOrganizationModule: StoryModule = { meta: deleteOrganizationMeta, Default: DeleteOrganizationDefault };
+const organizationProfileLeaveSectionModule: StoryModule = {
+  meta: organizationProfileLeaveSectionMeta,
+  Default: OrganizationProfileLeaveSectionDefault,
+};
+const organizationProfileDeleteSectionModule: StoryModule = {
+  meta: organizationProfileDeleteSectionMeta,
+  Default: OrganizationProfileDeleteSectionDefault,
+};
 const organizationProfileModule: StoryModule = { meta: organizationProfileMeta, Default: OrganizationProfileDefault };
-const organizationProfileGeneralModule: StoryModule = {
-  meta: organizationProfileGeneralMeta,
-  Default: OrganizationProfileGeneralDefault,
+const organizationProfileGeneralPanelModule: StoryModule = {
+  meta: organizationProfileGeneralPanelMeta,
+  Default: OrganizationProfileGeneralPanelDefault,
 };
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault, Centered: CardCentered };
@@ -115,13 +121,11 @@ const tooltipModule: StoryModule = { meta: tooltipMeta };
 const useDataTableModule: StoryModule = { meta: useDataTableMeta };
 
 export const registry: StoryModule[] = [
-  // AIO
+  // Organization
   organizationProfileModule,
-  // Panels
-  organizationProfileGeneralModule,
-  // Sections
-  leaveOrganizationModule,
-  deleteOrganizationModule,
+  organizationProfileGeneralPanelModule,
+  organizationProfileLeaveSectionModule,
+  organizationProfileDeleteSectionModule,
   // Blocks
   destructiveModule,
   // Components
diff --git a/packages/swingset/src/stories/delete-organization.stories.tsx b/packages/swingset/src/stories/delete-organization.stories.tsx
deleted file mode 100644
index da11b24e639..00000000000
--- a/packages/swingset/src/stories/delete-organization.stories.tsx
+++ /dev/null
@@ -1,30 +0,0 @@
-/** @jsxImportSource @emotion/react */
-import { useMachine } from '@clerk/ui/mosaic/machine/useMachine';
-import { deleteOrgMachine } from '@clerk/ui/mosaic/sections/delete-organization.machine';
-import { DeleteOrganizationView } from '@clerk/ui/mosaic/sections/delete-organization.view';
-
-import type { StoryMeta } from '@/lib/types';
-
-export const meta: StoryMeta = {
-  group: 'Sections',
-  title: 'DeleteOrganization',
-  label: 'Delete Org',
-  source: 'packages/ui/src/mosaic/sections/delete-organization.tsx',
-};
-
-export function Default() {
-  const [snapshot, send, actor] = useMachine(deleteOrgMachine, {
-    context: {
-      organizationName: 'Acme Inc',
-      destroyOrganization: () => new Promise<void>(resolve => setTimeout(resolve, 800)),
-    },
-  });
-
-  return (
-    <DeleteOrganizationView
-      snapshot={snapshot}
-      send={send}
-      canSubmit={actor.can({ type: 'CONFIRM' })}
-    />
-  );
-}
diff --git a/packages/swingset/src/stories/leave-organization.stories.tsx b/packages/swingset/src/stories/leave-organization.stories.tsx
deleted file mode 100644
index dfec833c4a0..00000000000
--- a/packages/swingset/src/stories/leave-organization.stories.tsx
+++ /dev/null
@@ -1,30 +0,0 @@
-/** @jsxImportSource @emotion/react */
-import { useMachine } from '@clerk/ui/mosaic/machine/useMachine';
-import { leaveOrgMachine } from '@clerk/ui/mosaic/sections/leave-organization.machine';
-import { LeaveOrganizationView } from '@clerk/ui/mosaic/sections/leave-organization.view';
-
-import type { StoryMeta } from '@/lib/types';
-
-export const meta: StoryMeta = {
-  group: 'Sections',
-  title: 'LeaveOrganization',
-  label: 'Leave Org',
-  source: 'packages/ui/src/mosaic/sections/leave-organization.tsx',
-};
-
-export function Default() {
-  const [snapshot, send, actor] = useMachine(leaveOrgMachine, {
-    context: {
-      organizationName: 'Acme Inc',
-      leaveOrganization: () => new Promise<void>(resolve => setTimeout(resolve, 800)),
-    },
-  });
-
-  return (
-    <LeaveOrganizationView
-      snapshot={snapshot}
-      send={send}
-      canSubmit={actor.can({ type: 'CONFIRM' })}
-    />
-  );
-}
diff --git a/packages/swingset/src/stories/delete-organization.mdx b/packages/swingset/src/stories/organization-profile-delete-section.mdx
similarity index 69%
rename from packages/swingset/src/stories/delete-organization.mdx
rename to packages/swingset/src/stories/organization-profile-delete-section.mdx
index 3a82207d49f..0d885514caa 100644
--- a/packages/swingset/src/stories/delete-organization.mdx
+++ b/packages/swingset/src/stories/organization-profile-delete-section.mdx
@@ -1,12 +1,12 @@
-import * as DeleteOrganizationStories from './delete-organization.stories';
+import * as OrganizationProfileDeleteSectionStories from './organization-profile-delete-section.stories';
 
-# Delete Organization
+# Organization Profile Delete Section
 
 A section that owns the open/deleting state and wires the `Destructive` block to the delete-organization flow.
 
 <Story
   name='Default'
-  storyModule={DeleteOrganizationStories}
+  storyModule={OrganizationProfileDeleteSectionStories}
   composition={[
     { name: 'Destructive', href: '/blocks/destructive', layer: 'Blocks' },
     { name: 'Button', href: '/components/button', layer: 'Components' },
diff --git a/packages/swingset/src/stories/organization-profile-delete-section.stories.tsx b/packages/swingset/src/stories/organization-profile-delete-section.stories.tsx
new file mode 100644
index 00000000000..ebb912a173b
--- /dev/null
+++ b/packages/swingset/src/stories/organization-profile-delete-section.stories.tsx
@@ -0,0 +1,29 @@
+/** @jsxImportSource @emotion/react */
+import { useMachine } from '@clerk/ui/mosaic/machine/useMachine';
+import { organizationProfileDeleteSectionMachine } from '@clerk/ui/mosaic/sections/organization-profile-delete-section.machine';
+import { OrganizationProfileDeleteSectionView } from '@clerk/ui/mosaic/sections/organization-profile-delete-section.view';
+
+import type { StoryMeta } from '@/lib/types';
+
+export const meta: StoryMeta = {
+  group: 'Organization',
+  title: 'OrganizationProfileDeleteSection',
+  source: 'packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx',
+};
+
+export function Default() {
+  const [snapshot, send, actor] = useMachine(organizationProfileDeleteSectionMachine, {
+    context: {
+      organizationName: 'Acme Inc',
+      destroyOrganization: () => new Promise<void>(resolve => setTimeout(resolve, 800)),
+    },
+  });
+
+  return (
+    <OrganizationProfileDeleteSectionView
+      snapshot={snapshot}
+      send={send}
+      canSubmit={actor.can({ type: 'CONFIRM' })}
+    />
+  );
+}
diff --git a/packages/swingset/src/stories/organization-profile-general-panel.mdx b/packages/swingset/src/stories/organization-profile-general-panel.mdx
new file mode 100644
index 00000000000..6cb03d83629
--- /dev/null
+++ b/packages/swingset/src/stories/organization-profile-general-panel.mdx
@@ -0,0 +1,22 @@
+import * as OrganizationProfileGeneralPanelStories from './organization-profile-general-panel.stories';
+
+# Organization Profile General Panel
+
+The General tab panel of the Organization Profile — composes the organization-level sections shown under "General".
+
+<Story
+  name='Default'
+  storyModule={OrganizationProfileGeneralPanelStories}
+  composition={[
+    {
+      name: 'OrganizationProfileLeaveSection',
+      href: '/organization/organization-profile-leave-section',
+      layer: 'Organization',
+    },
+    {
+      name: 'OrganizationProfileDeleteSection',
+      href: '/organization/organization-profile-delete-section',
+      layer: 'Organization',
+    },
+  ]}
+/>
diff --git a/packages/swingset/src/stories/organization-profile-general-panel.stories.tsx b/packages/swingset/src/stories/organization-profile-general-panel.stories.tsx
new file mode 100644
index 00000000000..52d21aa9147
--- /dev/null
+++ b/packages/swingset/src/stories/organization-profile-general-panel.stories.tsx
@@ -0,0 +1,22 @@
+/** @jsxImportSource @emotion/react */
+import { OrganizationProfileGeneralPanelView } from '@clerk/ui/mosaic/panels/organization-profile-general-panel-view';
+
+import type { StoryMeta } from '@/lib/types';
+
+import { Default as OrganizationProfileDeleteSectionDemo } from './organization-profile-delete-section.stories';
+import { Default as OrganizationProfileLeaveSectionDemo } from './organization-profile-leave-section.stories';
+
+export const meta: StoryMeta = {
+  group: 'Organization',
+  title: 'OrganizationProfileGeneralPanel',
+  source: 'packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx',
+};
+
+export function Default() {
+  return (
+    <OrganizationProfileGeneralPanelView
+      leaveOrganization={<OrganizationProfileLeaveSectionDemo />}
+      deleteOrganization={<OrganizationProfileDeleteSectionDemo />}
+    />
+  );
+}
diff --git a/packages/swingset/src/stories/organization-profile-general.mdx b/packages/swingset/src/stories/organization-profile-general.mdx
deleted file mode 100644
index 3fd513c3662..00000000000
--- a/packages/swingset/src/stories/organization-profile-general.mdx
+++ /dev/null
@@ -1,14 +0,0 @@
-import * as OrganizationProfileGeneralStories from './organization-profile-general.stories';
-
-# Organization Profile General
-
-The General tab panel of the Organization Profile — composes the organization-level sections shown under "General".
-
-<Story
-  name='Default'
-  storyModule={OrganizationProfileGeneralStories}
-  composition={[
-    { name: 'LeaveOrganization', href: '/sections/leave-organization', layer: 'Sections' },
-    { name: 'DeleteOrganization', href: '/sections/delete-organization', layer: 'Sections' },
-  ]}
-/>
diff --git a/packages/swingset/src/stories/organization-profile-general.stories.tsx b/packages/swingset/src/stories/organization-profile-general.stories.tsx
deleted file mode 100644
index 3682934c571..00000000000
--- a/packages/swingset/src/stories/organization-profile-general.stories.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-/** @jsxImportSource @emotion/react */
-import { OrganizationProfileGeneralView } from '@clerk/ui/mosaic/panels/organization-profile-general-view';
-
-import type { StoryMeta } from '@/lib/types';
-
-import { Default as DeleteOrganizationDemo } from './delete-organization.stories';
-import { Default as LeaveOrganizationDemo } from './leave-organization.stories';
-
-export const meta: StoryMeta = {
-  group: 'Panels',
-  title: 'OrganizationProfileGeneral',
-  label: 'Org Profile General',
-  source: 'packages/ui/src/mosaic/panels/organization-profile-general.tsx',
-};
-
-export function Default() {
-  return (
-    <OrganizationProfileGeneralView
-      leaveOrganization={<LeaveOrganizationDemo />}
-      deleteOrganization={<DeleteOrganizationDemo />}
-    />
-  );
-}
diff --git a/packages/swingset/src/stories/leave-organization.mdx b/packages/swingset/src/stories/organization-profile-leave-section.mdx
similarity index 53%
rename from packages/swingset/src/stories/leave-organization.mdx
rename to packages/swingset/src/stories/organization-profile-leave-section.mdx
index 966737006cb..ce0be64a871 100644
--- a/packages/swingset/src/stories/leave-organization.mdx
+++ b/packages/swingset/src/stories/organization-profile-leave-section.mdx
@@ -1,12 +1,12 @@
-import * as LeaveOrganizationStories from './leave-organization.stories';
+import * as OrganizationProfileLeaveSectionStories from './organization-profile-leave-section.stories';
 
-# Leave Organization
+# Organization Profile Leave Section
 
-A section that owns the open/deleting state and wires the `Destructive` block to the leave-organization flow.
+A section that owns the open/leaving state and wires the `Destructive` block to the leave-organization flow.
 
 <Story
   name='Default'
-  storyModule={LeaveOrganizationStories}
+  storyModule={OrganizationProfileLeaveSectionStories}
   composition={[
     { name: 'Destructive', href: '/blocks/destructive', layer: 'Blocks' },
     { name: 'Button', href: '/components/button', layer: 'Components' },
diff --git a/packages/swingset/src/stories/organization-profile-leave-section.stories.tsx b/packages/swingset/src/stories/organization-profile-leave-section.stories.tsx
new file mode 100644
index 00000000000..d0b2324dcdc
--- /dev/null
+++ b/packages/swingset/src/stories/organization-profile-leave-section.stories.tsx
@@ -0,0 +1,29 @@
+/** @jsxImportSource @emotion/react */
+import { useMachine } from '@clerk/ui/mosaic/machine/useMachine';
+import { organizationProfileLeaveSectionMachine } from '@clerk/ui/mosaic/sections/organization-profile-leave-section.machine';
+import { OrganizationProfileLeaveSectionView } from '@clerk/ui/mosaic/sections/organization-profile-leave-section.view';
+
+import type { StoryMeta } from '@/lib/types';
+
+export const meta: StoryMeta = {
+  group: 'Organization',
+  title: 'OrganizationProfileLeaveSection',
+  source: 'packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx',
+};
+
+export function Default() {
+  const [snapshot, send, actor] = useMachine(organizationProfileLeaveSectionMachine, {
+    context: {
+      organizationName: 'Acme Inc',
+      leaveOrganization: () => new Promise<void>(resolve => setTimeout(resolve, 800)),
+    },
+  });
+
+  return (
+    <OrganizationProfileLeaveSectionView
+      snapshot={snapshot}
+      send={send}
+      canSubmit={actor.can({ type: 'CONFIRM' })}
+    />
+  );
+}
diff --git a/packages/swingset/src/stories/organization-profile.mdx b/packages/swingset/src/stories/organization-profile.mdx
index bf473a8c921..261e90e9fbd 100644
--- a/packages/swingset/src/stories/organization-profile.mdx
+++ b/packages/swingset/src/stories/organization-profile.mdx
@@ -8,7 +8,11 @@ The full Organization Profile AIO — lays out the organization panels under a t
   name='Default'
   storyModule={OrganizationProfileStories}
   composition={[
-    { name: 'OrganizationProfileGeneral', href: '/panels/organization-profile-general', layer: 'Panels' },
+    {
+      name: 'OrganizationProfileGeneralPanel',
+      href: '/organization/organization-profile-general-panel',
+      layer: 'Organization',
+    },
     { name: 'Tabs', href: '/components/tabs', layer: 'Components' },
   ]}
 />
diff --git a/packages/swingset/src/stories/organization-profile.stories.tsx b/packages/swingset/src/stories/organization-profile.stories.tsx
index d6bc644fd36..48fb9994751 100644
--- a/packages/swingset/src/stories/organization-profile.stories.tsx
+++ b/packages/swingset/src/stories/organization-profile.stories.tsx
@@ -3,15 +3,14 @@ import { OrganizationProfileView } from '@clerk/ui/mosaic/aio/organization-profi
 
 import type { StoryMeta } from '@/lib/types';
 
-import { Default as OrganizationProfileGeneralDemo } from './organization-profile-general.stories';
+import { Default as OrganizationProfileGeneralPanelDemo } from './organization-profile-general-panel.stories';
 
 export const meta: StoryMeta = {
-  group: 'AIO',
+  group: 'Organization',
   title: 'OrganizationProfile',
-  label: 'Org Profile',
   source: 'packages/ui/src/mosaic/aio/organization-profile.tsx',
 };
 
 export function Default() {
-  return <OrganizationProfileView general={<OrganizationProfileGeneralDemo />} />;
+  return <OrganizationProfileView general={<OrganizationProfileGeneralPanelDemo />} />;
 }
diff --git a/packages/ui/src/experimental/__tests__/mosaic.test.tsx b/packages/ui/src/experimental/__tests__/mosaic.test.tsx
index b6b50097689..3f49cfedf54 100644
--- a/packages/ui/src/experimental/__tests__/mosaic.test.tsx
+++ b/packages/ui/src/experimental/__tests__/mosaic.test.tsx
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest';
 
-import { OrganizationProfileGeneral } from '../../mosaic/panels/organization-profile-general';
-import { DeleteOrganization } from '../../mosaic/sections/delete-organization';
-import { LeaveOrganization } from '../../mosaic/sections/leave-organization';
+import { OrganizationProfileGeneralPanel as GeneralPanelPart } from '../../mosaic/panels/organization-profile-general-panel';
+import { OrganizationProfileDeleteSection as DeleteSectionPart } from '../../mosaic/sections/organization-profile-delete-section';
+import { OrganizationProfileLeaveSection as LeaveSectionPart } from '../../mosaic/sections/organization-profile-leave-section';
 import {
   OrganizationProfile,
   OrganizationProfileDeleteSection,
@@ -18,17 +18,17 @@ import {
 // component object.
 describe('experimental/mosaic flat part exports', () => {
   it('exports the general panel as a top-level export equal to the compound part', () => {
-    expect(OrganizationProfileGeneralPanel).toBe(OrganizationProfileGeneral);
+    expect(OrganizationProfileGeneralPanel).toBe(GeneralPanelPart);
     expect(OrganizationProfileGeneralPanel).toBe(OrganizationProfile.GeneralPanel);
   });
 
   it('exports the leave section as a top-level export equal to the compound part', () => {
-    expect(OrganizationProfileLeaveSection).toBe(LeaveOrganization);
+    expect(OrganizationProfileLeaveSection).toBe(LeaveSectionPart);
     expect(OrganizationProfileLeaveSection).toBe(OrganizationProfile.LeaveSection);
   });
 
   it('exports the delete section as a top-level export equal to the compound part', () => {
-    expect(OrganizationProfileDeleteSection).toBe(DeleteOrganization);
+    expect(OrganizationProfileDeleteSection).toBe(DeleteSectionPart);
     expect(OrganizationProfileDeleteSection).toBe(OrganizationProfile.DeleteSection);
   });
 });
diff --git a/packages/ui/src/experimental/mosaic.ts b/packages/ui/src/experimental/mosaic.ts
index fe9a96dbdce..23e7a6b680b 100644
--- a/packages/ui/src/experimental/mosaic.ts
+++ b/packages/ui/src/experimental/mosaic.ts
@@ -34,7 +34,7 @@
 export { MosaicProvider } from '../mosaic/MosaicProvider';
 export type { MosaicProviderProps } from '../mosaic/MosaicProvider';
 export { OrganizationProfile } from '../mosaic/aio/organization-profile';
-export { OrganizationProfileGeneral as OrganizationProfileGeneralPanel } from '../mosaic/panels/organization-profile-general';
-export { DeleteOrganization as OrganizationProfileDeleteSection } from '../mosaic/sections/delete-organization';
-export { LeaveOrganization as OrganizationProfileLeaveSection } from '../mosaic/sections/leave-organization';
+export { OrganizationProfileGeneralPanel } from '../mosaic/panels/organization-profile-general-panel';
+export { OrganizationProfileDeleteSection } from '../mosaic/sections/organization-profile-delete-section';
+export { OrganizationProfileLeaveSection } from '../mosaic/sections/organization-profile-leave-section';
 export type { MosaicAppearance } from '../mosaic/appearance';
diff --git a/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx b/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
index 78c6ab42cab..1d9f241bb10 100644
--- a/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
+++ b/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
@@ -1,20 +1,20 @@
 import { describe, expect, it } from 'vitest';
 
-import { OrganizationProfileGeneral } from '../../panels/organization-profile-general';
-import { DeleteOrganization } from '../../sections/delete-organization';
-import { LeaveOrganization } from '../../sections/leave-organization';
+import { OrganizationProfileGeneralPanel } from '../../panels/organization-profile-general-panel';
+import { OrganizationProfileDeleteSection } from '../../sections/organization-profile-delete-section';
+import { OrganizationProfileLeaveSection } from '../../sections/organization-profile-leave-section';
 import { OrganizationProfile } from '../organization-profile';
 
 describe('OrganizationProfile compound parts', () => {
   it('exposes the general panel as a standalone part', () => {
-    expect(OrganizationProfile.GeneralPanel).toBe(OrganizationProfileGeneral);
+    expect(OrganizationProfile.GeneralPanel).toBe(OrganizationProfileGeneralPanel);
   });
 
   it('exposes the leave section as a standalone part', () => {
-    expect(OrganizationProfile.LeaveSection).toBe(LeaveOrganization);
+    expect(OrganizationProfile.LeaveSection).toBe(OrganizationProfileLeaveSection);
   });
 
   it('exposes the delete section as a standalone part', () => {
-    expect(OrganizationProfile.DeleteSection).toBe(DeleteOrganization);
+    expect(OrganizationProfile.DeleteSection).toBe(OrganizationProfileDeleteSection);
   });
 });
diff --git a/packages/ui/src/mosaic/aio/organization-profile.tsx b/packages/ui/src/mosaic/aio/organization-profile.tsx
index 7fc75f2ab8a..5b2ca1dcba3 100644
--- a/packages/ui/src/mosaic/aio/organization-profile.tsx
+++ b/packages/ui/src/mosaic/aio/organization-profile.tsx
@@ -1,8 +1,8 @@
 import type { ReactElement } from 'react';
 
-import { OrganizationProfileGeneral } from '../panels/organization-profile-general';
-import { DeleteOrganization } from '../sections/delete-organization';
-import { LeaveOrganization } from '../sections/leave-organization';
+import { OrganizationProfileGeneralPanel } from '../panels/organization-profile-general-panel';
+import { OrganizationProfileDeleteSection } from '../sections/organization-profile-delete-section';
+import { OrganizationProfileLeaveSection } from '../sections/organization-profile-leave-section';
 import { useOrganizationProfileController } from './organization-profile.controller';
 import { OrganizationProfileView } from './organization-profile-view';
 
@@ -11,7 +11,7 @@ function OrganizationProfileRoot(): ReactElement | null {
   if (controller.status !== 'ready') {
     return null;
   }
-  return <OrganizationProfileView general={<OrganizationProfileGeneral />} />;
+  return <OrganizationProfileView general={<OrganizationProfileGeneralPanel />} />;
 }
 
 // Standalone parts of the profile, exposed via the compound namespace. Each part is
@@ -24,7 +24,7 @@ function OrganizationProfileRoot(): ReactElement | null {
 // `OrganizationProfile.X = ...` statements, leaving the parts `undefined` at runtime. Folding
 // them into the exported binding's initializer keeps them attached across that boundary.
 export const OrganizationProfile = Object.assign(OrganizationProfileRoot, {
-  GeneralPanel: OrganizationProfileGeneral,
-  LeaveSection: LeaveOrganization,
-  DeleteSection: DeleteOrganization,
+  GeneralPanel: OrganizationProfileGeneralPanel,
+  LeaveSection: OrganizationProfileLeaveSection,
+  DeleteSection: OrganizationProfileDeleteSection,
 });
diff --git a/packages/ui/src/mosaic/machine/__tests__/delete-organization-machine.ts b/packages/ui/src/mosaic/machine/__tests__/delete-organization-machine.ts
index 39d5a1fb32c..8aa1d338e43 100644
--- a/packages/ui/src/mosaic/machine/__tests__/delete-organization-machine.ts
+++ b/packages/ui/src/mosaic/machine/__tests__/delete-organization-machine.ts
@@ -6,7 +6,7 @@ import type { DoneInvokeEvent, ErrorInvokeEvent, StateMachine } from '../types';
  * Shared fixture: the delete-organization flow expressed as an explicit machine.
  *
  * Today this logic is smeared across four `useState` flags in
- * `sections/delete-organization.tsx` + `block/destructive.tsx`
+ * `sections/organization-profile-delete-section.tsx` + `block/destructive.tsx`
  * (`open`, `isDeleting`, `confirmValue`, and the derived `canSubmit`). Modelling
  * it as a machine — `idle → confirming → deleting → deleted`, guarded on the
  * typed name matching, with an error path back to `confirming` — makes every
diff --git a/packages/ui/src/mosaic/panels/organization-profile-general-view.tsx b/packages/ui/src/mosaic/panels/organization-profile-general-panel-view.tsx
similarity index 64%
rename from packages/ui/src/mosaic/panels/organization-profile-general-view.tsx
rename to packages/ui/src/mosaic/panels/organization-profile-general-panel-view.tsx
index 64e4793d9c1..28ddd2a6470 100644
--- a/packages/ui/src/mosaic/panels/organization-profile-general-view.tsx
+++ b/packages/ui/src/mosaic/panels/organization-profile-general-panel-view.tsx
@@ -3,17 +3,17 @@ import type { ReactNode } from 'react';
 import { Box } from '../components/box';
 import { alpha } from '../utils';
 
-interface OrganizationProfileGeneralViewProps {
-  /** The leave-organization section, rendered above the divider. */
+interface OrganizationProfileGeneralPanelViewProps {
+  /** The organization-profile-leave-section section, rendered above the divider. */
   leaveOrganization: ReactNode;
-  /** The delete-organization section, rendered below the divider. */
+  /** The organization-profile-delete-section section, rendered below the divider. */
   deleteOrganization: ReactNode;
 }
 
-export function OrganizationProfileGeneralView({
+export function OrganizationProfileGeneralPanelView({
   leaveOrganization,
   deleteOrganization,
-}: OrganizationProfileGeneralViewProps) {
+}: OrganizationProfileGeneralPanelViewProps) {
   return (
     <Box
       sx={{
diff --git a/packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx b/packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx
new file mode 100644
index 00000000000..be67223347e
--- /dev/null
+++ b/packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx
@@ -0,0 +1,14 @@
+import type { ReactElement } from 'react';
+
+import { OrganizationProfileDeleteSection } from '../sections/organization-profile-delete-section';
+import { OrganizationProfileLeaveSection } from '../sections/organization-profile-leave-section';
+import { OrganizationProfileGeneralPanelView } from './organization-profile-general-panel-view';
+
+export function OrganizationProfileGeneralPanel(): ReactElement {
+  return (
+    <OrganizationProfileGeneralPanelView
+      leaveOrganization={<OrganizationProfileLeaveSection />}
+      deleteOrganization={<OrganizationProfileDeleteSection />}
+    />
+  );
+}
diff --git a/packages/ui/src/mosaic/panels/organization-profile-general.tsx b/packages/ui/src/mosaic/panels/organization-profile-general.tsx
deleted file mode 100644
index 80f894609b1..00000000000
--- a/packages/ui/src/mosaic/panels/organization-profile-general.tsx
+++ /dev/null
@@ -1,14 +0,0 @@
-import type { ReactElement } from 'react';
-
-import { DeleteOrganization } from '../sections/delete-organization';
-import { LeaveOrganization } from '../sections/leave-organization';
-import { OrganizationProfileGeneralView } from './organization-profile-general-view';
-
-export function OrganizationProfileGeneral(): ReactElement {
-  return (
-    <OrganizationProfileGeneralView
-      leaveOrganization={<LeaveOrganization />}
-      deleteOrganization={<DeleteOrganization />}
-    />
-  );
-}
diff --git a/packages/ui/src/mosaic/sections/__tests__/delete-organization.controller.test.tsx b/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.controller.test.tsx
similarity index 95%
rename from packages/ui/src/mosaic/sections/__tests__/delete-organization.controller.test.tsx
rename to packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.controller.test.tsx
index 7c46d47520e..f12811510b5 100644
--- a/packages/ui/src/mosaic/sections/__tests__/delete-organization.controller.test.tsx
+++ b/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.controller.test.tsx
@@ -2,7 +2,7 @@ import { act, fireEvent, render, screen } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { deferred } from '../../machines/__tests__/test-utils';
-import { useDeleteOrganizationController } from '../delete-organization.controller';
+import { useOrganizationProfileDeleteSectionController } from '../organization-profile-delete-section.controller';
 
 const ORG_NAME = 'Acme Inc';
 
@@ -48,7 +48,7 @@ afterEach(() => {
 });
 
 function Harness() {
-  const controller = useDeleteOrganizationController();
+  const controller = useOrganizationProfileDeleteSectionController();
   if (controller.status !== 'ready') {
     return <output data-testid='state'>{controller.status}</output>;
   }
@@ -69,7 +69,7 @@ function openAndConfirm() {
   fireEvent.click(screen.getByText('Confirm'));
 }
 
-describe('useDeleteOrganizationController', () => {
+describe('useOrganizationProfileDeleteSectionController', () => {
   it('is loading until useOrganization is loaded', () => {
     isLoaded = false;
 
diff --git a/packages/ui/src/mosaic/sections/__tests__/delete-organization.machine.test.ts b/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.machine.test.ts
similarity index 82%
rename from packages/ui/src/mosaic/sections/__tests__/delete-organization.machine.test.ts
rename to packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.machine.test.ts
index 6178a2efb45..5f697280bb1 100644
--- a/packages/ui/src/mosaic/sections/__tests__/delete-organization.machine.test.ts
+++ b/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.machine.test.ts
@@ -1,14 +1,14 @@
 import { describe, expect, it, vi } from 'vitest';
 
 import { createActor } from '../../machine/createActor';
-import { deleteOrgMachine } from '../delete-organization.machine';
+import { organizationProfileDeleteSectionMachine } from '../organization-profile-delete-section.machine';
 
 const tick = () => new Promise<void>(resolve => setTimeout(resolve, 0));
 
-describe('deleteOrgMachine', () => {
+describe('organizationProfileDeleteSectionMachine', () => {
   it('guards confirmation until the typed organization name matches', () => {
     const destroyOrganization = vi.fn(() => Promise.resolve());
-    const actor = createActor(deleteOrgMachine, {
+    const actor = createActor(organizationProfileDeleteSectionMachine, {
       context: {
         organizationName: 'Acme Inc',
         destroyOrganization,
@@ -25,7 +25,7 @@ describe('deleteOrgMachine', () => {
 
   it('invokes the injected delete function after a valid confirmation', async () => {
     const destroyOrganization = vi.fn(() => Promise.resolve());
-    const actor = createActor(deleteOrgMachine, {
+    const actor = createActor(organizationProfileDeleteSectionMachine, {
       context: {
         organizationName: 'Acme Inc',
         destroyOrganization,
@@ -48,7 +48,7 @@ describe('deleteOrgMachine', () => {
 
   it('returns to confirming with an error when deletion fails', async () => {
     const destroyOrganization = vi.fn(() => Promise.reject(new Error('nope')));
-    const actor = createActor(deleteOrgMachine, {
+    const actor = createActor(organizationProfileDeleteSectionMachine, {
       context: {
         organizationName: 'Acme Inc',
         destroyOrganization,
diff --git a/packages/ui/src/mosaic/sections/__tests__/delete-organization.view.test.tsx b/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.view.test.tsx
similarity index 79%
rename from packages/ui/src/mosaic/sections/__tests__/delete-organization.view.test.tsx
rename to packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.view.test.tsx
index 446aefccfa3..b434fe94351 100644
--- a/packages/ui/src/mosaic/sections/__tests__/delete-organization.view.test.tsx
+++ b/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.view.test.tsx
@@ -3,13 +3,13 @@ import { describe, expect, it, vi } from 'vitest';
 
 import type { Snapshot } from '../../machine/types';
 import { MosaicProvider } from '../../MosaicProvider';
-import type { DeleteOrgContext } from '../delete-organization.machine';
-import { DeleteOrganizationView } from '../delete-organization.view';
+import type { OrganizationProfileDeleteSectionContext } from '../organization-profile-delete-section.machine';
+import { OrganizationProfileDeleteSectionView } from '../organization-profile-delete-section.view';
 
-function renderView(snapshot: Snapshot<DeleteOrgContext>, send = vi.fn(), canSubmit = false) {
+function renderView(snapshot: Snapshot<OrganizationProfileDeleteSectionContext>, send = vi.fn(), canSubmit = false) {
   render(
     <MosaicProvider>
-      <DeleteOrganizationView
+      <OrganizationProfileDeleteSectionView
         snapshot={snapshot}
         send={send}
         canSubmit={canSubmit}
@@ -19,7 +19,9 @@ function renderView(snapshot: Snapshot<DeleteOrgContext>, send = vi.fn(), canSub
   return { send };
 }
 
-function snapshot(overrides: Partial<Snapshot<DeleteOrgContext>> = {}): Snapshot<DeleteOrgContext> {
+function snapshot(
+  overrides: Partial<Snapshot<OrganizationProfileDeleteSectionContext>> = {},
+): Snapshot<OrganizationProfileDeleteSectionContext> {
   return {
     value: 'confirming',
     status: 'active',
@@ -33,7 +35,7 @@ function snapshot(overrides: Partial<Snapshot<DeleteOrgContext>> = {}): Snapshot
   };
 }
 
-describe('DeleteOrganizationView', () => {
+describe('OrganizationProfileDeleteSectionView', () => {
   it('emits a typed confirmation event from the input', () => {
     const { send } = renderView(snapshot());
 
diff --git a/packages/ui/src/mosaic/sections/__tests__/leave-organization.controller.test.tsx b/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.controller.test.tsx
similarity index 94%
rename from packages/ui/src/mosaic/sections/__tests__/leave-organization.controller.test.tsx
rename to packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.controller.test.tsx
index 4c1242cc7a4..9c8177c7249 100644
--- a/packages/ui/src/mosaic/sections/__tests__/leave-organization.controller.test.tsx
+++ b/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.controller.test.tsx
@@ -2,7 +2,7 @@ import { act, fireEvent, render, screen } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { deferred } from '../../machines/__tests__/test-utils';
-import { useLeaveOrganizationController } from '../leave-organization.controller';
+import { useOrganizationProfileLeaveSectionController } from '../organization-profile-leave-section.controller';
 
 const ORG_NAME = 'Acme Inc';
 
@@ -43,7 +43,7 @@ afterEach(() => {
 });
 
 function Harness() {
-  const controller = useLeaveOrganizationController();
+  const controller = useOrganizationProfileLeaveSectionController();
   if (controller.status !== 'ready') {
     return <output data-testid='state'>{controller.status}</output>;
   }
@@ -64,7 +64,7 @@ function openAndConfirm() {
   fireEvent.click(screen.getByText('Confirm'));
 }
 
-describe('useLeaveOrganizationController', () => {
+describe('useOrganizationProfileLeaveSectionController', () => {
   it('is loading until useOrganization is loaded', () => {
     isLoaded = false;
 
diff --git a/packages/ui/src/mosaic/sections/__tests__/leave-organization.machine.test.ts b/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.machine.test.ts
similarity index 82%
rename from packages/ui/src/mosaic/sections/__tests__/leave-organization.machine.test.ts
rename to packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.machine.test.ts
index 98d40fde18e..24ee1a0c2cb 100644
--- a/packages/ui/src/mosaic/sections/__tests__/leave-organization.machine.test.ts
+++ b/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.machine.test.ts
@@ -1,14 +1,14 @@
 import { describe, expect, it, vi } from 'vitest';
 
 import { createActor } from '../../machine/createActor';
-import { leaveOrgMachine } from '../leave-organization.machine';
+import { organizationProfileLeaveSectionMachine } from '../organization-profile-leave-section.machine';
 
 const tick = () => new Promise<void>(resolve => setTimeout(resolve, 0));
 
-describe('leaveOrgMachine', () => {
+describe('organizationProfileLeaveSectionMachine', () => {
   it('guards confirmation until the typed organization name matches', () => {
     const leaveOrganization = vi.fn(() => Promise.resolve());
-    const actor = createActor(leaveOrgMachine, {
+    const actor = createActor(organizationProfileLeaveSectionMachine, {
       context: {
         organizationName: 'Acme Inc',
         leaveOrganization,
@@ -25,7 +25,7 @@ describe('leaveOrgMachine', () => {
 
   it('invokes the injected leave function after a valid confirmation', async () => {
     const leaveOrganization = vi.fn(() => Promise.resolve());
-    const actor = createActor(leaveOrgMachine, {
+    const actor = createActor(organizationProfileLeaveSectionMachine, {
       context: {
         organizationName: 'Acme Inc',
         leaveOrganization,
@@ -48,7 +48,7 @@ describe('leaveOrgMachine', () => {
 
   it('returns to confirming with an error when leaving fails', async () => {
     const leaveOrganization = vi.fn(() => Promise.reject(new Error('nope')));
-    const actor = createActor(leaveOrgMachine, {
+    const actor = createActor(organizationProfileLeaveSectionMachine, {
       context: {
         organizationName: 'Acme Inc',
         leaveOrganization,
diff --git a/packages/ui/src/mosaic/sections/__tests__/leave-organization.view.test.tsx b/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.view.test.tsx
similarity index 79%
rename from packages/ui/src/mosaic/sections/__tests__/leave-organization.view.test.tsx
rename to packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.view.test.tsx
index 1b6df7d9f81..8d41ff4bc24 100644
--- a/packages/ui/src/mosaic/sections/__tests__/leave-organization.view.test.tsx
+++ b/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.view.test.tsx
@@ -3,13 +3,13 @@ import { describe, expect, it, vi } from 'vitest';
 
 import type { Snapshot } from '../../machine/types';
 import { MosaicProvider } from '../../MosaicProvider';
-import type { LeaveOrgContext } from '../leave-organization.machine';
-import { LeaveOrganizationView } from '../leave-organization.view';
+import type { OrganizationProfileLeaveSectionContext } from '../organization-profile-leave-section.machine';
+import { OrganizationProfileLeaveSectionView } from '../organization-profile-leave-section.view';
 
-function renderView(snapshot: Snapshot<LeaveOrgContext>, send = vi.fn(), canSubmit = false) {
+function renderView(snapshot: Snapshot<OrganizationProfileLeaveSectionContext>, send = vi.fn(), canSubmit = false) {
   render(
     <MosaicProvider>
-      <LeaveOrganizationView
+      <OrganizationProfileLeaveSectionView
         snapshot={snapshot}
         send={send}
         canSubmit={canSubmit}
@@ -19,7 +19,9 @@ function renderView(snapshot: Snapshot<LeaveOrgContext>, send = vi.fn(), canSubm
   return { send };
 }
 
-function snapshot(overrides: Partial<Snapshot<LeaveOrgContext>> = {}): Snapshot<LeaveOrgContext> {
+function snapshot(
+  overrides: Partial<Snapshot<OrganizationProfileLeaveSectionContext>> = {},
+): Snapshot<OrganizationProfileLeaveSectionContext> {
   return {
     value: 'confirming',
     status: 'active',
@@ -33,7 +35,7 @@ function snapshot(overrides: Partial<Snapshot<LeaveOrgContext>> = {}): Snapshot<
   };
 }
 
-describe('LeaveOrganizationView', () => {
+describe('OrganizationProfileLeaveSectionView', () => {
   it('emits a typed confirmation event from the input', () => {
     const { send } = renderView(snapshot());
 
diff --git a/packages/ui/src/mosaic/sections/delete-organization.tsx b/packages/ui/src/mosaic/sections/delete-organization.tsx
deleted file mode 100644
index 66be0a8bb36..00000000000
--- a/packages/ui/src/mosaic/sections/delete-organization.tsx
+++ /dev/null
@@ -1,18 +0,0 @@
-import type { ReactElement } from 'react';
-
-import { useDeleteOrganizationController } from './delete-organization.controller';
-import { DeleteOrganizationView } from './delete-organization.view';
-
-export function DeleteOrganization(): ReactElement | null {
-  const controller = useDeleteOrganizationController();
-  if (controller.status !== 'ready') {
-    return null;
-  }
-  return (
-    <DeleteOrganizationView
-      snapshot={controller.snapshot}
-      send={controller.send}
-      canSubmit={controller.canSubmit}
-    />
-  );
-}
diff --git a/packages/ui/src/mosaic/sections/leave-organization.tsx b/packages/ui/src/mosaic/sections/leave-organization.tsx
deleted file mode 100644
index 28f0c8a08bf..00000000000
--- a/packages/ui/src/mosaic/sections/leave-organization.tsx
+++ /dev/null
@@ -1,18 +0,0 @@
-import type { ReactElement } from 'react';
-
-import { useLeaveOrganizationController } from './leave-organization.controller';
-import { LeaveOrganizationView } from './leave-organization.view';
-
-export function LeaveOrganization(): ReactElement | null {
-  const controller = useLeaveOrganizationController();
-  if (controller.status !== 'ready') {
-    return null;
-  }
-  return (
-    <LeaveOrganizationView
-      snapshot={controller.snapshot}
-      send={controller.send}
-      canSubmit={controller.canSubmit}
-    />
-  );
-}
diff --git a/packages/ui/src/mosaic/sections/delete-organization.controller.tsx b/packages/ui/src/mosaic/sections/organization-profile-delete-section.controller.tsx
similarity index 75%
rename from packages/ui/src/mosaic/sections/delete-organization.controller.tsx
rename to packages/ui/src/mosaic/sections/organization-profile-delete-section.controller.tsx
index 454069c3fd5..5bcbfe4a70f 100644
--- a/packages/ui/src/mosaic/sections/delete-organization.controller.tsx
+++ b/packages/ui/src/mosaic/sections/organization-profile-delete-section.controller.tsx
@@ -4,27 +4,30 @@ import { useMosaicEnvironment } from '../hooks/useMosaicEnvironment';
 import { useMosaicRouter } from '../hooks/useMosaicRouter';
 import type { Snapshot } from '../machine/types';
 import { useMachine } from '../machine/useMachine';
-import type { DeleteOrgContext, DeleteOrgEvent } from './delete-organization.machine';
-import { deleteOrgMachine } from './delete-organization.machine';
+import type {
+  OrganizationProfileDeleteSectionContext,
+  OrganizationProfileDeleteSectionEvent,
+} from './organization-profile-delete-section.machine';
+import { organizationProfileDeleteSectionMachine } from './organization-profile-delete-section.machine';
 
-type DeleteOrganizationController =
+type OrganizationProfileDeleteSectionController =
   | { status: 'loading' }
   | { status: 'hidden' }
   | {
       status: 'ready';
-      snapshot: Snapshot<DeleteOrgContext>;
-      send: (event: DeleteOrgEvent) => void;
+      snapshot: Snapshot<OrganizationProfileDeleteSectionContext>;
+      send: (event: OrganizationProfileDeleteSectionEvent) => void;
       canSubmit: boolean;
     };
 
-export function useDeleteOrganizationController(): DeleteOrganizationController {
+export function useOrganizationProfileDeleteSectionController(): OrganizationProfileDeleteSectionController {
   const { isLoaded: isOrganizationLoaded, organization } = useOrganization();
   const { isLoaded: isSessionLoaded, session } = useSession();
   const { userMemberships } = useOrganizationList({ userMemberships: true });
   const router = useMosaicRouter();
   const afterLeaveUrl = useMosaicEnvironment()?.displayConfig.afterLeaveOrganizationUrl;
 
-  const [snapshot, send, actor] = useMachine(deleteOrgMachine, {
+  const [snapshot, send, actor] = useMachine(organizationProfileDeleteSectionMachine, {
     context: {
       organizationName: organization?.name ?? '',
       destroyOrganization: async () => {
diff --git a/packages/ui/src/mosaic/sections/delete-organization.machine.ts b/packages/ui/src/mosaic/sections/organization-profile-delete-section.machine.ts
similarity index 80%
rename from packages/ui/src/mosaic/sections/delete-organization.machine.ts
rename to packages/ui/src/mosaic/sections/organization-profile-delete-section.machine.ts
index 0a3f6c23d08..298ca17c1c4 100644
--- a/packages/ui/src/mosaic/sections/delete-organization.machine.ts
+++ b/packages/ui/src/mosaic/sections/organization-profile-delete-section.machine.ts
@@ -1,21 +1,24 @@
 import { setup } from '../machine/setup';
 
-export interface DeleteOrgContext {
+export interface OrganizationProfileDeleteSectionContext {
   organizationName: string;
   confirmationValue: string;
   destroyOrganization: () => Promise<void>;
   error: string | null;
 }
 
-export type DeleteOrgEvent =
+export type OrganizationProfileDeleteSectionEvent =
   | { type: 'OPEN' }
   | { type: 'TYPE_CONFIRMATION'; value: string }
   | { type: 'CONFIRM' }
   | { type: 'CANCEL' };
 
-const { createMachine, assign, fromPromise } = setup<DeleteOrgContext, DeleteOrgEvent>();
+const { createMachine, assign, fromPromise } = setup<
+  OrganizationProfileDeleteSectionContext,
+  OrganizationProfileDeleteSectionEvent
+>();
 
-export const deleteOrgMachine = createMachine({
+export const organizationProfileDeleteSectionMachine = createMachine({
   id: 'deleteOrg',
   initial: 'idle',
   context: {
diff --git a/packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx b/packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx
new file mode 100644
index 00000000000..b0e9b33569c
--- /dev/null
+++ b/packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx
@@ -0,0 +1,18 @@
+import type { ReactElement } from 'react';
+
+import { useOrganizationProfileDeleteSectionController } from './organization-profile-delete-section.controller';
+import { OrganizationProfileDeleteSectionView } from './organization-profile-delete-section.view';
+
+export function OrganizationProfileDeleteSection(): ReactElement | null {
+  const controller = useOrganizationProfileDeleteSectionController();
+  if (controller.status !== 'ready') {
+    return null;
+  }
+  return (
+    <OrganizationProfileDeleteSectionView
+      snapshot={controller.snapshot}
+      send={controller.send}
+      canSubmit={controller.canSubmit}
+    />
+  );
+}
diff --git a/packages/ui/src/mosaic/sections/delete-organization.view.tsx b/packages/ui/src/mosaic/sections/organization-profile-delete-section.view.tsx
similarity index 83%
rename from packages/ui/src/mosaic/sections/delete-organization.view.tsx
rename to packages/ui/src/mosaic/sections/organization-profile-delete-section.view.tsx
index 46fdc1353fe..035f97cd8de 100644
--- a/packages/ui/src/mosaic/sections/delete-organization.view.tsx
+++ b/packages/ui/src/mosaic/sections/organization-profile-delete-section.view.tsx
@@ -2,15 +2,22 @@ import { Destructive } from '../block/destructive';
 import { Box } from '../components/box';
 import { Button } from '../components/button';
 import type { Snapshot } from '../machine/types';
-import type { DeleteOrgContext, DeleteOrgEvent } from './delete-organization.machine';
+import type {
+  OrganizationProfileDeleteSectionContext,
+  OrganizationProfileDeleteSectionEvent,
+} from './organization-profile-delete-section.machine';
 
-interface DeleteOrganizationViewProps {
-  snapshot: Snapshot<DeleteOrgContext>;
-  send: (event: DeleteOrgEvent) => void;
+interface OrganizationProfileDeleteSectionViewProps {
+  snapshot: Snapshot<OrganizationProfileDeleteSectionContext>;
+  send: (event: OrganizationProfileDeleteSectionEvent) => void;
   canSubmit: boolean;
 }
 
-export function DeleteOrganizationView({ snapshot, send, canSubmit }: DeleteOrganizationViewProps) {
+export function OrganizationProfileDeleteSectionView({
+  snapshot,
+  send,
+  canSubmit,
+}: OrganizationProfileDeleteSectionViewProps) {
   const isDeleting = snapshot.value === 'deleting';
 
   return (
diff --git a/packages/ui/src/mosaic/sections/leave-organization.controller.tsx b/packages/ui/src/mosaic/sections/organization-profile-leave-section.controller.tsx
similarity index 77%
rename from packages/ui/src/mosaic/sections/leave-organization.controller.tsx
rename to packages/ui/src/mosaic/sections/organization-profile-leave-section.controller.tsx
index 58eb3d512a2..9cd19c3916f 100644
--- a/packages/ui/src/mosaic/sections/leave-organization.controller.tsx
+++ b/packages/ui/src/mosaic/sections/organization-profile-leave-section.controller.tsx
@@ -4,27 +4,30 @@ import { useMosaicEnvironment } from '../hooks/useMosaicEnvironment';
 import { useMosaicRouter } from '../hooks/useMosaicRouter';
 import type { Snapshot } from '../machine/types';
 import { useMachine } from '../machine/useMachine';
-import type { LeaveOrgContext, LeaveOrgEvent } from './leave-organization.machine';
-import { leaveOrgMachine } from './leave-organization.machine';
+import type {
+  OrganizationProfileLeaveSectionContext,
+  OrganizationProfileLeaveSectionEvent,
+} from './organization-profile-leave-section.machine';
+import { organizationProfileLeaveSectionMachine } from './organization-profile-leave-section.machine';
 
-type LeaveOrganizationController =
+type OrganizationProfileLeaveSectionController =
   | { status: 'loading' }
   | { status: 'hidden' }
   | {
       status: 'ready';
-      snapshot: Snapshot<LeaveOrgContext>;
-      send: (event: LeaveOrgEvent) => void;
+      snapshot: Snapshot<OrganizationProfileLeaveSectionContext>;
+      send: (event: OrganizationProfileLeaveSectionEvent) => void;
       canSubmit: boolean;
     };
 
-export function useLeaveOrganizationController(): LeaveOrganizationController {
+export function useOrganizationProfileLeaveSectionController(): OrganizationProfileLeaveSectionController {
   const { isLoaded, organization, membership } = useOrganization();
   const { user } = useUser();
   const { userMemberships } = useOrganizationList({ userMemberships: true });
   const router = useMosaicRouter();
   const afterLeaveUrl = useMosaicEnvironment()?.displayConfig.afterLeaveOrganizationUrl;
 
-  const [snapshot, send, actor] = useMachine(leaveOrgMachine, {
+  const [snapshot, send, actor] = useMachine(organizationProfileLeaveSectionMachine, {
     context: {
       organizationName: organization?.name ?? '',
       leaveOrganization: async () => {
diff --git a/packages/ui/src/mosaic/sections/leave-organization.machine.ts b/packages/ui/src/mosaic/sections/organization-profile-leave-section.machine.ts
similarity index 80%
rename from packages/ui/src/mosaic/sections/leave-organization.machine.ts
rename to packages/ui/src/mosaic/sections/organization-profile-leave-section.machine.ts
index 76a52bcbcfb..9a2014dc5dc 100644
--- a/packages/ui/src/mosaic/sections/leave-organization.machine.ts
+++ b/packages/ui/src/mosaic/sections/organization-profile-leave-section.machine.ts
@@ -1,21 +1,24 @@
 import { setup } from '../machine/setup';
 
-export interface LeaveOrgContext {
+export interface OrganizationProfileLeaveSectionContext {
   organizationName: string;
   confirmationValue: string;
   leaveOrganization: () => Promise<void>;
   error: string | null;
 }
 
-export type LeaveOrgEvent =
+export type OrganizationProfileLeaveSectionEvent =
   | { type: 'OPEN' }
   | { type: 'TYPE_CONFIRMATION'; value: string }
   | { type: 'CONFIRM' }
   | { type: 'CANCEL' };
 
-const { createMachine, assign, fromPromise } = setup<LeaveOrgContext, LeaveOrgEvent>();
+const { createMachine, assign, fromPromise } = setup<
+  OrganizationProfileLeaveSectionContext,
+  OrganizationProfileLeaveSectionEvent
+>();
 
-export const leaveOrgMachine = createMachine({
+export const organizationProfileLeaveSectionMachine = createMachine({
   id: 'leaveOrg',
   initial: 'idle',
   context: {
diff --git a/packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx b/packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx
new file mode 100644
index 00000000000..93f540babf6
--- /dev/null
+++ b/packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx
@@ -0,0 +1,18 @@
+import type { ReactElement } from 'react';
+
+import { useOrganizationProfileLeaveSectionController } from './organization-profile-leave-section.controller';
+import { OrganizationProfileLeaveSectionView } from './organization-profile-leave-section.view';
+
+export function OrganizationProfileLeaveSection(): ReactElement | null {
+  const controller = useOrganizationProfileLeaveSectionController();
+  if (controller.status !== 'ready') {
+    return null;
+  }
+  return (
+    <OrganizationProfileLeaveSectionView
+      snapshot={controller.snapshot}
+      send={controller.send}
+      canSubmit={controller.canSubmit}
+    />
+  );
+}
diff --git a/packages/ui/src/mosaic/sections/leave-organization.view.tsx b/packages/ui/src/mosaic/sections/organization-profile-leave-section.view.tsx
similarity index 83%
rename from packages/ui/src/mosaic/sections/leave-organization.view.tsx
rename to packages/ui/src/mosaic/sections/organization-profile-leave-section.view.tsx
index 404c0b68547..807c2f2b4eb 100644
--- a/packages/ui/src/mosaic/sections/leave-organization.view.tsx
+++ b/packages/ui/src/mosaic/sections/organization-profile-leave-section.view.tsx
@@ -2,15 +2,22 @@ import { Destructive } from '../block/destructive';
 import { Box } from '../components/box';
 import { Button } from '../components/button';
 import type { Snapshot } from '../machine/types';
-import type { LeaveOrgContext, LeaveOrgEvent } from './leave-organization.machine';
+import type {
+  OrganizationProfileLeaveSectionContext,
+  OrganizationProfileLeaveSectionEvent,
+} from './organization-profile-leave-section.machine';
 
-interface LeaveOrganizationViewProps {
-  snapshot: Snapshot<LeaveOrgContext>;
-  send: (event: LeaveOrgEvent) => void;
+interface OrganizationProfileLeaveSectionViewProps {
+  snapshot: Snapshot<OrganizationProfileLeaveSectionContext>;
+  send: (event: OrganizationProfileLeaveSectionEvent) => void;
   canSubmit: boolean;
 }
 
-export function LeaveOrganizationView({ snapshot, send, canSubmit }: LeaveOrganizationViewProps) {
+export function OrganizationProfileLeaveSectionView({
+  snapshot,
+  send,
+  canSubmit,
+}: OrganizationProfileLeaveSectionViewProps) {
   const isLeaving = snapshot.value === 'leaving';
 
   return (

From 2fb9cbd66854fb8be14f1ac8924317863768dc98 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 1 Jul 2026 11:17:49 -0400
Subject: [PATCH 12/15] Delete .changeset/public-mangos-join.md

---
 .changeset/public-mangos-join.md | 2 --
 1 file changed, 2 deletions(-)
 delete mode 100644 .changeset/public-mangos-join.md

diff --git a/.changeset/public-mangos-join.md b/.changeset/public-mangos-join.md
deleted file mode 100644
index a845151cc84..00000000000
--- a/.changeset/public-mangos-join.md
+++ /dev/null
@@ -1,2 +0,0 @@
----
----

From c1e7c00023360218f181f49e6e077f9f7511353c Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 1 Jul 2026 13:45:09 -0400
Subject: [PATCH 13/15] refactor(ui): group mosaic organization profile files
 under a feature directory

---
 .../organization-profile-delete-section.stories.tsx       | 6 +++---
 .../organization-profile-general-panel.stories.tsx        | 4 ++--
 .../organization-profile-leave-section.stories.tsx        | 6 +++---
 .../swingset/src/stories/organization-profile.stories.tsx | 4 ++--
 packages/ui/src/experimental/__tests__/mosaic.test.tsx    | 6 +++---
 packages/ui/src/experimental/mosaic.ts                    | 8 ++++----
 ...rganization-profile-delete-section.controller.test.tsx | 0
 .../organization-profile-delete-section.machine.test.ts   | 0
 .../organization-profile-delete-section.view.test.tsx     | 0
 ...organization-profile-leave-section.controller.test.tsx | 0
 .../organization-profile-leave-section.machine.test.ts    | 0
 .../organization-profile-leave-section.view.test.tsx      | 0
 .../__tests__/organization-profile.controller.test.tsx    | 0
 .../__tests__/organization-profile.test.tsx               | 6 +++---
 .../organization-profile-delete-section.controller.tsx    | 0
 .../organization-profile-delete-section.machine.ts        | 0
 .../organization-profile-delete-section.tsx               | 0
 .../organization-profile-delete-section.view.tsx          | 0
 .../organization-profile-general-panel-view.tsx           | 0
 .../organization-profile-general-panel.tsx                | 4 ++--
 .../organization-profile-leave-section.controller.tsx     | 0
 .../organization-profile-leave-section.machine.ts         | 0
 .../organization-profile-leave-section.tsx                | 0
 .../organization-profile-leave-section.view.tsx           | 0
 .../{aio => organization}/organization-profile-view.tsx   | 0
 .../organization-profile.controller.tsx                   | 0
 .../mosaic/{aio => organization}/organization-profile.tsx | 6 +++---
 references/mosaic-architecture.md                         | 6 +++---
 28 files changed, 28 insertions(+), 28 deletions(-)
 rename packages/ui/src/mosaic/{sections => organization}/__tests__/organization-profile-delete-section.controller.test.tsx (100%)
 rename packages/ui/src/mosaic/{sections => organization}/__tests__/organization-profile-delete-section.machine.test.ts (100%)
 rename packages/ui/src/mosaic/{sections => organization}/__tests__/organization-profile-delete-section.view.test.tsx (100%)
 rename packages/ui/src/mosaic/{sections => organization}/__tests__/organization-profile-leave-section.controller.test.tsx (100%)
 rename packages/ui/src/mosaic/{sections => organization}/__tests__/organization-profile-leave-section.machine.test.ts (100%)
 rename packages/ui/src/mosaic/{sections => organization}/__tests__/organization-profile-leave-section.view.test.tsx (100%)
 rename packages/ui/src/mosaic/{aio => organization}/__tests__/organization-profile.controller.test.tsx (100%)
 rename packages/ui/src/mosaic/{aio => organization}/__tests__/organization-profile.test.tsx (67%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-delete-section.controller.tsx (100%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-delete-section.machine.ts (100%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-delete-section.tsx (100%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-delete-section.view.tsx (100%)
 rename packages/ui/src/mosaic/{panels => organization}/organization-profile-general-panel-view.tsx (100%)
 rename packages/ui/src/mosaic/{panels => organization}/organization-profile-general-panel.tsx (66%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-leave-section.controller.tsx (100%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-leave-section.machine.ts (100%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-leave-section.tsx (100%)
 rename packages/ui/src/mosaic/{sections => organization}/organization-profile-leave-section.view.tsx (100%)
 rename packages/ui/src/mosaic/{aio => organization}/organization-profile-view.tsx (100%)
 rename packages/ui/src/mosaic/{aio => organization}/organization-profile.controller.tsx (100%)
 rename packages/ui/src/mosaic/{aio => organization}/organization-profile.tsx (82%)

diff --git a/packages/swingset/src/stories/organization-profile-delete-section.stories.tsx b/packages/swingset/src/stories/organization-profile-delete-section.stories.tsx
index ebb912a173b..8e1282cbe99 100644
--- a/packages/swingset/src/stories/organization-profile-delete-section.stories.tsx
+++ b/packages/swingset/src/stories/organization-profile-delete-section.stories.tsx
@@ -1,14 +1,14 @@
 /** @jsxImportSource @emotion/react */
 import { useMachine } from '@clerk/ui/mosaic/machine/useMachine';
-import { organizationProfileDeleteSectionMachine } from '@clerk/ui/mosaic/sections/organization-profile-delete-section.machine';
-import { OrganizationProfileDeleteSectionView } from '@clerk/ui/mosaic/sections/organization-profile-delete-section.view';
+import { organizationProfileDeleteSectionMachine } from '@clerk/ui/mosaic/organization/organization-profile-delete-section.machine';
+import { OrganizationProfileDeleteSectionView } from '@clerk/ui/mosaic/organization/organization-profile-delete-section.view';
 
 import type { StoryMeta } from '@/lib/types';
 
 export const meta: StoryMeta = {
   group: 'Organization',
   title: 'OrganizationProfileDeleteSection',
-  source: 'packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx',
+  source: 'packages/ui/src/mosaic/organization/organization-profile-delete-section.tsx',
 };
 
 export function Default() {
diff --git a/packages/swingset/src/stories/organization-profile-general-panel.stories.tsx b/packages/swingset/src/stories/organization-profile-general-panel.stories.tsx
index 52d21aa9147..0d592a68f75 100644
--- a/packages/swingset/src/stories/organization-profile-general-panel.stories.tsx
+++ b/packages/swingset/src/stories/organization-profile-general-panel.stories.tsx
@@ -1,5 +1,5 @@
 /** @jsxImportSource @emotion/react */
-import { OrganizationProfileGeneralPanelView } from '@clerk/ui/mosaic/panels/organization-profile-general-panel-view';
+import { OrganizationProfileGeneralPanelView } from '@clerk/ui/mosaic/organization/organization-profile-general-panel-view';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -9,7 +9,7 @@ import { Default as OrganizationProfileLeaveSectionDemo } from './organization-p
 export const meta: StoryMeta = {
   group: 'Organization',
   title: 'OrganizationProfileGeneralPanel',
-  source: 'packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx',
+  source: 'packages/ui/src/mosaic/organization/organization-profile-general-panel.tsx',
 };
 
 export function Default() {
diff --git a/packages/swingset/src/stories/organization-profile-leave-section.stories.tsx b/packages/swingset/src/stories/organization-profile-leave-section.stories.tsx
index d0b2324dcdc..e98a3111159 100644
--- a/packages/swingset/src/stories/organization-profile-leave-section.stories.tsx
+++ b/packages/swingset/src/stories/organization-profile-leave-section.stories.tsx
@@ -1,14 +1,14 @@
 /** @jsxImportSource @emotion/react */
 import { useMachine } from '@clerk/ui/mosaic/machine/useMachine';
-import { organizationProfileLeaveSectionMachine } from '@clerk/ui/mosaic/sections/organization-profile-leave-section.machine';
-import { OrganizationProfileLeaveSectionView } from '@clerk/ui/mosaic/sections/organization-profile-leave-section.view';
+import { organizationProfileLeaveSectionMachine } from '@clerk/ui/mosaic/organization/organization-profile-leave-section.machine';
+import { OrganizationProfileLeaveSectionView } from '@clerk/ui/mosaic/organization/organization-profile-leave-section.view';
 
 import type { StoryMeta } from '@/lib/types';
 
 export const meta: StoryMeta = {
   group: 'Organization',
   title: 'OrganizationProfileLeaveSection',
-  source: 'packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx',
+  source: 'packages/ui/src/mosaic/organization/organization-profile-leave-section.tsx',
 };
 
 export function Default() {
diff --git a/packages/swingset/src/stories/organization-profile.stories.tsx b/packages/swingset/src/stories/organization-profile.stories.tsx
index 48fb9994751..09cf2d1b20e 100644
--- a/packages/swingset/src/stories/organization-profile.stories.tsx
+++ b/packages/swingset/src/stories/organization-profile.stories.tsx
@@ -1,5 +1,5 @@
 /** @jsxImportSource @emotion/react */
-import { OrganizationProfileView } from '@clerk/ui/mosaic/aio/organization-profile-view';
+import { OrganizationProfileView } from '@clerk/ui/mosaic/organization/organization-profile-view';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -8,7 +8,7 @@ import { Default as OrganizationProfileGeneralPanelDemo } from './organization-p
 export const meta: StoryMeta = {
   group: 'Organization',
   title: 'OrganizationProfile',
-  source: 'packages/ui/src/mosaic/aio/organization-profile.tsx',
+  source: 'packages/ui/src/mosaic/organization/organization-profile.tsx',
 };
 
 export function Default() {
diff --git a/packages/ui/src/experimental/__tests__/mosaic.test.tsx b/packages/ui/src/experimental/__tests__/mosaic.test.tsx
index 3f49cfedf54..f6da7d93580 100644
--- a/packages/ui/src/experimental/__tests__/mosaic.test.tsx
+++ b/packages/ui/src/experimental/__tests__/mosaic.test.tsx
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest';
 
-import { OrganizationProfileGeneralPanel as GeneralPanelPart } from '../../mosaic/panels/organization-profile-general-panel';
-import { OrganizationProfileDeleteSection as DeleteSectionPart } from '../../mosaic/sections/organization-profile-delete-section';
-import { OrganizationProfileLeaveSection as LeaveSectionPart } from '../../mosaic/sections/organization-profile-leave-section';
+import { OrganizationProfileDeleteSection as DeleteSectionPart } from '../../mosaic/organization/organization-profile-delete-section';
+import { OrganizationProfileGeneralPanel as GeneralPanelPart } from '../../mosaic/organization/organization-profile-general-panel';
+import { OrganizationProfileLeaveSection as LeaveSectionPart } from '../../mosaic/organization/organization-profile-leave-section';
 import {
   OrganizationProfile,
   OrganizationProfileDeleteSection,
diff --git a/packages/ui/src/experimental/mosaic.ts b/packages/ui/src/experimental/mosaic.ts
index 23e7a6b680b..6635a8242ba 100644
--- a/packages/ui/src/experimental/mosaic.ts
+++ b/packages/ui/src/experimental/mosaic.ts
@@ -33,8 +33,8 @@
  */
 export { MosaicProvider } from '../mosaic/MosaicProvider';
 export type { MosaicProviderProps } from '../mosaic/MosaicProvider';
-export { OrganizationProfile } from '../mosaic/aio/organization-profile';
-export { OrganizationProfileGeneralPanel } from '../mosaic/panels/organization-profile-general-panel';
-export { OrganizationProfileDeleteSection } from '../mosaic/sections/organization-profile-delete-section';
-export { OrganizationProfileLeaveSection } from '../mosaic/sections/organization-profile-leave-section';
+export { OrganizationProfile } from '../mosaic/organization/organization-profile';
+export { OrganizationProfileGeneralPanel } from '../mosaic/organization/organization-profile-general-panel';
+export { OrganizationProfileDeleteSection } from '../mosaic/organization/organization-profile-delete-section';
+export { OrganizationProfileLeaveSection } from '../mosaic/organization/organization-profile-leave-section';
 export type { MosaicAppearance } from '../mosaic/appearance';
diff --git a/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.controller.test.tsx b/packages/ui/src/mosaic/organization/__tests__/organization-profile-delete-section.controller.test.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.controller.test.tsx
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile-delete-section.controller.test.tsx
diff --git a/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.machine.test.ts b/packages/ui/src/mosaic/organization/__tests__/organization-profile-delete-section.machine.test.ts
similarity index 100%
rename from packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.machine.test.ts
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile-delete-section.machine.test.ts
diff --git a/packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.view.test.tsx b/packages/ui/src/mosaic/organization/__tests__/organization-profile-delete-section.view.test.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/__tests__/organization-profile-delete-section.view.test.tsx
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile-delete-section.view.test.tsx
diff --git a/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.controller.test.tsx b/packages/ui/src/mosaic/organization/__tests__/organization-profile-leave-section.controller.test.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.controller.test.tsx
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile-leave-section.controller.test.tsx
diff --git a/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.machine.test.ts b/packages/ui/src/mosaic/organization/__tests__/organization-profile-leave-section.machine.test.ts
similarity index 100%
rename from packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.machine.test.ts
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile-leave-section.machine.test.ts
diff --git a/packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.view.test.tsx b/packages/ui/src/mosaic/organization/__tests__/organization-profile-leave-section.view.test.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/__tests__/organization-profile-leave-section.view.test.tsx
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile-leave-section.view.test.tsx
diff --git a/packages/ui/src/mosaic/aio/__tests__/organization-profile.controller.test.tsx b/packages/ui/src/mosaic/organization/__tests__/organization-profile.controller.test.tsx
similarity index 100%
rename from packages/ui/src/mosaic/aio/__tests__/organization-profile.controller.test.tsx
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile.controller.test.tsx
diff --git a/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx b/packages/ui/src/mosaic/organization/__tests__/organization-profile.test.tsx
similarity index 67%
rename from packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
rename to packages/ui/src/mosaic/organization/__tests__/organization-profile.test.tsx
index 1d9f241bb10..2bcfd817d51 100644
--- a/packages/ui/src/mosaic/aio/__tests__/organization-profile.test.tsx
+++ b/packages/ui/src/mosaic/organization/__tests__/organization-profile.test.tsx
@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest';
 
-import { OrganizationProfileGeneralPanel } from '../../panels/organization-profile-general-panel';
-import { OrganizationProfileDeleteSection } from '../../sections/organization-profile-delete-section';
-import { OrganizationProfileLeaveSection } from '../../sections/organization-profile-leave-section';
 import { OrganizationProfile } from '../organization-profile';
+import { OrganizationProfileDeleteSection } from '../organization-profile-delete-section';
+import { OrganizationProfileGeneralPanel } from '../organization-profile-general-panel';
+import { OrganizationProfileLeaveSection } from '../organization-profile-leave-section';
 
 describe('OrganizationProfile compound parts', () => {
   it('exposes the general panel as a standalone part', () => {
diff --git a/packages/ui/src/mosaic/sections/organization-profile-delete-section.controller.tsx b/packages/ui/src/mosaic/organization/organization-profile-delete-section.controller.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-delete-section.controller.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-delete-section.controller.tsx
diff --git a/packages/ui/src/mosaic/sections/organization-profile-delete-section.machine.ts b/packages/ui/src/mosaic/organization/organization-profile-delete-section.machine.ts
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-delete-section.machine.ts
rename to packages/ui/src/mosaic/organization/organization-profile-delete-section.machine.ts
diff --git a/packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx b/packages/ui/src/mosaic/organization/organization-profile-delete-section.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-delete-section.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-delete-section.tsx
diff --git a/packages/ui/src/mosaic/sections/organization-profile-delete-section.view.tsx b/packages/ui/src/mosaic/organization/organization-profile-delete-section.view.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-delete-section.view.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-delete-section.view.tsx
diff --git a/packages/ui/src/mosaic/panels/organization-profile-general-panel-view.tsx b/packages/ui/src/mosaic/organization/organization-profile-general-panel-view.tsx
similarity index 100%
rename from packages/ui/src/mosaic/panels/organization-profile-general-panel-view.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-general-panel-view.tsx
diff --git a/packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx b/packages/ui/src/mosaic/organization/organization-profile-general-panel.tsx
similarity index 66%
rename from packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-general-panel.tsx
index be67223347e..ddae2c3672f 100644
--- a/packages/ui/src/mosaic/panels/organization-profile-general-panel.tsx
+++ b/packages/ui/src/mosaic/organization/organization-profile-general-panel.tsx
@@ -1,8 +1,8 @@
 import type { ReactElement } from 'react';
 
-import { OrganizationProfileDeleteSection } from '../sections/organization-profile-delete-section';
-import { OrganizationProfileLeaveSection } from '../sections/organization-profile-leave-section';
+import { OrganizationProfileDeleteSection } from './organization-profile-delete-section';
 import { OrganizationProfileGeneralPanelView } from './organization-profile-general-panel-view';
+import { OrganizationProfileLeaveSection } from './organization-profile-leave-section';
 
 export function OrganizationProfileGeneralPanel(): ReactElement {
   return (
diff --git a/packages/ui/src/mosaic/sections/organization-profile-leave-section.controller.tsx b/packages/ui/src/mosaic/organization/organization-profile-leave-section.controller.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-leave-section.controller.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-leave-section.controller.tsx
diff --git a/packages/ui/src/mosaic/sections/organization-profile-leave-section.machine.ts b/packages/ui/src/mosaic/organization/organization-profile-leave-section.machine.ts
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-leave-section.machine.ts
rename to packages/ui/src/mosaic/organization/organization-profile-leave-section.machine.ts
diff --git a/packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx b/packages/ui/src/mosaic/organization/organization-profile-leave-section.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-leave-section.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-leave-section.tsx
diff --git a/packages/ui/src/mosaic/sections/organization-profile-leave-section.view.tsx b/packages/ui/src/mosaic/organization/organization-profile-leave-section.view.tsx
similarity index 100%
rename from packages/ui/src/mosaic/sections/organization-profile-leave-section.view.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-leave-section.view.tsx
diff --git a/packages/ui/src/mosaic/aio/organization-profile-view.tsx b/packages/ui/src/mosaic/organization/organization-profile-view.tsx
similarity index 100%
rename from packages/ui/src/mosaic/aio/organization-profile-view.tsx
rename to packages/ui/src/mosaic/organization/organization-profile-view.tsx
diff --git a/packages/ui/src/mosaic/aio/organization-profile.controller.tsx b/packages/ui/src/mosaic/organization/organization-profile.controller.tsx
similarity index 100%
rename from packages/ui/src/mosaic/aio/organization-profile.controller.tsx
rename to packages/ui/src/mosaic/organization/organization-profile.controller.tsx
diff --git a/packages/ui/src/mosaic/aio/organization-profile.tsx b/packages/ui/src/mosaic/organization/organization-profile.tsx
similarity index 82%
rename from packages/ui/src/mosaic/aio/organization-profile.tsx
rename to packages/ui/src/mosaic/organization/organization-profile.tsx
index 5b2ca1dcba3..cf7403395d7 100644
--- a/packages/ui/src/mosaic/aio/organization-profile.tsx
+++ b/packages/ui/src/mosaic/organization/organization-profile.tsx
@@ -1,9 +1,9 @@
 import type { ReactElement } from 'react';
 
-import { OrganizationProfileGeneralPanel } from '../panels/organization-profile-general-panel';
-import { OrganizationProfileDeleteSection } from '../sections/organization-profile-delete-section';
-import { OrganizationProfileLeaveSection } from '../sections/organization-profile-leave-section';
 import { useOrganizationProfileController } from './organization-profile.controller';
+import { OrganizationProfileDeleteSection } from './organization-profile-delete-section';
+import { OrganizationProfileGeneralPanel } from './organization-profile-general-panel';
+import { OrganizationProfileLeaveSection } from './organization-profile-leave-section';
 import { OrganizationProfileView } from './organization-profile-view';
 
 function OrganizationProfileRoot(): ReactElement | null {
diff --git a/references/mosaic-architecture.md b/references/mosaic-architecture.md
index 9e9f10e62d2..42fa47e7294 100644
--- a/references/mosaic-architecture.md
+++ b/references/mosaic-architecture.md
@@ -540,9 +540,9 @@ To migrate a component from the old system to Mosaic:
 | `src/mosaic/resolveSlot.ts`                       | Pure per-slot appearance-layer resolver (`resolveSlotCss`)                  |
 | `src/mosaic/conditions.ts`                        | Condition vocabulary (`_hover`, …) + `expandConditions`                     |
 | `src/mosaic/machine/`                             | State-machine runtime (`createMachine`, `createActor`, `useMachine`)        |
-| `src/mosaic/sections/*-machine.ts`                | Pure flow rules for Mosaic sections                                         |
-| `src/mosaic/sections/*-controller.tsx`            | Clerk/mock data adapters and actor wiring for Mosaic sections               |
-| `src/mosaic/sections/*-view.tsx`                  | Clerk-free view modules that render snapshots and send events               |
+| `src/mosaic/<feature>/*-machine.ts`               | Pure flow rules for a Mosaic feature (e.g. `organization/`)                 |
+| `src/mosaic/<feature>/*-controller.tsx`           | Clerk/mock data adapters and actor wiring for a Mosaic feature              |
+| `src/mosaic/<feature>/*-view.tsx`                 | Clerk-free view modules that render snapshots and send events               |
 | `src/mosaic/__tests__/slot-recipe.test.ts`        | Recipe resolution, attrs, conditions, `useSlot`/`slot` specs                |
 | `src/mosaic/__tests__/resolveSlot.test.ts`        | Appearance-layer resolution specs                                           |
 | `src/mosaic/__tests__/MosaicProvider.test.tsx`    | Appearance/scope parsing + theme-from-variables specs                       |

From 61d1f4524e9b8228c8170244f03240371ae7874c Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 2 Jul 2026 11:25:42 -0400
Subject: [PATCH 14/15] fix(ui): layer mosaic cache styles and accept element
 icon overrides

Wrap the Mosaic Emotion cache's insert with @layer so generated component styles carry the same layer as the reset (mirroring StyleCacheProvider). Previously only the reset was layered, so component styles were inserted unlayered and outranked a consumer's @layer-ed app styles.

Change appearance.icons overrides from render functions to React elements, injected via cloneElement. Elements serialize across the RSC server/client boundary, so consumers can supply icon overrides from a Server Component.
---
 .../swingset/src/stories/icon.stories.tsx     | 41 ++++++------
 packages/ui/src/mosaic/MosaicProvider.tsx     | 16 +++++
 .../__tests__/MosaicProvider.ssr.test.tsx     | 47 ++++++++++++++
 .../mosaic/__tests__/MosaicProvider.test.tsx  | 44 ++++++++++++-
 .../ui/src/mosaic/__tests__/icon.test.tsx     | 64 ++++++++++---------
 packages/ui/src/mosaic/appearance.ts          | 19 +++---
 packages/ui/src/mosaic/components/icon.tsx    | 27 +++++---
 7 files changed, 188 insertions(+), 70 deletions(-)
 create mode 100644 packages/ui/src/mosaic/__tests__/MosaicProvider.ssr.test.tsx

diff --git a/packages/swingset/src/stories/icon.stories.tsx b/packages/swingset/src/stories/icon.stories.tsx
index 42d04648a01..d52091a8777 100644
--- a/packages/swingset/src/stories/icon.stories.tsx
+++ b/packages/swingset/src/stories/icon.stories.tsx
@@ -1,5 +1,4 @@
 /** @jsxImportSource @emotion/react */
-import type { MosaicIconRenderer } from '@clerk/ui/mosaic/appearance';
 import type { IconProps } from '@clerk/ui/mosaic/components/icon';
 import { Icon, iconRecipe } from '@clerk/ui/mosaic/components/icon';
 import { iconRegistry } from '@clerk/ui/mosaic/icons/registry';
@@ -75,26 +74,30 @@ export function Names() {
   );
 }
 
-// Mosaic's styling (sizing/color) applies to the override just like the built-in glyph, so the
-// replacement only needs its viewBox + paths — spread `props` to receive the sizing className and
-// `data-cl-slot`. Defined at module scope (not inline in the story) to keep a stable component type.
-const CircleGlyph: MosaicIconRenderer = props => (
-  <svg
-    {...props}
-    viewBox='0 0 20 20'
-    fill='currentColor'
-  >
-    <circle
-      cx={10}
-      cy={10}
-      r={6}
-    />
-  </svg>
-);
-
 export function Override() {
   return (
-    <MosaicProvider appearance={{ icons: { 'chevron-right': CircleGlyph } }}>
+    <MosaicProvider
+      appearance={{
+        // Overrides are elements now, not render functions: Mosaic injects its sizing className and
+        // `data-cl-slot` into the element via cloneElement, so the replacement only needs its viewBox
+        // + paths. Passing an element (vs a function) also lets overrides be supplied from a Server
+        // Component, since elements serialize across the RSC boundary.
+        icons: {
+          'chevron-right': (
+            <svg
+              viewBox='0 0 20 20'
+              fill='currentColor'
+            >
+              <circle
+                cx={10}
+                cy={10}
+                r={6}
+              />
+            </svg>
+          ),
+        },
+      }}
+    >
       <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
         <Icon name='chevron-right' />
         <Icon name='chevron-left' />
diff --git a/packages/ui/src/mosaic/MosaicProvider.tsx b/packages/ui/src/mosaic/MosaicProvider.tsx
index ae2db8060ad..1a817750aed 100644
--- a/packages/ui/src/mosaic/MosaicProvider.tsx
+++ b/packages/ui/src/mosaic/MosaicProvider.tsx
@@ -79,6 +79,22 @@ export function MosaicProvider({
       nonce,
     });
 
+    // Route every cache insert through `@layer` so generated component styles carry the same layer
+    // as the static reset above. The reset alone is not enough: without wrapping `insert`, Emotion
+    // ships each component rule unlayered, and unlayered styles always outrank a consumer's
+    // `@layer`-ed app styles. Mirrors StyleCacheProvider's wrap — keep the two in sync.
+    if (cssLayerName) {
+      const layer = cssLayerName;
+      const insert = emotionCache.insert.bind(emotionCache);
+      emotionCache.insert = (selector, serialized, sheet, shouldCache) => {
+        if (!serialized.styles.startsWith('@layer')) {
+          const layered = { ...serialized, styles: `@layer ${layer} {${serialized.styles}}` };
+          return insert(selector, layered, sheet, shouldCache);
+        }
+        return insert(selector, serialized, sheet, shouldCache);
+      };
+    }
+
     return emotionCache;
   }, [nonce, cssLayerName]);
 
diff --git a/packages/ui/src/mosaic/__tests__/MosaicProvider.ssr.test.tsx b/packages/ui/src/mosaic/__tests__/MosaicProvider.ssr.test.tsx
new file mode 100644
index 00000000000..4acf3ea25d3
--- /dev/null
+++ b/packages/ui/src/mosaic/__tests__/MosaicProvider.ssr.test.tsx
@@ -0,0 +1,47 @@
+// @vitest-environment node
+//
+// Runs in a real node environment (no jsdom `document`) so `renderToString` exercises the actual
+// server path: `ensureInsertionPoint` returns null and Emotion inserts through the wrapped cache.
+// `@clerk/ui/experimental/mosaic` is a `'use client'` boundary, but Next.js still server-renders it,
+// so the provider must render without touching the DOM and its layer wrapping must hold on the server.
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { MosaicProvider } from '../MosaicProvider';
+
+describe('MosaicProvider SSR', () => {
+  it('renders on the server without throwing', () => {
+    expect(() =>
+      renderToString(
+        <MosaicProvider>
+          <div css={{ color: 'red' }} />
+        </MosaicProvider>,
+      ),
+    ).not.toThrow();
+  });
+
+  it('emits the reset wrapped in the layer when cssLayerName is set', () => {
+    const html = renderToString(
+      <MosaicProvider cssLayerName='cl-test'>
+        <div />
+      </MosaicProvider>,
+    );
+
+    // Combined substring, not two separate `toContain`s: proves the reset itself sits inside the layer.
+    expect(html).toContain('@layer cl-test{:where([data-cl-slot])');
+  });
+
+  it('wraps server-inserted component styles in the layer when cssLayerName is set', () => {
+    const html = renderToString(
+      <MosaicProvider cssLayerName='cl-test'>
+        <div css={{ color: 'red' }} />
+      </MosaicProvider>,
+    );
+
+    expect(html).toContain('color:red');
+    // The component rule (`.cl-mosaic-*`) must be nested in the layer, not merely coexist with the
+    // already-layered reset elsewhere in the markup.
+    expect(html).toMatch(/@layer cl-test\s*\{\s*\.cl-mosaic/);
+  });
+});
diff --git a/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx b/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx
index d1db9db4176..24c763560d3 100644
--- a/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx
+++ b/packages/ui/src/mosaic/__tests__/MosaicProvider.test.tsx
@@ -13,10 +13,13 @@ const appearance: MosaicAppearance = {
   },
 };
 
-// Every MosaicProvider render now self-creates the Emotion insertion-point node, so
-// clean it up after each test to keep the document fresh across the whole file.
+// Every MosaicProvider render now self-creates the Emotion insertion-point node and Emotion
+// appends its own <style data-emotion> tags, so clear both after each test to keep the document
+// fresh across the whole file (Emotion tags would otherwise leak across the layer-wrapping cases).
 afterEach(() => {
-  document.querySelectorAll('style#cl-mosaic-style-insertion-point').forEach(node => node.remove());
+  document
+    .querySelectorAll('style#cl-mosaic-style-insertion-point, style[data-emotion]')
+    .forEach(node => node.remove());
 });
 
 describe('parseMosaicAppearance', () => {
@@ -94,6 +97,41 @@ describe('MosaicProvider global reset', () => {
   });
 });
 
+describe('MosaicProvider cssLayerName', () => {
+  // Emotion's generated component styles carry `data-emotion`; the static reset does not, so this
+  // isolates the styles inserted *through the cache* — the ones the layer wrap has to cover.
+  const emotionCss = () =>
+    Array.from(document.querySelectorAll('style[data-emotion]'))
+      .map(node => node.textContent ?? '')
+      .join('');
+
+  it('wraps cache-generated component styles in the layer when cssLayerName is set', () => {
+    render(
+      <MosaicProvider cssLayerName='cl-test'>
+        <div css={{ color: 'red' }} />
+      </MosaicProvider>,
+    );
+
+    const css = emotionCss();
+    expect(css).toContain('color:red');
+    // Without the insert wrap, the generated rule ships unlayered and outranks a consumer's
+    // @layer-ed app styles. The @layer only appears in Emotion output when the wrap is applied.
+    expect(css).toContain('@layer cl-test');
+  });
+
+  it('leaves cache-generated styles unlayered when no cssLayerName is set', () => {
+    render(
+      <MosaicProvider>
+        <div css={{ color: 'blue' }} />
+      </MosaicProvider>,
+    );
+
+    const css = emotionCss();
+    expect(css).toContain('color:blue');
+    expect(css).not.toContain('@layer');
+  });
+});
+
 describe('MosaicProvider Emotion insertion point', () => {
   it('creates the insertion-point node when the host has not supplied one', () => {
     expect(document.querySelector('style#cl-mosaic-style-insertion-point')).toBeNull();
diff --git a/packages/ui/src/mosaic/__tests__/icon.test.tsx b/packages/ui/src/mosaic/__tests__/icon.test.tsx
index a3bab67518a..072158d9ab8 100644
--- a/packages/ui/src/mosaic/__tests__/icon.test.tsx
+++ b/packages/ui/src/mosaic/__tests__/icon.test.tsx
@@ -24,16 +24,9 @@ describe('Icon', () => {
     expect(svg?.querySelector('path')).not.toBeNull();
   });
 
-  it('renders the override instead of the default glyph', () => {
+  it('renders the override element instead of the default glyph', () => {
     const appearance: MosaicAppearance = {
-      icons: {
-        'chevron-right': props => (
-          <span
-            {...props}
-            data-testid='override'
-          />
-        ),
-      },
+      icons: { 'chevron-right': <span data-testid='override' /> },
     };
     const { getByTestId, container } = wrap(<Icon name='chevron-right' />, appearance);
     expect(getByTestId('override')).not.toBeNull();
@@ -41,16 +34,9 @@ describe('Icon', () => {
     expect(container.querySelector('svg')).toBeNull();
   });
 
-  it('applies Mosaic styling (className) and the slot attr to the override', () => {
+  it('injects Mosaic styling (className) and the slot attr into the override element', () => {
     const appearance: MosaicAppearance = {
-      icons: {
-        'chevron-right': props => (
-          <span
-            {...props}
-            data-testid='override'
-          />
-        ),
-      },
+      icons: { 'chevron-right': <span data-testid='override' /> },
     };
     const { getByTestId } = wrap(
       <Icon
@@ -64,19 +50,44 @@ describe('Icon', () => {
     expect(el.getAttribute('data-cl-slot')).toBe('icon');
   });
 
-  it('applies appearance.elements.icon styling to an overridden glyph (consistent with the built-in)', () => {
+  it("merges the override element's own className with Mosaic's rather than clobbering it", () => {
     const appearance: MosaicAppearance = {
-      elements: { icon: { opacity: 0.5 } },
       icons: {
-        'chevron-right': props => (
+        'chevron-right': (
           <span
-            {...props}
             data-testid='override'
+            className='consumer-glyph'
           />
         ),
       },
     };
     const { getByTestId } = wrap(<Icon name='chevron-right' />, appearance);
+    const el = getByTestId('override');
+    expect(el.classList.contains('consumer-glyph')).toBe(true);
+    // Mosaic's serialized class is applied alongside the consumer's, not in place of it.
+    expect(el.classList.length).toBeGreaterThan(1);
+  });
+
+  it('forwards svg props from the Icon call site onto the override element', () => {
+    const appearance: MosaicAppearance = {
+      icons: { 'chevron-right': <span data-testid='override' /> },
+    };
+    const { getByTestId } = wrap(
+      <Icon
+        name='chevron-right'
+        aria-label='Next'
+      />,
+      appearance,
+    );
+    expect(getByTestId('override').getAttribute('aria-label')).toBe('Next');
+  });
+
+  it('applies appearance.elements.icon styling to an overridden glyph (consistent with the built-in)', () => {
+    const appearance: MosaicAppearance = {
+      elements: { icon: { opacity: 0.5 } },
+      icons: { 'chevron-right': <span data-testid='override' /> },
+    };
+    const { getByTestId } = wrap(<Icon name='chevron-right' />, appearance);
     // The override carries a serialized Mosaic class...
     expect(getByTestId('override').className).toBeTruthy();
     // ...and that class actually applies the appearance.elements.icon styling.
@@ -85,14 +96,7 @@ describe('Icon', () => {
 
   it('falls through to the default when a different name is overridden', () => {
     const appearance: MosaicAppearance = {
-      icons: {
-        'chevron-left': props => (
-          <span
-            {...props}
-            data-testid='override'
-          />
-        ),
-      },
+      icons: { 'chevron-left': <span data-testid='override' /> },
     };
     const { container, queryByTestId } = wrap(<Icon name='chevron-right' />, appearance);
     expect(queryByTestId('override')).toBeNull();
diff --git a/packages/ui/src/mosaic/appearance.ts b/packages/ui/src/mosaic/appearance.ts
index 5e9e614c8da..8d6efd6f59f 100644
--- a/packages/ui/src/mosaic/appearance.ts
+++ b/packages/ui/src/mosaic/appearance.ts
@@ -5,17 +5,20 @@ import type { MosaicElements } from './registry';
 import type { MosaicVariables } from './variables';
 
 /**
- * The props handed to an icon override: the resolved `className` (Mosaic's sizing/color, applied to
- * the override exactly as to the built-in glyph, so icons stay visually consistent), `data-cl-slot`
- * for targeting, and any forwarded `svg` props. Spread them onto your element.
+ * A replacement glyph for a named icon, authored as a React element (`<MyIcon />` or a raw
+ * `<svg>…</svg>`). Mosaic injects its sizing/color `className`, `data-cl-slot`, and any svg props
+ * forwarded from the `<Icon>` call site into this element via `cloneElement`, so the override is
+ * styled and targetable exactly like the built-in glyph. Author the element to accept those props
+ * (a component should spread them onto its root svg; a raw svg receives them directly).
+ *
+ * An element rather than a render function so overrides serialize across the RSC server→client
+ * boundary: `appearance.icons` can then be supplied from a Server Component. An inline function
+ * cannot cross that boundary; an element (or a `'use client'` component reference) can.
  */
-export type MosaicIconRenderProps = React.ComponentPropsWithoutRef<'svg'> & { 'data-cl-slot'?: string };
-
-/** Replaces a named icon's glyph. Spread the received props onto your element so Mosaic styling applies. */
-export type MosaicIconRenderer = (props: MosaicIconRenderProps) => React.ReactElement;
+export type MosaicIconOverride = React.ReactElement;
 
 /** `appearance.icons`: per-name glyph overrides, applied globally. */
-export type MosaicIconOverrides = Partial<Record<IconName, MosaicIconRenderer>>;
+export type MosaicIconOverrides = Partial<Record<IconName, MosaicIconOverride>>;
 
 /**
  * The flow-scope keys an `appearance` may carry. Overrides nested under one of these keys (inside
diff --git a/packages/ui/src/mosaic/components/icon.tsx b/packages/ui/src/mosaic/components/icon.tsx
index 39eeaf40af4..e95978f27d2 100644
--- a/packages/ui/src/mosaic/components/icon.tsx
+++ b/packages/ui/src/mosaic/components/icon.tsx
@@ -34,26 +34,33 @@ export type IconProps = React.ComponentPropsWithRef<'svg'> & RecipeVariantProps<
 /**
  * Renders a Mosaic icon by name. The glyph can be swapped per-name via `appearance.icons` on
  * `MosaicProvider`. Mosaic's recipe styling (sizing/color) is applied to *both* the built-in glyph and
- * an override so they stay visually consistent — the override receives the resolved `className` plus
- * `data-cl-slot="icon"` and forwarded props.
+ * an override so they stay visually consistent — the override element is cloned with the resolved
+ * `className` (merged with its own), `data-cl-slot="icon"`, and forwarded props.
  */
 export const Icon = React.forwardRef<SVGSVGElement, IconProps>(function MosaicIcon({ name, size, sx, ...rest }, ref) {
   const { root } = useRecipe(iconRecipe, { variants: { size }, sx });
   const override = useMosaicIcons()[name];
 
   if (override) {
-    // The override is authored in a consumer file without the Emotion jsx pragma, so the `css` prop
-    // would be ignored there. Serialize Mosaic's styling to a real `className` (via the Mosaic cache)
-    // so it applies to the override exactly as it does to the built-in glyph.
+    // The override is authored in a consumer file without the Emotion jsx pragma, so its own `css`
+    // prop would be ignored. Serialize Mosaic's styling to a real `className` (via the Mosaic cache)
+    // and inject it — plus `data-cl-slot` and the forwarded svg props — into the override element with
+    // cloneElement, so it styles exactly like the built-in glyph. Cloning an element (rather than
+    // calling a render fn) is what lets overrides be plain elements, which unlike functions serialize
+    // across the RSC boundary.
     return (
       <ClassNames>
-        {emotion =>
-          override({
+        {emotion => {
+          // SAFETY: React 18 types `ReactElement.props` as `any`; we only read an optional className
+          // to merge with Mosaic's so a consumer's own class survives. cloneElement re-validates the
+          // merged props against the element's real type at render, surfacing any mismatch there.
+          const overrideClassName = (override.props as { className?: string }).className;
+          return React.cloneElement(override, {
             ...rest,
             'data-cl-slot': root['data-cl-slot'],
-            className: emotion.cx(emotion.css(root.css), root.className),
-          })
-        }
+            className: emotion.cx(emotion.css(root.css), root.className, overrideClassName),
+          });
+        }}
       </ClassNames>
     );
   }

From 27cb37ae1de81f92d34a906483d37ccceaafbe13 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 2 Jul 2026 11:39:46 -0400
Subject: [PATCH 15/15] docs(ui): explain why mosaic icon overrides do not
 receive Icon's ref

---
 packages/ui/src/mosaic/components/icon.tsx | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/mosaic/components/icon.tsx b/packages/ui/src/mosaic/components/icon.tsx
index e95978f27d2..fdd61f8f65a 100644
--- a/packages/ui/src/mosaic/components/icon.tsx
+++ b/packages/ui/src/mosaic/components/icon.tsx
@@ -44,10 +44,15 @@ export const Icon = React.forwardRef<SVGSVGElement, IconProps>(function MosaicIc
   if (override) {
     // The override is authored in a consumer file without the Emotion jsx pragma, so its own `css`
     // prop would be ignored. Serialize Mosaic's styling to a real `className` (via the Mosaic cache)
-    // and inject it — plus `data-cl-slot` and the forwarded svg props — into the override element with
+    // and inject it, plus `data-cl-slot` and the forwarded svg props, into the override element with
     // cloneElement, so it styles exactly like the built-in glyph. Cloning an element (rather than
     // calling a render fn) is what lets overrides be plain elements, which unlike functions serialize
     // across the RSC boundary.
+    //
+    // Icon's `ref` is intentionally not forwarded to the override. It is typed for the built-in
+    // `SVGSVGElement`, but an override can be any element, so forwarding would mistype it (or drop it
+    // for a non-forwardRef component). A consumer that needs a ref puts one on the element they author
+    // (`icons: { name: <svg ref={r} /> }`); cloneElement preserves it, since we do not set `ref` here.
     return (
       <ClassNames>
         {emotion => {