From 1d8aec9c986277cca90f252703c9cdd534014bff Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 14:42:59 -0600
Subject: [PATCH 1/5] feat(mosaic): anchor the tabs indicator to the selected
 tab

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/tabs-anchor-indicator.md           |   2 +
 .../segmented-control.styles.ts               |   1 +
 packages/mosaic/src/components/tabs/index.ts  |   1 -
 .../mosaic/src/components/tabs/tabs.styles.ts |  55 ++++-
 .../mosaic/src/components/tabs/tabs.test.tsx  |  72 +++++-
 packages/mosaic/src/components/tabs/tabs.tsx  |  36 +--
 ...rganization-profile-members-panel.view.tsx |   1 -
 packages/mosaic/src/primitives/tabs/README.md |  40 ++--
 .../src/primitives/tabs/tabs-context.ts       |  10 +-
 .../src/primitives/tabs/tabs-indicator.tsx    |  70 +-----
 .../mosaic/src/primitives/tabs/tabs-list.tsx  |   3 +-
 .../mosaic/src/primitives/tabs/tabs-panel.tsx |   5 +-
 .../mosaic/src/primitives/tabs/tabs-root.tsx  | 109 ++++++---
 .../mosaic/src/primitives/tabs/tabs.test.tsx  | 226 +++++-------------
 .../mosaic/src/primitives/utils/dom.test.ts   |  25 --
 packages/mosaic/src/primitives/utils/dom.ts   |  19 --
 packages/mosaic/src/styles/index.ts           |   1 -
 .../swingset/src/stories/tabs.component.mdx   |  23 +-
 .../src/stories/tabs.component.stories.tsx    |   1 -
 packages/swingset/src/stories/tabs.mdx        |  39 +--
 20 files changed, 340 insertions(+), 399 deletions(-)
 create mode 100644 .changeset/tabs-anchor-indicator.md

diff --git a/.changeset/tabs-anchor-indicator.md b/.changeset/tabs-anchor-indicator.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/tabs-anchor-indicator.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/mosaic/src/components/segmented-control/segmented-control.styles.ts b/packages/mosaic/src/components/segmented-control/segmented-control.styles.ts
index 57fe9fa37a4..14657cde42b 100644
--- a/packages/mosaic/src/components/segmented-control/segmented-control.styles.ts
+++ b/packages/mosaic/src/components/segmented-control/segmented-control.styles.ts
@@ -12,6 +12,7 @@ import {
   typeScaleVars,
 } from '../../tokens.stylex';
 
+// Literals: StyleX cannot import them. Must match `tabs.styles.ts`.
 const anchors = '@supports (anchor-scope: all) and (not (-moz-appearance: none))' as const;
 const noAnchors = '@supports not ((anchor-scope: all) and (not (-moz-appearance: none)))' as const;
 const reduceMotion = '@media (prefers-reduced-motion: reduce)' as const;
