From 7b2913d6f9ac1b649c25ba661de87369c5b1acaa Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 16:43:12 -0600
Subject: [PATCH 1/5] feat(mosaic): animate contact list rows and the primary
 badge in the user profile

Emails and phone numbers in the account section keep the order they were
first shown in while the panel is mounted. Each row sits in a grid slot
whose track transitions between 1fr and 0fr, with the content fading
inside a clip layer anchored to the top. Setting a primary moves the
badge, which enters and exits on the motion rules, rather than the rows.
A set-primary request marks its row busy; once it outlasts a short delay
a spinner shows where the badge will land and the badge change waits for
it. Under reduced motion every change is a cut.

Adds usePresenceList and useStableOrder to the primitives, and a
useContactList hook shared by the email and phone rows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .changeset/contact-list-rows.md               |   2 +
 packages/mosaic/docs/motion.md                | 106 ++++++++
 ...ser-profile-contact-list-row.view.test.tsx | 180 ++++++++++++-
 .../user-profile-email-actions.test.tsx       |  80 ++++--
 .../use-contact-list.ts                       |  68 +++++
 ...-profile-account-section.markers.stylex.ts |   3 +
 .../user-profile-account-section.messages.ts  |   1 +
 .../user-profile-account-section.model.ts     |   7 +-
 .../user-profile-account-section.styles.ts    | 121 +++++++++
 .../user-profile-contact-list-row.view.tsx    | 241 ++++++++++++++----
 .../user-profile-email-row.view.tsx           |  45 ++--
 .../user-profile-phone-row.view.tsx           |  54 ++--
 packages/mosaic/src/primitives/hooks/index.ts |   2 +
 .../hooks/use-presence-list.test.tsx          | 116 +++++++++
 .../src/primitives/hooks/use-presence-list.ts |  99 +++++++
 .../hooks/use-stable-order.test.tsx           |  62 +++++
 .../src/primitives/hooks/use-stable-order.ts  |  37 +++
 .../stories/user-profile-account-section.mdx  |  15 ++
 .../user-profile-account-section.stories.tsx  |  28 +-
 19 files changed, 1121 insertions(+), 146 deletions(-)
 create mode 100644 .changeset/contact-list-rows.md
 create mode 100644 packages/mosaic/src/features/user-profile/user-profile-account-section/use-contact-list.ts
 create mode 100644 packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts
 create mode 100644 packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
 create mode 100644 packages/mosaic/src/primitives/hooks/use-presence-list.test.tsx
 create mode 100644 packages/mosaic/src/primitives/hooks/use-presence-list.ts
 create mode 100644 packages/mosaic/src/primitives/hooks/use-stable-order.test.tsx
 create mode 100644 packages/mosaic/src/primitives/hooks/use-stable-order.ts

diff --git a/.changeset/contact-list-rows.md b/.changeset/contact-list-rows.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/contact-list-rows.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/mosaic/docs/motion.md b/packages/mosaic/docs/motion.md
index c3456049e83..cf32a4c75c6 100644
--- a/packages/mosaic/docs/motion.md
+++ b/packages/mosaic/docs/motion.md
@@ -276,12 +276,118 @@ nothing. The surface keeps its fade and pins the scale (inline text has none to
 and its entrance delay goes to `instant` as well: it exists to wait for the row, and
 a row that has snapped open leaves nothing to wait for.
 
+### Rows in a list
+
+The contact rows in the user profile (`user-profile-contact-list-row.view.tsx`) adopt
+the recipe for a `<ul>` whose rows come and go. What differs from the banner:
+
+- **The slot is the `<li>`.** `grid-template-rows` on the list item, the clip layer
+  inside it (`grid-row: 1 / span 2`, `min-height: 0`, no padding), and the real row
+  rendered as a `div` through `Section.Item`'s `render`. `usePresenceList` keeps a
+  removed row mounted, in place and `inert`, until its collapse ends.
+- **The entering track starts from `data-starting-style`**, as every other
+  transition does. Rows present at the list's first render skip the entering state,
+  or the list expands from nothing on load.
+- **The track waits out the dialog.** A row is added or removed by a dialog that is
+  still animating out when the data lands, and a track that starts at the same moment
+  is lost behind it. The slot's transition carries a `base` delay both ways (the
+  dialog exits at `fast`, its phone sheet at `base`), and the content's own delays
+  are offset by the same amount so they stay relative to the track.
+- **One duration and one curve both ways**: `--cl-duration-slower` on
+  `--cl-ease-in-out`. The row is still there when either transition ends, so a
+  collapse is a layout settle rather than an exit and takes the same curve as the
+  expand.
+- **Anchored to the start, faded at the bottom.** The row's top border is the list's
+  separator, so the content sits at the top of the clip and the border is there from
+  the first frame to the last in both directions; the moving edge is the bottom one,
+  under a static `mask-image` the height of the row's bottom padding less the focus
+  ring's extent, so at rest it touches neither the text nor a focused trigger's
+  outline. Every row carries its 1px border and the body's own top border is zeroed
+  for this list, so the first row's border is the header divider: when it exits, its
+  border leaves with its track and the next row's lands in the same place, rather
+  than two borders meeting and one snapping away. `Section.Item`'s sibling-marker
+  rule cannot see across the slots, so the border is the row's own.
+- **The content fade lives on the row's children** (a marker on the row,
+  `stylex.when.ancestor` on `Section.Content` and `Section.Actions`), never on the
+  row itself: opacity on the row would fade its border too. Inline text takes opacity
+  only. It enters after `base + slow` (the track's own `base` delay, then `slow`, so
+  the track is ~90% open before text shows; longer than the banner's `fast` because
+  this track runs `slower` on in-out), at `base`; it exits at once with the track, at
+  `fast`.
+- **Reduced motion is a cut.** Every transition off and every value at rest;
+  `useTransition` then unmounts an exiting row as soon as it finds nothing to wait
+  for.
+
+**Rows do not reorder.** While the list is mounted it keeps the order it was first
+shown in (`useStableOrder`): a new row is appended, a removed row drops out, and a
+row the model now sorts elsewhere stays put. Setting a primary therefore moves the
+badge, which enters and exits on the ordinary rules (`base` in on `--cl-ease-enter`
+with `scale(0.9 → 1)` on `--cl-ease-default`, `fast` out on `--cl-ease-exit`),
+rather than moving rows past each other.
+
+**A pending request shows where its outcome will land.** A set-primary request marks
+its row busy at once; once it outlasts `useSpinDelay`'s 150ms, a small `Spinner`
+(`role='progressbar'`, named) fades in beside the value, in the spot the badge will
+take, and the badge change is held until the spinner has shown for its 400ms
+minimum. The old badge then exits at `fast` and the new one enters after a `fast`
+delay, so the two never cross; the spinner leaves with the old badge. Both share one
+transition (opacity, `scale(0.9 → 1)`, `blur(1px → 0)`) in one grid cell, so neither
+shifts the other, and the badge adds half a rem of `translate` toward the row the
+primary moves to or arrives from, with the scale's origin left at center. The pending
+pattern itself is in "Small elements", below.
+
 ## Reflowing siblings
 
 When siblings reflow (an item added or removed), use `useLayoutAnimation` from
 `primitives/hooks`; its JSDoc covers the wiring. Set `--cl-layout-duration` /
 `--cl-layout-easing` from the duration and easing tokens, not literals.
 
+## Small elements: pills, badges, indicators
+
+The reference is the Primary badge and its pending spinner on the contact rows
+(`user-profile-contact-list-row.view.tsx`, `badgeSlotItem`). The tag input's tags
+should adopt the same recipe. Everything here is tuned on a ~20px pill; the numbers
+do not scale up to surfaces.
+
+**The base transition is the ordinary one.** `base` in with opacity on
+`--cl-ease-enter` and `scale(0.9 → 1)` on `--cl-ease-default`, plus any `translate`
+on the same curve; `fast` out with all of it on `--cl-ease-exit`. Use the individual `scale` property, not `transform`: a spinner
+rotates through a `transform` keyframe, and a `transform: scale()` on the same element
+would be overridden by it. The two compose.
+
+**A slight blur, `blur(1px)`, at both ends.** Add `filter` to the transition list,
+on `--cl-ease-enter` in and `--cl-ease-exit` out, and drop it to `blur(0)` under
+reduced motion with the scale. It reads as the pill resolving into place rather than
+switching on.
+
+**Replacing one with another: exit first, then enter.** When a badge moves from one
+row to another, or a spinner gives way to a badge, give the entering element a
+`transition-delay` equal to the leaving one's exit duration (`fast`), with the delay
+dropped on the exit branch. The two then never cross and the eye reads one thing
+leaving and another arriving. Without the delay they overlap mid-fade and read as a
+flicker.
+
+**Put the two in one cell so neither shifts the other.** A `display: grid` wrapper
+with both children at `grid-area: 1 / 1`, start-aligned, and `:empty { display: none }`
+so an empty slot adds no gap to the flex row around it. The wrapper's width follows
+whichever child is widest, which is the only layout change, and it happens at the
+end of the text where nothing follows.
+
+**A pending state shows where its outcome will land.** Mark the container busy at
+once, and once the request outlasts `useSpinDelay`'s threshold, fade a small named
+`Spinner` (`role='progressbar'`) into the slot the result will take. Hold the result
+until the spinner has shown for its minimum, then let the spinner leave with the old
+state and the new state arrive after its `fast` delay.
+
+**Spinners are small elements too.** A spinner that appears after a spin delay and
+leaves when the work is done takes the same entrance and exit as a badge: opacity,
+`scale`, the 1px blur, and the `fast` delay when it is replacing or being replaced by
+something in its slot. The contact rows' pending spinner does; `SubmitButton`'s still
+snaps its spinner on and off through `opacity` and is the next to adopt it. Keep its
+accessibility approach either way: hide a pending spinner with opacity, never
+`display` or `visibility`, so the `progressbar` stays in the tree for the whole
+action.
+
 ## Color and state changes (hover, press)
 
 A state change on an element that is already there and stays there — background,
diff --git a/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx b/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
index ba9098b25f9..717a25f4e28 100644
--- a/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
+++ b/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
@@ -1,10 +1,23 @@
-import { render, screen } from '@testing-library/react';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { UserProfileContactListRowView } from '../user-profile-account-section/user-profile-contact-list-row.view';
 
