From 03a555a54d04ecb77b2fa8bdf2ac8adb60b26507 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 16 Sep 2026 19:45:49 -0400
Subject: [PATCH 1/3] feat(ui): mirror direction-aware Mosaic icons under rtl

---
 .changeset/mosaic-rtl-mirror-icons.md         |  5 ++
 .claude/skills/mosaic/references/stylex.md    | 13 +++-
 .../steps/reverification-method-picker.tsx    | 12 ++-
 .../features/user-button/user-button.view.tsx |  3 +
 .../user-profile-api-keys-panel.view.tsx      | 11 ++-
 ...r-profile-billing-history-section.view.tsx | 11 ++-
 packages/mosaic/src/utils/rtl.styles.ts       |  7 ++
 packages/mosaic/src/utils/rtl.test.tsx        | 35 +++++++++
 packages/swingset/CLAUDE.md                   |  1 +
 .../swingset/src/components/ClientRoot.tsx    | 73 ++++++++++---------
 .../src/components/DirectionProvider.tsx      | 25 +++++++
 .../src/components/DirectionToggle.tsx        | 26 +++++++
 references/mosaic-architecture.md             |  2 +-
 13 files changed, 182 insertions(+), 42 deletions(-)
 create mode 100644 .changeset/mosaic-rtl-mirror-icons.md
 create mode 100644 packages/mosaic/src/utils/rtl.styles.ts
 create mode 100644 packages/mosaic/src/utils/rtl.test.tsx
 create mode 100644 packages/swingset/src/components/DirectionProvider.tsx
 create mode 100644 packages/swingset/src/components/DirectionToggle.tsx

diff --git a/.changeset/mosaic-rtl-mirror-icons.md b/.changeset/mosaic-rtl-mirror-icons.md
new file mode 100644
index 00000000000..b4384210b9f
--- /dev/null
+++ b/.changeset/mosaic-rtl-mirror-icons.md
@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Direction-aware icons in Mosaic (the forward chevrons on menu rows and the previous/next arrows in paginated lists) now mirror horizontally when rendered under an ancestor with `dir="rtl"`.
diff --git a/.claude/skills/mosaic/references/stylex.md b/.claude/skills/mosaic/references/stylex.md
index 49a9041db4a..a760afbba98 100644
--- a/.claude/skills/mosaic/references/stylex.md
+++ b/.claude/skills/mosaic/references/stylex.md
@@ -52,8 +52,17 @@ rule reserves the `.stylex.ts` extension for StyleX define-primitives: **a
   components render the same visual surface — e.g. inputs (`TextInput`,
   `NumberInput`, date fields, `Selector`) sharing one `inputWrapper` /
   `inputStatusBorder` / `inputStatusFocusWithin` set instead of redefining the
-  border/focus treatment five times. Three exist today: `reset.styles.ts`,
-  `typography.styles.ts` and `focus-outline.styles.ts`.
+  border/focus treatment five times. Four exist today: `reset.styles.ts`,
+  `typography.styles.ts`, `focus-outline.styles.ts` and `rtl.styles.ts`.
+- **DO** compose `rtl.mirror` from `utils/rtl.styles.ts` onto a direction-aware
+  icon — a chevron that means "forward"/"back", a pagination arrow, the
+  log-out arrow leaving its frame — via its
+  `xstyle`. It flips the glyph with `scaleX(-1)` only under an ancestor carrying
+  `dir="rtl"`, so the same `chevron-right` reads as "forward" in both directions.
+  Pick it by meaning, not by shape: a chevron that points at a dropdown or an
+  external-link arrow stays unmirrored.
+- **DON'T** register a mirrored twin (`chevron-forward`) in the icon registry or
+  swap the name at the call site by direction. The direction lives in CSS.
 - **DON'T** put a shared style file under `components/`. That directory holds one
   subdirectory per component and nothing else, so a loose file there reads as a
   component that lost its folder.
diff --git a/packages/mosaic/src/features/reverification/steps/reverification-method-picker.tsx b/packages/mosaic/src/features/reverification/steps/reverification-method-picker.tsx
index 244ccb2bb2a..67b78173a51 100644
--- a/packages/mosaic/src/features/reverification/steps/reverification-method-picker.tsx
+++ b/packages/mosaic/src/features/reverification/steps/reverification-method-picker.tsx
@@ -8,6 +8,7 @@ import { Icon, IconFrame } from '../../../components/icon';
 import { Item } from '../../../components/item';
 import { Spinner } from '../../../components/spinner';
 import { Text } from '../../../components/text';