diff --git a/packages/mosaic/src/components/tabs/index.ts b/packages/mosaic/src/components/tabs/index.ts
index ad10c98dbd1..9cf08932446 100644
--- a/packages/mosaic/src/components/tabs/index.ts
+++ b/packages/mosaic/src/components/tabs/index.ts
@@ -1,6 +1,5 @@
 export { Tabs } from './tabs';
 export type {
-  TabsIndicatorProps,
   TabsListProps,
   TabsPanelProps,
   TabsPanelsProps,
diff --git a/packages/mosaic/src/components/tabs/tabs.styles.ts b/packages/mosaic/src/components/tabs/tabs.styles.ts
index 1c9e0ca5494..0901952b737 100644
--- a/packages/mosaic/src/components/tabs/tabs.styles.ts
+++ b/packages/mosaic/src/components/tabs/tabs.styles.ts
@@ -2,9 +2,24 @@ import * as stylex from '@stylexjs/stylex';
 
 import { colorVars, durationVars, easingVars, fontFamilyVars, space, typeScaleVars } from '../../tokens.stylex';
 
+// Literals: StyleX cannot import them. Must match `segmented-control.styles.ts`.
+const anchors = '@supports (anchor-scope: all) and (not (-moz-appearance: none))' as const;
+const noAnchors = '@supports not ((anchor-scope: all) and (not (-moz-appearance: none)))' as const;
 const reduceMotion = '@media (prefers-reduced-motion: reduce)' as const;
+const activeAnchor = '--_cl-tabs-active';
 const halfGap = `calc(${space['5']} / -2)`;
 
+const lead = durationVars['--cl-duration-slow'];
+const trail = durationVars['--cl-duration-slower'];
+
+const underline = {
+  backgroundColor: colorVars['--cl-color-foreground'],
+  pointerEvents: 'none',
+  position: 'absolute',
+  bottom: '-1px',
+  height: '2px',
+} as const;
+
 export const styles = stylex.create({
   root: {
     gap: space['6'],
@@ -13,6 +28,8 @@ export const styles = stylex.create({
     width: '100%',
   },
   list: {
+    // eslint-disable-next-line @stylexjs/valid-styles -- `anchor-scope`: anchor positioning postdates StyleX's property allowlist; it compiles and emits correctly.
+    anchorScope: activeAnchor,
     gap: space['5'],
     alignItems: 'center',
     display: 'flex',
@@ -44,6 +61,10 @@ export const styles = stylex.create({
     paddingBottom: space['3'],
     paddingTop: space['2.5'],
   },
+  anchor: {
+    // eslint-disable-next-line @stylexjs/valid-styles -- `anchor-name`: anchor positioning postdates StyleX's property allowlist; it compiles and emits correctly.
+    anchorName: { default: null, ':where([data-selected])': activeAnchor },
+  },
   hitArea: {
     '--_cl-tab-hit-end': { default: '0px', ':has(+ [role="tab"])': halfGap },
     '--_cl-tab-hit-start': { default: halfGap, ':first-child': '0px' },
@@ -66,16 +87,32 @@ export const styles = stylex.create({
     gridRowStart: '1',
   },
   indicator: {
-    backgroundColor: colorVars['--cl-color-foreground'],
-    pointerEvents: 'none',
-    position: 'absolute',
+    ...underline,
+    // eslint-disable-next-line @stylexjs/valid-styles -- `position-anchor`: anchor positioning postdates StyleX's property allowlist; it compiles and emits correctly.
+    positionAnchor: activeAnchor,
+    display: {
+      [anchors]: { default: 'none', ':where([data-selected] ~ *)': 'block' },
+      default: 'none',
+    },
+    insetInlineEnd: 'anchor(end)',
+    insetInlineStart: 'anchor(start)',
     transitionDuration: {
-      default: durationVars['--cl-duration-base'],
-      [reduceMotion]: durationVars['--cl-duration-instant'],
+      default: `${trail}, ${lead}`,
+      [reduceMotion]: {
+        default: durationVars['--cl-duration-instant'],
+        ':where([data-direction="backward"])': durationVars['--cl-duration-instant'],
+      },
+      ':where([data-direction="backward"])': `${lead}, ${trail}`,
+    },
+    transitionProperty: 'inset-inline-start, inset-inline-end',
+    transitionTimingFunction: easingVars['--cl-ease-default'],
+  },
+  fallbackIndicator: {
+    ...underline,
+    insetInline: 0,
+    display: {
+      default: 'none',
+      [noAnchors]: { default: 'none', ':where([data-selected] > *)': 'block' },
     },
-    transitionProperty: 'left, width',
-    transitionTimingFunction: easingVars['--cl-ease-enter'],
-    bottom: '-1px',
-    height: '2px',
   },
 });
diff --git a/packages/mosaic/src/components/tabs/tabs.test.tsx b/packages/mosaic/src/components/tabs/tabs.test.tsx
index e0c247bb2d9..89eb25c07f7 100644
--- a/packages/mosaic/src/components/tabs/tabs.test.tsx
+++ b/packages/mosaic/src/components/tabs/tabs.test.tsx
@@ -18,7 +18,6 @@ describe('Mosaic Tabs', () => {
         <Tabs.List>
           <Tabs.Tab value='members'>Members</Tabs.Tab>
           <Tabs.Tab value='invitations'>Invitations</Tabs.Tab>
-          <Tabs.Indicator data-testid='indicator' />
         </Tabs.List>
         <Tabs.Panels>
           <Tabs.Panel value='members'>Member list</Tabs.Panel>
@@ -29,7 +28,6 @@ describe('Mosaic Tabs', () => {
 
     expect(screen.getByRole('tablist')).toHaveClass('cl-tabs-list');
     expect(screen.getByRole('tab', { name: 'Members' })).toHaveClass('cl-tabs-tab');
-    expect(screen.getByTestId('indicator')).toHaveClass('cl-tabs-indicator');
     expect(screen.getByText('Member list')).toBeVisible();
     expect(screen.getByText('Invitation list')).not.toBeVisible();
 
@@ -39,6 +37,76 @@ describe('Mosaic Tabs', () => {
     expect(screen.getByText('Invitation list')).toBeVisible();
   });
 
+  it('renders the anchored indicator in the list and a fallback indicator in each tab', () => {
+    render(
+      <Tabs.Root defaultValue='members'>
+        <Tabs.List aria-label='Members'>
+          <Tabs.Tab value='members'>Members</Tabs.Tab>
+          <Tabs.Tab value='invitations'>Invitations</Tabs.Tab>
+        </Tabs.List>
+      </Tabs.Root>,
+    );
+
+    const list = screen.getByRole('tablist');
+    const anchored = list.lastElementChild;
+    expect(anchored).toHaveClass('cl-tabs-indicator', stylex.props(styles.indicator).className ?? '');
+    expect(anchored).toHaveAttribute('aria-hidden', 'true');
+
+    for (const tab of screen.getAllByRole('tab')) {
+      const fallback = tab.querySelector('.cl-tabs-indicator');
+      expect(fallback).toHaveClass(stylex.props(styles.fallbackIndicator).className ?? '');
+      expect(fallback).toHaveAttribute('aria-hidden', 'true');
+    }
+    expect(screen.getByRole('tab', { name: 'Members' })).toHaveAccessibleName('Members');
+  });
+
+  it('marks the indicator with the direction the selection traveled', async () => {
+    render(
+      <Tabs.Root defaultValue='invitations'>
+        <Tabs.List>
+          <Tabs.Tab value='members'>Members</Tabs.Tab>
+          <Tabs.Tab value='invitations'>Invitations</Tabs.Tab>
+          <Tabs.Tab value='requests'>Requests</Tabs.Tab>
+        </Tabs.List>
+      </Tabs.Root>,
+    );
+    const indicator = screen.getByRole('tablist').lastElementChild;
+
+    await userEvent.click(screen.getByRole('tab', { name: 'Members' }));
+    expect(indicator).toHaveAttribute('data-direction', 'backward');
+
+    await userEvent.click(screen.getByRole('tab', { name: 'Requests' }));
+    expect(indicator).toHaveAttribute('data-direction', 'forward');
+  });
+
+  it('keeps a nested tab list on its own indicator', async () => {
+    render(
+      <Tabs.Root defaultValue='outer-a'>
+        <Tabs.List aria-label='Outer'>
+          <Tabs.Tab value='outer-a'>Outer A</Tabs.Tab>
+          <Tabs.Tab value='outer-b'>Outer B</Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value='outer-a'>
+          <Tabs.Root defaultValue='inner-b'>
+            <Tabs.List aria-label='Inner'>
+              <Tabs.Tab value='inner-a'>Inner A</Tabs.Tab>
+              <Tabs.Tab value='inner-b'>Inner B</Tabs.Tab>
+            </Tabs.List>
+          </Tabs.Root>
+        </Tabs.Panel>
+      </Tabs.Root>,
+    );
+    const outer = screen.getByRole('tablist', { name: 'Outer' });
+    const inner = screen.getByRole('tablist', { name: 'Inner' });
+
+    await userEvent.click(screen.getByRole('tab', { name: 'Inner A' }));
+
+    expect(inner.lastElementChild).toHaveAttribute('data-direction', 'backward');
+    expect(outer.lastElementChild).toHaveAttribute('data-direction', 'forward');
+    expect(outer).toHaveClass(stylex.props(styles.list).className ?? '');
+    expect(inner).toHaveClass(stylex.props(styles.list).className ?? '');
+  });
+
   it('renders a stackable panel wrapper with a ref and xstyle', () => {
     const ref = React.createRef<HTMLDivElement>();
     render(
diff --git a/packages/mosaic/src/components/tabs/tabs.tsx b/packages/mosaic/src/components/tabs/tabs.tsx
index ead3c3dabfc..8cdf5efde70 100644
--- a/packages/mosaic/src/components/tabs/tabs.tsx
+++ b/packages/mosaic/src/components/tabs/tabs.tsx
@@ -2,7 +2,6 @@ import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
 import type {
-  TabsIndicatorProps as HeadlessTabsIndicatorProps,
   TabsListProps as HeadlessTabsListProps,
   TabsPanelProps as HeadlessTabsPanelProps,
   TabsProps as HeadlessTabsRootProps,
@@ -31,7 +30,6 @@ export type TabsTriggerProps = StyledProps<HeadlessTabsTriggerProps>;
 export type TabsPanelProps = StyledProps<HeadlessTabsPanelProps>;
 /** Props for the optional wrapper that stacks the panels in one grid cell so they can animate in and out. */
 export type TabsPanelsProps = MosaicComponentProps<'div'>;
-export type TabsIndicatorProps = StyledProps<HeadlessTabsIndicatorProps>;
 
 function Root({ xstyle, children, ...rest }: TabsRootProps) {
   return (
@@ -41,24 +39,35 @@ function Root({ xstyle, children, ...rest }: TabsRootProps) {
   );
 }
 
-function List({ xstyle, ...rest }: TabsListProps) {
+function List({ xstyle, children, ...rest }: TabsListProps) {
   return (
-    <Primitive.List
-      {...mergeStyleProps(themeProps('tabs-list'), stylex.props(reset.base, styles.list, xstyle), rest)}
-    />
+    <Primitive.List {...mergeStyleProps(themeProps('tabs-list'), stylex.props(reset.base, styles.list, xstyle), rest)}>
+      {children}
+      <Primitive.Indicator
+        {...mergeStyleProps(themeProps('tabs-indicator'), stylex.props(reset.base, styles.indicator))}
+      />
+    </Primitive.List>
   );
 }
 
-const Tab = React.forwardRef<HTMLButtonElement, TabsTabProps>(function MosaicTabsTab({ xstyle, ...rest }, ref) {
+const Tab = React.forwardRef<HTMLButtonElement, TabsTabProps>(function MosaicTabsTab(
+  { xstyle, children, ...rest },
+  ref,
+) {
   return (
     <Primitive.Tab
       ref={ref}
       {...mergeStyleProps(
         themeProps('tabs-tab'),
-        stylex.props(reset.base, styles.tab, styles.hitArea, focusOutline.visible, xstyle),
+        stylex.props(reset.base, styles.tab, styles.anchor, styles.hitArea, focusOutline.visible, xstyle),
         rest,
       )}
-    />
+    >
+      <Primitive.Indicator
+        {...mergeStyleProps(themeProps('tabs-indicator'), stylex.props(reset.base, styles.fallbackIndicator))}
+      />
+      {children}
+    </Primitive.Tab>
   );
 });
 
@@ -103,14 +112,6 @@ const Panels = React.forwardRef<HTMLDivElement, TabsPanelsProps>(function Mosaic
   });
 });
 
-function Indicator({ xstyle, ...rest }: TabsIndicatorProps) {
-  return (
-    <Primitive.Indicator
-      {...mergeStyleProps(themeProps('tabs-indicator'), stylex.props(reset.base, styles.indicator, xstyle), rest)}
-    />
-  );
-}
-
 export const Tabs = {
   Root,
   List,
@@ -118,5 +119,4 @@ export const Tabs = {
   Trigger,
   Panels,
   Panel,
-  Indicator,
 };
diff --git a/packages/mosaic/src/features/organization-profile/organization-profile-members-panel.view.tsx b/packages/mosaic/src/features/organization-profile/organization-profile-members-panel.view.tsx
index 3749fcf2014..fc0a61a2f61 100644
--- a/packages/mosaic/src/features/organization-profile/organization-profile-members-panel.view.tsx
+++ b/packages/mosaic/src/features/organization-profile/organization-profile-members-panel.view.tsx
@@ -79,7 +79,6 @@ export function OrganizationProfileMembersPanelView({
                 {tab.label}
               </Tabs.Tab>
             ))}
-            <Tabs.Indicator />
           </Tabs.List>
           {tabs.map(tab => (
             <Tabs.Panel
diff --git a/packages/mosaic/src/primitives/tabs/README.md b/packages/mosaic/src/primitives/tabs/README.md
index 7b9d10b188f..16bd45bcd08 100644
--- a/packages/mosaic/src/primitives/tabs/README.md
+++ b/packages/mosaic/src/primitives/tabs/README.md
@@ -1,6 +1,6 @@
 # Tabs
 
-A tabbed interface with automatic or manual activation, keyboard navigation, and an animated indicator. Panels are shown/hidden via the HTML `hidden` attribute (not unmounted).
+A tabbed interface with automatic or manual activation, keyboard navigation, and an optional indicator element. Panels are shown/hidden via the HTML `hidden` attribute (not unmounted).
 
 ## When to Use
 
@@ -62,7 +62,7 @@ By default, arrowing to a tab immediately activates it. Use `activationMode="man
 | `Tabs.Tab`       | `<button>`      | A tab trigger inside `Tabs.List` (`role="tab"`)    |
 | `Tabs.Trigger`   | `<button>`      | Standalone tab trigger for use outside `Tabs.List` |
 | `Tabs.Panel`     | `<div>`         | Content panel (`role="tabpanel"`)                  |
-| `Tabs.Indicator` | `<span>`        | Animated indicator tracking the active tab         |
+| `Tabs.Indicator` | `<span>`        | Decorative element for the selection               |
 
 ## Props
 
@@ -118,6 +118,7 @@ No additional props beyond standard HTML attributes and the `render` prop.
 | Attribute             | Applies To   | Description                                     |
 | --------------------- | ------------ | ----------------------------------------------- |
 | `data-selected`       | Tab, Trigger | Active tab                                      |
+| `data-direction`      | Indicator    | `forward` or `backward`, see below              |
 | `data-disabled`       | Tab, Trigger | Disabled tab                                    |
 | `data-hidden`         | Panel        | Inactive panel                                  |
 | `data-open`           | Panel        | Selected panel (when `shouldForceMount`)        |
@@ -125,33 +126,31 @@ No additional props beyond standard HTML attributes and the `render` prop.
 | `data-starting-style` | Panel        | Enter animation frame (when `shouldForceMount`) |
 | `data-ending-style`   | Panel        | Exit animation frame (when `shouldForceMount`)  |
 
-## CSS Variables
-
-### Indicator
-
-`Tabs.Indicator` exposes CSS custom properties for positioning and sizing:
-
-| CSS Variable      | Description                        |
-| ----------------- | ---------------------------------- |
-| `--cl-tab-left`   | Left offset of the active tab (px) |
-| `--cl-tab-width`  | Width of the active tab (px)       |
-| `--cl-tab-top`    | Top offset of the active tab (px)  |
-| `--cl-tab-height` | Height of the active tab (px)      |
+## Indicator
 
-Use these to animate the indicator:
+`Tabs.Indicator` carries `data-direction`: `forward` when the selection last moved to a later tab, `backward` when it moved to an earlier one. Position it with CSS anchor positioning:
 
 ```css
+.cl-tabs-list {
+  position: relative;
+  anchor-scope: --active-tab;
+}
+.cl-tabs-tab[data-selected] {
+  anchor-name: --active-tab;
+}
 .cl-tabs-indicator {
   position: absolute;
-  left: var(--cl-tab-left);
-  width: var(--cl-tab-width);
+  position-anchor: --active-tab;
+  inset-inline: anchor(start) anchor(end);
+  bottom: 0;
+  height: 2px;
   transition:
-    left 200ms ease,
-    width 200ms ease;
+    inset-inline-start 200ms,
+    inset-inline-end 200ms;
 }
 ```
 
-The transition only runs when the active tab changes. The initial render and resizes (font load, container resize) skip it, so the indicator never animates from `0,0` or on mount.
+## CSS Variables
 
 ### Panel (with `shouldForceMount`)
 
@@ -184,7 +183,6 @@ Use this to drive directional slide animations:
 
 ## Important Notes
 
-- **`Tabs.List` must have `position: relative`** in your CSS for the indicator to position correctly.
 - **Panels use the `hidden` attribute** by default — they stay in the DOM but are hidden when inactive. This preserves state in inactive panels.
 - **`shouldForceMount` panels** stay in layout flow with `inert` on inactive panels. This enables CSS enter/exit animations between tabs. The initially-selected panel appears instantly (no enter animation on page load).
 - **`Tabs.Trigger` vs `Tabs.Tab`**: Use `Tabs.Tab` inside `Tabs.List` for keyboard-navigable tabs with roving tabindex. Use `Tabs.Trigger` for standalone tab buttons placed anywhere in the tree (e.g., in a sidebar).
diff --git a/packages/mosaic/src/primitives/tabs/tabs-context.ts b/packages/mosaic/src/primitives/tabs/tabs-context.ts
index d8860e30a7a..f2e15b9c151 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-context.ts
+++ b/packages/mosaic/src/primitives/tabs/tabs-context.ts
@@ -1,5 +1,7 @@
 import { createContext, useContext } from 'react';
 
+export type TabsDirection = 'forward' | 'backward';
+
 export interface TabsContextValue {
   value: string;
   setValue: (value: string) => void;
@@ -7,13 +9,7 @@ export interface TabsContextValue {
   activationMode: 'automatic' | 'manual';
   tabsId: string;
   registerTab: (value: string, element: HTMLElement | null) => void;
-  getTabElement: (value: string) => HTMLElement | null;
-  // The list element is tracked as state (not a ref) so the indicator, a child,
-  // re-renders once the list mounts. A child's layout effect runs before its
-  // parent's ref is attached, so a plain ref would read null on first measure.
-  listElement: HTMLElement | null;
-  setListElement: (element: HTMLElement | null) => void;
-  direction: 1 | -1;
+  direction: TabsDirection;
 }
 
 export const TabsContext = createContext<TabsContextValue | null>(null);
diff --git a/packages/mosaic/src/primitives/tabs/tabs-indicator.tsx b/packages/mosaic/src/primitives/tabs/tabs-indicator.tsx
index f6b583608b8..0474f4fe35c 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-indicator.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-indicator.tsx
@@ -1,70 +1,24 @@
 'use client';
 
-import type React from 'react';
-import { useLayoutEffect, useRef, useState } from 'react';
+import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../utils';
-import { autoUpdate, getRectRelativeTo, type Rect } from '../utils/dom';
-import { useTabsContext } from './tabs-context';
+import { type ComponentProps, useRender } from '../utils';
+import { type TabsDirection, useTabsContext } from './tabs-context';
 
 export type TabsIndicatorProps = ComponentProps<'span'>;
 
-export function TabsIndicator(props: TabsIndicatorProps) {
+export const TabsIndicator = React.forwardRef<HTMLSpanElement, TabsIndicatorProps>(function TabsIndicator(props, ref) {
   const { render, ...otherProps } = props;
-  const { value, getTabElement, orientation, listElement } = useTabsContext();
-
-  const [style, setStyle] = useState<React.CSSProperties>({});
-  const lastMeasureRef = useRef<{ value: string; rect: Rect } | null>(null);
-
-  // Measure synchronously before paint so the indicator never commits a frame
-  // at a stale position when the active tab changes.
-  useLayoutEffect(() => {
-    const el = getTabElement(value);
-    const list = listElement;
-    if (!el || !list) {
-      return;
-    }
-
-    // Keep the indicator in sync when the active tab or the list changes size
-    // (font load, container resize) without a tab-selection change.
-    return autoUpdate([el, list], () => {
-      const newRect = getRectRelativeTo(el, list);
-
-      const last = lastMeasureRef.current;
-      lastMeasureRef.current = { value, rect: newRect };
-      if (last && isSameRect(last.rect, newRect)) {
-        return;
-      }
-      const isTabChange = last != null && last.value !== value;
-
-      const sharedVars = {
-        '--cl-tab-left': `${newRect.x}px`,
-        '--cl-tab-width': `${newRect.width}px`,
-        '--cl-tab-top': `${newRect.y}px`,
-        '--cl-tab-height': `${newRect.height}px`,
-        ...(isTabChange ? {} : { transition: 'none' }),
-      };
-
-      if (orientation === 'horizontal') {
-        setStyle({ position: 'absolute', left: newRect.x, width: newRect.width, ...sharedVars });
-      } else {
-        setStyle({ position: 'absolute', top: newRect.y, height: newRect.height, ...sharedVars });
-      }
-    });
-  }, [value, getTabElement, orientation, listElement]);
-
-  const defaultProps = {
-    'aria-hidden': true as const,
-    style,
-  };
+  const { direction } = useTabsContext();
 
   return useRender({
     defaultTagName: 'span',
     render,
-    props: mergeProps<'span'>(defaultProps, otherProps),
+    ref,
+    state: { direction },
+    stateAttributesMapping: {
+      direction: (v: TabsDirection) => ({ 'data-direction': v }),
+    },
+    props: { 'aria-hidden': true, ...otherProps },
   });
-}
-
-function isSameRect(a: Rect, b: Rect) {
-  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
-}
+});
diff --git a/packages/mosaic/src/primitives/tabs/tabs-list.tsx b/packages/mosaic/src/primitives/tabs/tabs-list.tsx
index ed874a56c5d..0ba5bb6e27d 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-list.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-list.tsx
@@ -10,11 +10,10 @@ export type TabsListProps = ComponentProps<'div'>;
 
 export function TabsList(props: TabsListProps) {
   const { render, children, ...otherProps } = props;
-  const { orientation, setListElement } = useTabsContext();
+  const { orientation } = useTabsContext();
 
   return (
     <Composite
-      ref={setListElement}
       orientation={orientation}
       render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
         const defaultProps: Record<string, unknown> = {
diff --git a/packages/mosaic/src/primitives/tabs/tabs-panel.tsx b/packages/mosaic/src/primitives/tabs/tabs-panel.tsx
index b952dcc05e2..0aed0d4751b 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-panel.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-panel.tsx
@@ -52,7 +52,10 @@ export const TabsPanel = React.forwardRef<HTMLDivElement, TabsPanelProps>(functi
     ...(shouldForceMount
       ? {
           ...effectiveTransitionProps,
-          style: { ...effectiveTransitionProps.style, '--cl-tab-transition-direction': String(direction) },
+          style: {
+            ...effectiveTransitionProps.style,
+            '--cl-tab-transition-direction': direction === 'forward' ? '1' : '-1',
+          },
         }
       : {}),
   };
diff --git a/packages/mosaic/src/primitives/tabs/tabs-root.tsx b/packages/mosaic/src/primitives/tabs/tabs-root.tsx
index aac3249545d..d086ff506f6 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-root.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-root.tsx
@@ -1,9 +1,31 @@
 'use client';
 
-import { type ReactNode, useCallback, useId, useMemo, useRef, useState } from 'react';
+import { type ReactNode, useCallback, useId, useMemo, useReducer, useRef } from 'react';
 
-import { useControllableState } from '../hooks/use-controllable-state';
-import { TabsContext, type TabsContextValue } from './tabs-context';
+import { TabsContext, type TabsContextValue, type TabsDirection } from './tabs-context';
+
+interface SelectionState {
+  value: string;
+  direction: TabsDirection;
+}
+
+interface SelectAction {
+  value: string;
+  fromIndex: number;
+  toIndex: number;
+}
+
+function selectionReducer(state: SelectionState, action: SelectAction): SelectionState {
+  if (action.value === state.value) {
+    return state;
+  }
+  const { fromIndex, toIndex } = action;
+  const moved = fromIndex !== -1 && toIndex !== -1 && fromIndex !== toIndex;
+  return {
+    value: action.value,
+    direction: moved ? (toIndex > fromIndex ? 'forward' : 'backward') : state.direction,
+  };
+}
 
 export interface TabsProps {
   value?: string;
@@ -15,60 +37,71 @@ export interface TabsProps {
 }
 
 export function TabsRoot(props: TabsProps) {
-  const { orientation = 'horizontal', activationMode = 'automatic', children } = props;
+  const {
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    orientation = 'horizontal',
+    activationMode = 'automatic',
+    children,
+  } = props;
 
-  const [value, setValueRaw] = useControllableState(props.value, props.defaultValue ?? '', props.onValueChange);
-
-  const [direction, setDirection] = useState<1 | -1>(1);
+  const [selection, dispatch] = useReducer(selectionReducer, {
+    value: valueProp ?? defaultValue ?? '',
+    direction: 'forward',
+  });
   const tabsId = useId();
-  const tabElementsRef = useRef<Map<string, HTMLElement>>(new Map());
-  const tabOrderRef = useRef<string[]>([]);
-  const [listElement, setListElement] = useState<HTMLElement | null>(null);
-  const valueRef = useRef(value);
-  valueRef.current = value;
+  const tabElementsRef = useRef(new Map<string, HTMLElement>());
 
   const registerTab = useCallback((tabValue: string, element: HTMLElement | null) => {
     if (element) {
       tabElementsRef.current.set(tabValue, element);
-      if (!tabOrderRef.current.includes(tabValue)) {
-        tabOrderRef.current.push(tabValue);
-      }
     } else {
       tabElementsRef.current.delete(tabValue);
-      tabOrderRef.current = tabOrderRef.current.filter(v => v !== tabValue);
     }
   }, []);
 
-  const getTabElement = useCallback((tabValue: string) => {
-    return tabElementsRef.current.get(tabValue) ?? null;
+  const getIndex = useCallback((tabValue: string) => {
+    const element = tabElementsRef.current.get(tabValue);
+    if (!element) {
+      return -1;
+    }
+    return Array.from(tabElementsRef.current.values()).filter(
+      other => other.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).length;
   }, []);
 
+  const update = useCallback(
+    (fromValue: string, toValue: string) => {
+      dispatch({ value: toValue, fromIndex: getIndex(fromValue), toIndex: getIndex(toValue) });
+    },
+    [getIndex],
+  );
+
+  if (valueProp !== undefined && valueProp !== selection.value) {
+    update(selection.value, valueProp);
+  }
+
+  const value = valueProp ?? selection.value;
+  const { direction } = selection;
+  const isControlled = valueProp !== undefined;
+
   const setValue = useCallback(
-    (newValue: string) => {
-      const prevIndex = tabOrderRef.current.indexOf(valueRef.current);
-      const nextIndex = tabOrderRef.current.indexOf(newValue);
-      if (prevIndex !== -1 && nextIndex !== -1 && nextIndex !== prevIndex) {
-        setDirection(nextIndex > prevIndex ? 1 : -1);
+    (nextValue: string) => {
+      if (nextValue === value) {
+        return;
+      }
+      if (!isControlled) {
+        update(value, nextValue);
       }
-      setValueRaw(newValue);
+      onValueChange?.(nextValue);
     },
-    [setValueRaw],
+    [value, isControlled, update, onValueChange],
   );
 
   const contextValue = useMemo<TabsContextValue>(
-    () => ({
-      value,
-      setValue,
-      orientation,
-      activationMode,
-      tabsId,
-      registerTab,
-      getTabElement,
-      listElement,
-      setListElement,
-      direction,
-    }),
-    [value, setValue, orientation, activationMode, tabsId, registerTab, getTabElement, listElement, direction],
+    () => ({ value, setValue, orientation, activationMode, tabsId, registerTab, direction }),
+    [value, setValue, orientation, activationMode, tabsId, registerTab, direction],
   );
 
   return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;
diff --git a/packages/mosaic/src/primitives/tabs/tabs.test.tsx b/packages/mosaic/src/primitives/tabs/tabs.test.tsx
index 80223fd144b..3df2ca8d51d 100644
--- a/packages/mosaic/src/primitives/tabs/tabs.test.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs.test.tsx
@@ -1,6 +1,6 @@
-import { act, cleanup, render, screen } from '@testing-library/react';
+import { cleanup, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { createRef } from 'react';
+import { createRef, useState } from 'react';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { axe } from '../test-utils/axe';
@@ -132,6 +132,16 @@ describe('Tabs', () => {
 
       expect(onValueChange).toHaveBeenCalledWith('tab2');
     });
+
+    it('does not call onValueChange when the selected tab is chosen again', async () => {
+      const onValueChange = vi.fn();
+      const user = userEvent.setup();
+      renderTabs({ onValueChange });
+
+      await user.click(screen.getByText('Account'));
+
+      expect(onValueChange).not.toHaveBeenCalled();
+    });
   });
 
   describe('controlled value', () => {
@@ -351,198 +361,84 @@ describe('Tabs', () => {
   });
 
   describe('Tabs.Indicator', () => {
-    function renderWithIndicator() {
-      return render(
-        <Tabs.Root defaultValue='tab1'>
-          <Tabs.List style={{ position: 'relative' }}>
+    function Indicated(props: Partial<React.ComponentProps<typeof Tabs.Root>>) {
+      return (
+        <Tabs.Root
+          defaultValue='tab1'
+          {...props}
+        >
+          <Tabs.List>
             <Tabs.Tab value='tab1'>Account</Tabs.Tab>
             <Tabs.Tab value='tab2'>Settings</Tabs.Tab>
+            <Tabs.Tab value='tab3'>Billing</Tabs.Tab>
             <Tabs.Indicator data-testid='indicator' />
           </Tabs.List>
           <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
           <Tabs.Panel value='tab2'>Settings content</Tabs.Panel>
-        </Tabs.Root>,
+          <Tabs.Panel value='tab3'>Billing content</Tabs.Panel>
+        </Tabs.Root>
       );
     }
 
-    it('has position absolute', () => {
-      renderWithIndicator();
-      const indicator = screen.getByTestId('indicator');
-      expect(indicator.style.position).toBe('absolute');
-    });
-
     it('has aria-hidden', () => {
-      renderWithIndicator();
-      const indicator = screen.getByTestId('indicator');
-      expect(indicator).toHaveAttribute('aria-hidden', 'true');
+      render(<Indicated />);
+      expect(screen.getByTestId('indicator')).toHaveAttribute('aria-hidden', 'true');
     });
 
-    it('sets --cl-tab-width and --cl-tab-left CSS vars', () => {
-      renderWithIndicator();
+    it('marks the direction the selection traveled', async () => {
+      const user = userEvent.setup();
+      render(<Indicated />);
       const indicator = screen.getByTestId('indicator');
-      // In a real browser, getBoundingClientRect returns actual measurements
-      expect(indicator.style.getPropertyValue('--cl-tab-width')).toBeTruthy();
-      expect(indicator.style.getPropertyValue('--cl-tab-left')).toBeTruthy();
-    });
 
-    it('updates position when tab changes', async () => {
-      const user = userEvent.setup();
-      renderWithIndicator();
+      expect(indicator).toHaveAttribute('data-direction', 'forward');
 
-      const indicator = screen.getByTestId('indicator');
+      await user.click(screen.getByText('Billing'));
+      expect(indicator).toHaveAttribute('data-direction', 'forward');
 
       await user.click(screen.getByText('Settings'));
-
-      // Verify the effect ran and style properties are set
-      expect(indicator.style.position).toBe('absolute');
-      expect(indicator.style.getPropertyValue('--cl-tab-width')).toBeDefined();
+      expect(indicator).toHaveAttribute('data-direction', 'backward');
     });
 
-    it('skips transition on initial render', () => {
-      renderWithIndicator();
-      const indicator = screen.getByTestId('indicator');
-      expect(indicator.style.transition).toBe('none');
-    });
-  });
+    it('marks the direction when a controlled value changes', () => {
+      const { rerender } = render(<Indicated value='tab3' />);
+      rerender(<Indicated value='tab1' />);
 
-  describe('Tabs.Indicator resize tracking (B1)', () => {
-    it('re-measures the active tab when it resizes without a tab change', () => {
-      // Capture every ResizeObserver the tree creates so the test can drive it.
-      const observers: Array<{ cb: ResizeObserverCallback; targets: Element[] }> = [];
-      class MockResizeObserver {
-        cb: ResizeObserverCallback;
-        targets: Element[] = [];
-        constructor(cb: ResizeObserverCallback) {
-          this.cb = cb;
-          observers.push(this);
-        }
-        observe(el: Element) {
-          this.targets.push(el);
-        }
-        unobserve() {}
-        disconnect() {}
-      }
-      vi.stubGlobal('ResizeObserver', MockResizeObserver);
-
-      try {
-        render(
-          <Tabs.Root defaultValue='tab1'>
-            <Tabs.List style={{ position: 'relative' }}>
-              <Tabs.Tab value='tab1'>Account</Tabs.Tab>
-              <Tabs.Tab value='tab2'>Settings</Tabs.Tab>
-              <Tabs.Indicator data-testid='indicator' />
-            </Tabs.List>
-            <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
-            <Tabs.Panel value='tab2'>Settings content</Tabs.Panel>
-          </Tabs.Root>,
-        );
-
-        const indicator = screen.getByTestId('indicator');
-        const list = screen.getByRole('tablist');
-
-        // The indicator should have registered an observer for its active tab.
-        expect(observers.length).toBeGreaterThan(0);
-
-        // Simulate the active tab growing (e.g. font load / container resize)
-        // with no tab-selection change.
-        const rect = (left: number, width: number) =>
-          ({ left, top: 0, right: left + width, bottom: 20, width, height: 20, x: left, y: 0, toJSON() {} }) as DOMRect;
-        list.getBoundingClientRect = () => rect(0, 400);
-        for (const tab of screen.getAllByRole('tab')) {
-          tab.getBoundingClientRect = () => rect(0, 250);
-        }
-
-        // Fire every observer the tree created.
-        act(() => {
-          for (const o of observers) {
-            o.cb([], o as unknown as ResizeObserver);
-          }
-        });
-
-        expect(indicator.style.getPropertyValue('--cl-tab-width')).toBe('250px');
-      } finally {
-        vi.unstubAllGlobals();
-      }
+      expect(screen.getByTestId('indicator')).toHaveAttribute('data-direction', 'backward');
     });
 
-    function setupObservedIndicator() {
-      const observers: Array<{ cb: ResizeObserverCallback }> = [];
-      class MockResizeObserver {
-        cb: ResizeObserverCallback;
-        constructor(cb: ResizeObserverCallback) {
-          this.cb = cb;
-          observers.push(this);
-        }
-        observe() {}
-        unobserve() {}
-        disconnect() {}
+    it('marks the direction when a controlled parent follows onValueChange', async () => {
+      const user = userEvent.setup();
+      function Controlled() {
+        const [value, setValue] = useState('tab3');
+        return (
+          <Indicated
+            value={value}
+            onValueChange={setValue}
+          />
+        );
       }
-      vi.stubGlobal('ResizeObserver', MockResizeObserver);
-
-      render(
-        <Tabs.Root defaultValue='tab1'>
-          <Tabs.List style={{ position: 'relative' }}>
-            <Tabs.Tab value='tab1'>Account</Tabs.Tab>
-            <Tabs.Tab value='tab2'>Settings</Tabs.Tab>
-            <Tabs.Indicator data-testid='indicator' />
-          </Tabs.List>
-          <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
-          <Tabs.Panel value='tab2'>Settings content</Tabs.Panel>
-        </Tabs.Root>,
-      );
-
-      const rect = (left: number, width: number) =>
-        ({ left, top: 0, right: left + width, bottom: 20, width, height: 20, x: left, y: 0, toJSON() {} }) as DOMRect;
-      const setTabRects = (widths: number[]) => {
-        screen.getByRole('tablist').getBoundingClientRect = () => rect(0, 400);
-        let left = 0;
-        screen.getAllByRole('tab').forEach((tab, i) => {
-          const tabLeft = left;
-          tab.getBoundingClientRect = () => rect(tabLeft, widths[i]);
-          left += widths[i];
-        });
-      };
-      const fireResize = () =>
-        act(() => {
-          for (const o of observers) {
-            o.cb([], o as unknown as ResizeObserver);
-          }
-        });
-
-      return { indicator: screen.getByTestId('indicator'), setTabRects, fireResize };
-    }
-
-    it('does not animate when the active tab resizes after mount', () => {
-      try {
-        const { indicator, setTabRects, fireResize } = setupObservedIndicator();
+      render(<Controlled />);
 
-        setTabRects([100, 120]);
-        fireResize();
+      await user.click(screen.getByText('Account'));
 
-        expect(indicator.style.getPropertyValue('--cl-tab-width')).toBe('100px');
-        expect(indicator.style.transition).toBe('none');
-      } finally {
-        vi.unstubAllGlobals();
-      }
+      expect(screen.getByText('Account')).toHaveAttribute('aria-selected', 'true');
+      expect(screen.getByTestId('indicator')).toHaveAttribute('data-direction', 'backward');
     });
 
-    it('keeps animating a tab change when the observer reports the same size', async () => {
-      try {
-        const user = userEvent.setup();
-        const { indicator, setTabRects, fireResize } = setupObservedIndicator();
-
-        setTabRects([100, 120]);
-        await user.click(screen.getByText('Settings'));
-
-        expect(indicator.style.getPropertyValue('--cl-tab-left')).toBe('100px');
-        expect(indicator.style.transition).toBe('');
+    it('follows vertical tabs the same way', async () => {
+      const user = userEvent.setup();
+      render(
+        <Indicated
+          orientation='vertical'
+          defaultValue='tab3'
+        />,
+      );
 
-        fireResize();
+      await user.click(screen.getByText('Billing'));
+      await user.keyboard('{ArrowUp}');
 
-        expect(indicator.style.transition).toBe('');
-      } finally {
-        vi.unstubAllGlobals();
-      }
+      expect(screen.getByText('Settings')).toHaveAttribute('aria-selected', 'true');
+      expect(screen.getByTestId('indicator')).toHaveAttribute('data-direction', 'backward');
     });
   });
 
diff --git a/packages/mosaic/src/primitives/utils/dom.test.ts b/packages/mosaic/src/primitives/utils/dom.test.ts
index 3f958244c50..c42fd3601ff 100644
--- a/packages/mosaic/src/primitives/utils/dom.test.ts
+++ b/packages/mosaic/src/primitives/utils/dom.test.ts
@@ -4,7 +4,6 @@ import {
   autoUpdate,
   canScrollToward,
   getDimensions,
-  getRectRelativeTo,
   getScale,
   getScrollDimensions,
   isElement,
@@ -135,30 +134,6 @@ describe('getScale', () => {
   });
 });
 
-describe('getRectRelativeTo', () => {
-  it('places the element inside the parent padding box, following its scroll', () => {
-    const parent = create();
-    const element = document.createElement('div');
-    parent.append(element);
-    stubRect(parent, { x: 100, y: 50, width: 300, height: 200 });
-    stub(parent, { clientLeft: 2, clientTop: 1, scrollLeft: 30, scrollTop: 0 });
-    stubRect(element, { x: 140, y: 61, width: 80, height: 20 });
-
-    expect(getRectRelativeTo(element, parent)).toEqual({ x: 68, y: 10, width: 80, height: 20 });
-  });
-
-  it('removes the parent scale', () => {
-    const parent = create();
-    const element = document.createElement('div');
-    parent.append(element);
-    stub(parent, { offsetWidth: 200, offsetHeight: 100 });
-    stubRect(parent, { x: 0, y: 0, width: 100, height: 50 });
-    stubRect(element, { x: 20, y: 10, width: 40, height: 10 });
-
-    expect(getRectRelativeTo(element, parent)).toEqual({ x: 40, y: 20, width: 80, height: 20 });
-  });
-});
-
 describe('autoUpdate', () => {
   it('updates right away and whenever an element resizes', () => {
     let notify = () => {};
diff --git a/packages/mosaic/src/primitives/utils/dom.ts b/packages/mosaic/src/primitives/utils/dom.ts
index 68bfa3132f6..bd331ba991d 100644
--- a/packages/mosaic/src/primitives/utils/dom.ts
+++ b/packages/mosaic/src/primitives/utils/dom.ts
@@ -8,8 +8,6 @@ export interface Dimensions {
   height: number;
 }
 
-export type Rect = Coords & Dimensions;
-
 const ALIGNMENT_PROPERTIES = ['justify-content', 'align-items', 'align-content', 'justify-items'];
 
 /**
@@ -90,23 +88,6 @@ export function getScale(element: HTMLElement): Coords {
   };
 }
 
-/**
- * The element's position and size in `parent`'s coordinate space: relative to its padding box,
- * following its scroll, and with its scale removed. When `parent` is the containing block, these are
- * the `left` / `top` / `width` / `height` an absolutely positioned child needs to cover the element.
- */
-export function getRectRelativeTo(element: Element, parent: HTMLElement): Rect {
-  const rect = element.getBoundingClientRect();
-  const parentRect = parent.getBoundingClientRect();
-  const scale = getScale(parent);
-  return {
-    x: (rect.left - parentRect.left) / scale.x - parent.clientLeft + parent.scrollLeft,
-    y: (rect.top - parentRect.top) / scale.y - parent.clientTop + parent.scrollTop,
-    width: rect.width / scale.x,
-    height: rect.height / scale.y,
-  };
-}
-
 /**
  * Calls `update` now and again whenever any of `elements` resizes. Returns a cleanup that stops
  * observing. Without `ResizeObserver`, `update` runs once.
diff --git a/packages/mosaic/src/styles/index.ts b/packages/mosaic/src/styles/index.ts
index f24b675e3a6..151eadb9356 100644
--- a/packages/mosaic/src/styles/index.ts
+++ b/packages/mosaic/src/styles/index.ts
@@ -118,7 +118,6 @@ export { SegmentedControl } from '../components/segmented-control';
 export type { SegmentedControlItemProps, SegmentedControlRootProps } from '../components/segmented-control';
 export { Tabs } from '../components/tabs';
 export type {
-  TabsIndicatorProps,
   TabsListProps,
   TabsPanelProps,
   TabsPanelsProps,
diff --git a/packages/swingset/src/stories/tabs.component.mdx b/packages/swingset/src/stories/tabs.component.mdx
index ba23260f43a..114b4ba9599 100644
--- a/packages/swingset/src/stories/tabs.component.mdx
+++ b/packages/swingset/src/stories/tabs.component.mdx
@@ -23,7 +23,6 @@ import { Tabs } from '@clerk/mosaic/components/tabs';
   <Tabs.List>
     <Tabs.Tab value='tab1'>Account</Tabs.Tab>
     <Tabs.Tab value='tab2'>Security</Tabs.Tab>
-    <Tabs.Indicator />
   </Tabs.List>
   <Tabs.Panels>
     <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
@@ -34,22 +33,22 @@ import { Tabs } from '@clerk/mosaic/components/tabs';
 
 ## Parts
 
-| Part             | Element    | Description                                                                           |
-| ---------------- | ---------- | ------------------------------------------------------------------------------------- |
-| `Tabs.Root`      | `<div>`    | Column container providing active-value state and activation mode for horizontal tabs |
-| `Tabs.List`      | `<div>`    | `role="tablist"` container with roving-tabindex navigation                            |
-| `Tabs.Tab`       | `<button>` | A keyboard-navigable tab trigger inside `Tabs.List`                                   |
-| `Tabs.Trigger`   | `<button>` | Standalone tab trigger for use outside `Tabs.List`                                    |
-| `Tabs.Panels`    | `<div>`    | Grid container that stacks direct `Tabs.Panel` children                               |
-| `Tabs.Panel`     | `<div>`    | `role="tabpanel"`; hidden when inactive                                               |
-| `Tabs.Indicator` | `<span>`   | Decorative element that tracks the active tab's position and size                     |
+| Part           | Element    | Description                                                                            |
+| -------------- | ---------- | -------------------------------------------------------------------------------------- |
+| `Tabs.Root`    | `<div>`    | Column container providing active-value state and activation mode for horizontal tabs  |
+| `Tabs.List`    | `<div>`    | `role="tablist"` container with roving-tabindex navigation and the selection underline |
+| `Tabs.Tab`     | `<button>` | A keyboard-navigable tab trigger inside `Tabs.List`                                    |
+| `Tabs.Trigger` | `<button>` | Standalone tab trigger for use outside `Tabs.List`                                     |
+| `Tabs.Panels`  | `<div>`    | Grid container that stacks direct `Tabs.Panel` children                                |
+| `Tabs.Panel`   | `<div>`    | `role="tabpanel"`; hidden when inactive                                                |
 
 All parts accept `xstyle`. Parts other than `Tabs.Root` also accept a `render` prop for polymorphic
 rendering and standard HTML attributes. `Tabs.Root` renders a column container inside the primitive's
 context provider so the list and panels stack regardless of the surrounding layout.
 
-The selection indicator uses a short CSS transition and disables its motion when the user prefers
-reduced motion.
+The underline under the selected tab is `.cl-tabs-indicator`. Style that class to restyle the
+selection. It slides between tabs where the browser supports animating CSS anchor positioning, and
+sits still under the selected tab elsewhere or when the user prefers reduced motion.
 
 `Tabs.Panels` places its direct panels in one grid cell. Pair it with force-mounted panels and the
 tabs primitive's transition attributes when a theme needs to animate outgoing and incoming panels.
diff --git a/packages/swingset/src/stories/tabs.component.stories.tsx b/packages/swingset/src/stories/tabs.component.stories.tsx
index 4d982bffc67..967aee97215 100644
--- a/packages/swingset/src/stories/tabs.component.stories.tsx
+++ b/packages/swingset/src/stories/tabs.component.stories.tsx
@@ -18,7 +18,6 @@ export function Default() {
         <Tabs.Tab value='account'>Account</Tabs.Tab>
         <Tabs.Tab value='security'>Security</Tabs.Tab>
         <Tabs.Tab value='notifications'>Notifications</Tabs.Tab>
-        <Tabs.Indicator />
       </Tabs.List>
       <Tabs.Panels>
         <Tabs.Panel value='account'>Manage your account details.</Tabs.Panel>
diff --git a/packages/swingset/src/stories/tabs.mdx b/packages/swingset/src/stories/tabs.mdx
index b06dc1f2eb2..4ac877c489a 100644
--- a/packages/swingset/src/stories/tabs.mdx
+++ b/packages/swingset/src/stories/tabs.mdx
@@ -4,7 +4,7 @@ import * as TabsStories from './tabs.stories';
 
 A set of layered sections where one panel is shown at a time, selected from a row of tabs.
 It is a **headless** primitive: it supplies behavior, active-tab
-state, roving-tabindex keyboard navigation, an optional position-tracking indicator, and
+state, roving-tabindex keyboard navigation, an optional indicator element, and
 ARIA wiring, but ships **no styles** — you bring your own CSS by targeting the `data-*`
 attributes each part emits.
 
@@ -57,7 +57,7 @@ const [value, setValue] = useState('tab1');
 | `Tabs.Tab`       | `<button>`      | A keyboard-navigable tab trigger inside `Tabs.List`                |
 | `Tabs.Trigger`   | `<button>`      | Standalone tab trigger for use outside `Tabs.List` (not roving)    |
 | `Tabs.Panel`     | `<div>`         | `role="tabpanel"`; hidden via the `hidden` attribute when inactive |
-| `Tabs.Indicator` | `<span>`        | Decorative element that tracks the active tab's position and size  |
+| `Tabs.Indicator` | `<span>`        | Decorative element for the selection (`aria-hidden`)               |
 
 All rendered parts accept a `render` prop for polymorphic rendering and standard HTML
 attributes for their default element. `Tabs.Root` renders no element of its own.
@@ -105,24 +105,27 @@ Each part emits `data-*` attributes you can target with any CSS solution:
 | `data-starting-style` | Panel        | Enter-animation first frame (force-mounted panels only)          |
 | `data-ending-style`   | Panel        | Exit-animation frame (force-mounted panels only)                 |
 
-`Tabs.Indicator` is absolutely positioned and exposes the active tab's geometry as CSS
-variables (give `Tabs.List` `position: relative`):
-
-| Variable          | Description                             |
-| ----------------- | --------------------------------------- |
-| `--cl-tab-left`   | Active tab left offset relative to list |
-| `--cl-tab-width`  | Active tab width                        |
-| `--cl-tab-top`    | Active tab top offset relative to list  |
-| `--cl-tab-height` | Active tab height                       |
-
-A force-mounted `Tabs.Panel` also exposes `--cl-tab-transition-direction` (`1` when moving
-to a later tab, `-1` to an earlier one) for directional slide animations.
+`Tabs.Indicator` carries `data-direction`: `forward` when the selection last moved to a later tab,
+`backward` when it moved to an earlier one. Pair it with CSS anchor positioning to place it under
+the selected tab:
 
 ```css
-.cl-tabs-indicator {
+.tabs-list {
+  position: relative;
+  anchor-scope: --active-tab;
+}
+.tabs-tab[data-selected] {
+  anchor-name: --active-tab;
+}
+.tabs-indicator {
   position: absolute;
-  left: var(--cl-tab-left);
-  width: var(--cl-tab-width);
-  transition: left 200ms ease, width 200ms ease;
+  position-anchor: --active-tab;
+  inset-inline: anchor(start) anchor(end);
+  bottom: 0;
+  height: 2px;
+  transition: inset-inline-start 200ms, inset-inline-end 200ms;
 }
 ```
+
+A force-mounted `Tabs.Panel` also exposes `--cl-tab-transition-direction` (`1` when moving
+to a later tab, `-1` to an earlier one) for directional slide animations.

From d8d1734b35c840a59ce587cbbbab1637a002890b Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 14:44:27 -0600
Subject: [PATCH 2/5] fix(mosaic): support forced colors and RTL arrow keys in
 Tabs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../mosaic/src/components/tabs/tabs.styles.ts |  4 ++-
 .../mosaic/src/primitives/tabs/tabs-list.tsx  |  7 +++++-
 .../mosaic/src/primitives/tabs/tabs.test.tsx  | 25 +++++++++++++++++++
 3 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/packages/mosaic/src/components/tabs/tabs.styles.ts b/packages/mosaic/src/components/tabs/tabs.styles.ts
index 0901952b737..4c202861223 100644
--- a/packages/mosaic/src/components/tabs/tabs.styles.ts
+++ b/packages/mosaic/src/components/tabs/tabs.styles.ts
@@ -6,6 +6,7 @@ import { colorVars, durationVars, easingVars, fontFamilyVars, space, typeScaleVa
 const anchors = '@supports (anchor-scope: all) and (not (-moz-appearance: none))' as const;
 const noAnchors = '@supports not ((anchor-scope: all) and (not (-moz-appearance: none)))' as const;
 const reduceMotion = '@media (prefers-reduced-motion: reduce)' as const;
+const forcedColors = '@media (forced-colors: active)' as const;
 const activeAnchor = '--_cl-tabs-active';
 const halfGap = `calc(${space['5']} / -2)`;
 
@@ -13,7 +14,8 @@ const lead = durationVars['--cl-duration-slow'];
 const trail = durationVars['--cl-duration-slower'];
 
 const underline = {
-  backgroundColor: colorVars['--cl-color-foreground'],
+  backgroundColor: { default: colorVars['--cl-color-foreground'], [forcedColors]: 'Highlight' },
+  forcedColorAdjust: 'none',
   pointerEvents: 'none',
   position: 'absolute',
   bottom: '-1px',
diff --git a/packages/mosaic/src/primitives/tabs/tabs-list.tsx b/packages/mosaic/src/primitives/tabs/tabs-list.tsx
index 0ba5bb6e27d..ca249d80019 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-list.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-list.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { Composite } from '@floating-ui/react';
-import React from 'react';
+import React, { useState } from 'react';
 
 import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
 import { useTabsContext } from './tabs-context';
@@ -11,13 +11,18 @@ export type TabsListProps = ComponentProps<'div'>;
 export function TabsList(props: TabsListProps) {
   const { render, children, ...otherProps } = props;
   const { orientation } = useTabsContext();
+  const [rtl, setRtl] = useState(false);
 
   return (
     <Composite
       orientation={orientation}
+      rtl={orientation === 'horizontal' && rtl}
       render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
         const defaultProps: Record<string, unknown> = {
           role: 'tablist' as const,
+          onFocus: (event: React.FocusEvent<HTMLElement>) => {
+            setRtl((event.currentTarget.closest('[dir]')?.getAttribute('dir') ?? '').toLowerCase() === 'rtl');
+          },
           onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => {
             if (event.key !== 'Home' && event.key !== 'End') {
               return;
diff --git a/packages/mosaic/src/primitives/tabs/tabs.test.tsx b/packages/mosaic/src/primitives/tabs/tabs.test.tsx
index 3df2ca8d51d..f4611107979 100644
--- a/packages/mosaic/src/primitives/tabs/tabs.test.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs.test.tsx
@@ -205,6 +205,31 @@ describe('Tabs', () => {
       expect(document.activeElement).toBe(screen.getByText('Billing'));
     });
 
+    it('follows the visual order of arrow keys in RTL', async () => {
+      const user = userEvent.setup();
+      render(
+        <div dir='rtl'>
+          <Tabs.Root defaultValue='tab2'>
+            <Tabs.List>
+              <Tabs.Tab value='tab1'>Account</Tabs.Tab>
+              <Tabs.Tab value='tab2'>Settings</Tabs.Tab>
+              <Tabs.Tab value='tab3'>Billing</Tabs.Tab>
+            </Tabs.List>
+            <Tabs.Panel value='tab1'>Account content</Tabs.Panel>
+            <Tabs.Panel value='tab2'>Settings content</Tabs.Panel>
+            <Tabs.Panel value='tab3'>Billing content</Tabs.Panel>
+          </Tabs.Root>
+        </div>,
+      );
+
+      await user.click(screen.getByText('Settings'));
+      await user.keyboard('{ArrowLeft}');
+      expect(document.activeElement).toBe(screen.getByText('Billing'));
+
+      await user.keyboard('{ArrowRight}');
+      expect(document.activeElement).toBe(screen.getByText('Settings'));
+    });
+
     it('uses ArrowDown/ArrowUp for vertical orientation', async () => {
       const user = userEvent.setup();
       renderTabs({ orientation: 'vertical' });

From 407970aa3ebca61b5f187443d58dbe1f1edf823e Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 14:52:17 -0600
Subject: [PATCH 3/5] fix(mosaic): land the tabs indicator without overshoot

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/mosaic/src/components/tabs/tabs.styles.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/mosaic/src/components/tabs/tabs.styles.ts b/packages/mosaic/src/components/tabs/tabs.styles.ts
index 4c202861223..01815fd6a2c 100644
--- a/packages/mosaic/src/components/tabs/tabs.styles.ts
+++ b/packages/mosaic/src/components/tabs/tabs.styles.ts
@@ -107,7 +107,7 @@ export const styles = stylex.create({
       ':where([data-direction="backward"])': `${lead}, ${trail}`,
     },
     transitionProperty: 'inset-inline-start, inset-inline-end',
-    transitionTimingFunction: easingVars['--cl-ease-default'],
+    transitionTimingFunction: easingVars['--cl-ease-enter'],
   },
   fallbackIndicator: {
     ...underline,

From 0e9df9f6b65b9d3f0e97705457f50ce0b1cd7502 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 15:01:47 -0600
Subject: [PATCH 4/5] fix(mosaic): shorten the tabs indicator timing

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/mosaic/src/components/tabs/tabs.styles.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/mosaic/src/components/tabs/tabs.styles.ts b/packages/mosaic/src/components/tabs/tabs.styles.ts
index 01815fd6a2c..e10ac1cb37a 100644
--- a/packages/mosaic/src/components/tabs/tabs.styles.ts
+++ b/packages/mosaic/src/components/tabs/tabs.styles.ts
@@ -10,8 +10,8 @@ const forcedColors = '@media (forced-colors: active)' as const;
 const activeAnchor = '--_cl-tabs-active';
 const halfGap = `calc(${space['5']} / -2)`;
 
-const lead = durationVars['--cl-duration-slow'];
-const trail = durationVars['--cl-duration-slower'];
+const lead = durationVars['--cl-duration-base'];
+const trail = durationVars['--cl-duration-slow'];
 
 const underline = {
   backgroundColor: { default: colorVars['--cl-color-foreground'], [forcedColors]: 'Highlight' },

From f8414f4829ffcc71976e790abcfc084b5b06f22a Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 15:47:27 -0600
Subject: [PATCH 5/5] fix(mosaic): keep the tabs indicator direction in step
 with the selection

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../mosaic/src/components/tabs/tabs.styles.ts    |  4 ++--
 .../mosaic/src/components/tabs/tabs.test.tsx     |  8 ++++----
 packages/mosaic/src/components/tabs/tabs.tsx     |  2 +-
 packages/mosaic/src/primitives/tabs/tabs-tab.tsx | 16 +++++++---------
 .../mosaic/src/primitives/tabs/tabs-trigger.tsx  | 13 ++++++-------
 5 files changed, 20 insertions(+), 23 deletions(-)

diff --git a/packages/mosaic/src/components/tabs/tabs.styles.ts b/packages/mosaic/src/components/tabs/tabs.styles.ts
index e10ac1cb37a..02cf6ffb29a 100644
--- a/packages/mosaic/src/components/tabs/tabs.styles.ts
+++ b/packages/mosaic/src/components/tabs/tabs.styles.ts
@@ -69,7 +69,7 @@ export const styles = stylex.create({
   },
   hitArea: {
     '--_cl-tab-hit-end': { default: '0px', ':has(+ [role="tab"])': halfGap },
-    '--_cl-tab-hit-start': { default: halfGap, ':first-child': '0px' },
+    '--_cl-tab-hit-start': { default: halfGap, ':first-of-type': '0px' },
     position: 'relative',
     '::before': {
       insetBlock: 0,
@@ -93,7 +93,7 @@ export const styles = stylex.create({
     // eslint-disable-next-line @stylexjs/valid-styles -- `position-anchor`: anchor positioning postdates StyleX's property allowlist; it compiles and emits correctly.
     positionAnchor: activeAnchor,
     display: {
-      [anchors]: { default: 'none', ':where([data-selected] ~ *)': 'block' },
+      [anchors]: { default: 'none', ':has(~ [data-selected])': 'block' },
       default: 'none',
     },
     insetInlineEnd: 'anchor(end)',
diff --git a/packages/mosaic/src/components/tabs/tabs.test.tsx b/packages/mosaic/src/components/tabs/tabs.test.tsx
index 89eb25c07f7..41ff07e801c 100644
--- a/packages/mosaic/src/components/tabs/tabs.test.tsx
+++ b/packages/mosaic/src/components/tabs/tabs.test.tsx
@@ -48,7 +48,7 @@ describe('Mosaic Tabs', () => {
     );
 
     const list = screen.getByRole('tablist');
-    const anchored = list.lastElementChild;
+    const anchored = list.firstElementChild;
     expect(anchored).toHaveClass('cl-tabs-indicator', stylex.props(styles.indicator).className ?? '');
     expect(anchored).toHaveAttribute('aria-hidden', 'true');
 
@@ -70,7 +70,7 @@ describe('Mosaic Tabs', () => {
         </Tabs.List>
       </Tabs.Root>,
     );
-    const indicator = screen.getByRole('tablist').lastElementChild;
+    const indicator = screen.getByRole('tablist').firstElementChild;
 
     await userEvent.click(screen.getByRole('tab', { name: 'Members' }));
     expect(indicator).toHaveAttribute('data-direction', 'backward');
@@ -101,8 +101,8 @@ describe('Mosaic Tabs', () => {
 
     await userEvent.click(screen.getByRole('tab', { name: 'Inner A' }));
 
-    expect(inner.lastElementChild).toHaveAttribute('data-direction', 'backward');
-    expect(outer.lastElementChild).toHaveAttribute('data-direction', 'forward');
+    expect(inner.firstElementChild).toHaveAttribute('data-direction', 'backward');
+    expect(outer.firstElementChild).toHaveAttribute('data-direction', 'forward');
     expect(outer).toHaveClass(stylex.props(styles.list).className ?? '');
     expect(inner).toHaveClass(stylex.props(styles.list).className ?? '');
   });
diff --git a/packages/mosaic/src/components/tabs/tabs.tsx b/packages/mosaic/src/components/tabs/tabs.tsx
index 8cdf5efde70..c1380c2671f 100644
--- a/packages/mosaic/src/components/tabs/tabs.tsx
+++ b/packages/mosaic/src/components/tabs/tabs.tsx
@@ -42,10 +42,10 @@ function Root({ xstyle, children, ...rest }: TabsRootProps) {
 function List({ xstyle, children, ...rest }: TabsListProps) {
   return (
     <Primitive.List {...mergeStyleProps(themeProps('tabs-list'), stylex.props(reset.base, styles.list, xstyle), rest)}>
-      {children}
       <Primitive.Indicator
         {...mergeStyleProps(themeProps('tabs-indicator'), stylex.props(reset.base, styles.indicator))}
       />
+      {children}
     </Primitive.List>
   );
 }
diff --git a/packages/mosaic/src/primitives/tabs/tabs-tab.tsx b/packages/mosaic/src/primitives/tabs/tabs-tab.tsx
index ff5725edd66..0d16f583948 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-tab.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-tab.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { CompositeItem } from '@floating-ui/react';
-import React, { useLayoutEffect, useRef } from 'react';
+import React, { useCallback } from 'react';
 
 import { type ComponentProps, isRef, mergeProps, useRender } from '../utils';
 import { useTabsContext } from './tabs-context';
@@ -18,12 +18,10 @@ export const TabsTab = React.forwardRef<HTMLButtonElement, TabsTabProps>(functio
   const isSelected = selectedValue === tabValue;
   const tabId = `${tabsId}-tab-${tabValue}`;
   const panelId = `${tabsId}-panel-${tabValue}`;
-  const internalRef = useRef<HTMLButtonElement | null>(null);
-
-  useLayoutEffect(() => {
-    registerTab(tabValue, internalRef.current);
-    return () => registerTab(tabValue, null);
-  }, [tabValue, registerTab]);
+  const register = useCallback(
+    (element: HTMLButtonElement | null) => registerTab(tabValue, element),
+    [registerTab, tabValue],
+  );
 
   const state = {
     selected: isSelected,
@@ -32,7 +30,7 @@ export const TabsTab = React.forwardRef<HTMLButtonElement, TabsTabProps>(functio
 
   return (
     <CompositeItem
-      ref={internalRef}
+      ref={register}
       disabled={disabled}
       render={(compositeProps: React.HTMLAttributes<HTMLElement>) => {
         const defaultProps: Record<string, unknown> = {
@@ -91,7 +89,7 @@ export const TabsTab = React.forwardRef<HTMLButtonElement, TabsTabProps>(functio
         return useRender({
           defaultTagName: 'button',
           render,
-          ref: [internalRef, isRef(compositeRef) ? compositeRef : undefined, ref],
+          ref: [register, isRef(compositeRef) ? compositeRef : undefined, ref],
           state,
           stateAttributesMapping: {
             selected: (v: boolean) => (v ? { 'data-selected': '' } : null),
diff --git a/packages/mosaic/src/primitives/tabs/tabs-trigger.tsx b/packages/mosaic/src/primitives/tabs/tabs-trigger.tsx
index d6eeb2fb344..1af7fd52218 100644
--- a/packages/mosaic/src/primitives/tabs/tabs-trigger.tsx
+++ b/packages/mosaic/src/primitives/tabs/tabs-trigger.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import React, { useLayoutEffect, useRef } from 'react';
+import React, { useCallback } from 'react';
 
 import { type ComponentProps, mergeProps, useRender } from '../utils';
 import { useTabsContext } from './tabs-context';
@@ -13,16 +13,15 @@ export interface TabsTriggerProps extends ComponentProps<'button'> {
 export const TabsTrigger = React.forwardRef<HTMLButtonElement, TabsTriggerProps>(function TabsTrigger(props, ref) {
   const { render, value: tabValue, disabled, ...otherProps } = props;
   const { value: selectedValue, setValue, tabsId, registerTab } = useTabsContext();
-  const triggerRef = useRef<HTMLButtonElement | null>(null);
 
   const isSelected = selectedValue === tabValue;
   const tabId = `${tabsId}-tab-${tabValue}`;
   const panelId = `${tabsId}-panel-${tabValue}`;
 
-  useLayoutEffect(() => {
-    registerTab(tabValue, triggerRef.current);
-    return () => registerTab(tabValue, null);
-  }, [tabValue, registerTab]);
+  const register = useCallback(
+    (element: HTMLButtonElement | null) => registerTab(tabValue, element),
+    [registerTab, tabValue],
+  );
 
   const state = {
     selected: isSelected,
@@ -51,7 +50,7 @@ export const TabsTrigger = React.forwardRef<HTMLButtonElement, TabsTriggerProps>
   return useRender({
     defaultTagName: 'button',
     render,
-    ref: [triggerRef, ref],
+    ref: [register, ref],
     state,
     stateAttributesMapping: {
       selected: (v: boolean) => (v ? { 'data-selected': '' } : null),