+type Animated = { getAnimations?: () => Animation[] };
+
+function holdExits() {
+  const exit = createDeferredPromise();
+  (Element.prototype as Animated).getAnimations = () => [{ finished: exit.promise } as Animation];
+  return exit;
+}
+
 describe('UserProfileContactListRowView', () => {
+  afterEach(() => {
+    delete (Element.prototype as Animated).getAnimations;
+  });
+
   it.each(['email', 'phone'] as const)('hides the menu when no %s action applies', kind => {
     const onVerify = vi.fn();
     const onSetPrimary = vi.fn();
@@ -40,4 +53,167 @@ describe('UserProfileContactListRowView', () => {
     await user.click(screen.getByRole('menuitem', { name: 'Remove phone number' }));
     expect(onRemove).toHaveBeenCalledExactlyOnceWith('contact_1');
   });
+
+  it('renders first-load rows without an entering state', () => {
+    render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={[{ id: 'contact_1', value: 'first@example.com' }]}
+      />,
+    );
+
+    const row = screen.getByText('first@example.com').closest('.cl-section-item');
+    expect(row).not.toHaveAttribute('data-starting-style');
+    expect(row?.closest('li')).not.toHaveAttribute('data-starting-style');
+  });
+
+  it('renders a first-load primary badge without an entering state', () => {
+    render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={[{ id: 'contact_1', value: 'first@example.com', isDefault: true }]}
+      />,
+    );
+
+    expect(screen.getByText('Primary').closest('.cl-badge')).not.toHaveAttribute('data-starting-style');
+  });
+
+  it('enters a row added after mount from its starting state', () => {
+    const items = [{ id: 'contact_1', value: 'first@example.com' }];
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={[...items, { id: 'contact_2', value: 'second@example.com' }]}
+      />,
+    );
+
+    const row = screen.getByText('second@example.com').closest('.cl-section-item');
+    expect(row).toHaveAttribute('data-starting-style');
+    expect(row?.closest('li')).toHaveAttribute('data-starting-style');
+  });
+
+  it('collapses the empty state when the first item is added', () => {
+    holdExits();
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={[]}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={[{ id: 'contact_1', value: 'first@example.com' }]}
+      />,
+    );
+
+    expect(screen.getByText('No email addresses added').closest('li')).toHaveAttribute('data-ending-style');
+    expect(screen.getByText('first@example.com')).toBeInTheDocument();
+  });
+
+  it('keeps a removed item inert in place until its exit finishes', async () => {
+    const exit = holdExits();
+    const items = [
+      { id: 'contact_1', value: 'first@example.com' },
+      { id: 'contact_2', value: 'second@example.com' },
+      { id: 'contact_3', value: 'third@example.com' },
+    ];
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items.filter(item => item.id !== 'contact_2')}
+      />,
+    );
+
+    const slot = screen.getByText('second@example.com').closest('li');
+    expect(slot).toHaveAttribute('data-ending-style');
+    expect(slot).toHaveAttribute('inert');
+    expect(slot).toHaveAttribute('aria-hidden', 'true');
+    expect(slot?.previousElementSibling).toHaveTextContent('first@example.com');
+    expect(slot?.nextElementSibling).toHaveTextContent('third@example.com');
+
+    await act(async () => {
+      exit.resolve();
+      await exit.promise;
+    });
+    expect(screen.queryByText('second@example.com')).not.toBeInTheDocument();
+  });
+
+  it('shows the empty state while the last item exits', () => {
+    holdExits();
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='phone'
+        label='Phones'
+        items={[{ id: 'contact_1', value: '+1 (801) 555-0100' }]}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='phone'
+        label='Phones'
+        items={[]}
+      />,
+    );
+
+    expect(screen.getByText('+1 (801) 555-0100').closest('li')).toHaveAttribute('data-ending-style');
+    expect(screen.getByText('No phone numbers added')).toBeInTheDocument();
+  });
+
+  it('transitions the primary badge out when another item becomes primary', () => {
+    holdExits();
+    const items = [
+      { id: 'contact_1', value: 'first@example.com', isDefault: true, isVerified: true },
+      { id: 'contact_2', value: 'second@example.com', isVerified: true },
+    ];
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={[
+          { ...items[0], isDefault: false },
+          { ...items[1], isDefault: true },
+        ]}
+      />,
+    );
+
+    const badges = screen.getAllByText('Primary').map(label => label.closest<HTMLElement>('.cl-badge'));
+    expect(badges).toHaveLength(2);
+    expect(badges[0]).toHaveAttribute('data-ending-style');
+    expect(badges[1]).toHaveAttribute('data-starting-style');
+    expect(badges[0]?.getAttribute('style')).toContain('0.5rem');
+    expect(badges[1]?.getAttribute('style')).toContain('0.5rem');
+  });
 });