+import { rtl } from '../../../utils/rtl.styles';
 
 const styles = stylex.create({
   helpText: {
@@ -81,7 +82,16 @@ export function ReverificationMethodPicker({
                   <Item.Label>{method.label}</Item.Label>
                   {method.description ? <Item.Description>{method.description}</Item.Description> : null}
                 </Item.Content>
-                <Item.Actions>{isPending ? <Spinner size='sm' /> : <Icon name='chevron-right' />}</Item.Actions>
+                <Item.Actions>
+                  {isPending ? (
+                    <Spinner size='sm' />
+                  ) : (
+                    <Icon
+                      name='chevron-right'
+                      xstyle={rtl.mirror}
+                    />
+                  )}
+                </Item.Actions>
               </Item.Root>
             );
           })}
diff --git a/packages/mosaic/src/features/user-button/user-button.view.tsx b/packages/mosaic/src/features/user-button/user-button.view.tsx
index 33a6f5dfefd..d3e8594244c 100644
--- a/packages/mosaic/src/features/user-button/user-button.view.tsx
+++ b/packages/mosaic/src/features/user-button/user-button.view.tsx
@@ -21,6 +21,7 @@ import type { IconName } from '../../icons/registry';
 import { applyOrder } from '../../utils/apply-order';
 import { focusOutline } from '../../utils/focus-outline.styles';
 import { fill, plural } from '../../utils/messages';
+import { rtl } from '../../utils/rtl.styles';
 import { truncationStyles } from '../../utils/typography.styles';
 import type { UserButtonLayout } from './user-button.layout';
 import { resolveUserButtonLayout } from './user-button.layout';
@@ -794,6 +795,7 @@ function SwitchAccountRow() {
         <Trailing>
           <Icon
             name='chevron-right'
+            xstyle={rtl.mirror}
             size='sm'
           />
         </Trailing>
@@ -957,6 +959,7 @@ function Footer() {
               <Icon
                 name='log-out'
                 size='sm'
+                xstyle={rtl.mirror}
               />
             }
             label={m.accounts.signOutAll}
diff --git a/packages/mosaic/src/features/user-profile/user-profile-api-keys-panel.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-api-keys-panel.view.tsx
index 189eda2d84c..782fe7af056 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-api-keys-panel.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-api-keys-panel.view.tsx
@@ -8,6 +8,7 @@ import { Input } from '../../components/input';
 import { Menu } from '../../components/menu';
 import { Profile } from '../../components/profile';
 import { mergeStyleProps, themeProps } from '../../props';
+import { rtl } from '../../utils/rtl.styles';
 import { styles } from './user-profile-api-keys-panel.styles';
 
 export interface UserProfileAPIKey {
@@ -202,7 +203,10 @@ export function UserProfileApiKeysPanelView({
               variant='ghost'
               onClick={() => onPageChange?.(pagination.page - 1)}
             >
-              <Icon name='chevron-left' />
+              <Icon
+                name='chevron-left'
+                xstyle={rtl.mirror}
+              />
             </Button>
             <Button
               aria-current='page'
@@ -225,7 +229,10 @@ export function UserProfileApiKeysPanelView({
               variant='ghost'
               onClick={() => onPageChange?.(pagination.page + 1)}
             >
-              <Icon name='chevron-right' />
+              <Icon
+                name='chevron-right'
+                xstyle={rtl.mirror}
+              />
             </Button>
           </div>
           <label {...stylex.props(styles.pageSizeLabel)}>
diff --git a/packages/mosaic/src/features/user-profile/user-profile-billing-history-section.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-billing-history-section.view.tsx
index d6d53ae605a..3f066d55e08 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-billing-history-section.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-billing-history-section.view.tsx
@@ -5,6 +5,7 @@ import { Badge } from '../../components/badge';
 import { Button } from '../../components/button';
 import { Icon } from '../../components/icon';
 import { Section } from '../../components/section';
+import { rtl } from '../../utils/rtl.styles';
 import { styles } from './user-profile-billing-history-section.styles';
 
 export interface UserProfileBillingHistoryItem {
@@ -128,7 +129,10 @@ export function UserProfileBillingHistorySectionView({
                 variant='ghost'
                 onClick={() => onPageChange?.(pagination.page - 1)}
               >
-                <Icon name='chevron-left' />
+                <Icon
+                  name='chevron-left'
+                  xstyle={rtl.mirror}
+                />
               </Button>
               <Button
                 aria-current='page'
@@ -151,7 +155,10 @@ export function UserProfileBillingHistorySectionView({
                 variant='ghost'
                 onClick={() => onPageChange?.(pagination.page + 1)}
               >
-                <Icon name='chevron-right' />
+                <Icon
+                  name='chevron-right'
+                  xstyle={rtl.mirror}
+                />
               </Button>
             </div>
             <label {...stylex.props(styles.pageSizeLabel)}>
diff --git a/packages/mosaic/src/utils/rtl.styles.ts b/packages/mosaic/src/utils/rtl.styles.ts
new file mode 100644
index 00000000000..7d2053cc028
--- /dev/null
+++ b/packages/mosaic/src/utils/rtl.styles.ts
@@ -0,0 +1,7 @@
+import * as stylex from '@stylexjs/stylex';
+
+export const rtl = stylex.create({
+  mirror: {
+    transform: { default: null, ':is([dir="rtl"] *)': 'scaleX(-1)' },
+  },
+});
diff --git a/packages/mosaic/src/utils/rtl.test.tsx b/packages/mosaic/src/utils/rtl.test.tsx
new file mode 100644
index 00000000000..b1e8adfa08f
--- /dev/null
+++ b/packages/mosaic/src/utils/rtl.test.tsx
@@ -0,0 +1,35 @@
+import * as stylex from '@stylexjs/stylex';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { Icon } from '../components/icon';
+import { rtl } from './rtl.styles';
+
+// StyleX generates the same atom for the same property+value across separate `create` calls, so a
+// local probe names the atom to assert on without hardcoding a hash that a StyleX upgrade rewrites.
+const probe = stylex.create({
+  mirrored: { transform: { default: null, ':is([dir="rtl"] *)': 'scaleX(-1)' } },
+});
+
+const atoms = (style: stylex.StyleXStyles) =>
+  (stylex.props(style).className ?? '').split(' ').filter(name => name && !name.includes('__'));
+
+const mirrorAtom = atoms(probe.mirrored);
+
+describe('Mosaic rtl styles', () => {
+  it('mirrors on the horizontal axis only under an rtl ancestor', () => {
+    expect(mirrorAtom).toHaveLength(1);
+    expect(atoms(rtl.mirror)).toEqual(mirrorAtom);
+  });
+
+  it('lands on an icon that composes it through xstyle', () => {
+    const { container } = render(
+      <Icon
+        name='chevron-right'
+        xstyle={rtl.mirror}
+      />,
+    );
+
+    expect(container.querySelector('svg')).toHaveClass(...mirrorAtom);
+  });
+});
diff --git a/packages/swingset/CLAUDE.md b/packages/swingset/CLAUDE.md
index 1eb41b490d1..a90634273e6 100644
--- a/packages/swingset/CLAUDE.md
+++ b/packages/swingset/CLAUDE.md
@@ -32,6 +32,7 @@ These require reading several files together; the `README.md` covers the step-by
 - **Shared playground state.** `DocsViewer` wraps each overview in a `PlaygroundProvider` (`PlaygroundContext.tsx`), keyed by slug and seeded from the component's `meta` via `getModuleBySlug`. It owns the knob values (props). The `<Preview>` and the interactive `<PropTable>` both read/write this single context, so editing a prop in the table updates the preview above it.
 
 - **Every story renders inside `MosaicProvider`.** `StoryPreview` (the MDX `<Preview>`) renders a named story with the playground's knob values as props and exposes a Reset button. `StoryEmbed` (the MDX `<Story>`) renders a single static variation with default knob values and no controls.
+  - The header's **RTL** switch (`DirectionToggle`, state in `DirectionProvider`) sets `dir` on `<html>`. It has to sit that high because popover and menu popups portal to `<body>`, so a `dir` on the preview container would never reach them; swingset's own chrome flips along with the story.
 
 - **The prop table is the knob surface.** `PropTable` (MDX `<PropTable>`) derives rows from `meta.styles._variants`/`_defaultVariants`, then appends the `className` + `style` escape-hatch rows every Mosaic component accepts. Each variant row renders a `KnobControl` in its **Value** column, seeded with the prop's default and bound to the playground context. The escape-hatch rows and `extra` stay static.
 
diff --git a/packages/swingset/src/components/ClientRoot.tsx b/packages/swingset/src/components/ClientRoot.tsx
index 08a85129e6b..d22b88fef6a 100644
--- a/packages/swingset/src/components/ClientRoot.tsx
+++ b/packages/swingset/src/components/ClientRoot.tsx
@@ -16,6 +16,8 @@ import { SidebarInset, SidebarProvider, SidebarTrigger } from '@/components/ui/s
 import { getModule } from '@/lib/registry';
 
 import { AppSidebar } from './app-sidebar';
+import { DirectionProvider } from './DirectionProvider';
+import { DirectionToggle } from './DirectionToggle';
 import { ThemeToggle } from './ThemeToggle';
 
 function useBreadcrumb() {
@@ -38,39 +40,42 @@ export function ClientRoot({ children }: { children: React.ReactNode }) {
   const crumbs = useBreadcrumb();
 
   return (
-    <SidebarProvider>
-      <AppSidebar />
-      <SidebarInset>
-        <header className='bg-background sticky top-0 z-10 flex h-12 shrink-0 items-center gap-2 border-b px-4'>
-          <SidebarTrigger className='-ml-1' />
-          <Separator
-            orientation='vertical'
-            className='data-vertical:h-4 data-vertical:self-auto mr-2'
-          />
-          {crumbs.length > 0 && (
-            <Breadcrumb>
-              <BreadcrumbList>
-                {crumbs.map((crumb, i) => (
-                  <React.Fragment key={crumb}>
-                    {i > 0 && <BreadcrumbSeparator className='hidden md:block' />}
-                    <BreadcrumbItem className={i < crumbs.length - 1 ? 'hidden md:block' : undefined}>
-                      {i < crumbs.length - 1 ? (
-                        <BreadcrumbLink href='#'>{crumb}</BreadcrumbLink>
-                      ) : (
-                        <BreadcrumbPage>{crumb}</BreadcrumbPage>
-                      )}
-                    </BreadcrumbItem>
-                  </React.Fragment>
-                ))}
-              </BreadcrumbList>
-            </Breadcrumb>
-          )}
-          <div className='ml-auto'>
-            <ThemeToggle />
-          </div>
-        </header>
-        {children}
-      </SidebarInset>
-    </SidebarProvider>
+    <DirectionProvider>
+      <SidebarProvider>
+        <AppSidebar />
+        <SidebarInset>
+          <header className='bg-background sticky top-0 z-10 flex h-12 shrink-0 items-center gap-2 border-b px-4'>
+            <SidebarTrigger className='-ml-1' />
+            <Separator
+              orientation='vertical'
+              className='data-vertical:h-4 data-vertical:self-auto mr-2'
+            />
+            {crumbs.length > 0 && (
+              <Breadcrumb>
+                <BreadcrumbList>
+                  {crumbs.map((crumb, i) => (
+                    <React.Fragment key={crumb}>
+                      {i > 0 && <BreadcrumbSeparator className='hidden md:block' />}
+                      <BreadcrumbItem className={i < crumbs.length - 1 ? 'hidden md:block' : undefined}>
+                        {i < crumbs.length - 1 ? (
+                          <BreadcrumbLink href='#'>{crumb}</BreadcrumbLink>
+                        ) : (
+                          <BreadcrumbPage>{crumb}</BreadcrumbPage>
+                        )}
+                      </BreadcrumbItem>
+                    </React.Fragment>
+                  ))}
+                </BreadcrumbList>
+              </Breadcrumb>
+            )}
+            <div className='ml-auto flex items-center gap-4'>
+              <DirectionToggle />
+              <ThemeToggle />
+            </div>
+          </header>
+          {children}
+        </SidebarInset>
+      </SidebarProvider>
+    </DirectionProvider>
   );
 }
diff --git a/packages/swingset/src/components/DirectionProvider.tsx b/packages/swingset/src/components/DirectionProvider.tsx
new file mode 100644
index 00000000000..4186ad8522e
--- /dev/null
+++ b/packages/swingset/src/components/DirectionProvider.tsx
@@ -0,0 +1,25 @@
+'use client';
+
+import * as React from 'react';
+
+export type Direction = 'ltr' | 'rtl';
+
+interface DirectionContextValue {
+  direction: Direction;
+  setDirection: (direction: Direction) => void;
+}
+
+const DirectionContext = React.createContext<DirectionContextValue>({ direction: 'ltr', setDirection: () => {} });
+
+export function DirectionProvider({ children }: { children: React.ReactNode }) {
+  const [direction, setDirection] = React.useState<Direction>('ltr');
+  React.useEffect(() => {
+    document.documentElement.dir = direction;
+  }, [direction]);
+  const value = React.useMemo(() => ({ direction, setDirection }), [direction]);
+  return <DirectionContext.Provider value={value}>{children}</DirectionContext.Provider>;
+}
+
+export function useDirection() {
+  return React.useContext(DirectionContext);
+}
diff --git a/packages/swingset/src/components/DirectionToggle.tsx b/packages/swingset/src/components/DirectionToggle.tsx
new file mode 100644
index 00000000000..9908837fde9
--- /dev/null
+++ b/packages/swingset/src/components/DirectionToggle.tsx
@@ -0,0 +1,26 @@
+'use client';
+
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+
+import { useDirection } from './DirectionProvider';
+
+export function DirectionToggle() {
+  const { direction, setDirection } = useDirection();
+
+  return (
+    <div className='flex items-center gap-2'>
+      <Switch
+        id='direction-toggle'
+        checked={direction === 'rtl'}
+        onCheckedChange={checked => setDirection(checked ? 'rtl' : 'ltr')}
+      />
+      <Label
+        htmlFor='direction-toggle'
+        className='text-muted-foreground cursor-pointer text-xs'
+      >
+        RTL
+      </Label>
+    </div>
+  );
+}
diff --git a/references/mosaic-architecture.md b/references/mosaic-architecture.md
index d7f1453bd18..0c02222de5d 100644
--- a/references/mosaic-architecture.md
+++ b/references/mosaic-architecture.md
@@ -125,7 +125,7 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(function
 
 A theme's CSS wins over the Mosaic sheet without any prop: the sheet is imported into a cascade layer (`@import '@clerk/mosaic/styles.css' layer(components)`) and an unlayered rule beats any layered one.
 
-`utils/reset.styles.ts` holds the per-element resets so a component does not re-declare UA-normalization; `utils/typography.styles.ts` and `utils/focus-outline.styles.ts` do the same for the treatments several components share.
+`utils/reset.styles.ts` holds the per-element resets so a component does not re-declare UA-normalization; `utils/typography.styles.ts`, `utils/focus-outline.styles.ts` and `utils/rtl.styles.ts` do the same for the treatments several components share. `rtl.mirror` flips a direction-aware icon (a forward/back chevron, a pagination arrow) under a `dir="rtl"` ancestor; there are no mirrored twins in the icon registry.
 
 For the full StyleX authoring rules (token usage, the local `s(n)` spacing helper, the CSS build), see the `mosaic` Claude Code skill's `references/stylex.md`.
 

From 9133dc6577108177cbc13aab53e947be607619d5 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 16 Sep 2026 19:47:07 -0400
Subject: [PATCH 2/3] chore(repo): use an empty changeset

---
 .changeset/mosaic-rtl-mirror-icons.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/.changeset/mosaic-rtl-mirror-icons.md b/.changeset/mosaic-rtl-mirror-icons.md
index b4384210b9f..a845151cc84 100644
--- a/.changeset/mosaic-rtl-mirror-icons.md
+++ b/.changeset/mosaic-rtl-mirror-icons.md
@@ -1,5 +1,2 @@
 ---
-'@clerk/ui': patch
 ---
-
-Direction-aware icons in Mosaic (the forward chevrons on menu rows and the previous/next arrows in paginated lists) now mirror horizontally when rendered under an ancestor with `dir="rtl"`.

From d4b2df6479606c0152c0dc824542b6776c12add9 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Thu, 17 Sep 2026 14:18:48 -0400
Subject: [PATCH 3/3] chore(mosaic): add changeset for rtl icon mirroring

---
 .changeset/mosaic-rtl-mirror-icons.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.changeset/mosaic-rtl-mirror-icons.md b/.changeset/mosaic-rtl-mirror-icons.md
index a845151cc84..1284ddefcf3 100644
--- a/.changeset/mosaic-rtl-mirror-icons.md
+++ b/.changeset/mosaic-rtl-mirror-icons.md
@@ -1,2 +1,5 @@
 ---
+'@clerk/mosaic': patch
 ---
+
+Direction-aware icons (the forward chevrons on menu rows, the log-out arrow, and the previous/next arrows in paginated lists) now mirror horizontally when rendered under an ancestor with `dir="rtl"`.