diff --git a/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx b/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx
index 26d58ac7e24..7478d45c4b0 100644
--- a/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx
+++ b/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx
@@ -25,28 +25,51 @@ function renderEmail(overrides: Partial<UserProfileAccountSectionViewProps> = {}
 }
 
 describe('email actions', () => {
-  it('returns focus to the email menu after opening with the keyboard and canceling with Escape', async () => {
+  it('marks the email busy while it is being set as primary', async () => {
     const user = userEvent.setup();
-    const onRemoveEmail = vi.fn();
-    renderEmail({ onRemoveEmail });
-    const trigger = screen.getByRole('button', { name: 'Manage test@example.com' });
+    const request = createDeferredPromise();
+    const onSetPrimaryEmail = vi.fn().mockReturnValue(request.promise);
+    renderEmail({ onSetPrimaryEmail });
+    const row = screen.getByText('test@example.com').closest('.cl-section-item');
 
-    trigger.focus();
-    await user.keyboard('{Enter}');
-    await user.keyboard('{Enter}');
-    expect(screen.getByRole('alertdialog', { name: 'Remove email address?' })).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Manage test@example.com' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Set as primary' }));
+    expect(row).toHaveAttribute('aria-busy', 'true');
 
-    await user.keyboard('{Escape}');
+    await act(async () => {
+      request.resolve();
+      await request.promise;
+    });
+    expect(row).not.toHaveAttribute('aria-busy');
+  });
 
-    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());
-    expect(onRemoveEmail).not.toHaveBeenCalled();
-    await waitFor(() => expect(trigger).toHaveFocus());
+  it('stays busy while the pending indicator is held after a slow request', async () => {
+    const user = userEvent.setup();
+    const onSetPrimaryEmail = vi.fn(() => new Promise<void>(resolve => setTimeout(resolve, 200)));
+    renderEmail({ onSetPrimaryEmail });
+    const row = screen.getByText('test@example.com').closest('.cl-section-item');
+
+    await user.click(screen.getByRole('button', { name: 'Manage test@example.com' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Set as primary' }));
+    await act(() => new Promise(resolve => setTimeout(resolve, 300)));
+
+    expect(screen.getByRole('progressbar', { name: 'Setting as primary' })).toBeInTheDocument();
+    expect(row).toHaveAttribute('aria-busy', 'true');
+
+    await waitFor(() => expect(screen.queryByRole('progressbar')).not.toBeInTheDocument(), { timeout: 1500 });
+    expect(row).not.toHaveAttribute('aria-busy');
   });
 
-  it('focuses Add email after removing the last email', async () => {
+  it('keeps the list order when the primary changes, and holds the badge while the spinner shows', async () => {
     const user = userEvent.setup();
+    const order = () =>
+      screen.getAllByRole('button', { name: /^Manage / }).map(button => button.getAttribute('aria-label'));
+    const primary = () => screen.getByText('Primary').closest('.cl-section-item')?.textContent;
     function Example() {
-      const [emails, setEmails] = useState([{ id: 'email_1', value: 'test@example.com', isVerified: true }]);
+      const [emails, setEmails] = useState([
+        { id: 'email_1', value: 'first@example.com', isDefault: true, isVerified: true },
+        { id: 'email_2', value: 'second@example.com', isVerified: true },
+      ]);
       return (
         <MosaicProvider>
           <UserProfileAccountSectionView
@@ -55,22 +78,31 @@ describe('email actions', () => {
             username='test'
             phones={[]}
             emails={emails}
-            onSendEmailCode={() => Promise.resolve()}
-            onVerifyEmailCode={() => Promise.resolve()}
-            onRemoveEmail={id => setEmails(current => current.filter(email => email.id !== id))}
+            onRemoveEmail={vi.fn()}
+            onSetPrimaryEmail={async id => {
+              await new Promise(resolve => setTimeout(resolve, 200));
+              setEmails(current =>
+                [...current]
+                  .map(email => ({ ...email, isDefault: email.id === id }))
+                  .sort((a, b) => Number(b.isDefault) - Number(a.isDefault)),
+              );
+            }}
           />
         </MosaicProvider>
       );
     }
     render(<Example />);
-    await user.click(screen.getByRole('button', { name: 'Manage test@example.com' }));
-    await user.click(screen.getByRole('menuitem', { name: 'Remove email' }));
-    await user.click(within(screen.getByRole('alertdialog')).getByRole('button', { name: 'Remove' }));
+    await user.click(screen.getByRole('button', { name: 'Manage second@example.com' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Set as primary' }));
 
-    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());
-    expect(screen.queryByRole('button', { name: 'Manage test@example.com' })).not.toBeInTheDocument();
-    expect(screen.getByRole('button', { name: 'Add email' })).toBeEnabled();
-    await waitFor(() => expect(screen.getByRole('button', { name: 'Add email' })).toHaveFocus());
+    await act(() => new Promise(resolve => setTimeout(resolve, 300)));
+    expect(primary()).toContain('first@example.com');
+    expect(
+      screen.getByRole('progressbar', { name: 'Setting as primary' }).closest('.cl-section-item'),
+    ).toHaveTextContent('second@example.com');
+
+    await waitFor(() => expect(primary()).toContain('second@example.com'), { timeout: 1500 });
+    expect(order()).toEqual(['Manage first@example.com', 'Manage second@example.com']);
   });
 
   it('shows a primary update error without opening a dialog', async () => {
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/use-contact-list.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/use-contact-list.ts
new file mode 100644
index 00000000000..7ba287da81d
--- /dev/null
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/use-contact-list.ts
@@ -0,0 +1,68 @@
+import { useRef, useState } from 'react';
+
+import { useSpinDelay } from '../../../hooks/use-spin-delay';
+import { useStableOrder } from '../../../primitives/hooks';
+
+interface ContactItem {
+  id: string;
+  isDefault?: boolean;
+  isVerified?: boolean;
+}
+
+const byId = (item: ContactItem) => item.id;
+
+export function useContactList<T extends ContactItem>({
+  items,
+  onSetPrimary,
+  primaryErrorMessage,
+}: {
+  items: T[];
+  onSetPrimary?: (id: string) => void | Promise<void>;
+  primaryErrorMessage: string;
+}) {
+  const row = useRef<HTMLDivElement>(null);
+  const ordered = useStableOrder(items, byId);
+  const [pendingPrimaryId, setPendingPrimaryId] = useState<string>();
+  const shownPendingId = useSpinDelay(pendingPrimaryId ?? null) ?? undefined;
+  const holding = shownPendingId !== undefined;
+  const [held, setHeld] = useState(ordered);
+  if (!holding && held !== ordered) {
+    setHeld(ordered);
+  }
+  const shownItems = holding ? held : ordered;
+  const [primaryError, setPrimaryError] = useState<string>();
+  const settingPrimary = useRef(false);
+
+  const setPrimary = async (id: string) => {
+    const item = items.find(item => item.id === id);
+    if (!onSetPrimary || !item?.isVerified || item.isDefault || settingPrimary.current) {
+      return;
+    }
+    settingPrimary.current = true;
+    setPendingPrimaryId(id);
+    setPrimaryError(undefined);
+    try {
+      await onSetPrimary(id);
+    } catch (error) {
+      setPrimaryError(error instanceof Error ? error.message : primaryErrorMessage);
+    } finally {
+      settingPrimary.current = false;
+      setPendingPrimaryId(undefined);
+    }
+  };
+
+  const removalFallback = () =>
+    Array.from(row.current?.querySelectorAll<HTMLButtonElement>('button:not([disabled])') ?? []).find(
+      button => !button.closest('[aria-hidden="true"]'),
+    ) ?? row.current;
+
+  return {
+    row,
+    shownItems,
+    pendingPrimaryId,
+    shownPendingId,
+    primaryError,
+    setPrimary: onSetPrimary && !pendingPrimaryId && !holding ? (id: string) => void setPrimary(id) : undefined,
+    removalFallback,
+  };
+}
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts
new file mode 100644
index 00000000000..868f8e0945e
--- /dev/null
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts
@@ -0,0 +1,3 @@
+import * as stylex from '@stylexjs/stylex';
+
+export const contactItemMarker = stylex.defineMarker();
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.messages.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.messages.ts
index 97ef3318fbf..870d8a21d9f 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.messages.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.messages.ts
@@ -43,6 +43,7 @@ export const userProfileAccountSectionMessages = {
   add: 'Add',
   manage: 'Manage',
   setPrimary: 'Set as primary',
+  settingPrimary: 'Setting as primary',
   completeVerification: 'Complete verification',
 
   manageValue: 'Manage {value}',
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.model.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.model.ts
index 5a8dd497493..b12c4e8ce0e 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.model.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.model.ts
@@ -1,6 +1,7 @@
 import { getFullName } from '@clerk/shared/internal/clerk-js/user';
 import { useClerk, useUser } from '@clerk/shared/react';
 import type { AttributeData, Attributes, EnterpriseAccountResource, UserResource } from '@clerk/shared/types';
+import { useMemo } from 'react';
 
 import { useMosaicEnvironment } from '../../../hooks/use-mosaic-environment';
 import type { MessageValues } from '../../../localization';
@@ -81,6 +82,8 @@ function toPhones(user: UserResource): UserProfilePhone[] {
 
 export function useUserProfileAccountSectionModel(): UserProfileAccountSectionModel {
   const { isLoaded, user } = useUser();
+  const emails = useMemo(() => (user ? toEmails(user) : []), [user]);
+  const phones = useMemo(() => (user ? toPhones(user) : []), [user]);
   const clerk = useClerk();
   const environment = useMosaicEnvironment();
 
@@ -134,8 +137,8 @@ export function useUserProfileAccountSectionModel(): UserProfileAccountSectionMo
     hasImage: user.hasImage,
     username: showUsername ? (user.username ?? '') : undefined,
     usernameRequired: Boolean(usernameAttribute?.required),
-    emails: showEmails ? toEmails(user) : undefined,
-    phones: showPhones ? toPhones(user) : undefined,
+    emails: showEmails ? emails : undefined,
+    phones: showPhones ? phones : undefined,
     onProfilePictureChange: file => saveAsUser(current => current.setProfileImage({ file })),
     onRemoveProfilePicture: user.hasImage
       ? () => saveAsUser(current => current.setProfileImage({ file: null }))
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
new file mode 100644
index 00000000000..c58bffb4fea
--- /dev/null
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
@@ -0,0 +1,121 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { durationVars, easingVars, focusVars, space } from '../../../tokens.stylex';
+import { contactItemMarker } from './user-profile-account-section.markers.stylex';
+
+const ring = `calc(${focusVars['--cl-focus-outline-width']} + ${focusVars['--cl-focus-outline-offset']})`;
+
+export const styles = stylex.create({
+  contactBody: {
+    borderBlockStartWidth: '0px',
+  },
+  contactSlot: {
+    display: 'grid',
+    gridTemplateRows: {
+      default: '1fr',
+      ':where([data-starting-style], [data-ending-style])': '0fr',
+    },
+    transitionDelay: durationVars['--cl-duration-base'],
+    transitionDuration: durationVars['--cl-duration-slower'],
+    transitionProperty: {
+      default: 'grid-template-rows',
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    transitionTimingFunction: easingVars['--cl-ease-in-out'],
+  },
+  contactClip: {
+    marginInline: `calc(-1 * ${ring})`,
+    overflow: 'clip',
+    paddingInline: ring,
+    alignContent: 'start',
+    display: 'grid',
+    gridRowEnd: 'span 2',
+    gridRowStart: '1',
+    maskImage: `linear-gradient(to top, transparent, black calc(${space['4']} - ${ring}))`,
+    minHeight: 0,
+  },
+  contactItem: {
+    borderBlockStartWidth: '1px',
+  },
+  contactFade: {
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactItemMarker)]: 0,
+      '@media (prefers-reduced-motion: reduce)': {
+        default: 1,
+        [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactItemMarker)]: 1,
+      },
+    },
+    transitionDelay: {
+      default: `calc(${durationVars['--cl-duration-base']} + ${durationVars['--cl-duration-slow']})`,
+      [stylex.when.ancestor(':where([data-ending-style])', contactItemMarker)]: durationVars['--cl-duration-base'],
+    },
+    transitionDuration: {
+      default: durationVars['--cl-duration-base'],
+      [stylex.when.ancestor(':where([data-ending-style])', contactItemMarker)]: durationVars['--cl-duration-fast'],
+    },
+    transitionProperty: {
+      default: 'opacity',
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    transitionTimingFunction: {
+      default: easingVars['--cl-ease-enter'],
+      [stylex.when.ancestor(':where([data-ending-style])', contactItemMarker)]: easingVars['--cl-ease-exit'],
+    },
+  },
+  badgeSlot: {
+    alignItems: 'center',
+    display: { default: 'grid', ':empty': 'none' },
+    justifyItems: 'start',
+  },
+  badgeSlotItem: {
+    filter: {
+      default: 'blur(0)',
+      ':where([data-starting-style], [data-ending-style])': 'blur(1px)',
+      '@media (prefers-reduced-motion: reduce)': {
+        default: 'blur(0)',
+        ':where([data-starting-style], [data-ending-style])': 'blur(0)',
+      },
+    },
+    gridColumnStart: '1',
+    gridRowStart: '1',
+    opacity: { default: 1, ':where([data-starting-style], [data-ending-style])': 0 },
+    scale: {
+      default: 1,
+      ':where([data-starting-style], [data-ending-style])': 0.9,
+      '@media (prefers-reduced-motion: reduce)': {
+        default: 1,
+        ':where([data-starting-style], [data-ending-style])': 1,
+      },
+    },
+    transitionDelay: {
+      default: durationVars['--cl-duration-fast'],
+      ':where([data-ending-style])': durationVars['--cl-duration-instant'],
+    },
+    transitionDuration: {
+      default: durationVars['--cl-duration-base'],
+      ':where([data-ending-style])': durationVars['--cl-duration-fast'],
+    },
+    transitionProperty: {
+      default: 'opacity, scale, filter, translate',
+      '@media (prefers-reduced-motion: reduce)': 'opacity',
+    },
+    transitionTimingFunction: {
+      default: `${easingVars['--cl-ease-enter']}, ${easingVars['--cl-ease-default']}, ${easingVars['--cl-ease-enter']}, ${easingVars['--cl-ease-default']}`,
+      ':where([data-ending-style])': easingVars['--cl-ease-exit'],
+    },
+    translate: {
+      default: '0 0',
+      ':where([data-ending-style])': '0 var(--_cl-badge-shift, 0px)',
+      ':where([data-starting-style])': '0 calc(-1 * var(--_cl-badge-shift, 0px))',
+      '@media (prefers-reduced-motion: reduce)': {
+        default: '0 0',
+        ':where([data-starting-style], [data-ending-style])': '0 0',
+      },
+    },
+  },
+});
+
+export const badgeShift = stylex.create({
+  along: (direction: number) => ({ '--_cl-badge-shift': `${direction * 0.5}rem` }),
+});
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
index 5ace8fe683c..89824eedc7c 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
@@ -1,5 +1,7 @@
+import { inertProps } from '@clerk/shared/inert';
 import * as stylex from '@stylexjs/stylex';
 import type { ReactNode, Ref } from 'react';
+import { useEffect, useRef } from 'react';
 
 import type { ActionMenuAction } from '../../../components/action-menu';
 import { ActionMenu } from '../../../components/action-menu';
@@ -7,9 +9,15 @@ import { Badge } from '../../../components/badge';
 import { Button } from '../../../components/button';
 import { Icon } from '../../../components/icon';
 import { Section } from '../../../components/section';
+import { Spinner } from '../../../components/spinner';
 import { fill, useMessages } from '../../../localization';
+import type { TransitionProps } from '../../../primitives/hooks';
+import { usePresenceList, useTransition } from '../../../primitives/hooks';
+import { reset } from '../../../styles/reset.styles';
 import { truncationStyles } from '../../../styles/typography.styles';
-import { styles } from '../user-profile-profile-panel.styles';
+import { styles as panelStyles } from '../user-profile-profile-panel.styles';
+import { contactItemMarker } from './user-profile-account-section.markers.stylex';
+import { badgeShift, styles } from './user-profile-account-section.styles';
 
 export interface UserProfileContactListRowViewProps {
   rowRef?: Ref<HTMLDivElement>;
@@ -22,9 +30,92 @@ export interface UserProfileContactListRowViewProps {
   onVerify?: (id: string) => void;
   onSetPrimary?: (id: string) => void;
   onRemove?: (id: string) => void;
+  /** The item whose set-primary request is in flight. */
+  pendingId?: string;
+  /** The item showing the pending indicator, once the request has outlasted the spin delay. */
+  shownPendingId?: string;
   children?: ReactNode;
 }
 
+const byId = (item: { id: string }) => item.id;
+
+function withoutEntrance(transitionProps: TransitionProps, appear: boolean) {
+  return appear ? transitionProps : { ...transitionProps, 'data-starting-style': undefined, style: undefined };
+}
+
+function SlotItem({
+  open,
+  appear,
+  children,
+}: {
+  open: boolean;
+  appear: boolean;
+  children: (ref: Ref<HTMLSpanElement>, props: TransitionProps) => ReactNode;
+}) {
+  const element = useRef<HTMLSpanElement>(null);
+  const { mounted, transitionProps } = useTransition({ open, ref: element });
+
+  if (!mounted) {
+    return null;
+  }
+
+  return children(element, withoutEntrance(transitionProps, appear));
+}
+
+function ContactListItem({
+  present = true,
+  appear,
+  pending = false,
+  onExited,
+  actions,
+  children,
+}: {
+  present?: boolean;
+  appear: boolean;
+  pending?: boolean;
+  onExited?: () => void;
+  actions?: ReactNode;
+  children: ReactNode;
+}) {
+  const element = useRef<HTMLLIElement>(null);
+  const { mounted, transitionProps } = useTransition({ open: present, ref: element });
+
+  useEffect(() => {
+    if (!mounted) {
+      onExited?.();
+    }
+  }, [mounted, onExited]);
+
+  if (!mounted) {
+    return null;
+  }
+
+  const slotProps = withoutEntrance(transitionProps, appear);
+  const rowProps = { ...slotProps, style: undefined };
+
+  return (
+    <li
+      ref={element}
+      aria-hidden={present ? undefined : true}
+      {...stylex.props(reset.base, styles.contactSlot)}
+      {...slotProps}
+      {...inertProps(!present)}
+    >
+      <div {...stylex.props(styles.contactClip)}>
+        <Section.Item
+          render={<div />}
+          aria-busy={pending || undefined}
+          xstyle={[styles.contactItem, contactItemMarker]}
+          {...rowProps}
+        >
+          <Section.Content xstyle={styles.contactFade}>{children}</Section.Content>
+          {actions ? <Section.Actions xstyle={styles.contactFade}>{actions}</Section.Actions> : null}
+        </Section.Item>
+      </div>
+    </li>
+  );
+}
+
 export function UserProfileContactListRowView({
   kind,
   label,
@@ -33,13 +124,27 @@ export function UserProfileContactListRowView({
   onVerify,
   onSetPrimary,
   onRemove,
+  pendingId,
+  shownPendingId,
   addAction,
   rowRef,
   triggerRef,
   children,
 }: UserProfileContactListRowViewProps) {
   const m = useMessages('userProfileAccountSection');
-  const emptyDescription = m[kind].empty;
+  const entries = usePresenceList(items, byId);
+  const primaryId = items.find(item => item.isDefault)?.id;
+  const primaryMove = useRef({ id: primaryId, direction: 0 });
+  if (primaryMove.current.id !== primaryId) {
+    const from = entries.findIndex(entry => entry.item.id === primaryMove.current.id);
+    const to = entries.findIndex(entry => entry.item.id === primaryId);
+    primaryMove.current = { id: primaryId, direction: from === -1 || to === -1 ? 0 : Math.sign(to - from) };
+  }
+  const settled = useRef(false);
+  useEffect(() => {
+    settled.current = true;
+  }, []);
+  const appear = settled.current;
 
   return (
     <Section.Group
@@ -71,56 +176,90 @@ export function UserProfileContactListRowView({
           </Section.Actions>
         ) : null}
       </Section.Header>
-      <Section.Body>
+      <Section.Body xstyle={styles.contactBody}>
         <Section.Items>
-          {items.length === 0 ? (
-            <Section.Item>
-              <Section.Content>
-                <Section.Description>{emptyDescription}</Section.Description>
-              </Section.Content>
-            </Section.Item>
-          ) : (
-            items.map(item => {
-              const actions: ActionMenuAction[] = [];
-
-              if (item.isVerified === false && onVerify) {
-                actions.push({
-                  label: item.isDefault ? m.completeVerification : m[kind].verify,
-                  onClick: () => onVerify(item.id),
-                });
-              } else if (!item.isDefault && item.isVerified === true && onSetPrimary) {
-                actions.push({ label: m.setPrimary, onClick: () => onSetPrimary(item.id) });
-              }
-
-              if (onRemove && item.canRemove !== false) {
-                actions.push({
-                  label: m[kind].remove,
-                  color: 'negative',
-                  onClick: () => onRemove(item.id),
-                });
-              }
-
-              return (
-                <Section.Item key={item.id}>
-                  <Section.Content>
-                    <Section.Description xstyle={styles.contactValue}>
-                      <span {...stylex.props(truncationStyles.singleLine, styles.contactText)}>{item.value}</span>
-                      {item.isDefault ? <Badge color='neutral'>{m.primary}</Badge> : null}
-                    </Section.Description>
-                  </Section.Content>
-                  {actions.length > 0 ? (
-                    <Section.Actions>
-                      <ActionMenu
-                        triggerRef={triggerRef?.(item.id)}
-                        actions={actions}
-                        label={fill(m.manageValue, { value: item.value })}
-                      />
-                    </Section.Actions>
-                  ) : null}
-                </Section.Item>
-              );
-            })
-          )}
+          {entries.map(({ key, item, present, onExited }) => {
+            const actions: ActionMenuAction[] = [];
+
+            if (item.isVerified === false && onVerify) {
+              actions.push({
+                label: item.isDefault ? m.completeVerification : m[kind].verify,
+                onClick: () => onVerify(item.id),
+              });
+            } else if (!item.isDefault && item.isVerified === true && onSetPrimary) {
+              actions.push({ label: m.setPrimary, onClick: () => onSetPrimary(item.id) });
+            }
+
+            if (onRemove && item.canRemove !== false) {
+              actions.push({
+                label: m[kind].remove,
+                color: 'negative',
+                onClick: () => onRemove(item.id),
+              });
+            }
+
+            return (
+              <ContactListItem
+                key={key}
+                present={present}
+                appear={appear}
+                pending={pendingId === item.id || shownPendingId === item.id}
+                onExited={onExited}
+                actions={
+                  actions.length > 0 ? (
+                    <ActionMenu
+                      triggerRef={present ? triggerRef?.(item.id) : undefined}
+                      actions={actions}
+                      label={fill(m.manageValue, { value: item.value })}
+                    />
+                  ) : null
+                }
+              >
+                <Section.Description xstyle={panelStyles.contactValue}>
+                  <span {...stylex.props(truncationStyles.singleLine, panelStyles.contactText)}>{item.value}</span>
+                  <span {...stylex.props(styles.badgeSlot)}>
+                    <SlotItem
+                      open={item.isDefault === true}
+                      appear={appear}
+                    >
+                      {(ref, props) => (
+                        <Badge
+                          ref={ref}
+                          color='neutral'
+                          xstyle={[styles.badgeSlotItem, badgeShift.along(primaryMove.current.direction)]}
+                          {...props}
+                        >
+                          {m.primary}
+                        </Badge>
+                      )}
+                    </SlotItem>
+                    <SlotItem
+                      open={shownPendingId === item.id}
+                      appear={appear}
+                    >
+                      {(ref, props) => (
+                        <Spinner
+                          ref={ref}
+                          role='progressbar'
+                          aria-hidden={undefined}
+                          aria-label={m.settingPrimary}
+                          size='sm'
+                          xstyle={styles.badgeSlotItem}
+                          {...props}
+                        />
+                      )}
+                    </SlotItem>
+                  </span>
+                </Section.Description>
+              </ContactListItem>
+            );
+          })}
+          <ContactListItem
+            present={items.length === 0}
+            appear={appear}
+          >
+            <Section.Description>{m[kind].empty}</Section.Description>
+          </ContactListItem>
         </Section.Items>
         {children}
       </Section.Body>
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-email-row.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-email-row.view.tsx
index 0da4cb95ef0..8027b59fec1 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-email-row.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-email-row.view.tsx
@@ -1,4 +1,4 @@
-import { useMemo, useRef, useState } from 'react';
+import { useMemo } from 'react';
 
 import { Confirmation } from '../../../blocks/confirmation';
 import { Button } from '../../../components/button';
@@ -6,6 +6,7 @@ import { Icon } from '../../../components/icon';
 import { Section } from '../../../components/section';
 import { useListRemovalFocus } from '../../../hooks/use-list-removal-focus';
 import { fill, useMessages } from '../../../localization';
+import { useContactList } from './use-contact-list';
 import type { UserProfileEmail } from './user-profile-account-section.types';
 import type { UserProfileAddEmailControllerOptions } from './user-profile-add-email.controller';
 import { useUserProfileAddEmailController } from './user-profile-add-email.controller';
@@ -37,11 +38,15 @@ export function UserProfileEmailRowView({
   onRemoveEmail,
 }: UserProfileEmailRowViewProps) {
   const m = useMessages('userProfileAccountSection');
-  const row = useRef<HTMLDivElement>(null);
+  const list = useContactList({
+    items: emails,
+    onSetPrimary: onSetPrimaryEmail,
+    primaryErrorMessage: m.email.primaryError,
+  });
   const removalFocus = useListRemovalFocus({
-    ids: emails.map(email => email.id),
+    ids: list.shownItems.map(email => email.id),
     onRemove: onRemoveEmail,
-    fallback: () => row.current?.querySelector<HTMLButtonElement>('button:not([disabled])') ?? row.current,
+    fallback: list.removalFallback,
   });
   const addEmailAction =
     onSendEmailCode && onVerifyEmailCode ? (
@@ -68,28 +73,6 @@ export function UserProfileEmailRowView({
       </Button>
     ) : undefined;
   const removeEmailConfirmation = useMemo(() => Confirmation.createHandle<UserProfileEmail>(), []);
-  const [isSettingPrimary, setIsSettingPrimary] = useState(false);
-  const [primaryError, setPrimaryError] = useState<string>();
-  const settingPrimary = useRef(false);
-
-  const setPrimaryEmail = async (id: string) => {
-    const email = emails.find(email => email.id === id);
-    if (!onSetPrimaryEmail || !email?.isVerified || email.isDefault || settingPrimary.current) {
-      return;
-    }
-    settingPrimary.current = true;
-    setIsSettingPrimary(true);
-    setPrimaryError(undefined);
-    try {
-      await onSetPrimaryEmail(id);
-    } catch (error) {
-      setPrimaryError(error instanceof Error ? error.message : m.email.primaryError);
-    } finally {
-      settingPrimary.current = false;
-      setIsSettingPrimary(false);
-    }
-  };
-
   const removeEmail = (id: string) => {
     const email = emails.find(email => email.id === id);
     if (email && email.canRemove !== false && onRemoveEmail) {
@@ -112,17 +95,19 @@ export function UserProfileEmailRowView({
   return (
     <>
       <UserProfileContactListRowView
-        rowRef={row}
+        rowRef={list.row}
         triggerRef={removalFocus.registerTrigger}
-        items={emails}
+        items={list.shownItems}
         kind='email'
         label={m.email.label}
         addAction={addEmailAction}
         onRemove={onRemoveEmail ? removeEmail : undefined}
-        onSetPrimary={onSetPrimaryEmail && !isSettingPrimary ? id => void setPrimaryEmail(id) : undefined}
+        onSetPrimary={list.setPrimary}
+        pendingId={list.pendingPrimaryId}
+        shownPendingId={list.shownPendingId}
         onVerify={onVerifyEmail}
       >
-        <Section.Error>{primaryError}</Section.Error>
+        <Section.Error>{list.primaryError}</Section.Error>
       </UserProfileContactListRowView>
       {onRemoveEmail ? (
         <Confirmation
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-phone-row.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-phone-row.view.tsx
index 861e9e00b68..5da17883290 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-phone-row.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-phone-row.view.tsx
@@ -1,5 +1,5 @@
 import { stringToFormattedPhoneString } from '@clerk/shared/phone';
-import { useMemo, useRef, useState } from 'react';
+import { useMemo } from 'react';
 
 import { Confirmation } from '../../../blocks/confirmation';
 import { Button } from '../../../components/button';
@@ -7,6 +7,7 @@ import { Icon } from '../../../components/icon';
 import { Section } from '../../../components/section';
 import { useListRemovalFocus } from '../../../hooks/use-list-removal-focus';
 import { fill, useMessages } from '../../../localization';
+import { useContactList } from './use-contact-list';
 import type { UserProfilePhone } from './user-profile-account-section.types';
 import type { UserProfileAddPhoneControllerOptions } from './user-profile-add-phone.controller';
 import { useUserProfileAddPhoneController } from './user-profile-add-phone.controller';
@@ -36,11 +37,19 @@ export function UserProfilePhoneRowView({
   onRemovePhone,
 }: UserProfilePhoneRowViewProps) {
   const m = useMessages('userProfileAccountSection');
-  const row = useRef<HTMLDivElement>(null);
+  const formattedPhones = useMemo(
+    () => phones.map(phone => ({ ...phone, value: stringToFormattedPhoneString(phone.value) })),
+    [phones],
+  );
+  const list = useContactList({
+    items: formattedPhones,
+    onSetPrimary: onSetPrimaryPhone,
+    primaryErrorMessage: m.phone.primaryError,
+  });
   const removalFocus = useListRemovalFocus({
-    ids: phones.map(phone => phone.id),
+    ids: list.shownItems.map(phone => phone.id),
     onRemove: onRemovePhone,
-    fallback: () => row.current?.querySelector<HTMLButtonElement>('button:not([disabled])') ?? row.current,
+    fallback: list.removalFallback,
   });
   const addPhoneAction =
     onSendPhoneCode && onVerifyPhoneCode ? (
@@ -50,39 +59,12 @@ export function UserProfilePhoneRowView({
       />
     ) : undefined;
   const removePhoneConfirmation = useMemo(() => Confirmation.createHandle<UserProfilePhone>(), []);
-  const [isSettingPrimary, setIsSettingPrimary] = useState(false);
-  const [primaryError, setPrimaryError] = useState<string>();
-  const settingPrimary = useRef(false);
-
-  const setPrimaryPhone = async (id: string) => {
-    const phone = phones.find(phone => phone.id === id);
-    if (!onSetPrimaryPhone || !phone?.isVerified || phone.isDefault || settingPrimary.current) {
-      return;
-    }
-    settingPrimary.current = true;
-    setIsSettingPrimary(true);
-    setPrimaryError(undefined);
-    try {
-      await onSetPrimaryPhone(id);
-    } catch (error) {
-      setPrimaryError(error instanceof Error ? error.message : m.phone.primaryError);
-    } finally {
-      settingPrimary.current = false;
-      setIsSettingPrimary(false);
-    }
-  };
-
   const removePhone = (id: string) => {
     const phone = phones.find(phone => phone.id === id);
     if (phone && phone.canRemove !== false && onRemovePhone) {
       removePhoneConfirmation.open(phone);
     }
   };
-  const formattedPhones = phones.map(phone => ({
-    ...phone,
-    value: stringToFormattedPhoneString(phone.value),
-  }));
-
   if (!allowMultipleAccounts) {
     return (
       <UserProfileContactRowView
@@ -98,17 +80,19 @@ export function UserProfilePhoneRowView({
   return (
     <>
       <UserProfileContactListRowView
-        rowRef={row}
+        rowRef={list.row}
         triggerRef={removalFocus.registerTrigger}
-        items={formattedPhones}
+        items={list.shownItems}
         kind='phone'
         label={m.phone.label}
         addAction={addPhoneAction}
         onRemove={onRemovePhone ? removePhone : undefined}
-        onSetPrimary={onSetPrimaryPhone && !isSettingPrimary ? id => void setPrimaryPhone(id) : undefined}
+        onSetPrimary={list.setPrimary}
+        pendingId={list.pendingPrimaryId}
+        shownPendingId={list.shownPendingId}
         onVerify={onVerifyPhone}
       >
-        <Section.Error>{primaryError}</Section.Error>
+        <Section.Error>{list.primaryError}</Section.Error>
       </UserProfileContactListRowView>
       {onRemovePhone ? (
         <Confirmation
diff --git a/packages/mosaic/src/primitives/hooks/index.ts b/packages/mosaic/src/primitives/hooks/index.ts
index 21951fdd2e4..2fe4a6643ac 100644
--- a/packages/mosaic/src/primitives/hooks/index.ts
+++ b/packages/mosaic/src/primitives/hooks/index.ts
@@ -12,6 +12,8 @@ export type {
   UseDataTableReturn,
 } from './use-data-table';
 export { useControllableState } from './use-controllable-state';
+export { type PresenceEntry, usePresenceList } from './use-presence-list';
+export { useStableOrder } from './use-stable-order';
 export { useLayoutAnimation } from './use-layout-animation';
 export {
   type TransitionProps,
diff --git a/packages/mosaic/src/primitives/hooks/use-presence-list.test.tsx b/packages/mosaic/src/primitives/hooks/use-presence-list.test.tsx
new file mode 100644
index 00000000000..f9a619dcda0
--- /dev/null
+++ b/packages/mosaic/src/primitives/hooks/use-presence-list.test.tsx
@@ -0,0 +1,116 @@
+import { act, render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { mergeRenderList, usePresenceList } from './use-presence-list';
+
+interface Item {
+  id: string;
+  label?: string;
+}
+
+const byId = (item: Item) => item.id;
+
+let latest: ReturnType<typeof usePresenceList<Item>>;
+
+function List({ items }: { items: Item[] }) {
+  latest = usePresenceList(items, byId);
+  return null;
+}
+
+function ids() {
+  return latest.map(entry => `${entry.key}${entry.present ? '' : '-'}`);
+}
+
+function exit(key: string) {
+  act(() => latest.find(entry => entry.key === key)?.onExited());
+}
+
+describe('usePresenceList', () => {
+  it('lists the given items as present', () => {
+    render(<List items={[{ id: 'a' }, { id: 'b' }]} />);
+
+    expect(ids()).toEqual(['a', 'b']);
+  });
+
+  it('keeps a removed item after its surviving predecessor until it has exited', () => {
+    const { rerender } = render(<List items={[{ id: 'a' }, { id: 'b' }, { id: 'c' }]} />);
+
+    rerender(<List items={[{ id: 'a' }, { id: 'c' }]} />);
+    expect(ids()).toEqual(['a', 'b-', 'c']);
+
+    exit('b');
+    expect(ids()).toEqual(['a', 'c']);
+  });
+
+  it('renders a removed item with the data it last had', () => {
+    const { rerender } = render(
+      <List
+        items={[
+          { id: 'a', label: 'first' },
+          { id: 'b', label: 'second' },
+        ]}
+      />,
+    );
+
+    rerender(<List items={[{ id: 'a', label: 'renamed' }]} />);
+
+    expect(latest.map(entry => entry.item.label)).toEqual(['renamed', 'second']);
+  });
+
+  it('follows a removed item through later reorders and unrelated renders', () => {
+    const { rerender } = render(<List items={[{ id: 'a' }, { id: 'b' }, { id: 'c' }]} />);
+
+    rerender(<List items={[{ id: 'a' }, { id: 'c' }]} />);
+    rerender(<List items={[{ id: 'a' }, { id: 'c' }]} />);
+    expect(ids()).toEqual(['a', 'b-', 'c']);
+
+    rerender(<List items={[{ id: 'c' }, { id: 'a' }]} />);
+    expect(ids()).toEqual(['c', 'a', 'b-']);
+  });
+
+  it('places a removed leading item first', () => {
+    const { rerender } = render(<List items={[{ id: 'a' }, { id: 'b' }]} />);
+
+    rerender(<List items={[{ id: 'b' }, { id: 'c' }]} />);
+
+    expect(ids()).toEqual(['a-', 'b', 'c']);
+  });
+
+  it('makes a returning item present again and ignores its stale exit', () => {
+    const { rerender } = render(<List items={[{ id: 'a' }, { id: 'b' }]} />);
+
+    rerender(<List items={[{ id: 'a' }]} />);
+    const stale = latest.find(entry => entry.key === 'b');
+    rerender(<List items={[{ id: 'a' }, { id: 'b' }]} />);
+    act(() => stale?.onExited());
+
+    expect(ids()).toEqual(['a', 'b']);
+  });
+
+  it('keeps one onExited per key across renders', () => {
+    const { rerender } = render(<List items={[{ id: 'a' }, { id: 'b' }]} />);
+    const first = latest.find(entry => entry.key === 'b')?.onExited;
+
+    rerender(<List items={[{ id: 'a' }]} />);
+
+    expect(latest.find(entry => entry.key === 'b')?.onExited).toBe(first);
+  });
+
+  it('returns the same entries while nothing changed', () => {
+    const items = [{ id: 'a' }];
+    const { rerender } = render(<List items={items} />);
+    const first = latest;
+
+    rerender(<List items={items} />);
+
+    expect(latest).toBe(first);
+  });
+});
+
+describe('mergeRenderList', () => {
+  it('anchors a missing key after its nearest surviving predecessor', () => {
+    expect(mergeRenderList(['a', 'b', 'c', 'd'], ['a', 'd'])).toEqual(['a', 'b', 'c', 'd']);
+    expect(mergeRenderList(['a', 'b'], ['c'])).toEqual(['a', 'b', 'c']);
+    expect(mergeRenderList(['a', 'b', 'c'], ['c', 'a'])).toEqual(['c', 'a', 'b']);
+  });
+});
diff --git a/packages/mosaic/src/primitives/hooks/use-presence-list.ts b/packages/mosaic/src/primitives/hooks/use-presence-list.ts
new file mode 100644
index 00000000000..bf4159a199e
--- /dev/null
+++ b/packages/mosaic/src/primitives/hooks/use-presence-list.ts
@@ -0,0 +1,99 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+export interface PresenceEntry<T> {
+  key: string;
+  item: T;
+  present: boolean;
+  onExited: () => void;
+}
+
+interface PresenceState<T> {
+  keys: string[];
+  render: string[];
+  held: ReadonlyMap<string, T>;
+}
+
+function sameOrder(a: string[], b: string[]) {
+  return a.length === b.length && a.every((key, index) => key === b[index]);
+}
+
+export function mergeRenderList(previous: string[], current: string[]): string[] {
+  const result = [...current];
+  previous.forEach((key, index) => {
+    if (result.includes(key)) {
+      return;
+    }
+    const anchor = previous
+      .slice(0, index)
+      .reverse()
+      .find(candidate => result.includes(candidate));
+    result.splice(anchor === undefined ? 0 : result.indexOf(anchor) + 1, 0, key);
+  });
+  return result;
+}
+
+/**
+ * Keeps an item that has left `items` in the returned entries, just after the nearest item that
+ * preceded it and is still present, until its `onExited` is called. Drive each entry's
+ * `useTransition` from `present` and call `onExited` once it unmounts, so a removed item plays
+ * its exit before leaving the DOM. A removed item renders with the data it last had.
+ */
+export function usePresenceList<T>(items: T[], getKey: (item: T) => string) {
+  const keys = useMemo(() => items.map(getKey), [items, getKey]);
+  const keysRef = useRef(keys);
+  keysRef.current = keys;
+
+  const [state, setState] = useState<PresenceState<T>>(() => ({ keys, render: keys, held: new Map() }));
+  const previous = useRef(items);
+  useEffect(() => {
+    previous.current = items;
+  }, [items]);
+
+  if (!sameOrder(state.keys, keys)) {
+    const render = mergeRenderList(state.render, keys);
+    const current = new Set(keys);
+    const held = new Map<string, T>();
+    for (const key of render) {
+      if (!current.has(key)) {
+        const item = state.held.get(key) ?? previous.current[state.keys.indexOf(key)];
+        if (item !== undefined) {
+          held.set(key, item);
+        }
+      }
+    }
+    setState({ keys, render: render.filter(key => current.has(key) || held.has(key)), held });
+  }
+
+  const callbacks = useRef(new Map<string, () => void>());
+  const onExited = useCallback((key: string) => {
+    let callback = callbacks.current.get(key);
+    if (!callback) {
+      callback = () => {
+        if (keysRef.current.includes(key)) {
+          return;
+        }
+        callbacks.current.delete(key);
+        setState(current => {
+          if (!current.render.includes(key)) {
+            return current;
+          }
+          const held = new Map(current.held);
+          held.delete(key);
+          return { ...current, render: current.render.filter(candidate => candidate !== key), held };
+        });
+      };
+      callbacks.current.set(key, callback);
+    }
+    return callback;
+  }, []);
+
+  return useMemo<PresenceEntry<T>[]>(() => {
+    const byKey = new Map(items.map((item, index) => [keys[index], item]));
+    return state.render.flatMap(key => {
+      const item = byKey.get(key) ?? state.held.get(key);
+      return item === undefined ? [] : [{ key, item, present: byKey.has(key), onExited: onExited(key) }];
+    });
+  }, [items, keys, state, onExited]);
+}
diff --git a/packages/mosaic/src/primitives/hooks/use-stable-order.test.tsx b/packages/mosaic/src/primitives/hooks/use-stable-order.test.tsx
new file mode 100644
index 00000000000..d8655b83d96
--- /dev/null
+++ b/packages/mosaic/src/primitives/hooks/use-stable-order.test.tsx
@@ -0,0 +1,62 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { useStableOrder } from './use-stable-order';
+
+interface Item {
+  id: string;
+  label?: string;
+}
+
+const byId = (item: Item) => item.id;
+
+let latest: Item[];
+
+function List({ items }: { items: Item[] }) {
+  latest = useStableOrder(items, byId);
+  return null;
+}
+
+describe('useStableOrder', () => {
+  it('keeps the first order when items move', () => {
+    const { rerender } = render(<List items={[{ id: 'a' }, { id: 'b' }, { id: 'c' }]} />);
+
+    rerender(<List items={[{ id: 'c' }, { id: 'a' }, { id: 'b' }]} />);
+
+    expect(latest.map(byId)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('appends new items and drops removed ones', () => {
+    const { rerender } = render(<List items={[{ id: 'a' }, { id: 'b' }]} />);
+
+    rerender(<List items={[{ id: 'd' }, { id: 'b' }]} />);
+    expect(latest.map(byId)).toEqual(['b', 'd']);
+
+    rerender(<List items={[{ id: 'a' }, { id: 'd' }, { id: 'b' }]} />);
+    expect(latest.map(byId)).toEqual(['b', 'd', 'a']);
+  });
+
+  it('returns the latest data for each item', () => {
+    const { rerender } = render(<List items={[{ id: 'a', label: 'one' }, { id: 'b' }]} />);
+
+    rerender(<List items={[{ id: 'b' }, { id: 'a', label: 'uno' }]} />);
+
+    expect(latest[0]).toEqual({ id: 'a', label: 'uno' });
+  });
+
+  it('returns the same array while nothing changed', () => {
+    const items = [{ id: 'a' }];
+    const { rerender } = render(<List items={items} />);
+    const first = latest;
+
+    rerender(<List items={items} />);
+
+    expect(latest).toBe(first);
+  });
+
+  it('keeps a duplicated key once', () => {
+    render(<List items={[{ id: 'a', label: 'one' }, { id: 'b' }, { id: 'a', label: 'two' }]} />);
+
+    expect(latest).toEqual([{ id: 'a', label: 'one' }, { id: 'b' }]);
+  });
+});
diff --git a/packages/mosaic/src/primitives/hooks/use-stable-order.ts b/packages/mosaic/src/primitives/hooks/use-stable-order.ts
new file mode 100644
index 00000000000..71debe6afff
--- /dev/null
+++ b/packages/mosaic/src/primitives/hooks/use-stable-order.ts
@@ -0,0 +1,37 @@
+'use client';
+
+import { useMemo, useRef } from 'react';
+
+function sameOrder(a: string[], b: string[]) {
+  return a.length === b.length && a.every((key, index) => key === b[index]);
+}
+
+/**
+ * Keeps items in the order they were first seen: a new item is appended, a removed item drops
+ * out, and an item that moves in `items` stays where it was. The order given on the first
+ * render is the one kept. A key that appears more than once is kept once.
+ */
+export function useStableOrder<T>(items: T[], getKey: (item: T) => string): T[] {
+  const keys = Array.from(new Set(items.map(getKey)));
+  const order = useRef<string[]>([]);
+  const current = new Set(keys);
+  const next = [...order.current.filter(key => current.has(key)), ...keys.filter(key => !order.current.includes(key))];
+  if (!sameOrder(order.current, next)) {
+    order.current = next;
+  }
+  const ordered = order.current;
+
+  return useMemo(() => {
+    const byKey = new Map<string, T>();
+    for (const item of items) {
+      const key = getKey(item);
+      if (!byKey.has(key)) {
+        byKey.set(key, item);
+      }
+    }
+    return ordered.flatMap(key => {
+      const item = byKey.get(key);
+      return item === undefined ? [] : [item];
+    });
+  }, [items, getKey, ordered]);
+}
diff --git a/packages/swingset/src/stories/user-profile-account-section.mdx b/packages/swingset/src/stories/user-profile-account-section.mdx
index ee41391ae5d..ca35f332110 100644
--- a/packages/swingset/src/stories/user-profile-account-section.mdx
+++ b/packages/swingset/src/stories/user-profile-account-section.mdx
@@ -33,6 +33,7 @@ the verified address.
     { name: 'Avatar', href: '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/components/avatar', layer: 'Components' },
     { name: 'Button', href: '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/components/button', layer: 'Components' },
     { name: 'Badge', href: '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/components/badge', layer: 'Components' },
+    { name: 'Spinner', href: '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/components/spinner', layer: 'Components' },
     { name: 'Icon', href: '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/components/icon', layer: 'Components' },
     { name: 'Dialog', href: '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/components/dialog', layer: 'Components' },
     { name: 'Card', href: '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/components/card', layer: 'Components' },
@@ -51,6 +52,20 @@ action. The connection's logo leads the label, or a generic lock when it ships n
   storyModule={Stories}
 />
 
+## Motion
+
+A new email address or phone number expands into the list and a removed one collapses out of it,
+each fading at its bottom edge. The list keeps the order it was first shown in, so setting a primary
+moves the badge between rows rather than the rows themselves. **Set as primary** resolves after a
+short simulated request; when the request outlasts a short delay, a spinner shows where the badge
+will land, and the badge waits for the spinner to go.
+
+## Set primary pending
+
+Setting a primary takes a few seconds here, so the pending spinner is easy to see.
+
+<Story name='SetPrimaryPending' storyModule={Stories} />
+
 ## Add phone failure
 
 Add a phone number to see a failed send request while keeping the entered number.
diff --git a/packages/swingset/src/stories/user-profile-account-section.stories.tsx b/packages/swingset/src/stories/user-profile-account-section.stories.tsx
index 407cae0a6f8..69715e01aff 100644
--- a/packages/swingset/src/stories/user-profile-account-section.stories.tsx
+++ b/packages/swingset/src/stories/user-profile-account-section.stories.tsx
@@ -22,6 +22,10 @@ import { useUserProfileVerifyEmailSsoFixture } from './fixtures/user-profile-ver
 
 export { default as __source } from './user-profile-account-section.stories?raw';
 
+function primaryFirst<T extends { isDefault?: boolean }>(items: T[]): T[] {
+  return [...items.filter(item => item.isDefault), ...items.filter(item => !item.isDefault)];
+}
+
 export const meta: StoryMeta = {
   group: 'User Profile',
   status: 'wip',
@@ -41,6 +45,7 @@ function AccountSection({
   emailRemovalState,
   phoneRemovalState,
   nameManagedBy,
+  setPrimaryDelay = 700,
 }: {
   allowMultipleAccounts: boolean;
   failAt?: UserProfileAddPhoneDialogProps['step'];
@@ -50,6 +55,7 @@ function AccountSection({
   emailRemovalState?: 'pending' | 'error';
   phoneRemovalState?: 'pending' | 'error';
   nameManagedBy?: { name: string };
+  setPrimaryDelay?: number;
 }) {
   const [phoneRemovalFailed, setPhoneRemovalFailed] = useState(false);
   const [emailRemovalFailed, setEmailRemovalFailed] = useState(false);
@@ -60,6 +66,9 @@ function AccountSection({
       ? [
           { id: 'email_1', value: 'item1@clerk.dev', isDefault: true, isVerified: true },
           { id: 'email_2', value: 'item2@clerk.dev', isVerified: true },
+          { id: 'email_3', value: 'item3@clerk.dev', isVerified: true },
+          { id: 'email_4', value: 'item4@clerk.dev', isVerified: true },
+          { id: 'email_5', value: 'item5@clerk.dev', isVerified: true },
         ]
       : [{ id: 'email_1', value: 'item1@clerk.dev', isDefault: true, isVerified: true }],
   );
@@ -104,7 +113,10 @@ function AccountSection({
         }
         setEmails(current => current.filter(email => email.id !== id));
       }}
-      onSetPrimaryEmail={id => setEmails(current => current.map(email => ({ ...email, isDefault: email.id === id })))}
+      onSetPrimaryEmail={async id => {
+        await new Promise(resolve => setTimeout(resolve, setPrimaryDelay));
+        setEmails(current => primaryFirst(current.map(email => ({ ...email, isDefault: email.id === id }))));
+      }}
       onRemovePhone={async id => {
         if (phoneRemovalState === 'pending') {
           await new Promise(resolve => setTimeout(resolve, 1500));
@@ -115,7 +127,10 @@ function AccountSection({
         }
         setPhones(current => current.filter(phone => phone.id !== id));
       }}
-      onSetPrimaryPhone={id => setPhones(current => current.map(phone => ({ ...phone, isDefault: phone.id === id })))}
+      onSetPrimaryPhone={async id => {
+        await new Promise(resolve => setTimeout(resolve, setPrimaryDelay));
+        setPhones(current => primaryFirst(current.map(phone => ({ ...phone, isDefault: phone.id === id }))));
+      }}
     />
   );
 }
@@ -141,6 +156,15 @@ export function MultipleAccounts() {
   return <AccountSection allowMultipleAccounts />;
 }
 
+export function SetPrimaryPending() {
+  return (
+    <AccountSection
+      allowMultipleAccounts
+      setPrimaryDelay={2500}
+    />
+  );
+}
+
 export function AddEmailFails() {
   return (
     <AccountSection

From 68fac27966acaa920dda0a06b963d36f9abcd485 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 17:26:11 -0600
Subject: [PATCH 2/5] test(mosaic): restore the email focus tests dropped from
 the account section

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../user-profile-email-actions.test.tsx       | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx b/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx
index 7478d45c4b0..e44efc74dbd 100644
--- a/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx
+++ b/packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx
@@ -105,6 +105,54 @@ describe('email actions', () => {
     expect(order()).toEqual(['Manage first@example.com', 'Manage second@example.com']);
   });
 
+  it('returns focus to the email menu after opening with the keyboard and canceling with Escape', async () => {
+    const user = userEvent.setup();
+    const onRemoveEmail = vi.fn();
+    renderEmail({ onRemoveEmail });
+    const trigger = screen.getByRole('button', { name: 'Manage test@example.com' });
+
+    trigger.focus();
+    await user.keyboard('{Enter}');
+    await user.keyboard('{Enter}');
+    expect(screen.getByRole('alertdialog', { name: 'Remove email address?' })).toBeInTheDocument();
+
+    await user.keyboard('{Escape}');
+
+    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());
+    expect(onRemoveEmail).not.toHaveBeenCalled();
+    await waitFor(() => expect(trigger).toHaveFocus());
+  });
+
+  it('focuses Add email after removing the last email', async () => {
+    const user = userEvent.setup();
+    function Example() {
+      const [emails, setEmails] = useState([{ id: 'email_1', value: 'test@example.com', isVerified: true }]);
+      return (
+        <MosaicProvider>
+          <UserProfileAccountSectionView
+            allowMultipleAccounts
+            name='Test'
+            username='test'
+            phones={[]}
+            emails={emails}
+            onSendEmailCode={() => Promise.resolve()}
+            onVerifyEmailCode={() => Promise.resolve()}
+            onRemoveEmail={id => setEmails(current => current.filter(email => email.id !== id))}
+          />
+        </MosaicProvider>
+      );
+    }
+    render(<Example />);
+    await user.click(screen.getByRole('button', { name: 'Manage test@example.com' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Remove email' }));
+    await user.click(within(screen.getByRole('alertdialog')).getByRole('button', { name: 'Remove' }));
+
+    await waitFor(() => expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());
+    expect(screen.queryByRole('button', { name: 'Manage test@example.com' })).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Add email' })).toBeEnabled();
+    await waitFor(() => expect(screen.getByRole('button', { name: 'Add email' })).toHaveFocus());
+  });
+
   it('shows a primary update error without opening a dialog', async () => {
     const user = userEvent.setup();
     const onSetPrimaryEmail = vi.fn().mockRejectedValue(new Error('Unable to update primary email.'));

From 7edf4407df707c90420669174a681eaf48558883 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 17:40:19 -0600
Subject: [PATCH 3/5] fix(mosaic): keep first-load contact rows still and the
 first row unbordered

A row locks in whether it animates when it first mounts, so a re-render
before the first frame no longer hands first-load rows their entering
state. A row draws its top border only when an open slot precedes it,
so the first row has none under the card's edge.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/mosaic/docs/motion.md                | 13 ++++++----
 packages/mosaic/eslint-suppressions.json      | 12 +--------
 ...ser-profile-contact-list-row.view.test.tsx | 26 +++++++++++++++++++
 ...-profile-account-section.markers.stylex.ts |  1 +
 .../user-profile-account-section.styles.ts    | 10 +++----
 .../user-profile-contact-list-row.view.tsx    | 18 +++++++++----
 6 files changed, 54 insertions(+), 26 deletions(-)

diff --git a/packages/mosaic/docs/motion.md b/packages/mosaic/docs/motion.md
index cf32a4c75c6..1102b01ed50 100644
--- a/packages/mosaic/docs/motion.md
+++ b/packages/mosaic/docs/motion.md
@@ -302,11 +302,14 @@ the recipe for a `<ul>` whose rows come and go. What differs from the banner:
   the first frame to the last in both directions; the moving edge is the bottom one,
   under a static `mask-image` the height of the row's bottom padding less the focus
   ring's extent, so at rest it touches neither the text nor a focused trigger's
-  outline. Every row carries its 1px border and the body's own top border is zeroed
-  for this list, so the first row's border is the header divider: when it exits, its
-  border leaves with its track and the next row's lands in the same place, rather
-  than two borders meeting and one snapping away. `Section.Item`'s sibling-marker
-  rule cannot see across the slots, so the border is the row's own.
+  outline. A row draws its border only when an open slot precedes it: the first row
+  has none under the card's own edge, and when a row starts closing the row below it
+  drops its line at once rather than meeting the card border and snapping away when
+  the closed row unmounts. `Section.Item`'s sibling-marker rule cannot see across
+  the slots, so the rule is keyed on the slot.
+- **Rows that are already there never enter.** A row locks in whether it animates
+  when it first mounts: rows present at the list's first render skip the entering
+  state, and a re-render before the first frame must not hand it back to them.
 - **The content fade lives on the row's children** (a marker on the row,
   `stylex.when.ancestor` on `Section.Content` and `Section.Actions`), never on the
   row itself: opacity on the row would fade its border too. Inline text takes opacity
diff --git a/packages/mosaic/eslint-suppressions.json b/packages/mosaic/eslint-suppressions.json
index e14b2d4adb6..1d6200f3a81 100644
--- a/packages/mosaic/eslint-suppressions.json
+++ b/packages/mosaic/eslint-suppressions.json
@@ -49,16 +49,6 @@
       "count": 1
     }
   },
-  "src/features/user-profile/user-profile-account-section/user-profile-email-row.view.tsx": {
-    "sonarjs/cognitive-complexity": {
-      "count": 1
-    }
-  },
-  "src/features/user-profile/user-profile-active-devices-section.view.tsx": {
-    "sonarjs/cognitive-complexity": {
-      "count": 1
-    }
-  },
   "src/features/user-profile/user-profile-active-devices-section/user-profile-active-devices-section.model.ts": {
     "@typescript-eslint/no-restricted-imports": {
       "count": 1
@@ -157,4 +147,4 @@
       "count": 1
     }
   }
-}
+}
\ No newline at end of file
diff --git a/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx b/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
index 717a25f4e28..4fb4605b7e6 100644
--- a/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
+++ b/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
@@ -68,6 +68,32 @@ describe('UserProfileContactListRowView', () => {
     expect(row?.closest('li')).not.toHaveAttribute('data-starting-style');
   });
 
+  it('keeps first-load rows out of the entering state when the list re-renders before the first frame', () => {
+    const items = [{ id: 'contact_1', value: 'first@example.com', isDefault: true }];
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items}
+        pendingId='none'
+      />,
+    );
+
+    const row = screen.getByText('first@example.com').closest('.cl-section-item');
+    expect(row).not.toHaveAttribute('data-starting-style');
+    expect(row?.closest('li')).not.toHaveAttribute('data-starting-style');
+    expect(row?.closest('li')).not.toHaveAttribute('style');
+    expect(screen.getByText('Primary').closest('.cl-badge')).not.toHaveAttribute('data-starting-style');
+  });
+
   it('renders a first-load primary badge without an entering state', () => {
     render(
       <UserProfileContactListRowView
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts
index 868f8e0945e..5b857bffd03 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts
@@ -1,3 +1,4 @@
 import * as stylex from '@stylexjs/stylex';
 
+export const contactSlotMarker = stylex.defineMarker();
 export const contactItemMarker = stylex.defineMarker();
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
index c58bffb4fea..863cf2c60ff 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
@@ -1,14 +1,11 @@
 import * as stylex from '@stylexjs/stylex';
 
 import { durationVars, easingVars, focusVars, space } from '../../../tokens.stylex';
-import { contactItemMarker } from './user-profile-account-section.markers.stylex';
+import { contactItemMarker, contactSlotMarker } from './user-profile-account-section.markers.stylex';
 
 const ring = `calc(${focusVars['--cl-focus-outline-width']} + ${focusVars['--cl-focus-outline-offset']})`;
 
 export const styles = stylex.create({
-  contactBody: {
-    borderBlockStartWidth: '0px',
-  },
   contactSlot: {
     display: 'grid',
     gridTemplateRows: {
@@ -35,7 +32,10 @@ export const styles = stylex.create({
     minHeight: 0,
   },
   contactItem: {
-    borderBlockStartWidth: '1px',
+    borderBlockStartWidth: {
+      default: '0px',
+      [stylex.when.ancestor(':where([data-open] ~ *)', contactSlotMarker)]: '1px',
+    },
   },
   contactFade: {
     opacity: {
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
index 89824eedc7c..12a21f34b94 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
@@ -16,7 +16,7 @@ import { usePresenceList, useTransition } from '../../../primitives/hooks';
 import { reset } from '../../../styles/reset.styles';
 import { truncationStyles } from '../../../styles/typography.styles';
 import { styles as panelStyles } from '../user-profile-profile-panel.styles';
-import { contactItemMarker } from './user-profile-account-section.markers.stylex';
+import { contactItemMarker, contactSlotMarker } from './user-profile-account-section.markers.stylex';
 import { badgeShift, styles } from './user-profile-account-section.styles';
 
 export interface UserProfileContactListRowViewProps {
@@ -53,13 +53,17 @@ function SlotItem({
   children: (ref: Ref<HTMLSpanElement>, props: TransitionProps) => ReactNode;
 }) {
   const element = useRef<HTMLSpanElement>(null);
+  const entrance = useRef<boolean | null>(null);
   const { mounted, transitionProps } = useTransition({ open, ref: element });
+  if (mounted && entrance.current === null) {
+    entrance.current = appear;
+  }
 
   if (!mounted) {
     return null;
   }
 
-  return children(element, withoutEntrance(transitionProps, appear));
+  return children(element, withoutEntrance(transitionProps, entrance.current ?? appear));
 }
 
 function ContactListItem({
@@ -78,7 +82,11 @@ function ContactListItem({
   children: ReactNode;
 }) {
   const element = useRef<HTMLLIElement>(null);
+  const entrance = useRef<boolean | null>(null);
   const { mounted, transitionProps } = useTransition({ open: present, ref: element });
+  if (mounted && entrance.current === null) {
+    entrance.current = appear;
+  }
 
   useEffect(() => {
     if (!mounted) {
@@ -90,14 +98,14 @@ function ContactListItem({
     return null;
   }
 
-  const slotProps = withoutEntrance(transitionProps, appear);
+  const slotProps = withoutEntrance(transitionProps, entrance.current ?? appear);
   const rowProps = { ...slotProps, style: undefined };
 
   return (
     <li
       ref={element}
       aria-hidden={present ? undefined : true}
-      {...stylex.props(reset.base, styles.contactSlot)}
+      {...stylex.props(reset.base, styles.contactSlot, contactSlotMarker)}
       {...slotProps}
       {...inertProps(!present)}
     >
@@ -176,7 +184,7 @@ export function UserProfileContactListRowView({
           </Section.Actions>
         ) : null}
       </Section.Header>
-      <Section.Body xstyle={styles.contactBody}>
+      <Section.Body>
         <Section.Items>
           {entries.map(({ key, item, present, onExited }) => {
             const actions: ActionMenuAction[] = [];

From acebe12d098dd18598970fc66cb1e72c32486a30 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 18:01:59 -0600
Subject: [PATCH 4/5] feat(mosaic): carry the empty state inside the last
 contact row

The empty text is no longer its own animated row. Each slot keeps an
auto track above the row's track; when a row is the last one that track
holds the empty text, so removing the last row collapses the slot to the
empty row's height while the row fades out and the empty text fades in,
and adding the first row plays the reverse. A static empty row takes
over at rest.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 packages/mosaic/docs/motion.md                | 11 +++++++
 ...ser-profile-contact-list-row.view.test.tsx | 27 ++++++++++-----
 .../user-profile-account-section.styles.ts    | 32 ++++++++++++++++--
 .../user-profile-contact-list-row.view.tsx    | 33 +++++++++++++++----
 4 files changed, 87 insertions(+), 16 deletions(-)

diff --git a/packages/mosaic/docs/motion.md b/packages/mosaic/docs/motion.md
index 1102b01ed50..e47bce83d74 100644
--- a/packages/mosaic/docs/motion.md
+++ b/packages/mosaic/docs/motion.md
@@ -321,6 +321,17 @@ the recipe for a `<ul>` whose rows come and go. What differs from the banner:
   `useTransition` then unmounts an exiting row as soon as it finds nothing to wait
   for.
 
+- **The empty state rides the last row.** Two slots cannot be made to start in the
+  same frame, so the empty text is not its own animated row. Every slot has an
+  `auto` track above the row's `1fr` track; when a row is the last one, that track
+  holds the empty text (`aria-hidden`, opacity 0 under the row), so the slot's
+  collapse stops at the empty text's height instead of zero and one track carries
+  the whole change: the height moves from the row's to the empty row's, the row's
+  content fades out at `fast`, and the empty text fades in after `base + fast`. Once
+  the exit ends, a static empty row with no transitions takes its place at the same
+  size. The first row added plays this in reverse: its slot mounts at the empty
+  text's height with that text visible, which fades out at `fast` as the track opens.
+
 **Rows do not reorder.** While the list is mounted it keeps the order it was first
 shown in (`useStableOrder`): a new row is appended, a removed row drops out, and a
 row the model now sorts elsewhere stays put. Setting a primary therefore moves the
diff --git a/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx b/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
index 4fb4605b7e6..da49e7b0167 100644
--- a/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
+++ b/packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx
@@ -129,8 +129,7 @@ describe('UserProfileContactListRowView', () => {
     expect(row?.closest('li')).toHaveAttribute('data-starting-style');
   });
 
-  it('collapses the empty state when the first item is added', () => {
-    holdExits();
+  it('carries the empty text inside the first item as it enters', () => {
     const { rerender } = render(
       <UserProfileContactListRowView
         kind='email'
@@ -138,6 +137,7 @@ describe('UserProfileContactListRowView', () => {
         items={[]}
       />,
     );
+    expect(screen.getByText('No email addresses added').closest('li')).not.toHaveAttribute('data-open');
 
     rerender(
       <UserProfileContactListRowView
@@ -147,8 +147,10 @@ describe('UserProfileContactListRowView', () => {
       />,
     );
 
-    expect(screen.getByText('No email addresses added').closest('li')).toHaveAttribute('data-ending-style');
-    expect(screen.getByText('first@example.com')).toBeInTheDocument();
+    const slot = screen.getByText('first@example.com').closest('li');
+    expect(slot).toHaveAttribute('data-starting-style');
+    expect(screen.getAllByText('No email addresses added')).toHaveLength(1);
+    expect(screen.getByText('No email addresses added').closest('li')).toBe(slot);
   });
 
   it('keeps a removed item inert in place until its exit finishes', async () => {
@@ -188,8 +190,8 @@ describe('UserProfileContactListRowView', () => {
     expect(screen.queryByText('second@example.com')).not.toBeInTheDocument();
   });
 
-  it('shows the empty state while the last item exits', () => {
-    holdExits();
+  it('carries the empty text inside the last item while it exits, then shows it at rest', async () => {
+    const exit = holdExits();
     const { rerender } = render(
       <UserProfileContactListRowView
         kind='phone'
@@ -206,8 +208,17 @@ describe('UserProfileContactListRowView', () => {
       />,
     );
 
-    expect(screen.getByText('+1 (801) 555-0100').closest('li')).toHaveAttribute('data-ending-style');
-    expect(screen.getByText('No phone numbers added')).toBeInTheDocument();
+    const slot = screen.getByText('+1 (801) 555-0100').closest('li');
+    expect(slot).toHaveAttribute('data-ending-style');
+    expect(screen.getAllByText('No phone numbers added')).toHaveLength(1);
+    expect(screen.getByText('No phone numbers added').closest('li')).toBe(slot);
+
+    await act(async () => {
+      exit.resolve();
+      await exit.promise;
+    });
+    expect(screen.queryByText('+1 (801) 555-0100')).not.toBeInTheDocument();
+    expect(screen.getByText('No phone numbers added').closest('li')).not.toHaveAttribute('data-ending-style');
   });
 
   it('transitions the primary badge out when another item becomes primary', () => {
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
index 863cf2c60ff..f141beeffb9 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
@@ -9,8 +9,8 @@ export const styles = stylex.create({
   contactSlot: {
     display: 'grid',
     gridTemplateRows: {
-      default: '1fr',
-      ':where([data-starting-style], [data-ending-style])': '0fr',
+      default: 'auto 1fr',
+      ':where([data-starting-style], [data-ending-style])': 'auto 0fr',
     },
     transitionDelay: durationVars['--cl-duration-base'],
     transitionDuration: durationVars['--cl-duration-slower'],
@@ -31,6 +31,34 @@ export const styles = stylex.create({
     maskImage: `linear-gradient(to top, transparent, black calc(${space['4']} - ${ring}))`,
     minHeight: 0,
   },
+  contactEmpty: {
+    gridRowStart: '1',
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactSlotMarker)]: 1,
+      '@media (prefers-reduced-motion: reduce)': {
+        default: 0,
+        [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactSlotMarker)]: 1,
+      },
+    },
+    transitionDelay: {
+      default: durationVars['--cl-duration-instant'],
+      [stylex.when.ancestor(':where([data-ending-style])', contactSlotMarker)]:
+        `calc(${durationVars['--cl-duration-base']} + ${durationVars['--cl-duration-fast']})`,
+    },
+    transitionDuration: {
+      default: durationVars['--cl-duration-fast'],
+      [stylex.when.ancestor(':where([data-ending-style])', contactSlotMarker)]: durationVars['--cl-duration-base'],
+    },
+    transitionProperty: {
+      default: 'opacity',
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    transitionTimingFunction: {
+      default: easingVars['--cl-ease-exit'],
+      [stylex.when.ancestor(':where([data-ending-style])', contactSlotMarker)]: easingVars['--cl-ease-enter'],
+    },
+  },
   contactItem: {
     borderBlockStartWidth: {
       default: '0px',
diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
index 12a21f34b94..00815edbebe 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-contact-list-row.view.tsx
@@ -70,6 +70,7 @@ function ContactListItem({
   present = true,
   appear,
   pending = false,
+  emptyText,
   onExited,
   actions,
   children,
@@ -77,6 +78,7 @@ function ContactListItem({
   present?: boolean;
   appear: boolean;
   pending?: boolean;
+  emptyText?: string;
   onExited?: () => void;
   actions?: ReactNode;
   children: ReactNode;
@@ -109,6 +111,15 @@ function ContactListItem({
       {...slotProps}
       {...inertProps(!present)}
     >
+      {emptyText ? (
+        <Section.Item
+          render={<div />}
+          aria-hidden
+          xstyle={styles.contactEmpty}
+        >
+          <Section.Description>{emptyText}</Section.Description>
+        </Section.Item>
+      ) : null}
       <div {...stylex.props(styles.contactClip)}>
         <Section.Item
           render={<div />}
@@ -187,6 +198,7 @@ export function UserProfileContactListRowView({
       <Section.Body>
         <Section.Items>
           {entries.map(({ key, item, present, onExited }) => {
+            const terminal = items.length === 0 || (present && items.length === 1);
             const actions: ActionMenuAction[] = [];
 
             if (item.isVerified === false && onVerify) {
@@ -212,6 +224,7 @@ export function UserProfileContactListRowView({
                 present={present}
                 appear={appear}
                 pending={pendingId === item.id || shownPendingId === item.id}
+                emptyText={terminal ? m[kind].empty : undefined}
                 onExited={onExited}
                 actions={
                   actions.length > 0 ? (
@@ -262,12 +275,20 @@ export function UserProfileContactListRowView({
               </ContactListItem>
             );
           })}
-          <ContactListItem
-            present={items.length === 0}
-            appear={appear}
-          >
-            <Section.Description>{m[kind].empty}</Section.Description>
-          </ContactListItem>
+          {items.length === 0 && entries.length === 0 ? (
+            <li {...stylex.props(reset.base, styles.contactSlot, contactSlotMarker)}>
+              <div {...stylex.props(styles.contactClip)}>
+                <Section.Item
+                  render={<div />}
+                  xstyle={[styles.contactItem, contactItemMarker]}
+                >
+                  <Section.Content>
+                    <Section.Description>{m[kind].empty}</Section.Description>
+                  </Section.Content>
+                </Section.Item>
+              </div>
+            </li>
+          ) : null}
         </Section.Items>
         {children}
       </Section.Body>

From 5e4422f11c6ed3d89c3b2d31a75f713ee8e797f4 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 8 Oct 2026 18:06:38 -0600
Subject: [PATCH 5/5] fix(mosaic): keep the last contact row's clip in the
 slot's first column

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../user-profile-account-section.styles.ts                      | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
index f141beeffb9..990c9600e90 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts
@@ -26,12 +26,14 @@ export const styles = stylex.create({
     paddingInline: ring,
     alignContent: 'start',
     display: 'grid',
+    gridColumnStart: '1',
     gridRowEnd: 'span 2',
     gridRowStart: '1',
     maskImage: `linear-gradient(to top, transparent, black calc(${space['4']} - ${ring}))`,
     minHeight: 0,
   },
   contactEmpty: {
+    gridColumnStart: '1',
     gridRowStart: '1',
     opacity: {
       default: 0,