From 1ebb2983ee7b1b03562b6b60aead4b63249bfe6c Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 1 Oct 2026 16:33:18 -0600
Subject: [PATCH 01/14] feat(mosaic): add section skeletons with a page-wide
 loading wave

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/section-skeletons.md               |  2 +
 .../src/components/section/section.styles.ts  | 10 +-
 .../mosaic/src/components/section/section.tsx | 93 +++++++++++++------
 ...er-profile-active-devices-section.view.tsx | 36 +++++++
 .../user-profile-active-devices.messages.ts   |  1 +
 .../user-profile-security-icon.tsx            |  6 +-
 packages/mosaic/src/hooks/useSkeletonWave.ts  | 27 ++++++
 packages/mosaic/src/utils/skeleton.styles.ts  | 35 +++++++
 .../swingset/src/components/StoryEmbed.tsx    |  8 +-
 .../swingset/src/components/StoryPreview.tsx  |  3 +-
 packages/swingset/src/lib/utils.ts            |  6 ++
 packages/swingset/src/stories/section.mdx     | 13 +++
 .../swingset/src/stories/section.stories.tsx  | 73 +++++++++++++++
 .../user-profile-active-devices-section.mdx   |  7 ++
 ...profile-active-devices-section.stories.tsx |  9 +-
 15 files changed, 293 insertions(+), 36 deletions(-)
 create mode 100644 .changeset/section-skeletons.md
 create mode 100644 packages/mosaic/src/hooks/useSkeletonWave.ts
 create mode 100644 packages/mosaic/src/utils/skeleton.styles.ts

diff --git a/.changeset/section-skeletons.md b/.changeset/section-skeletons.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/section-skeletons.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/mosaic/src/components/section/section.styles.ts b/packages/mosaic/src/components/section/section.styles.ts
index 3cfef0569b5..8bdbe06a3d6 100644
--- a/packages/mosaic/src/components/section/section.styles.ts
+++ b/packages/mosaic/src/components/section/section.styles.ts
@@ -135,7 +135,6 @@ export const styles = stylex.create({
     flexDirection: 'column',
     flexGrow: 1,
     justifyContent: 'center',
-    rowGap: space['0.5'],
     minWidth: 0,
   },
   label: {
@@ -144,6 +143,15 @@ export const styles = stylex.create({
     fontWeight: fontWeightVars['--cl-font-medium'],
     lineHeight: typeScaleVars['--cl-text-sm-leading'],
   },
+  titleSkeleton: {
+    width: space['32'],
+  },
+  labelSkeleton: {
+    width: space['24'],
+  },
+  descriptionSkeleton: {
+    width: space['40'],
+  },
   description: {
     color: colorVars['--cl-color-foreground-secondary'],
     fontSize: typeScaleVars['--cl-text-sm-size'],
diff --git a/packages/mosaic/src/components/section/section.tsx b/packages/mosaic/src/components/section/section.tsx
index 4baeeca3ee7..226d91d15db 100644
--- a/packages/mosaic/src/components/section/section.tsx
+++ b/packages/mosaic/src/components/section/section.tsx
@@ -1,7 +1,9 @@
 import { useSafeLayoutEffect } from '@clerk/shared/react';
+import { useMergeRefs } from '@floating-ui/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import { useSkeletonWave } from '../../hooks/useSkeletonWave';
 import { useTransition } from '../../primitives/hooks/use-transition';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps } from '../../props';
@@ -9,6 +11,7 @@ import { mergeStyleProps, themeProps } from '../../props';
 import { FeedbackBody, hasMessage, useHeldMessage, useMessageHeight } from '../../utils/feedback';
 import { feedbackHeight, feedbackStyles } from '../../utils/feedback.styles';
 import { reset } from '../../utils/reset.styles';
+import { skeletonStyles } from '../../utils/skeleton.styles';
 import { sizes as typographySizes, styles as typographyStyles } from '../../utils/typography.styles';
 import type { HeadingProps } from '../heading';
 import { Heading, useHeadingLevel } from '../heading';
@@ -16,18 +19,18 @@ import { sectionHeaderDescriptionMarker, sectionHeaderMarker, sectionNestedItemM
 import { styles } from './section.styles';
 
 export type SectionRootProps = Omit<MosaicComponentProps<'section'>, 'title'>;
-export type SectionGroupProps = MosaicComponentProps<'div'>;
+export type SectionGroupProps = MosaicComponentProps<'div'> & { skeleton?: boolean };
 export type SectionHeaderProps = MosaicComponentProps<'div'>;
-export type SectionTitleProps = Omit<HeadingProps, 'size'>;
+export type SectionTitleProps = Omit<HeadingProps, 'size'> & { skeleton?: boolean };
 export type SectionBodyProps = MosaicComponentProps<'div'>;
 export type SectionRowProps = MosaicComponentProps<'div'>;
 export type SectionItemsProps = MosaicComponentProps<'ul'>;
 export type SectionItemProps = MosaicComponentProps<'div'> & { wrap?: boolean };
 export type SectionMediaSize = 'sm' | 'md' | 'lg' | 'xl';
-export type SectionMediaProps = MosaicComponentProps<'div'> & { size?: SectionMediaSize };
+export type SectionMediaProps = MosaicComponentProps<'div'> & { size?: SectionMediaSize; skeleton?: boolean };
 export type SectionContentProps = MosaicComponentProps<'div'>;
-export type SectionLabelProps = MosaicComponentProps<'div'>;
-export type SectionDescriptionProps = MosaicComponentProps<'div'>;
+export type SectionLabelProps = MosaicComponentProps<'div'> & { skeleton?: boolean };
+export type SectionDescriptionProps = MosaicComponentProps<'div'> & { skeleton?: boolean };
 export type SectionActionsProps = MosaicComponentProps<'div'>;
 export type SectionErrorProps = MosaicComponentProps<'p'>;
 
@@ -53,7 +56,7 @@ const Root = React.forwardRef<HTMLElement, SectionRootProps>(function SectionRoo
 });
 
 const Group = React.forwardRef<HTMLDivElement, SectionGroupProps>(function SectionGroup(
-  { render, xstyle, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...rest },
+  { skeleton = false, render, xstyle, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...rest },
   ref,
 ) {
   const [titleId, setTitleId] = React.useState<string>();
@@ -62,12 +65,21 @@ const Group = React.forwardRef<HTMLDivElement, SectionGroupProps>(function Secti
     defaultTagName: 'div',
     render,
     ref,
-    props: {
-      role: 'group',
-      ...mergeStyleProps(themeProps('section-group'), stylex.props(reset.base, styles.group, xstyle), rest),
-      'aria-label': ariaLabel,
-      'aria-labelledby': ariaLabelledBy ?? (ariaLabel ? undefined : titleId),
-    },
+    props: skeleton
+      ? {
+          'aria-hidden': true,
+          ...mergeStyleProps(
+            themeProps('section-group', { skeleton }),
+            stylex.props(reset.base, styles.group, xstyle),
+            rest,
+          ),
+        }
+      : {
+          role: 'group',
+          ...mergeStyleProps(themeProps('section-group'), stylex.props(reset.base, styles.group, xstyle), rest),
+          'aria-label': ariaLabel,
+          'aria-labelledby': ariaLabelledBy ?? (ariaLabel ? undefined : titleId),
+        },
   });
 
   return <SectionGroupContext.Provider value={setTitleId}>{element}</SectionGroupContext.Provider>;
@@ -94,13 +106,15 @@ const Header = React.forwardRef<HTMLDivElement, SectionHeaderProps>(function Sec
 });
 
 const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function SectionTitle(
-  { id: idProp, xstyle, ...rest },
+  { id: idProp, skeleton = false, xstyle, ...rest },
   ref,
 ) {
   const setTitleId = React.useContext(SectionGroupContext);
   const generatedId = React.useId();
   const level = useHeadingLevel();
-  const id = idProp ?? (setTitleId ? `cl-section-${generatedId}-title` : undefined);
+  const wave = useSkeletonWave<HTMLHeadingElement>(skeleton);
+  const mergedRef = useMergeRefs([ref, wave]);
+  const id = skeleton ? undefined : (idProp ?? (setTitleId ? `cl-section-${generatedId}-title` : undefined));
 
   useSafeLayoutEffect(() => {
     if (!id || !setTitleId) {
@@ -113,12 +127,18 @@ const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function S
 
   return (
     <Heading
-      ref={ref}
+      ref={mergedRef}
       id={id}
       level={level}
       size='base'
-      xstyle={[styles.title, xstyle]}
-      {...mergeStyleProps(themeProps('section-title'), rest)}
+      xstyle={[
+        styles.title,
+        skeleton && skeletonStyles.bone,
+        skeleton && skeletonStyles.line,
+        skeleton && styles.titleSkeleton,
+        xstyle,
+      ]}
+      {...mergeStyleProps(themeProps('section-title', { skeleton }), rest)}
     />
   );
 });
@@ -183,16 +203,18 @@ const Item = React.forwardRef<HTMLDivElement, SectionItemProps>(function Section
 });
 
 const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function SectionMedia(
-  { size = 'md', render, xstyle, ...rest },
+  { size = 'md', skeleton = false, render, xstyle, ...rest },
   ref,
 ) {
+  const wave = useSkeletonWave<HTMLDivElement>(skeleton);
+
   return useRender({
     defaultTagName: 'div',
     render,
-    ref,
+    ref: [ref, wave],
     props: mergeStyleProps(
-      themeProps('section-media', { size }),
-      stylex.props(reset.base, styles.mediaBase, mediaSizes[size], xstyle),
+      themeProps('section-media', { size, skeleton }),
+      stylex.props(reset.base, styles.mediaBase, mediaSizes[size], skeleton && skeletonStyles.bone, xstyle),
       rest,
     ),
   });
@@ -217,34 +239,51 @@ const Content = React.forwardRef<HTMLDivElement, SectionContentProps>(function S
 });
 
 const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function SectionLabel(
-  { render, xstyle, ...rest },
+  { skeleton = false, render, xstyle, ...rest },
   ref,
 ) {
+  const wave = useSkeletonWave<HTMLDivElement>(skeleton);
+
   return useRender({
     defaultTagName: 'div',
     render,
-    ref,
-    props: mergeStyleProps(themeProps('section-label'), stylex.props(reset.base, styles.label, xstyle), rest),
+    ref: [ref, wave],
+    props: mergeStyleProps(
+      themeProps('section-label', { skeleton }),
+      stylex.props(
+        reset.base,
+        styles.label,
+        skeleton && skeletonStyles.bone,
+        skeleton && skeletonStyles.line,
+        skeleton && styles.labelSkeleton,
+        xstyle,
+      ),
+      rest,
+    ),
   });
 });
 
 const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(function SectionDescription(
-  { render, xstyle, ...rest },
+  { skeleton = false, render, xstyle, ...rest },
   ref,
 ) {
   const inHeader = React.useContext(SectionHeaderContext);
+  const wave = useSkeletonWave<HTMLDivElement>(skeleton);
 
   return useRender({
     defaultTagName: 'div',
     render,
-    ref,
+    ref: [ref, wave],
     props: mergeStyleProps(
-      themeProps('section-description'),
+      themeProps('section-description', { skeleton }),
       stylex.props(
         reset.base,
         styles.description,
         inHeader && styles.headerDescription,
         inHeader && sectionHeaderDescriptionMarker,
+        skeleton && skeletonStyles.bone,
+        skeleton && skeletonStyles.line,
+        skeleton && styles.descriptionSkeleton,
         xstyle,
       ),
       rest,
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
index f2f3325ca58..3e743879fda 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
@@ -9,6 +9,7 @@ import { Badge } from '../../components/badge';
 import { Button } from '../../components/button';
 import { Dialog } from '../../components/dialog';
 import { Section } from '../../components/section';
+import { VisuallyHidden } from '../../components/visually-hidden';
 import { useListRemovalFocus } from '../../hooks/useListRemovalFocus';
 import type { MosaicMessages } from '../../localization';
 import { fill, plural, useLocale, useMessages } from '../../localization';
@@ -174,6 +175,41 @@ export function UserProfileActiveDevicesSectionView({
   );
 }
 
+const SKELETON_ITEMS = [0, 1, 2];
+
+export function UserProfileActiveDevicesSectionSkeleton() {
+  const m = useMessages('userProfileActiveDevices');
+
+  return (
+    <div {...stylex.props(styles.sectionCards)}>
+      <VisuallyHidden role='status'>{m.loading}</VisuallyHidden>
+      <Section.Root>
+        <Section.Group skeleton>
+          <Section.Header>
+            <Section.Title skeleton />
+          </Section.Header>
+          <Section.Body>
+            <Section.Items>
+              {SKELETON_ITEMS.map(item => (
+                <Section.Item key={item}>
+                  <Section.Media
+                    size='lg'
+                    skeleton
+                  />
+                  <Section.Content>
+                    <Section.Label skeleton />
+                    <Section.Description skeleton />
+                  </Section.Content>
+                </Section.Item>
+              ))}
+            </Section.Items>
+          </Section.Body>
+        </Section.Group>
+      </Section.Root>
+    </div>
+  );
+}
+
 function deviceBadges(device: UserProfileDevice, m: MosaicMessages['userProfileActiveDevices']): string[] {
   const labels: (string | null)[] = [
     device.isCurrent ? m.thisDevice : null,
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices.messages.ts b/packages/mosaic/src/features/user-profile/user-profile-active-devices.messages.ts
index ed29beef3b4..9320e03cec5 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-active-devices.messages.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices.messages.ts
@@ -1,5 +1,6 @@
 export const userProfileActiveDevicesMessages = {
   title: 'Active devices',
+  loading: 'Loading active devices',
   emptyCurrent: 'No current device available',
   signOutAll: 'Sign out of all devices',
   signOutAllError: 'Something went wrong signing these devices out. Please try again.',
diff --git a/packages/mosaic/src/features/user-profile/user-profile-security-icon.tsx b/packages/mosaic/src/features/user-profile/user-profile-security-icon.tsx
index e7013d95d4c..c6938eb382d 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-security-icon.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-security-icon.tsx
@@ -1,9 +1,5 @@
-import * as stylex from '@stylexjs/stylex';
-
 import { Icon } from '../../components/icon';
 import { Section } from '../../components/section';
-import { mergeStyleProps } from '../../props';
-import { space } from '../../tokens.stylex';
 import { styles } from './user-profile-security-panel.styles';
 
 export type UserProfileSecurityIconName = 'authenticator' | 'backup-codes' | 'desktop' | 'mobile' | 'passkey' | 'sms';
@@ -21,7 +17,7 @@ export function UserProfileSecurityIcon({ name }: { name: UserProfileSecurityIco
   return (
     <Section.Media
       size='lg'
-      {...mergeStyleProps(stylex.props(styles.media), { style: { height: space['9'], width: space['9'] } })}
+      xstyle={styles.media}
     >
       <Icon
         name={icons[name]}
diff --git a/packages/mosaic/src/hooks/useSkeletonWave.ts b/packages/mosaic/src/hooks/useSkeletonWave.ts
new file mode 100644
index 00000000000..e8d5d8a6fcf
--- /dev/null
+++ b/packages/mosaic/src/hooks/useSkeletonWave.ts
@@ -0,0 +1,27 @@
+import { useSafeLayoutEffect } from '@clerk/shared/react';
+import { useRef } from 'react';
+
+const PERIOD_MS = 1200;
+const MS_PER_PX = 2.5;
+
+export function useSkeletonWave<T extends HTMLElement>(enabled: boolean) {
+  const ref = useRef<T | null>(null);
+
+  useSafeLayoutEffect(() => {
+    const element = ref.current;
+    if (!enabled || !element) {
+      return;
+    }
+    const now = Number(document.timeline?.currentTime ?? performance.now());
+    const top = element.getBoundingClientRect().top + window.scrollY;
+    const phase = (((now - top * MS_PER_PX) % PERIOD_MS) + PERIOD_MS) % PERIOD_MS;
+    element.style.setProperty('--_cl-skeleton-delay', `${-phase}ms`);
+    element.setAttribute('data-skeleton-wave', '');
+    return () => {
+      element.style.removeProperty('--_cl-skeleton-delay');
+      element.removeAttribute('data-skeleton-wave');
+    };
+  }, [enabled]);
+
+  return ref;
+}
diff --git a/packages/mosaic/src/utils/skeleton.styles.ts b/packages/mosaic/src/utils/skeleton.styles.ts
new file mode 100644
index 00000000000..2a23ecdff16
--- /dev/null
+++ b/packages/mosaic/src/utils/skeleton.styles.ts
@@ -0,0 +1,35 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars } from '../tokens.stylex';
+
+const wave = stylex.keyframes({
+  '0%': { opacity: 1 },
+  '37.5%': { opacity: 0.6 },
+  '75%': { opacity: 1 },
+  '100%': { opacity: 1 },
+});
+
+export const skeletonStyles = stylex.create({
+  bone: {
+    borderRadius: radiusVars['--cl-radius-md'],
+    animationDelay: 'var(--_cl-skeleton-delay, 0ms)',
+    animationDuration: '1.2s',
+    animationFillMode: 'both',
+    animationIterationCount: 'infinite',
+    animationName: {
+      default: 'none',
+      ':where([data-skeleton-wave])': wave,
+      '@media (prefers-reduced-motion: reduce)': { default: 'none', ':where([data-skeleton-wave])': 'none' },
+    },
+    animationTimingFunction: 'cubic-bezier(0.645, 0.045, 0.355, 1)',
+    backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
+    userSelect: 'none',
+  },
+  line: {
+    borderRadius: radiusVars['--cl-radius-sm'],
+    marginBlock: '0.2lh',
+    display: 'block',
+    height: '0.6lh',
+    maxWidth: '100%',
+  },
+});
diff --git a/packages/swingset/src/components/StoryEmbed.tsx b/packages/swingset/src/components/StoryEmbed.tsx
index c7f4401bc44..0724bb7b9a5 100644
--- a/packages/swingset/src/components/StoryEmbed.tsx
+++ b/packages/swingset/src/components/StoryEmbed.tsx
@@ -9,6 +9,7 @@ import { toUsageSnippet } from '@/lib/exampleSnippet';
 import { extractStorySource } from '@/lib/extractStorySource';
 import { generateKnobs, initKnobValues } from '@/lib/generateKnobs';
 import type { StoryModule } from '@/lib/types';
+import { cn, fillsFrame } from '@/lib/utils';
 
 import { StoryMosaicProvider } from './ChaosProvider';
 import { CodeFooter } from './CodeFooter';
@@ -62,7 +63,12 @@ export function StoryEmbed({ name, storyModule, showCode = true, composition }:
 
   return (
     <div className='not-prose border-border bg-background my-4 overflow-hidden rounded-lg border'>
-      <div className='flex min-h-20 items-center justify-center p-2.5 sm:p-6'>
+      <div
+        className={cn(
+          'flex min-h-20 items-center justify-center p-2.5 sm:p-6',
+          fillsFrame(storyModule) && '[&>*]:w-full',
+        )}
+      >
         <StoryMosaicProvider>
           <StoryComp {...defaultValues} />
         </StoryMosaicProvider>
diff --git a/packages/swingset/src/components/StoryPreview.tsx b/packages/swingset/src/components/StoryPreview.tsx
index 8ba03946298..6f6333ca48e 100644
--- a/packages/swingset/src/components/StoryPreview.tsx
+++ b/packages/swingset/src/components/StoryPreview.tsx
@@ -6,6 +6,7 @@ import { useEffect, useState } from 'react';
 
 import { generateKnobs, initKnobValues } from '@/lib/generateKnobs';
 import type { StoryModule } from '@/lib/types';
+import { cn, fillsFrame } from '@/lib/utils';
 
 import { StoryMosaicProvider } from './ChaosProvider';
 import { usePlayground } from './PlaygroundContext';
@@ -49,7 +50,7 @@ export function StoryPreview({ name, storyModule }: StoryPreviewProps) {
         </button>
       </div>
 
-      <div className='flex min-h-40 items-center justify-center p-10'>
+      <div className={cn('flex min-h-40 items-center justify-center p-10', fillsFrame(storyModule) && '[&>*]:w-full')}>
         {mounted && (
           <StoryMosaicProvider>
             <StoryComp {...values} />
diff --git a/packages/swingset/src/lib/utils.ts b/packages/swingset/src/lib/utils.ts
index 9ad0df4269e..fd78a50df81 100644
--- a/packages/swingset/src/lib/utils.ts
+++ b/packages/swingset/src/lib/utils.ts
@@ -1,6 +1,12 @@
 import { type ClassValue, clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
 
+import type { StoryModule } from './types';
+
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
+
+export function fillsFrame(storyModule: StoryModule) {
+  return storyModule.meta.navigation?.category === 'Sections';
+}
diff --git a/packages/swingset/src/stories/section.mdx b/packages/swingset/src/stories/section.mdx
index 7559e7e7399..0c6cfb266d5 100644
--- a/packages/swingset/src/stories/section.mdx
+++ b/packages/swingset/src/stories/section.mdx
@@ -46,6 +46,12 @@ and `xl` sizes.
 than `26rem`. `sectionCompactStyles.hidden` and `sectionCompactStyles.only` toggle inline content at
 the same width.
 
+`Section.Group`, `Section.Title`, `Section.Media`, `Section.Label`, and `Section.Description` take
+`skeleton` for a loading state. A skeleton part renders empty as a placeholder the size of the
+content it stands in for, and a skeleton group is hidden from assistive technology, so pair it with
+a visually hidden status message. Placeholders pulse in one wave that travels down the page, across
+every skeleton on it. When to show the skeleton, and for how long, is up to the caller.
+
 `Section.Title` renders at the level from the nearest `HeadingLevelProvider`, or `h2` outside one.
 On a page, put the sections in `Panel.Sections` so the card titles sit one level below the page
 title. See [Panel](/components/panel) and [Heading](/components/heading).
@@ -134,3 +140,10 @@ External CSS can move the card from `.cl-section-group` to `.cl-section-body`; t
   name='Flat'
   storyModule={SectionStories}
 />
+
+### Loading
+
+<Story
+  name='Loading'
+  storyModule={SectionStories}
+/>
diff --git a/packages/swingset/src/stories/section.stories.tsx b/packages/swingset/src/stories/section.stories.tsx
index 452c1002280..20ce039154a 100644
--- a/packages/swingset/src/stories/section.stories.tsx
+++ b/packages/swingset/src/stories/section.stories.tsx
@@ -5,6 +5,7 @@ import { Icon, IconFrame } from '@clerk/mosaic/components/icon';
 import { Section } from '@clerk/mosaic/components/section';
 import { space } from '@clerk/mosaic/tokens.stylex';
 import * as stylex from '@stylexjs/stylex';
+import { useEffect, useState } from 'react';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -14,6 +15,14 @@ const styles = stylex.create({
   rootMax: {
     maxWidth: 560,
   },
+  loadingStack: {
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: space['4'],
+    maxWidth: 560,
+    width: '100%',
+  },
   descriptionFlex: {
     alignItems: 'center',
     display: 'flex',
@@ -525,3 +534,67 @@ export function Flat() {
     </>
   );
 }
+
+const loadingItems = [
+  { icon: 'device-laptop', label: 'Chrome on macOS', description: 'San Francisco, US · Active now' },
+  { icon: 'device-phone', label: 'Safari on iOS', description: 'San Francisco, US · 2 hours ago' },
+  { icon: 'device-laptop', label: 'Firefox on Windows', description: 'Denver, US · 3 days ago' },
+] as const;
+
+export function Loading() {
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (!loading) {
+      return;
+    }
+    const timer = setTimeout(() => setLoading(false), 2000);
+    return () => clearTimeout(timer);
+  }, [loading]);
+
+  return (
+    <div {...stylex.props(styles.loadingStack)}>
+      <Button
+        color='neutral'
+        size='sm'
+        variant='outline'
+        disabled={loading}
+        onClick={() => setLoading(true)}
+      >
+        Reload
+      </Button>
+      <Section.Root>
+        <Section.Group skeleton={loading}>
+          <Section.Header>
+            <Section.Title skeleton={loading}>{loading ? null : 'Active devices'}</Section.Title>
+          </Section.Header>
+          <Section.Body>
+            <Section.Items>
+              {loadingItems.map(item => (
+                <Section.Item key={item.label}>
+                  <Section.Media
+                    size='lg'
+                    skeleton={loading}
+                  >
+                    {loading ? null : (
+                      <IconFrame>
+                        <Icon
+                          name={item.icon}
+                          size='lg'
+                        />
+                      </IconFrame>
+                    )}
+                  </Section.Media>
+                  <Section.Content>
+                    <Section.Label skeleton={loading}>{loading ? null : item.label}</Section.Label>
+                    <Section.Description skeleton={loading}>{loading ? null : item.description}</Section.Description>
+                  </Section.Content>
+                </Section.Item>
+              ))}
+            </Section.Items>
+          </Section.Body>
+        </Section.Group>
+      </Section.Root>
+    </div>
+  );
+}
diff --git a/packages/swingset/src/stories/user-profile-active-devices-section.mdx b/packages/swingset/src/stories/user-profile-active-devices-section.mdx
index f1a04716f56..7809efcbf87 100644
--- a/packages/swingset/src/stories/user-profile-active-devices-section.mdx
+++ b/packages/swingset/src/stories/user-profile-active-devices-section.mdx
@@ -31,3 +31,10 @@ The first attempt of each kind fails, second attempt succeeds.
   name='Impersonation'
   storyModule={Stories}
 />
+
+## Loading
+
+<Story
+  name='Loading'
+  storyModule={Stories}
+/>
diff --git a/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx b/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx
index 5127d7e25a1..f4d1f6874d0 100644
--- a/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx
+++ b/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx
@@ -1,4 +1,7 @@
-import { UserProfileActiveDevicesSectionView } from '@clerk/mosaic/features/user-profile/user-profile-active-devices-section.view';
+import {
+  UserProfileActiveDevicesSectionSkeleton,
+  UserProfileActiveDevicesSectionView,
+} from '@clerk/mosaic/features/user-profile/user-profile-active-devices-section.view';
 
 import type { StoryMeta } from '@/lib/types';
 
@@ -42,3 +45,7 @@ export function Impersonation() {
     />
   );
 }
+
+export function Loading() {
+  return <UserProfileActiveDevicesSectionSkeleton />;
+}

From c95f4f760be6bd063f761cc7da04b2e0b53ba410 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 1 Oct 2026 17:21:44 -0600
Subject: [PATCH 02/14] feat(mosaic): move pulses onto the skeleton wave and
 add panel title skeletons

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/motion.md    | 41 +++++++++++++++----
 .../src/components/avatar/avatar.styles.ts    | 15 -------
 .../mosaic/src/components/avatar/avatar.tsx   | 19 ++++-----
 .../src/components/panel/panel.styles.ts      |  3 ++
 .../mosaic/src/components/panel/panel.tsx     | 23 +++++++++--
 .../src/components/section/section.styles.ts  |  3 ++
 .../mosaic/src/components/section/section.tsx | 27 +++++++++---
 ...rofile-active-devices-section.skeleton.tsx | 41 +++++++++++++++++++
 ...er-profile-active-devices-section.view.tsx | 36 ----------------
 .../user-profile-backup-codes.styles.ts       | 16 +-------
 .../user-profile-backup-codes.view.tsx        | 19 +++++++--
 packages/mosaic/src/hooks/useSkeletonWave.ts  |  4 +-
 packages/mosaic/src/tokens.stylex.ts          |  2 +-
 packages/mosaic/src/utils/skeleton.styles.ts  | 16 ++++----
 .../swingset/src/stories/panel.component.mdx  |  3 ++
 packages/swingset/src/stories/section.mdx     |  2 +
 ...profile-active-devices-section.stories.tsx |  6 +--
 17 files changed, 165 insertions(+), 111 deletions(-)
 create mode 100644 packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx

diff --git a/.claude/skills/mosaic/references/motion.md b/.claude/skills/mosaic/references/motion.md
index 3f2e1d7fdca..5cdf884accd 100644
--- a/.claude/skills/mosaic/references/motion.md
+++ b/.claude/skills/mosaic/references/motion.md
@@ -1,4 +1,4 @@
-# Motion: entrances, exits, and pulses
+# Motion: entrances, exits, and loading
 
 Token semantics live in `packages/mosaic/src/tokens.stylex.ts`, above
 `durationDefaults` / `easingDefaults` — read those comments first. This file is the
@@ -15,7 +15,7 @@ rather than eyeball it.
 | `--cl-ease-default`     | `cubic-bezier(0.175, 0.885, 0.32, 1.1)` | things ARRIVING (Swift Out)      |
 | `--cl-ease-enter`       | `cubic-bezier(0, 0, 0.2, 1)`            | arrivals that must not overshoot |
 | `--cl-ease-exit`        | `cubic-bezier(0.55, 0.085, 0.68, 0.53)` | things LEAVING (In Quad)         |
-| `--cl-ease-pulse`       | `cubic-bezier(0.4, 0, 0.6, 1)`          | repeating opacity pulses         |
+| `--cl-ease-in-out`      | `cubic-bezier(0.645, 0.045, 0.355, 1)`  | pulses and swaps (In-Out Cubic)  |
 
 Named curves come from [easing.dev](https://www.easing.dev) (Lochie Axon's Easing
 Graphs). Take one from there rather than inventing a bezier, so the catalog stays
@@ -52,12 +52,37 @@ For entrances, opacity takes `--cl-ease-enter`: there is nothing
 past `1` to overshoot into, so the pass is clamped away and only its cost — the
 slower approach to full opacity — is left.
 
-## Repeating pulses
-
-Use `--cl-ease-pulse` for repeating opacity fades such as loading skeletons. Its
-symmetric curve slows at both ends of each fade, keeping the reversal smooth.
-Keep the pulse duration on the component and disable the animation under
-`prefers-reduced-motion: reduce`.
+## Loading skeletons: one wave down the page
+
+Every loading placeholder pulses through one shared wave, never a local pulse of its
+own. The pieces:
+
+- `skeletonStyles.bone` (fill and radius) and `skeletonStyles.line` (a bar `0.6lh`
+  tall with `0.2lh` margins, so it fills exactly one line of the text it replaces)
+  in `utils/skeleton.styles.ts`.
+- `skeletonStyles.wave`: the keyframes (opacity `1 → 0.32 → 1` over the first 56%
+  of a 2s cycle, then a hold), on `--cl-ease-in-out`. A component with its own
+  fill and shape, such as `Avatar.Fallback`, takes `wave` alone.
+- `useSkeletonWave(enabled)` in `hooks/`: before first paint it sets a negative
+  `animation-delay` from the element's page position, `-(now − y × 2.1ms/px) mod
+2000ms`, and marks it `data-skeleton-wave`. Every bone shares the document clock
+  and lags it by its height on the page, so skeletons that mount separately read
+  as a single wave, and two lines in one row sit on different parts of it.
+
+`wave` only animates once `data-skeleton-wave` is set. Without that gate, a
+server-rendered skeleton pulses in unison before hydration and then jumps into
+phase. The keyframe duration and `PERIOD_MS` in the hook must match.
+
+Tuning, all relative to each other: the hook's px rate sets how fast the wave
+travels; the cycle over that rate sets the spacing between crests (~950px, about
+one crest per panel); the keyframe's dip width sets how wide a crest is. Shorten
+the cycle alone and crests crowd together; widen the dip alone and the hold
+disappears.
+
+Use the `skeleton` prop on `Section` parts and `Panel.Title` rather than composing
+bones by hand. Any new skeleton must measure the same as the content it replaces:
+`Section.Actions skeleton` exists because a 28px menu trigger outgrew a 20px line.
+Off under `prefers-reduced-motion: reduce`.
 
 ## A curve has a direction — don't run the entrance curve backwards
 
diff --git a/packages/mosaic/src/components/avatar/avatar.styles.ts b/packages/mosaic/src/components/avatar/avatar.styles.ts
index 96e6a2c5306..f6090d3bc97 100644
--- a/packages/mosaic/src/components/avatar/avatar.styles.ts
+++ b/packages/mosaic/src/components/avatar/avatar.styles.ts
@@ -2,11 +2,6 @@ import * as stylex from '@stylexjs/stylex';
 
 import { colorVars, fontFamilyVars, fontWeightVars, radiusVars, space } from '../../tokens.stylex';
 
-// Timed to match `skeleton.tsx`'s pulse, so the two generations of placeholder read as one thing.
-const pulse = stylex.keyframes({
-  '50%': { opacity: 0.5 },
-});
-
 export const styles = stylex.create({
   // root — sizes and positions its parts; fill comes from the image or fallback
   base: {
@@ -71,16 +66,6 @@ export const styles = stylex.create({
     visibility: 'hidden',
   },
 
-  fallbackPending: {
-    animationDuration: '2s',
-    animationIterationCount: 'infinite',
-    animationName: {
-      default: pulse,
-      '@media (prefers-reduced-motion: reduce)': 'none',
-    },
-    animationTimingFunction: 'cubic-bezier(0.4, 0, 0.6, 1)',
-  },
-
   icon: {
     borderColor: colorVars['--cl-color-border'],
     borderRadius: radiusVars['--cl-radius-full'],
diff --git a/packages/mosaic/src/components/avatar/avatar.tsx b/packages/mosaic/src/components/avatar/avatar.tsx
index 7c093c03236..479be1a937b 100644
--- a/packages/mosaic/src/components/avatar/avatar.tsx
+++ b/packages/mosaic/src/components/avatar/avatar.tsx
@@ -1,12 +1,15 @@
 import { useSafeLayoutEffect } from '@clerk/shared/react';
+import { useMergeRefs } from '@floating-ui/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import { useSkeletonWave } from '../../hooks/useSkeletonWave';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps, MosaicElementProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { focusOutline } from '../../utils/focus-outline.styles';
 import { reset } from '../../utils/reset.styles';
+import { skeletonStyles } from '../../utils/skeleton.styles';
 import { shapes, sizes, styles } from './avatar.styles';
 
 type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
@@ -145,24 +148,20 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
     return () => clearTimeout(timer);
   }, [delayMs]);
 
+  const pending = canRender && status === 'loading';
+  const wave = useSkeletonWave<HTMLSpanElement>(pending);
+  const mergedRef = useMergeRefs([ref, wave]);
+
   if (!canRender || status === 'loaded') {
     return null;
   }
 
-  const pending = status === 'loading';
-
   return (
     <span
-      ref={ref}
+      ref={mergedRef}
       {...mergeStyleProps(
         themeProps('avatar-fallback', { pending }),
-        stylex.props(
-          reset.base,
-          styles.fallback,
-          bordered && styles.overlay,
-          pending && styles.fallbackPending,
-          xstyle,
-        ),
+        stylex.props(reset.base, styles.fallback, bordered && styles.overlay, pending && skeletonStyles.wave, xstyle),
         rest,
       )}
     >
diff --git a/packages/mosaic/src/components/panel/panel.styles.ts b/packages/mosaic/src/components/panel/panel.styles.ts
index c9e74458738..f39fdf9453b 100644
--- a/packages/mosaic/src/components/panel/panel.styles.ts
+++ b/packages/mosaic/src/components/panel/panel.styles.ts
@@ -12,6 +12,9 @@ export const styles = stylex.create({
   title: {
     display: 'block',
   },
+  titleSkeleton: {
+    width: space['24'],
+  },
 
   /**
    * The headline as a button: the heading's own type, inline so the caret can align to its
diff --git a/packages/mosaic/src/components/panel/panel.tsx b/packages/mosaic/src/components/panel/panel.tsx
index 2cb11c725ce..0187e86ef3c 100644
--- a/packages/mosaic/src/components/panel/panel.tsx
+++ b/packages/mosaic/src/components/panel/panel.tsx
@@ -1,18 +1,20 @@
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import { useSkeletonWave } from '../../hooks/useSkeletonWave';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { focusOutline } from '../../utils/focus-outline.styles';
 import { reset } from '../../utils/reset.styles';
+import { skeletonStyles } from '../../utils/skeleton.styles';
 import { Heading, HeadingLevelProvider, useHeadingLevel } from '../heading';
 import { Icon } from '../icon';
 import { ContentPanelContext, ProfileContext } from '../profile/profile.context';
 import { styles } from './panel.styles';
 
 export type PanelRootProps = MosaicComponentProps<'div'>;
-export type PanelTitleProps = MosaicComponentProps<'div'>;
+export type PanelTitleProps = MosaicComponentProps<'div'> & { skeleton?: boolean };
 export type PanelSectionsProps = MosaicComponentProps<'div'>;
 
 const Root = React.forwardRef<HTMLDivElement, PanelRootProps>(function PanelRoot({ render, xstyle, ...rest }, ref) {
@@ -34,9 +36,10 @@ const Root = React.forwardRef<HTMLDivElement, PanelRootProps>(function PanelRoot
  * line box. That needs an inline formatting context, so the button is `display: inline`.
  */
 const Title = React.forwardRef<HTMLDivElement, PanelTitleProps>(function PanelTitle(
-  { children, render, xstyle, ...rest },
+  { skeleton = false, children, render, xstyle, ...rest },
   ref,
 ) {
+  const wave = useSkeletonWave<HTMLHeadingElement>(skeleton);
   const profile = React.useContext(ProfileContext);
   const panel = React.useContext(ContentPanelContext);
   const registerPageTitle = profile?.registerPageTitle;
@@ -56,8 +59,20 @@ const Title = React.forwardRef<HTMLDivElement, PanelTitleProps>(function PanelTi
     render,
     ref,
     props: {
-      ...mergeStyleProps(themeProps('panel-title'), stylex.props(reset.base, styles.title, xstyle), rest),
-      children: (
+      ...mergeStyleProps(
+        themeProps('panel-title', { skeleton }),
+        stylex.props(reset.base, styles.title, xstyle),
+        skeleton ? { 'aria-hidden': true } : {},
+        rest,
+      ),
+      children: skeleton ? (
+        <Heading
+          ref={wave}
+          level={level}
+          size='2xl'
+          xstyle={[skeletonStyles.bone, skeletonStyles.wave, skeletonStyles.line, styles.titleSkeleton]}
+        />
+      ) : (
         <Heading
           id={panel?.titleId}
           level={level}
diff --git a/packages/mosaic/src/components/section/section.styles.ts b/packages/mosaic/src/components/section/section.styles.ts
index 8bdbe06a3d6..477d7ab1e79 100644
--- a/packages/mosaic/src/components/section/section.styles.ts
+++ b/packages/mosaic/src/components/section/section.styles.ts
@@ -165,6 +165,9 @@ export const styles = stylex.create({
     flexShrink: 0,
     justifyContent: 'flex-end',
   },
+  actionsSkeleton: {
+    height: space['7'],
+  },
   actionsWrap: {
     justifyContent: { [compact]: 'flex-start', default: 'flex-end' },
     width: { [compact]: '100%', default: null },
diff --git a/packages/mosaic/src/components/section/section.tsx b/packages/mosaic/src/components/section/section.tsx
index 226d91d15db..f0a0c9bc1f6 100644
--- a/packages/mosaic/src/components/section/section.tsx
+++ b/packages/mosaic/src/components/section/section.tsx
@@ -31,7 +31,7 @@ export type SectionMediaProps = MosaicComponentProps<'div'> & { size?: SectionMe
 export type SectionContentProps = MosaicComponentProps<'div'>;
 export type SectionLabelProps = MosaicComponentProps<'div'> & { skeleton?: boolean };
 export type SectionDescriptionProps = MosaicComponentProps<'div'> & { skeleton?: boolean };
-export type SectionActionsProps = MosaicComponentProps<'div'>;
+export type SectionActionsProps = MosaicComponentProps<'div'> & { skeleton?: boolean };
 export type SectionErrorProps = MosaicComponentProps<'p'>;
 
 const mediaSizes = {
@@ -134,6 +134,7 @@ const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function S
       xstyle={[
         styles.title,
         skeleton && skeletonStyles.bone,
+        skeleton && skeletonStyles.wave,
         skeleton && skeletonStyles.line,
         skeleton && styles.titleSkeleton,
         xstyle,
@@ -214,7 +215,14 @@ const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function Secti
     ref: [ref, wave],
     props: mergeStyleProps(
       themeProps('section-media', { size, skeleton }),
-      stylex.props(reset.base, styles.mediaBase, mediaSizes[size], skeleton && skeletonStyles.bone, xstyle),
+      stylex.props(
+        reset.base,
+        styles.mediaBase,
+        mediaSizes[size],
+        skeleton && skeletonStyles.bone,
+        skeleton && skeletonStyles.wave,
+        xstyle,
+      ),
       rest,
     ),
   });
@@ -254,6 +262,7 @@ const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function Secti
         reset.base,
         styles.label,
         skeleton && skeletonStyles.bone,
+        skeleton && skeletonStyles.wave,
         skeleton && skeletonStyles.line,
         skeleton && styles.labelSkeleton,
         xstyle,
@@ -282,6 +291,7 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
         inHeader && styles.headerDescription,
         inHeader && sectionHeaderDescriptionMarker,
         skeleton && skeletonStyles.bone,
+        skeleton && skeletonStyles.wave,
         skeleton && skeletonStyles.line,
         skeleton && styles.descriptionSkeleton,
         xstyle,
@@ -292,7 +302,7 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
 });
 
 const Actions = React.forwardRef<HTMLDivElement, SectionActionsProps>(function SectionActions(
-  { render, xstyle, ...rest },
+  { skeleton = false, render, xstyle, ...rest },
   ref,
 ) {
   const wrap = React.useContext(SectionItemWrapContext);
@@ -303,8 +313,15 @@ const Actions = React.forwardRef<HTMLDivElement, SectionActionsProps>(function S
     render,
     ref,
     props: mergeStyleProps(
-      themeProps('section-actions'),
-      stylex.props(reset.base, styles.actions, wrap && styles.actionsWrap, inHeader && styles.headerActions, xstyle),
+      themeProps('section-actions', { skeleton }),
+      stylex.props(
+        reset.base,
+        styles.actions,
+        wrap && styles.actionsWrap,
+        inHeader && styles.headerActions,
+        skeleton && styles.actionsSkeleton,
+        xstyle,
+      ),
       rest,
     ),
   });
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
new file mode 100644
index 00000000000..c66dc7ffa11
--- /dev/null
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
@@ -0,0 +1,41 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { Section } from '../../components/section';
+import { VisuallyHidden } from '../../components/visually-hidden';
+import { useMessages } from '../../localization';
+import { styles } from './user-profile-security-panel.styles';
+
+const SKELETON_ITEMS = [0, 1, 2];
+
+export function UserProfileActiveDevicesSectionSkeleton() {
+  const m = useMessages('userProfileActiveDevices');
+
+  return (
+    <div {...stylex.props(styles.sectionCards)}>
+      <VisuallyHidden role='status'>{m.loading}</VisuallyHidden>
+      <Section.Root>
+        <Section.Group skeleton>
+          <Section.Header>
+            <Section.Title skeleton />
+          </Section.Header>
+          <Section.Body>
+            <Section.Items>
+              {SKELETON_ITEMS.map(item => (
+                <Section.Item key={item}>
+                  <Section.Media
+                    size='lg'
+                    skeleton
+                  />
+                  <Section.Content>
+                    <Section.Label skeleton />
+                    <Section.Description skeleton />
+                  </Section.Content>
+                </Section.Item>
+              ))}
+            </Section.Items>
+          </Section.Body>
+        </Section.Group>
+      </Section.Root>
+    </div>
+  );
+}
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
index 3e743879fda..f2f3325ca58 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
@@ -9,7 +9,6 @@ import { Badge } from '../../components/badge';
 import { Button } from '../../components/button';
 import { Dialog } from '../../components/dialog';
 import { Section } from '../../components/section';
-import { VisuallyHidden } from '../../components/visually-hidden';
 import { useListRemovalFocus } from '../../hooks/useListRemovalFocus';
 import type { MosaicMessages } from '../../localization';
 import { fill, plural, useLocale, useMessages } from '../../localization';
@@ -175,41 +174,6 @@ export function UserProfileActiveDevicesSectionView({
   );
 }
 
-const SKELETON_ITEMS = [0, 1, 2];
-
-export function UserProfileActiveDevicesSectionSkeleton() {
-  const m = useMessages('userProfileActiveDevices');
-
-  return (
-    <div {...stylex.props(styles.sectionCards)}>
-      <VisuallyHidden role='status'>{m.loading}</VisuallyHidden>
-      <Section.Root>
-        <Section.Group skeleton>
-          <Section.Header>
-            <Section.Title skeleton />
-          </Section.Header>
-          <Section.Body>
-            <Section.Items>
-              {SKELETON_ITEMS.map(item => (
-                <Section.Item key={item}>
-                  <Section.Media
-                    size='lg'
-                    skeleton
-                  />
-                  <Section.Content>
-                    <Section.Label skeleton />
-                    <Section.Description skeleton />
-                  </Section.Content>
-                </Section.Item>
-              ))}
-            </Section.Items>
-          </Section.Body>
-        </Section.Group>
-      </Section.Root>
-    </div>
-  );
-}
-
 function deviceBadges(device: UserProfileDevice, m: MosaicMessages['userProfileActiveDevices']): string[] {
   const labels: (string | null)[] = [
     device.isCurrent ? m.thisDevice : null,
diff --git a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
index de07661a95f..13c3d03822f 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
@@ -1,23 +1,9 @@
 import * as stylex from '@stylexjs/stylex';
 
-import { colorVars, easingVars, radiusVars, space } from '../../tokens.stylex';
-
-const pulse = stylex.keyframes({
-  '50%': { opacity: 0.5 },
-});
+import { colorVars, radiusVars, space } from '../../tokens.stylex';
 
 export const styles = stylex.create({
   skeleton: {
-    borderRadius: radiusVars['--cl-radius-sm'],
-    animationDuration: '2s',
-    animationIterationCount: 'infinite',
-    animationName: {
-      default: pulse,
-      '@media (prefers-reduced-motion: reduce)': 'none',
-    },
-    animationTimingFunction: easingVars['--cl-ease-pulse'],
-    backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
-    height: '1lh',
     width: space['16'],
   },
   codes: {
diff --git a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
index e425aa8b340..3938fde9f04 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
@@ -6,9 +6,11 @@ import { Card } from '../../components/card';
 import { useFlowAutoFocus } from '../../components/flow';
 import { Icon } from '../../components/icon';
 import { Text } from '../../components/text';
+import { useSkeletonWave } from '../../hooks/useSkeletonWave';
 import { useMessages } from '../../localization';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../../utils/reset.styles';
+import { skeletonStyles } from '../../utils/skeleton.styles';
 import { styles } from './user-profile-backup-codes.styles';
 
 export interface UserProfileBackupCodesViewProps {
@@ -83,10 +85,7 @@ export function UserProfileBackupCodesView({
                 aria-hidden='true'
                 {...stylex.props(reset.base, styles.cell)}
               >
-                <Text
-                  render={<span />}
-                  xstyle={styles.skeleton}
-                />
+                <BackupCodeSkeleton />
               </div>
             ))}
           </div>
@@ -155,3 +154,15 @@ export function UserProfileBackupCodesView({
     </>
   );
 }
+
+function BackupCodeSkeleton() {
+  const wave = useSkeletonWave<HTMLParagraphElement>(true);
+
+  return (
+    <Text
+      ref={wave}
+      render={<span />}
+      xstyle={[skeletonStyles.bone, skeletonStyles.wave, skeletonStyles.line, styles.skeleton]}
+    />
+  );
+}
diff --git a/packages/mosaic/src/hooks/useSkeletonWave.ts b/packages/mosaic/src/hooks/useSkeletonWave.ts
index e8d5d8a6fcf..a2ea399bc95 100644
--- a/packages/mosaic/src/hooks/useSkeletonWave.ts
+++ b/packages/mosaic/src/hooks/useSkeletonWave.ts
@@ -1,8 +1,8 @@
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import { useRef } from 'react';
 
-const PERIOD_MS = 1200;
-const MS_PER_PX = 2.5;
+const PERIOD_MS = 2000;
+const MS_PER_PX = 2.1;
 
 export function useSkeletonWave<T extends HTMLElement>(enabled: boolean) {
   const ref = useRef<T | null>(null);
diff --git a/packages/mosaic/src/tokens.stylex.ts b/packages/mosaic/src/tokens.stylex.ts
index 256a7957d35..4ed41c21e15 100644
--- a/packages/mosaic/src/tokens.stylex.ts
+++ b/packages/mosaic/src/tokens.stylex.ts
@@ -404,7 +404,7 @@ const easingDefaults = {
   '--cl-ease-default': 'cubic-bezier(0.175, 0.885, 0.32, 1.1)',
   '--cl-ease-enter': 'cubic-bezier(0, 0, 0.2, 1)',
   '--cl-ease-exit': 'cubic-bezier(0.55, 0.085, 0.68, 0.53)',
-  '--cl-ease-pulse': 'cubic-bezier(0.4, 0, 0.6, 1)',
+  '--cl-ease-in-out': 'cubic-bezier(0.645, 0.045, 0.355, 1)',
 } as const;
 
 export const easingVars = stylex.defineVars(easingDefaults);
diff --git a/packages/mosaic/src/utils/skeleton.styles.ts b/packages/mosaic/src/utils/skeleton.styles.ts
index 2a23ecdff16..c8b72874cf7 100644
--- a/packages/mosaic/src/utils/skeleton.styles.ts
+++ b/packages/mosaic/src/utils/skeleton.styles.ts
@@ -1,19 +1,18 @@
 import * as stylex from '@stylexjs/stylex';
 
-import { colorVars, radiusVars } from '../tokens.stylex';
+import { colorVars, easingVars, radiusVars } from '../tokens.stylex';
 
 const wave = stylex.keyframes({
   '0%': { opacity: 1 },
-  '37.5%': { opacity: 0.6 },
-  '75%': { opacity: 1 },
+  '28%': { opacity: 0.32 },
+  '56%': { opacity: 1 },
   '100%': { opacity: 1 },
 });
 
 export const skeletonStyles = stylex.create({
-  bone: {
-    borderRadius: radiusVars['--cl-radius-md'],
+  wave: {
     animationDelay: 'var(--_cl-skeleton-delay, 0ms)',
-    animationDuration: '1.2s',
+    animationDuration: '2s',
     animationFillMode: 'both',
     animationIterationCount: 'infinite',
     animationName: {
@@ -21,7 +20,10 @@ export const skeletonStyles = stylex.create({
       ':where([data-skeleton-wave])': wave,
       '@media (prefers-reduced-motion: reduce)': { default: 'none', ':where([data-skeleton-wave])': 'none' },
     },
-    animationTimingFunction: 'cubic-bezier(0.645, 0.045, 0.355, 1)',
+    animationTimingFunction: easingVars['--cl-ease-in-out'],
+  },
+  bone: {
+    borderRadius: radiusVars['--cl-radius-md'],
     backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
     userSelect: 'none',
   },
diff --git a/packages/swingset/src/stories/panel.component.mdx b/packages/swingset/src/stories/panel.component.mdx
index fe7fd875c85..a0f72b7ad9a 100644
--- a/packages/swingset/src/stories/panel.component.mdx
+++ b/packages/swingset/src/stories/panel.component.mdx
@@ -7,6 +7,9 @@ children, `Panel.Title` renders the page's heading, and `Panel.Sections` stacks
 [Section](/components/section)s one heading level below the title. Inside a
 [Profile](/components/profile) page that has gone compact, `Panel.Title` opens the navigation sheet.
 
+`Panel.Title` takes `skeleton` for a loading state: the heading renders empty as a placeholder in
+the same wave as [Section](/components/section) skeletons, and is hidden from assistive technology.
+
 ## Example
 
 <Story
diff --git a/packages/swingset/src/stories/section.mdx b/packages/swingset/src/stories/section.mdx
index 0c6cfb266d5..96192cbf388 100644
--- a/packages/swingset/src/stories/section.mdx
+++ b/packages/swingset/src/stories/section.mdx
@@ -51,6 +51,8 @@ the same width.
 content it stands in for, and a skeleton group is hidden from assistive technology, so pair it with
 a visually hidden status message. Placeholders pulse in one wave that travels down the page, across
 every skeleton on it. When to show the skeleton, and for how long, is up to the caller.
+`Section.Actions skeleton` draws nothing and holds the height of a small control, for items whose
+actions would otherwise make them taller than their content.
 
 `Section.Title` renders at the level from the nearest `HeadingLevelProvider`, or `h2` outside one.
 On a page, put the sections in `Panel.Sections` so the card titles sit one level below the page
diff --git a/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx b/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx
index f4d1f6874d0..87df5d03900 100644
--- a/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx
+++ b/packages/swingset/src/stories/user-profile-active-devices-section.stories.tsx
@@ -1,7 +1,5 @@
-import {
-  UserProfileActiveDevicesSectionSkeleton,
-  UserProfileActiveDevicesSectionView,
-} from '@clerk/mosaic/features/user-profile/user-profile-active-devices-section.view';
+import { UserProfileActiveDevicesSectionSkeleton } from '@clerk/mosaic/features/user-profile/user-profile-active-devices-section.skeleton';
+import { UserProfileActiveDevicesSectionView } from '@clerk/mosaic/features/user-profile/user-profile-active-devices-section.view';
 
 import type { StoryMeta } from '@/lib/types';
 

From e39b0867808abcc0834c66a6ac0bc5ac4ff4ee14 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 1 Oct 2026 17:31:41 -0600
Subject: [PATCH 03/14] docs(repo): document what a loading skeleton renders as
 bones

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/motion.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/.claude/skills/mosaic/references/motion.md b/.claude/skills/mosaic/references/motion.md
index 5cdf884accd..260ed611782 100644
--- a/.claude/skills/mosaic/references/motion.md
+++ b/.claude/skills/mosaic/references/motion.md
@@ -84,6 +84,20 @@ bones by hand. Any new skeleton must measure the same as the content it replaces
 `Section.Actions skeleton` exists because a 28px menu trigger outgrew a 20px line.
 Off under `prefers-reduced-motion: reduce`.
 
+**What to render as bones.** A bone stands in for content that is being fetched and
+not yet on screen. When a surface loads as one unit (a panel, a table on first
+load), render the whole thing as bones, including titles, card headings and column
+headers that are already known: one loading state reads cleaner, carries the wave,
+and swaps to content in one moment. Content that isn't being fetched keeps
+rendering. A section loaded by a later request shows bones beside sections that
+have already loaded, and a table moving to another page turns its rows into bones
+while its headers and controls stay. Whether a table's controls are bones on first
+load is still open.
+
+Each component defines its own bones (`skeleton` props, or `skeletonStyles.wave`
+for a component with its own shape), but every bone uses the shared wave and the
+same fill, `--cl-color-neutral-alpha-200`.
+
 ## A curve has a direction — don't run the entrance curve backwards
 
 The single most common motion bug in this codebase. `--cl-ease-default` is

From fefa2192ff184c7674f529bd3f81e5e77dc58439 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Thu, 1 Oct 2026 18:22:29 -0600
Subject: [PATCH 04/14] feat(mosaic): draw skeleton lines as cap-height bars on
 the baseline

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/motion.md   |  6 ++++--
 packages/mosaic/src/utils/skeleton.styles.ts | 15 ++++++++++++---
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/mosaic/references/motion.md b/.claude/skills/mosaic/references/motion.md
index 260ed611782..c512a998a95 100644
--- a/.claude/skills/mosaic/references/motion.md
+++ b/.claude/skills/mosaic/references/motion.md
@@ -57,8 +57,10 @@ slower approach to full opacity — is left.
 Every loading placeholder pulses through one shared wave, never a local pulse of its
 own. The pieces:
 
-- `skeletonStyles.bone` (fill and radius) and `skeletonStyles.line` (a bar `0.6lh`
-  tall with `0.2lh` margins, so it fills exactly one line of the text it replaces)
+- `skeletonStyles.bone` (fill and radius) and `skeletonStyles.line`: a `1lh` box,
+  so it holds exactly one line of the text it replaces, whose `::before` bar is
+  `1cap` tall (`0.7em` fallback) and sits on the baseline, covering the same band
+  as the text's capitals
   in `utils/skeleton.styles.ts`.
 - `skeletonStyles.wave`: the keyframes (opacity `1 → 0.32 → 1` over the first 56%
   of a 2s cycle, then a hold), on `--cl-ease-in-out`. A component with its own
diff --git a/packages/mosaic/src/utils/skeleton.styles.ts b/packages/mosaic/src/utils/skeleton.styles.ts
index c8b72874cf7..4abce411c50 100644
--- a/packages/mosaic/src/utils/skeleton.styles.ts
+++ b/packages/mosaic/src/utils/skeleton.styles.ts
@@ -28,10 +28,19 @@ export const skeletonStyles = stylex.create({
     userSelect: 'none',
   },
   line: {
-    borderRadius: radiusVars['--cl-radius-sm'],
-    marginBlock: '0.2lh',
+    borderRadius: 0,
+    backgroundColor: 'transparent',
     display: 'block',
-    height: '0.6lh',
+    height: '1lh',
     maxWidth: '100%',
+    '::before': {
+      borderRadius: radiusVars['--cl-radius-sm'],
+      backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
+      content: "''",
+      display: 'inline-block',
+      verticalAlign: 'baseline',
+      height: stylex.firstThatWorks('1cap', '0.7em'),
+      width: '100%',
+    },
   },
 });

From 82c447a23d99766ef818e979954b8c262ac3f258 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Fri, 2 Oct 2026 09:23:27 -0600
Subject: [PATCH 05/14] feat(mosaic): square text skeleton bars and size them
 in ch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/motion.md         | 14 +++++++++-----
 .../mosaic/src/components/panel/panel.styles.ts    |  2 +-
 .../src/components/section/section.styles.ts       |  6 +++---
 .../user-profile-backup-codes.styles.ts            |  2 +-
 packages/mosaic/src/utils/skeleton.styles.ts       |  1 -
 5 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/.claude/skills/mosaic/references/motion.md b/.claude/skills/mosaic/references/motion.md
index c512a998a95..8976eb85e0c 100644
--- a/.claude/skills/mosaic/references/motion.md
+++ b/.claude/skills/mosaic/references/motion.md
@@ -57,11 +57,15 @@ slower approach to full opacity — is left.
 Every loading placeholder pulses through one shared wave, never a local pulse of its
 own. The pieces:
 
-- `skeletonStyles.bone` (fill and radius) and `skeletonStyles.line`: a `1lh` box,
-  so it holds exactly one line of the text it replaces, whose `::before` bar is
-  `1cap` tall (`0.7em` fallback) and sits on the baseline, covering the same band
-  as the text's capitals
-  in `utils/skeleton.styles.ts`.
+- `skeletonStyles.bone` (fill and radius) and `skeletonStyles.line` in
+  `utils/skeleton.styles.ts`. `line` is a `1lh` box, so it holds exactly one line
+  of the text it replaces, and its `::before` bar is `1cap` tall (`0.7em`
+  fallback) and sits on the baseline, covering the same band as the text's
+  capitals. Text bars are square-cornered; only media bones take a radius.
+- Size a text bone's width in `ch` from the content it usually holds, at the short
+  end, so it reads like real text and shrinks with `maxWidth: 100%` on narrow
+  screens: a card or page title `6ch`, a label `12ch`, a description `20ch`, an
+  email `16ch`, a US phone number `15ch`, a backup code `7ch`.
 - `skeletonStyles.wave`: the keyframes (opacity `1 → 0.32 → 1` over the first 56%
   of a 2s cycle, then a hold), on `--cl-ease-in-out`. A component with its own
   fill and shape, such as `Avatar.Fallback`, takes `wave` alone.
diff --git a/packages/mosaic/src/components/panel/panel.styles.ts b/packages/mosaic/src/components/panel/panel.styles.ts
index f39fdf9453b..06730036541 100644
--- a/packages/mosaic/src/components/panel/panel.styles.ts
+++ b/packages/mosaic/src/components/panel/panel.styles.ts
@@ -13,7 +13,7 @@ export const styles = stylex.create({
     display: 'block',
   },
   titleSkeleton: {
-    width: space['24'],
+    width: '6ch',
   },
 
   /**
diff --git a/packages/mosaic/src/components/section/section.styles.ts b/packages/mosaic/src/components/section/section.styles.ts
index 477d7ab1e79..5f35af1973d 100644
--- a/packages/mosaic/src/components/section/section.styles.ts
+++ b/packages/mosaic/src/components/section/section.styles.ts
@@ -144,13 +144,13 @@ export const styles = stylex.create({
     lineHeight: typeScaleVars['--cl-text-sm-leading'],
   },
   titleSkeleton: {
-    width: space['32'],
+    width: '6ch',
   },
   labelSkeleton: {
-    width: space['24'],
+    width: '12ch',
   },
   descriptionSkeleton: {
-    width: space['40'],
+    width: '20ch',
   },
   description: {
     color: colorVars['--cl-color-foreground-secondary'],
diff --git a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
index 13c3d03822f..6e03c8f255d 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
@@ -4,7 +4,7 @@ import { colorVars, radiusVars, space } from '../../tokens.stylex';
 
 export const styles = stylex.create({
   skeleton: {
-    width: space['16'],
+    width: '7ch',
   },
   codes: {
     borderColor: colorVars['--cl-color-border'],
diff --git a/packages/mosaic/src/utils/skeleton.styles.ts b/packages/mosaic/src/utils/skeleton.styles.ts
index 4abce411c50..7201adcdda3 100644
--- a/packages/mosaic/src/utils/skeleton.styles.ts
+++ b/packages/mosaic/src/utils/skeleton.styles.ts
@@ -34,7 +34,6 @@ export const skeletonStyles = stylex.create({
     height: '1lh',
     maxWidth: '100%',
     '::before': {
-      borderRadius: radiusVars['--cl-radius-sm'],
       backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
       content: "''",
       display: 'inline-block',

From 22c0936833a1e365976b4e2727f5105ca4f33252 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Fri, 2 Oct 2026 10:27:16 -0600
Subject: [PATCH 06/14] fix(mosaic): drop children from skeleton section parts
 and add a skeletons skill reference

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/SKILL.md                |  1 +
 .claude/skills/mosaic/references/motion.md    | 55 +----------
 .claude/skills/mosaic/references/skeletons.md | 95 +++++++++++++++++++
 .../src/components/section/section.test.tsx   | 36 +++++++
 .../mosaic/src/components/section/section.tsx | 22 +++--
 packages/swingset/src/lib/utils.ts            |  2 +-
 6 files changed, 149 insertions(+), 62 deletions(-)
 create mode 100644 .claude/skills/mosaic/references/skeletons.md

diff --git a/.claude/skills/mosaic/SKILL.md b/.claude/skills/mosaic/SKILL.md
index 263cb8a65e0..5a96037cdc3 100644
--- a/.claude/skills/mosaic/SKILL.md
+++ b/.claude/skills/mosaic/SKILL.md
@@ -67,6 +67,7 @@ test. Copy from it.
 | Building on / authoring a headless primitive (`src/primitives/`)       | `references/headless.md`                               |
 | Styling a component (tokens, `stylex.create`, `themeProps`, CSS build) | `references/stylex.md`                                 |
 | Building an enter/exit transition, or any motion that reads as wrong   | `references/motion.md`                                 |
+| Building a loading skeleton (bones, sizing, the wave)                  | `references/skeletons.md`                              |
 | Writing the model (the Clerk adapter, `status`, permissions)           | `references/models.md`                                 |
 | Writing the controller (local state, pending, action wrapping)         | `references/controllers.md`                            |
 | Authoring or debugging a state machine, or wiring one to React         | `references/machines.md` → in-tree `machine/README.md` |
diff --git a/.claude/skills/mosaic/references/motion.md b/.claude/skills/mosaic/references/motion.md
index 8976eb85e0c..c32b06f070b 100644
--- a/.claude/skills/mosaic/references/motion.md
+++ b/.claude/skills/mosaic/references/motion.md
@@ -52,57 +52,10 @@ For entrances, opacity takes `--cl-ease-enter`: there is nothing
 past `1` to overshoot into, so the pass is clamped away and only its cost — the
 slower approach to full opacity — is left.
 
-## Loading skeletons: one wave down the page
-
-Every loading placeholder pulses through one shared wave, never a local pulse of its
-own. The pieces:
-
-- `skeletonStyles.bone` (fill and radius) and `skeletonStyles.line` in
-  `utils/skeleton.styles.ts`. `line` is a `1lh` box, so it holds exactly one line
-  of the text it replaces, and its `::before` bar is `1cap` tall (`0.7em`
-  fallback) and sits on the baseline, covering the same band as the text's
-  capitals. Text bars are square-cornered; only media bones take a radius.
-- Size a text bone's width in `ch` from the content it usually holds, at the short
-  end, so it reads like real text and shrinks with `maxWidth: 100%` on narrow
-  screens: a card or page title `6ch`, a label `12ch`, a description `20ch`, an
-  email `16ch`, a US phone number `15ch`, a backup code `7ch`.
-- `skeletonStyles.wave`: the keyframes (opacity `1 → 0.32 → 1` over the first 56%
-  of a 2s cycle, then a hold), on `--cl-ease-in-out`. A component with its own
-  fill and shape, such as `Avatar.Fallback`, takes `wave` alone.
-- `useSkeletonWave(enabled)` in `hooks/`: before first paint it sets a negative
-  `animation-delay` from the element's page position, `-(now − y × 2.1ms/px) mod
-2000ms`, and marks it `data-skeleton-wave`. Every bone shares the document clock
-  and lags it by its height on the page, so skeletons that mount separately read
-  as a single wave, and two lines in one row sit on different parts of it.
-
-`wave` only animates once `data-skeleton-wave` is set. Without that gate, a
-server-rendered skeleton pulses in unison before hydration and then jumps into
-phase. The keyframe duration and `PERIOD_MS` in the hook must match.
-
-Tuning, all relative to each other: the hook's px rate sets how fast the wave
-travels; the cycle over that rate sets the spacing between crests (~950px, about
-one crest per panel); the keyframe's dip width sets how wide a crest is. Shorten
-the cycle alone and crests crowd together; widen the dip alone and the hold
-disappears.
-
-Use the `skeleton` prop on `Section` parts and `Panel.Title` rather than composing
-bones by hand. Any new skeleton must measure the same as the content it replaces:
-`Section.Actions skeleton` exists because a 28px menu trigger outgrew a 20px line.
-Off under `prefers-reduced-motion: reduce`.
-
-**What to render as bones.** A bone stands in for content that is being fetched and
-not yet on screen. When a surface loads as one unit (a panel, a table on first
-load), render the whole thing as bones, including titles, card headings and column
-headers that are already known: one loading state reads cleaner, carries the wave,
-and swaps to content in one moment. Content that isn't being fetched keeps
-rendering. A section loaded by a later request shows bones beside sections that
-have already loaded, and a table moving to another page turns its rows into bones
-while its headers and controls stay. Whether a table's controls are bones on first
-load is still open.
-
-Each component defines its own bones (`skeleton` props, or `skeletonStyles.wave`
-for a component with its own shape), but every bone uses the shared wave and the
-same fill, `--cl-color-neutral-alpha-200`.
+## Loading skeletons
+
+Loading placeholders pulse in one shared wave on `--cl-ease-in-out`. How to build
+them, size them, and tune the wave is in `skeletons.md`.
 
 ## A curve has a direction — don't run the entrance curve backwards
 
diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
new file mode 100644
index 00000000000..ade0a25269f
--- /dev/null
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -0,0 +1,95 @@
+# Skeletons: loading placeholders
+
+A skeleton stands in for content that is being fetched and is not yet on screen. It
+has the exact size of that content, so the swap never shifts layout, and every bone
+on the page pulses in one shared wave.
+
+## What to render as bones
+
+When a surface loads as one unit (a panel, a table on first load), render the whole
+thing as bones, including titles, card headings and column headers that are already
+known: one loading state reads cleaner, carries the wave, and swaps to content in one
+moment. A unit is what the user sees appear at once, however many requests feed it.
+
+Content that isn't being fetched keeps rendering. A section loaded by a later request
+shows bones beside sections that have already loaded, and a table moving to another
+page turns its rows into bones while its headers and controls stay. Whether a table's
+controls are bones on first load is still open.
+
+Actions (buttons, menus) are not drawn, but their height is held when it outgrows
+the content beside it.
+
+## Building one
+
+Each component defines its own bones, but every bone uses the shared wave and the
+same fill, `--cl-color-neutral-alpha-200`.
+
+- **Use part props first.** `Section.Group`, `Section.Title`, `Section.Media`,
+  `Section.Label`, `Section.Description`, `Section.Actions`, and `Panel.Title` take
+  `skeleton`. A skeleton part renders empty (its children are dropped); a skeleton
+  group is `aria-hidden`.
+- **Compose them in a `.skeleton.tsx`** next to the view it mirrors, e.g.
+  `user-profile-active-devices-section.skeleton.tsx` exporting
+  `UserProfileActiveDevicesSectionSkeleton`. A panel's skeleton composes its
+  sections' skeletons. Don't add a `loading` prop to the view.
+- **Announce it.** The skeleton is hidden from assistive technology, so render a
+  `VisuallyHidden` `role='status'` message ("Loading active devices") beside it.
+- **Rows:** a typical count (2–3), not the page size.
+- **Fewest nodes:** one element per bone, no wrappers. A bone is the real part
+  rendered empty, so it inherits that part's padding, type size and line height.
+- **A component with its own shape** (a part that needs a skeleton but isn't covered
+  above) composes the pieces in `utils/skeleton.styles.ts` itself:
+  - `skeletonStyles.bone`: fill and radius, for media and blocks.
+  - `skeletonStyles.line`: a `1lh` box holding one line of text, whose `::before`
+    bar is `1cap` tall (`0.7em` fallback) on the baseline, square-cornered.
+  - `skeletonStyles.wave`: the animation. `Avatar.Fallback`, which has its own fill
+    and circle, takes `wave` alone.
+  - plus a `useSkeletonWave(enabled)` ref (`hooks/useSkeletonWave.ts`) on the same
+    element. Without it, `wave` never starts.
+
+## Sizing
+
+- **Height must match exactly.** Line bones fill one line of the part's own type, so
+  text rows match by construction. Watch anything taller than a line:
+  `Section.Actions skeleton` exists because a 28px `sm` menu trigger outgrew a 20px
+  line. `Panel.Title skeleton` puts the bone on the inner heading because the outer
+  `div` has a smaller line height.
+- **Width in `ch`**, from the content the bone usually holds, at the short end, so it
+  reads like real text and shrinks with `maxWidth: 100%` on narrow screens: a card or
+  page title `6ch`, a label `12ch`, a description `20ch`, an email `16ch`, a US phone
+  number `15ch`, a backup code `7ch`. Override a part's default with `xstyle`.
+- **Uniform across rows.** Every row uses the same widths; within a row, lines
+  differ.
+
+## The wave
+
+- `skeletonStyles.wave`: opacity `1 → 0.32 → 1` over the first 56% of a 2s cycle,
+  then a hold, on `--cl-ease-in-out`. Off under `prefers-reduced-motion: reduce`.
+- `useSkeletonWave` sets a negative `animation-delay` before first paint, from the
+  element's page position: `-(now − y × 2.1ms/px) mod 2000ms`. Every bone shares
+  the document clock and lags it by its height on the page, so skeletons that mount
+  separately read as one wave moving down the page, and two lines in one row sit on
+  different parts of it.
+- `wave` only animates once the hook sets `data-skeleton-wave`. Without that gate, a
+  server-rendered skeleton pulses in unison before hydration, then jumps into phase.
+- The keyframe duration and the hook's `PERIOD_MS` must match.
+- Tuning, all relative: the px rate sets how fast the wave travels; the cycle over
+  that rate sets the spacing between crests (~950px, about one per panel); the dip's
+  share of the cycle sets how wide a crest is. Shorten the cycle alone and crests
+  crowd together; widen the dip alone and the hold disappears.
+
+## When to show it
+
+Not decided by the skeleton. The wiring around a panel owns it. The planned gate is
+`useSpinDelay(loading, { delay: 150, minDuration: 500 })` with the skeleton mounted
+but `visibility: hidden` until the delay passes, so a fast load never flashes it and
+nothing shifts when it appears.
+
+## Checking one
+
+- Add a swingset **Loading** story with a **Reload** button that fakes a load (see
+  `section.stories.tsx` → `Loading`).
+- Measure, don't eyeball: with `agent-browser`, compare each row's and card's
+  `getBoundingClientRect().height` in the skeleton and loaded states. They must be
+  equal, except where the number of rows differs.
+- Clear swingset's `.next` after any `*.styles.ts` edit.
diff --git a/packages/mosaic/src/components/section/section.test.tsx b/packages/mosaic/src/components/section/section.test.tsx
index 3eea27e3a23..8d64cc33b1b 100644
--- a/packages/mosaic/src/components/section/section.test.tsx
+++ b/packages/mosaic/src/components/section/section.test.tsx
@@ -361,4 +361,40 @@ describe('Section', () => {
 
     expect(screen.getByTestId('item')).toHaveAttribute('data-wrap', '');
   });
+
+  it('hides a skeleton card and renders its parts empty', () => {
+    render(
+      <Section.Root>
+        <Section.Group
+          skeleton
+          data-testid='group'
+        >
+          <Section.Header>
+            <Section.Title skeleton>Account</Section.Title>
+          </Section.Header>
+          <Section.Body>
+            <Section.Items>
+              <Section.Item>
+                <Section.Media skeleton>media</Section.Media>
+                <Section.Content>
+                  <Section.Label skeleton>Name</Section.Label>
+                  <Section.Description skeleton>Description</Section.Description>
+                </Section.Content>
+                <Section.Actions skeleton>
+                  <button type='button'>Edit</button>
+                </Section.Actions>
+              </Section.Item>
+            </Section.Items>
+          </Section.Body>
+        </Section.Group>
+      </Section.Root>,
+    );
+
+    const group = screen.getByTestId('group');
+    expect(group).toHaveAttribute('aria-hidden', 'true');
+    expect(group).not.toHaveAttribute('role');
+    expect(group).toHaveTextContent('');
+    expect(group.querySelector('button')).toBeNull();
+    expect(group.querySelectorAll('[data-skeleton]')).toHaveLength(5);
+  });
 });
diff --git a/packages/mosaic/src/components/section/section.tsx b/packages/mosaic/src/components/section/section.tsx
index f0a0c9bc1f6..15a35fd0fd8 100644
--- a/packages/mosaic/src/components/section/section.tsx
+++ b/packages/mosaic/src/components/section/section.tsx
@@ -106,7 +106,7 @@ const Header = React.forwardRef<HTMLDivElement, SectionHeaderProps>(function Sec
 });
 
 const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function SectionTitle(
-  { id: idProp, skeleton = false, xstyle, ...rest },
+  { id: idProp, skeleton = false, xstyle, children, ...rest },
   ref,
 ) {
   const setTitleId = React.useContext(SectionGroupContext);
@@ -140,7 +140,9 @@ const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function S
         xstyle,
       ]}
       {...mergeStyleProps(themeProps('section-title', { skeleton }), rest)}
-    />
+    >
+      {skeleton ? undefined : children}
+    </Heading>
   );
 });
 
@@ -204,7 +206,7 @@ const Item = React.forwardRef<HTMLDivElement, SectionItemProps>(function Section
 });
 
 const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function SectionMedia(
-  { size = 'md', skeleton = false, render, xstyle, ...rest },
+  { size = 'md', skeleton = false, render, xstyle, children, ...rest },
   ref,
 ) {
   const wave = useSkeletonWave<HTMLDivElement>(skeleton);
@@ -223,7 +225,7 @@ const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function Secti
         skeleton && skeletonStyles.wave,
         xstyle,
       ),
-      rest,
+      { ...rest, children: skeleton ? undefined : children },
     ),
   });
 });
@@ -247,7 +249,7 @@ const Content = React.forwardRef<HTMLDivElement, SectionContentProps>(function S
 });
 
 const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function SectionLabel(
-  { skeleton = false, render, xstyle, ...rest },
+  { skeleton = false, render, xstyle, children, ...rest },
   ref,
 ) {
   const wave = useSkeletonWave<HTMLDivElement>(skeleton);
@@ -267,13 +269,13 @@ const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function Secti
         skeleton && styles.labelSkeleton,
         xstyle,
       ),
-      rest,
+      { ...rest, children: skeleton ? undefined : children },
     ),
   });
 });
 
 const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(function SectionDescription(
-  { skeleton = false, render, xstyle, ...rest },
+  { skeleton = false, render, xstyle, children, ...rest },
   ref,
 ) {
   const inHeader = React.useContext(SectionHeaderContext);
@@ -296,13 +298,13 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
         skeleton && styles.descriptionSkeleton,
         xstyle,
       ),
-      rest,
+      { ...rest, children: skeleton ? undefined : children },
     ),
   });
 });
 
 const Actions = React.forwardRef<HTMLDivElement, SectionActionsProps>(function SectionActions(
-  { skeleton = false, render, xstyle, ...rest },
+  { skeleton = false, render, xstyle, children, ...rest },
   ref,
 ) {
   const wrap = React.useContext(SectionItemWrapContext);
@@ -322,7 +324,7 @@ const Actions = React.forwardRef<HTMLDivElement, SectionActionsProps>(function S
         skeleton && styles.actionsSkeleton,
         xstyle,
       ),
-      rest,
+      { ...rest, children: skeleton ? undefined : children },
     ),
   });
 });
diff --git a/packages/swingset/src/lib/utils.ts b/packages/swingset/src/lib/utils.ts
index fd78a50df81..737be1812af 100644
--- a/packages/swingset/src/lib/utils.ts
+++ b/packages/swingset/src/lib/utils.ts
@@ -7,6 +7,6 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
 
-export function fillsFrame(storyModule: StoryModule) {
+export function fillsFrame(storyModule: StoryModule): boolean {
   return storyModule.meta.navigation?.category === 'Sections';
 }

From 10176cbdb1c64277f7ae18d09a55d23ac589ba0e Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Fri, 2 Oct 2026 16:10:36 -0600
Subject: [PATCH 07/14] feat(mosaic): make skeleton cards inert and let their
 parts inherit the skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/skeletons.md | 10 ++++---
 .../mosaic/src/components/panel/panel.tsx     |  3 +-
 .../src/components/section/section.test.tsx   | 23 +++++++++++----
 .../mosaic/src/components/section/section.tsx | 29 +++++++++++++++----
 ...rofile-active-devices-section.skeleton.tsx | 11 +++----
 packages/swingset/src/stories/section.mdx     | 15 +++++-----
 .../swingset/src/stories/section.stories.tsx  | 25 +++++++---------
 7 files changed, 70 insertions(+), 46 deletions(-)

diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
index 90d7f1d0d2d..6d67ba0a0f1 100644
--- a/.claude/skills/mosaic/references/skeletons.md
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -24,10 +24,12 @@ the content beside it.
 Each component defines its own bones, but every bone uses the shared wave and the
 same fill, `--cl-color-neutral-alpha-200`.
 
-- **Use part props first.** `Section.Group`, `Section.Title`, `Section.Media`,
-  `Section.Label`, `Section.Description`, `Section.Actions`, and `Panel.Title` take
-  `skeleton`. A skeleton part renders empty (its children are dropped); a skeleton
-  group is `aria-hidden`.
+- **Use part props first.** `Section.Group skeleton` makes every Title, Media, Label,
+  Description, and Actions inside it a bone, so the parts need no prop of their own
+  (`skeleton={false}` opts one out). Parts also take `skeleton` standalone, as does
+  `Panel.Title`. A skeleton part renders empty (its children are dropped), so a
+  view's own markup can be reused with the group flipped; a skeleton group and
+  `Panel.Title` are `inert` and `aria-hidden`.
 - **Compose them in a `.skeleton.tsx`** next to the view it mirrors, e.g.
   `user-profile-active-devices-section.skeleton.tsx` exporting
   `UserProfileActiveDevicesSectionSkeleton`. A panel's skeleton composes its
diff --git a/packages/mosaic/src/components/panel/panel.tsx b/packages/mosaic/src/components/panel/panel.tsx
index 813a22166bd..f7550cde17d 100644
--- a/packages/mosaic/src/components/panel/panel.tsx
+++ b/packages/mosaic/src/components/panel/panel.tsx
@@ -1,3 +1,4 @@
+import { inertProps } from '@clerk/shared/inert';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
@@ -62,7 +63,7 @@ const Title = React.forwardRef<HTMLDivElement, PanelTitleProps>(function PanelTi
       ...mergeStyleProps(
         themeProps('panel-title', { skeleton }),
         stylex.props(reset.base, styles.title, xstyle),
-        skeleton ? { 'aria-hidden': true } : {},
+        skeleton ? { 'aria-hidden': true, ...inertProps(true) } : {},
         rest,
       ),
       children: skeleton ? (
diff --git a/packages/mosaic/src/components/section/section.test.tsx b/packages/mosaic/src/components/section/section.test.tsx
index 2753f40783f..a674dcefc41 100644
--- a/packages/mosaic/src/components/section/section.test.tsx
+++ b/packages/mosaic/src/components/section/section.test.tsx
@@ -402,7 +402,7 @@ describe('Section', () => {
     expect(screen.getByTestId('item')).toHaveAttribute('data-wrap', '');
   });
 
-  it('hides a skeleton card and renders its parts empty', () => {
+  it('turns a skeleton card into inert, empty placeholders', () => {
     render(
       <Section.Root>
         <Section.Group
@@ -410,17 +410,17 @@ describe('Section', () => {
           data-testid='group'
         >
           <Section.Header>
-            <Section.Title skeleton>Account</Section.Title>
+            <Section.Title>Account</Section.Title>
           </Section.Header>
           <Section.Body>
             <Section.Items>
               <Section.Item>
-                <Section.Media skeleton>media</Section.Media>
+                <Section.Media>media</Section.Media>
                 <Section.Content>
-                  <Section.Label skeleton>Name</Section.Label>
-                  <Section.Description skeleton>Description</Section.Description>
+                  <Section.Label>Name</Section.Label>
+                  <Section.Description>Description</Section.Description>
                 </Section.Content>
-                <Section.Actions skeleton>
+                <Section.Actions>
                   <button type='button'>Edit</button>
                 </Section.Actions>
               </Section.Item>
@@ -432,9 +432,20 @@ describe('Section', () => {
 
     const group = screen.getByTestId('group');
     expect(group).toHaveAttribute('aria-hidden', 'true');
+    expect(group).toHaveAttribute('inert');
     expect(group).not.toHaveAttribute('role');
     expect(group).toHaveTextContent('');
     expect(group.querySelector('button')).toBeNull();
     expect(group.querySelectorAll('[data-skeleton]')).toHaveLength(5);
   });
+
+  it('lets a part opt out of its card skeleton', () => {
+    render(
+      <Section.Group skeleton>
+        <Section.Label skeleton={false}>Name</Section.Label>
+      </Section.Group>,
+    );
+
+    expect(screen.getByText('Name')).not.toHaveAttribute('data-skeleton');
+  });
 });
diff --git a/packages/mosaic/src/components/section/section.tsx b/packages/mosaic/src/components/section/section.tsx
index cb1b6dcc06b..5cb10f58212 100644
--- a/packages/mosaic/src/components/section/section.tsx
+++ b/packages/mosaic/src/components/section/section.tsx
@@ -1,3 +1,4 @@
+import { inertProps } from '@clerk/shared/inert';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
 import { useMergeRefs } from '@floating-ui/react';
 import * as stylex from '@stylexjs/stylex';
@@ -46,6 +47,12 @@ const SectionGroupContext = React.createContext<React.Dispatch<React.SetStateAct
 const SectionHeaderContext = React.createContext(false);
 const SectionItemsContext = React.createContext(false);
 const SectionItemWrapContext = React.createContext(false);
+const SectionSkeletonContext = React.createContext(false);
+
+function useInheritedSkeleton(skeleton: boolean | undefined) {
+  const inherited = React.useContext(SectionSkeletonContext);
+  return skeleton ?? inherited;
+}
 
 const Root = React.forwardRef<HTMLElement, SectionRootProps>(function SectionRoot({ render, xstyle, ...rest }, ref) {
   return useRender({
@@ -69,6 +76,7 @@ const Group = React.forwardRef<HTMLDivElement, SectionGroupProps>(function Secti
     props: skeleton
       ? {
           'aria-hidden': true,
+          ...inertProps(true),
           ...mergeStyleProps(
             themeProps('section-group', { skeleton }),
             stylex.props(reset.base, styles.group, xstyle),
@@ -83,7 +91,11 @@ const Group = React.forwardRef<HTMLDivElement, SectionGroupProps>(function Secti
         },
   });
 
-  return <SectionGroupContext.Provider value={setTitleId}>{element}</SectionGroupContext.Provider>;
+  return (
+    <SectionGroupContext.Provider value={setTitleId}>
+      <SectionSkeletonContext.Provider value={skeleton}>{element}</SectionSkeletonContext.Provider>
+    </SectionGroupContext.Provider>
+  );
 });
 
 const Header = React.forwardRef<HTMLDivElement, SectionHeaderProps>(function SectionHeader(
@@ -107,9 +119,10 @@ const Header = React.forwardRef<HTMLDivElement, SectionHeaderProps>(function Sec
 });
 
 const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function SectionTitle(
-  { id: idProp, skeleton = false, xstyle, children, ...rest },
+  { id: idProp, skeleton: skeletonProp, xstyle, children, ...rest },
   ref,
 ) {
+  const skeleton = useInheritedSkeleton(skeletonProp);
   const setTitleId = React.useContext(SectionGroupContext);
   const generatedId = React.useId();
   const level = useHeadingLevel();
@@ -207,9 +220,10 @@ const Item = React.forwardRef<HTMLDivElement, SectionItemProps>(function Section
 });
 
 const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function SectionMedia(
-  { size = 'md', skeleton = false, render, xstyle, children, ...rest },
+  { size = 'md', skeleton: skeletonProp, render, xstyle, children, ...rest },
   ref,
 ) {
+  const skeleton = useInheritedSkeleton(skeletonProp);
   const wave = useSkeletonWave<HTMLDivElement>(skeleton);
 
   return useRender({
@@ -250,9 +264,10 @@ const Content = React.forwardRef<HTMLDivElement, SectionContentProps>(function S
 });
 
 const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function SectionLabel(
-  { skeleton = false, render, xstyle, children, ...rest },
+  { skeleton: skeletonProp, render, xstyle, children, ...rest },
   ref,
 ) {
+  const skeleton = useInheritedSkeleton(skeletonProp);
   const wave = useSkeletonWave<HTMLDivElement>(skeleton);
 
   return useRender({
@@ -276,9 +291,10 @@ const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function Secti
 });
 
 const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(function SectionDescription(
-  { skeleton = false, render, xstyle, children, ...rest },
+  { skeleton: skeletonProp, render, xstyle, children, ...rest },
   ref,
 ) {
+  const skeleton = useInheritedSkeleton(skeletonProp);
   const inHeader = React.useContext(SectionHeaderContext);
   const wave = useSkeletonWave<HTMLDivElement>(skeleton);
 
@@ -305,9 +321,10 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
 });
 
 const Actions = React.forwardRef<HTMLDivElement, SectionActionsProps>(function SectionActions(
-  { skeleton = false, render, xstyle, children, ...rest },
+  { skeleton: skeletonProp, render, xstyle, children, ...rest },
   ref,
 ) {
+  const skeleton = useInheritedSkeleton(skeletonProp);
   const wrap = React.useContext(SectionItemWrapContext);
   const inHeader = React.useContext(SectionHeaderContext);
 
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
index c66dc7ffa11..766b55beeab 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
@@ -16,19 +16,16 @@ export function UserProfileActiveDevicesSectionSkeleton() {
       <Section.Root>
         <Section.Group skeleton>
           <Section.Header>
-            <Section.Title skeleton />
+            <Section.Title />
           </Section.Header>
           <Section.Body>
             <Section.Items>
               {SKELETON_ITEMS.map(item => (
                 <Section.Item key={item}>
-                  <Section.Media
-                    size='lg'
-                    skeleton
-                  />
+                  <Section.Media size='lg' />
                   <Section.Content>
-                    <Section.Label skeleton />
-                    <Section.Description skeleton />
+                    <Section.Label />
+                    <Section.Description />
                   </Section.Content>
                 </Section.Item>
               ))}
diff --git a/packages/swingset/src/stories/section.mdx b/packages/swingset/src/stories/section.mdx
index 4482b154dd5..5003facc90d 100644
--- a/packages/swingset/src/stories/section.mdx
+++ b/packages/swingset/src/stories/section.mdx
@@ -50,13 +50,14 @@ fixed leading slot sized to the text, for a provider logo or a lock.
 than `26rem`. `sectionCompactStyles.hidden` and `sectionCompactStyles.only` toggle inline content at
 the same width.
 
-`Section.Group`, `Section.Title`, `Section.Media`, `Section.Label`, and `Section.Description` take
-`skeleton` for a loading state. A skeleton part renders empty as a placeholder the size of the
-content it stands in for, and a skeleton group is hidden from assistive technology, so pair it with
-a visually hidden status message. Placeholders pulse in one wave that travels down the page, across
-every skeleton on it. When to show the skeleton, and for how long, is up to the caller.
-`Section.Actions skeleton` draws nothing and holds the height of a small control, for items whose
-actions would otherwise make them taller than their content.
+`Section.Group skeleton` turns a card into its loading state. The title, media, label,
+description, and actions inside it become placeholders, each the size of the content it stands in
+for, and their children are not rendered. A part can also take `skeleton` on its own, or
+`skeleton={false}` to stay as content inside a skeleton card. Skeleton actions draw nothing and hold
+the height of a small control. A skeleton card is inert and hidden from assistive technology, so
+pair it with a visually hidden status message. Placeholders pulse in one wave that travels down the
+page, across every skeleton on it. When to show the skeleton, and for how long, is up to the
+caller.
 
 `Section.Title` renders at the level from the nearest `HeadingLevelProvider`, or `h2` outside one.
 On a page, put the sections in `Panel.Sections` so the card titles sit one level below the page
diff --git a/packages/swingset/src/stories/section.stories.tsx b/packages/swingset/src/stories/section.stories.tsx
index 20ce039154a..fd014c80a82 100644
--- a/packages/swingset/src/stories/section.stories.tsx
+++ b/packages/swingset/src/stories/section.stories.tsx
@@ -566,28 +566,23 @@ export function Loading() {
       <Section.Root>
         <Section.Group skeleton={loading}>
           <Section.Header>
-            <Section.Title skeleton={loading}>{loading ? null : 'Active devices'}</Section.Title>
+            <Section.Title>Active devices</Section.Title>
           </Section.Header>
           <Section.Body>
             <Section.Items>
               {loadingItems.map(item => (
                 <Section.Item key={item.label}>
-                  <Section.Media
-                    size='lg'
-                    skeleton={loading}
-                  >
-                    {loading ? null : (
-                      <IconFrame>
-                        <Icon
-                          name={item.icon}
-                          size='lg'
-                        />
-                      </IconFrame>
-                    )}
+                  <Section.Media size='lg'>
+                    <IconFrame>
+                      <Icon
+                        name={item.icon}
+                        size='lg'
+                      />
+                    </IconFrame>
                   </Section.Media>
                   <Section.Content>
-                    <Section.Label skeleton={loading}>{loading ? null : item.label}</Section.Label>
-                    <Section.Description skeleton={loading}>{loading ? null : item.description}</Section.Description>
+                    <Section.Label>{item.label}</Section.Label>
+                    <Section.Description>{item.description}</Section.Description>
                   </Section.Content>
                 </Section.Item>
               ))}

From d4f433259761bf785057e3d8c6ae4f966cf50f0f Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Fri, 2 Oct 2026 16:57:21 -0600
Subject: [PATCH 08/14] refactor(mosaic): render the active devices skeleton
 from the real view with mock data

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/skeletons.md | 38 ++++++++++------
 ...rofile-active-devices-section.skeleton.tsx | 43 +++++--------------
 ...er-profile-active-devices-section.view.tsx | 22 ++++++----
 3 files changed, 50 insertions(+), 53 deletions(-)

diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
index 6d67ba0a0f1..8140e884040 100644
--- a/.claude/skills/mosaic/references/skeletons.md
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -24,19 +24,31 @@ the content beside it.
 Each component defines its own bones, but every bone uses the shared wave and the
 same fill, `--cl-color-neutral-alpha-200`.
 
-- **Use part props first.** `Section.Group skeleton` makes every Title, Media, Label,
-  Description, and Actions inside it a bone, so the parts need no prop of their own
-  (`skeleton={false}` opts one out). Parts also take `skeleton` standalone, as does
-  `Panel.Title`. A skeleton part renders empty (its children are dropped), so a
-  view's own markup can be reused with the group flipped; a skeleton group and
-  `Panel.Title` are `inert` and `aria-hidden`.
-- **Compose them in a `.skeleton.tsx`** next to the view it mirrors, e.g.
-  `user-profile-active-devices-section.skeleton.tsx` exporting
-  `UserProfileActiveDevicesSectionSkeleton`. A panel's skeleton composes its
-  sections' skeletons. Don't add a `loading` prop to the view.
-- **Announce it.** The skeleton is hidden from assistive technology, so render a
-  `VisuallyHidden` `role='status'` message ("Loading active devices") beside it.
-- **Rows:** a typical count (2–3), not the page size.
+- **Render the real view with mock data.** The view takes `skeleton` and passes it
+  to its container (`<Section.Group skeleton={skeleton}>`). Every part inside
+  inherits it and becomes a bone (`skeleton={false}` opts one out), drops its
+  children, and the container turns `inert` and `aria-hidden`. Because the
+  skeleton is the view's own markup, it can't drift from it: change a row and the
+  skeleton changes with it. While `skeleton` is set, the view skips its dialogs and
+  confirmations.
+- **The `.skeleton.tsx` is one line** next to the view, rendering it with a
+  `PLACEHOLDER_*` constant:
+  `<UserProfileActiveDevicesSectionView skeleton devices={PLACEHOLDER_DEVICES} />`
+  (see `user-profile-active-devices-section.skeleton.tsx`). The mock values are
+  never shown; they only decide the shape. A panel's skeleton composes its
+  sections' skeletons.
+- **Mock data decides row count and shape.** Aim it at the most common loaded
+  shape: a typical count (2–3), every line present, and the branch real data
+  usually takes (a current device, not the empty state). When the count is known
+  before the fetch, use it instead: a table moving between pages with a known
+  total shows exactly `min(pageSize, total − offset)` rows, so nothing shifts. A
+  first load or a new search can't know, so it uses the typical count and accepts
+  a shift. The page size is a maximum, not a count.
+- **Announce it.** The skeleton is hidden from assistive technology, so the view
+  renders a `VisuallyHidden` `role='status'` message ("Loading active devices")
+  while `skeleton` is set.
+- **Parts also take `skeleton` standalone**, as does `Panel.Title`, for a bone
+  outside a skeleton container.
 - **Fewest nodes:** one element per bone, no wrappers. A bone is the real part
   rendered empty, so it inherits that part's padding, type size and line height.
 - **A component with its own shape** (a part that needs a skeleton but isn't covered
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
index 766b55beeab..dd8ff093af2 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.skeleton.tsx
@@ -1,38 +1,17 @@
-import * as stylex from '@stylexjs/stylex';
+import type { UserProfileDevice } from './user-profile-active-devices.types';
+import { UserProfileActiveDevicesSectionView } from './user-profile-active-devices-section.view';
 
-import { Section } from '../../components/section';
-import { VisuallyHidden } from '../../components/visually-hidden';
-import { useMessages } from '../../localization';
-import { styles } from './user-profile-security-panel.styles';
-
-const SKELETON_ITEMS = [0, 1, 2];
+const PLACEHOLDER_DEVICES: UserProfileDevice[] = [
+  { id: 'current', name: 'Chrome on macOS', description: 'San Francisco, US', type: 'desktop', isCurrent: true },
+  { id: 'phone', name: 'Safari on iOS', description: 'San Francisco, US', type: 'mobile' },
+  { id: 'laptop', name: 'Firefox on Windows', description: 'Denver, US', type: 'desktop' },
+];
 
 export function UserProfileActiveDevicesSectionSkeleton() {
-  const m = useMessages('userProfileActiveDevices');
-
   return (
-    <div {...stylex.props(styles.sectionCards)}>
-      <VisuallyHidden role='status'>{m.loading}</VisuallyHidden>
-      <Section.Root>
-        <Section.Group skeleton>
-          <Section.Header>
-            <Section.Title />
-          </Section.Header>
-          <Section.Body>
-            <Section.Items>
-              {SKELETON_ITEMS.map(item => (
-                <Section.Item key={item}>
-                  <Section.Media size='lg' />
-                  <Section.Content>
-                    <Section.Label />
-                    <Section.Description />
-                  </Section.Content>
-                </Section.Item>
-              ))}
-            </Section.Items>
-          </Section.Body>
-        </Section.Group>
-      </Section.Root>
-    </div>
+    <UserProfileActiveDevicesSectionView
+      skeleton
+      devices={PLACEHOLDER_DEVICES}
+    />
   );
 }
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
index e9b1373ce80..59ccc805d25 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
@@ -9,6 +9,7 @@ import { Badge } from '../../components/badge';
 import { Button } from '../../components/button';
 import { Dialog } from '../../components/dialog';
 import { Section } from '../../components/section';
+import { VisuallyHidden } from '../../components/visually-hidden';
 import { useListRemovalFocus } from '../../hooks/use-list-removal-focus';
 import type { MosaicMessages } from '../../localization';
 import { fill, plural, useLocale, useMessages } from '../../localization';
@@ -23,12 +24,14 @@ export interface UserProfileActiveDevicesSectionViewProps {
   devices: UserProfileDevice[];
   onSignOutDevice?: (id: string) => void | Promise<void>;
   onSignOutAllOtherDevices?: () => void | Promise<void>;
+  skeleton?: boolean;
 }
 
 export function UserProfileActiveDevicesSectionView({
   devices,
   onSignOutDevice,
   onSignOutAllOtherDevices,
+  skeleton = false,
 }: UserProfileActiveDevicesSectionViewProps) {
   const m = useMessages('userProfileActiveDevices');
   const locale = useLocale();
@@ -84,8 +87,9 @@ export function UserProfileActiveDevicesSectionView({
 
   return (
     <div {...stylex.props(styles.sectionCards)}>
+      {skeleton ? <VisuallyHidden role='status'>{m.loading}</VisuallyHidden> : null}
       <Section.Root>
-        <Section.Group>
+        <Section.Group skeleton={skeleton}>
           <Section.Header>
             <Section.Title>{m.title}</Section.Title>
             {onSignOutAllOtherDevices && otherDevices.length > 0 ? (
@@ -133,7 +137,7 @@ export function UserProfileActiveDevicesSectionView({
           </Section.Body>
         </Section.Group>
       </Section.Root>
-      {onSignOutAllOtherDevices ? (
+      {onSignOutAllOtherDevices && !skeleton ? (
         <Confirmation
           open={isSignOutAllOpen}
           onOpenChange={open => {
@@ -153,12 +157,14 @@ export function UserProfileActiveDevicesSectionView({
           errorMessage={signOutAllError}
         />
       ) : null}
-      <UserProfileDeviceDetailsDialog
-        handle={deviceDetails}
-        finalFocus={removalFocus.finalFocus}
-        onSignOut={signOutDeviceAt}
-      />
-      {onSignOutDevice ? (
+      {skeleton ? null : (
+        <UserProfileDeviceDetailsDialog
+          handle={deviceDetails}
+          finalFocus={removalFocus.finalFocus}
+          onSignOut={signOutDeviceAt}
+        />
+      )}
+      {onSignOutDevice && !skeleton ? (
         <Confirmation
           color='primary'
           handle={signOutDevice}

From 9e54adab1bfb72ba139f8353a3a081f7e6086b5f Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Tue, 6 Oct 2026 11:30:01 -0600
Subject: [PATCH 09/14] feat(mosaic): replace the skeleton wave with a synced
 horizontal shimmer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/SKILL.md                |  2 +-
 .claude/skills/mosaic/references/motion.md    | 26 ++++-----
 .claude/skills/mosaic/references/skeletons.md | 57 +++++++++++--------
 .../mosaic/src/components/avatar/avatar.tsx   | 16 ++++--
 .../mosaic/src/components/panel/panel.tsx     |  8 +--
 .../mosaic/src/components/section/section.tsx | 26 ++++-----
 .../user-profile-backup-codes.view.tsx        |  8 +--
 .../mosaic/src/hooks/use-skeleton-shimmer.ts  | 22 +++++++
 .../mosaic/src/hooks/use-skeleton-wave.ts     | 27 ---------
 packages/mosaic/src/styles/skeleton.styles.ts | 43 +++++++++-----
 packages/mosaic/src/styles/skeleton.stylex.ts |  5 ++
 packages/swingset/src/stories/avatar.mdx      |  4 +-
 .../swingset/src/stories/panel.component.mdx  |  4 +-
 packages/swingset/src/stories/section.mdx     |  4 +-
 14 files changed, 140 insertions(+), 112 deletions(-)
 create mode 100644 packages/mosaic/src/hooks/use-skeleton-shimmer.ts
 delete mode 100644 packages/mosaic/src/hooks/use-skeleton-wave.ts
 create mode 100644 packages/mosaic/src/styles/skeleton.stylex.ts

diff --git a/.claude/skills/mosaic/SKILL.md b/.claude/skills/mosaic/SKILL.md
index 42355381729..c63e93c3216 100644
--- a/.claude/skills/mosaic/SKILL.md
+++ b/.claude/skills/mosaic/SKILL.md
@@ -67,7 +67,7 @@ test. Copy from it.
 | Building on / authoring a headless primitive (`src/primitives/`)                                       | `references/headless.md`                               |
 | Styling a component (tokens, `stylex.create`, `themeProps`, CSS build)                                 | `references/stylex.md`                                 |
 | Building an enter/exit transition, a row that expands and collapses, or any motion that reads as wrong | `references/motion.md`                                 |
-| Building a loading skeleton (bones, sizing, the wave)                                                  | `references/skeletons.md`                              |
+| Building a loading skeleton (bones, sizing, the shimmer)                                               | `references/skeletons.md`                              |
 | Writing the model (the Clerk adapter, `status`, permissions)                                           | `references/models.md`                                 |
 | Writing the controller (local state, pending, action wrapping)                                         | `references/controllers.md`                            |
 | Authoring or debugging a state machine, or wiring one to React                                         | `references/machines.md` → in-tree `machine/README.md` |
diff --git a/.claude/skills/mosaic/references/motion.md b/.claude/skills/mosaic/references/motion.md
index 4b40df00d41..99e91f66eac 100644
--- a/.claude/skills/mosaic/references/motion.md
+++ b/.claude/skills/mosaic/references/motion.md
@@ -5,17 +5,17 @@ Token semantics live in `packages/mosaic/src/tokens.stylex.ts`, above
 how-to layer: the rules that decide a transition's shape, and how to check one
 rather than eyeball it.
 
-| Token                   | Value                                   | For                                        |
-| ----------------------- | --------------------------------------- | ------------------------------------------ |
-| `--cl-duration-instant` | `0s`                                    | hover and press arrival                    |
-| `--cl-duration-fast`    | `0.1s`                                  | exits                                      |
-| `--cl-duration-base`    | `0.15s`                                 | entrances, hover exit                      |
-| `--cl-duration-slow`    | `0.25s`                                 | larger surfaces                            |
-| `--cl-duration-slower`  | `0.35s`                                 | —                                          |
-| `--cl-ease-default`     | `cubic-bezier(0.175, 0.885, 0.32, 1.1)` | things ARRIVING (Swift Out)                |
-| `--cl-ease-enter`       | `cubic-bezier(0, 0, 0.2, 1)`            | arrivals that must not overshoot           |
-| `--cl-ease-exit`        | `cubic-bezier(0.55, 0.085, 0.68, 0.53)` | things LEAVING (In Quad)                   |
-| `--cl-ease-in-out`      | `cubic-bezier(0.645, 0.045, 0.355, 1)`  | rest-to-rest layout, pulses (In Out Cubic) |
+| Token                   | Value                                   | For                                                      |
+| ----------------------- | --------------------------------------- | -------------------------------------------------------- |
+| `--cl-duration-instant` | `0s`                                    | hover and press arrival                                  |
+| `--cl-duration-fast`    | `0.1s`                                  | exits                                                    |
+| `--cl-duration-base`    | `0.15s`                                 | entrances, hover exit                                    |
+| `--cl-duration-slow`    | `0.25s`                                 | larger surfaces                                          |
+| `--cl-duration-slower`  | `0.35s`                                 | —                                                        |
+| `--cl-ease-default`     | `cubic-bezier(0.175, 0.885, 0.32, 1.1)` | things ARRIVING (Swift Out)                              |
+| `--cl-ease-enter`       | `cubic-bezier(0, 0, 0.2, 1)`            | arrivals that must not overshoot                         |
+| `--cl-ease-exit`        | `cubic-bezier(0.55, 0.085, 0.68, 0.53)` | things LEAVING (In Quad)                                 |
+| `--cl-ease-in-out`      | `cubic-bezier(0.645, 0.045, 0.355, 1)`  | rest-to-rest layout, the skeleton shimmer (In Out Cubic) |
 
 Named curves come from [easing.dev](https://www.easing.dev) (Lochie Axon's Easing
 Graphs). Take one from there rather than inventing a bezier, so the catalog stays
@@ -54,8 +54,8 @@ slower approach to full opacity — is left.
 
 ## Loading skeletons
 
-Loading placeholders pulse in one shared wave on `--cl-ease-in-out`. How to build
-them, size them, and tune the wave is in `skeletons.md`.
+Loading placeholders shimmer in sync on `--cl-ease-in-out`. How to build them, size
+them, and tune the shimmer is in `skeletons.md`.
 
 ## A curve has a direction — don't run the entrance curve backwards
 
diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
index 8140e884040..00dbdd68280 100644
--- a/.claude/skills/mosaic/references/skeletons.md
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -2,13 +2,13 @@
 
 A skeleton stands in for content that is being fetched and is not yet on screen. It
 has the exact size of that content, so the swap never shifts layout, and every bone
-on the page pulses in one shared wave.
+on the page shimmers in sync.
 
 ## What to render as bones
 
 When a surface loads as one unit (a panel, a table on first load), render the whole
 thing as bones, including titles, card headings and column headers that are already
-known: one loading state reads cleaner, carries the wave, and swaps to content in one
+known: one loading state reads cleaner, shimmers as one surface, and swaps to content in one
 moment. A unit is what the user sees appear at once, however many requests feed it.
 
 Content that isn't being fetched keeps rendering. A section loaded by a later request
@@ -21,7 +21,7 @@ the content beside it.
 
 ## Building one
 
-Each component defines its own bones, but every bone uses the shared wave and the
+Each component defines its own bones, but every bone uses the shared shimmer and the
 same fill, `--cl-color-neutral-alpha-200`.
 
 - **Render the real view with mock data.** The view takes `skeleton` and passes it
@@ -53,13 +53,15 @@ same fill, `--cl-color-neutral-alpha-200`.
   rendered empty, so it inherits that part's padding, type size and line height.
 - **A component with its own shape** (a part that needs a skeleton but isn't covered
   above) composes the pieces in `styles/skeleton.styles.ts` itself:
-  - `skeletonStyles.bone`: fill and radius, for media and blocks.
+  - `skeletonStyles.shimmer`: the gradient fill and its animation. Media and
+    blocks take it on the element; `Avatar.Fallback`, which has its own circle,
+    takes `shimmer` alone.
+  - `skeletonStyles.bone`: radius, for media and blocks (with `shimmer`).
   - `skeletonStyles.line`: a `1lh` box holding one line of text, whose `::before`
-    bar is `1cap` tall (`0.7em` fallback) on the baseline, square-cornered.
-  - `skeletonStyles.wave`: the animation. `Avatar.Fallback`, which has its own fill
-    and circle, takes `wave` alone.
-  - plus a `useSkeletonWave(enabled)` ref (`hooks/use-skeleton-wave.ts`) on the same
-    element. Without it, `wave` never starts.
+    bar is `1cap` tall (`0.7em` fallback) on the baseline, square-cornered. It
+    moves the shimmer from the element onto the bar.
+  - plus a `useSkeletonShimmer(enabled)` ref (`hooks/use-skeleton-shimmer.ts`) on
+    the same element. Without it, the shimmer stays paused.
 
 ## Sizing
 
@@ -75,22 +77,27 @@ same fill, `--cl-color-neutral-alpha-200`.
 - **Uniform across rows.** Every row uses the same widths; within a row, lines
   differ.
 
-## The wave
-
-- `skeletonStyles.wave`: opacity `1 → 0.32 → 1` over the first 56% of a 2s cycle,
-  then a hold, on `--cl-ease-in-out`. Off under `prefers-reduced-motion: reduce`.
-- `useSkeletonWave` sets a negative `animation-delay` before first paint, from the
-  element's page position: `-(now − y × 2.1ms/px) mod 2000ms`. Every bone shares
-  the document clock and lags it by its height on the page, so skeletons that mount
-  separately read as one wave moving down the page, and two lines in one row sit on
-  different parts of it.
-- `wave` only animates once the hook sets `data-skeleton-wave`. Without that gate, a
-  server-rendered skeleton pulses in unison before hydration, then jumps into phase.
-- The keyframe duration and the hook's `PERIOD_MS` must match.
-- Tuning, all relative: the px rate sets how fast the wave travels; the cycle over
-  that rate sets the spacing between crests (~950px, about one per panel); the dip's
-  share of the cycle sets how wide a crest is. Shorten the cycle alone and crests
-  crowd together; widen the dip alone and the hold disappears.
+## The shimmer
+
+Modeled on React Spectrum's `Skeleton`: a highlight sweeps left to right across every
+bone, and every bone on the page sweeps in step.
+
+- The surface is a `linear-gradient` (fill, highlight, fill at 33% / 50% / 66%)
+  sized to `300%` of the bone, and the keyframes move its `background-position`
+  from `100%` to `0%`, so the highlight crosses once per cycle: 2s on
+  `--cl-ease-in-out`, repeating. The highlight is lighter than the fill in both
+  schemes. Off under `prefers-reduced-motion: reduce`, leaving the plain fill.
+- Text bones animate their `::before` bar, so the highlight stays inside the cap
+  band; media animate the element.
+- `useSkeletonShimmer` locks every bone to the document clock: before first paint
+  it sets the private `--_cl-skeleton-state` variable (`styles/skeleton.stylex.ts`)
+  to `running` and sets each of the element's animations (pseudo-elements
+  included) to `startTime = 0`. Bones that mount at different times sweep
+  together.
+- The animation is `paused` until the hook runs, so a server-rendered skeleton
+  holds a static fill until hydration instead of sweeping out of step and jumping.
+- The sweep is relative to each bone's width, so a wide bar's highlight moves
+  faster than a narrow one's, as in Spectrum.
 
 ## When to show it
 
diff --git a/packages/mosaic/src/components/avatar/avatar.tsx b/packages/mosaic/src/components/avatar/avatar.tsx
index e0e38179cea..d439687a0c5 100644
--- a/packages/mosaic/src/components/avatar/avatar.tsx
+++ b/packages/mosaic/src/components/avatar/avatar.tsx
@@ -3,7 +3,7 @@ import { useMergeRefs } from '@floating-ui/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import { useSkeletonWave } from '../../hooks/use-skeleton-wave';
+import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps, MosaicElementProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
@@ -149,8 +149,8 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
   }, [delayMs]);
 
   const pending = canRender && status === 'loading';
-  const wave = useSkeletonWave<HTMLSpanElement>(pending);
-  const mergedRef = useMergeRefs([ref, wave]);
+  const shimmer = useSkeletonShimmer<HTMLSpanElement>(pending);
+  const mergedRef = useMergeRefs([ref, shimmer]);
 
   if (!canRender || status === 'loaded') {
     return null;
@@ -161,7 +161,13 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
       ref={mergedRef}
       {...mergeStyleProps(
         themeProps('avatar-fallback', { pending }),
-        stylex.props(reset.base, styles.fallback, bordered && styles.overlay, pending && skeletonStyles.wave, xstyle),
+        stylex.props(
+          reset.base,
+          styles.fallback,
+          bordered && styles.overlay,
+          pending && skeletonStyles.shimmer,
+          xstyle,
+        ),
         rest,
       )}
     >
@@ -192,7 +198,7 @@ const AvatarIcon = React.forwardRef<HTMLSpanElement, AvatarIconProps>(function M
 /**
  * Compound avatar. `Avatar.Root` positions and sizes the box; `Avatar.Image` renders
  * once its source loads; `Avatar.Fallback` holds the space until then, as a blank
- * placeholder that pulses only while an image is actually on its way; `Avatar.Icon`
+ * placeholder that shimmers only while an image is actually on its way; `Avatar.Icon`
  * adds an optional corner affordance.
  */
 export const Avatar = {
diff --git a/packages/mosaic/src/components/panel/panel.tsx b/packages/mosaic/src/components/panel/panel.tsx
index 6e9f6e7da98..d403a6cffff 100644
--- a/packages/mosaic/src/components/panel/panel.tsx
+++ b/packages/mosaic/src/components/panel/panel.tsx
@@ -2,7 +2,7 @@ import { inertProps } from '@clerk/shared/inert';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import { useSkeletonWave } from '../../hooks/use-skeleton-wave';
+import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
@@ -31,7 +31,7 @@ const Title = React.forwardRef<HTMLDivElement, PanelTitleProps>(function PanelTi
   ref,
 ) {
   const inProfilePage = React.useContext(ContentPanelContext);
-  const wave = useSkeletonWave<HTMLHeadingElement>(skeleton && !inProfilePage);
+  const shimmer = useSkeletonShimmer<HTMLHeadingElement>(skeleton && !inProfilePage);
   const profile = React.useContext(ProfileContext);
   const level = useHeadingLevel();
   const pageTitleRef = inProfilePage ? profile?.pageTitleRef : undefined;
@@ -50,10 +50,10 @@ const Title = React.forwardRef<HTMLDivElement, PanelTitleProps>(function PanelTi
       ),
       children: skeleton ? (
         <Heading
-          ref={wave}
+          ref={shimmer}
           level={level}
           size='2xl'
-          xstyle={[skeletonStyles.bone, skeletonStyles.wave, skeletonStyles.line, styles.titleSkeleton]}
+          xstyle={[skeletonStyles.bone, skeletonStyles.shimmer, skeletonStyles.line, styles.titleSkeleton]}
         />
       ) : (
         <Heading
diff --git a/packages/mosaic/src/components/section/section.tsx b/packages/mosaic/src/components/section/section.tsx
index b357a7f406a..d8b28e06797 100644
--- a/packages/mosaic/src/components/section/section.tsx
+++ b/packages/mosaic/src/components/section/section.tsx
@@ -4,7 +4,7 @@ import { useMergeRefs } from '@floating-ui/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import { useSkeletonWave } from '../../hooks/use-skeleton-wave';
+import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useTransition } from '../../primitives/hooks/use-transition';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps } from '../../props';
@@ -127,8 +127,8 @@ const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function S
   const setTitleId = React.useContext(SectionGroupContext);
   const generatedId = React.useId();
   const level = useHeadingLevel();
-  const wave = useSkeletonWave<HTMLHeadingElement>(skeleton);
-  const mergedRef = useMergeRefs([ref, wave]);
+  const shimmer = useSkeletonShimmer<HTMLHeadingElement>(skeleton);
+  const mergedRef = useMergeRefs([ref, shimmer]);
   const id = skeleton ? undefined : (idProp ?? (setTitleId ? `cl-section-${generatedId}-title` : undefined));
 
   useSafeLayoutEffect(() => {
@@ -150,7 +150,7 @@ const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function S
         styles.title,
         truncationStyles.singleLine,
         skeleton && skeletonStyles.bone,
-        skeleton && skeletonStyles.wave,
+        skeleton && skeletonStyles.shimmer,
         skeleton && skeletonStyles.line,
         skeleton && styles.titleSkeleton,
         xstyle,
@@ -226,12 +226,12 @@ const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function Secti
   ref,
 ) {
   const skeleton = useInheritedSkeleton(skeletonProp);
-  const wave = useSkeletonWave<HTMLDivElement>(skeleton);
+  const shimmer = useSkeletonShimmer<HTMLDivElement>(skeleton);
 
   return useRender({
     defaultTagName: 'div',
     render,
-    ref: [ref, wave],
+    ref: [ref, shimmer],
     props: mergeStyleProps(
       themeProps('section-media', { size, skeleton }),
       stylex.props(
@@ -239,7 +239,7 @@ const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function Secti
         styles.mediaBase,
         mediaSizes[size],
         skeleton && skeletonStyles.bone,
-        skeleton && skeletonStyles.wave,
+        skeleton && skeletonStyles.shimmer,
         xstyle,
       ),
       { ...rest, children: skeleton ? undefined : children },
@@ -270,19 +270,19 @@ const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function Secti
   ref,
 ) {
   const skeleton = useInheritedSkeleton(skeletonProp);
-  const wave = useSkeletonWave<HTMLDivElement>(skeleton);
+  const shimmer = useSkeletonShimmer<HTMLDivElement>(skeleton);
 
   return useRender({
     defaultTagName: 'div',
     render,
-    ref: [ref, wave],
+    ref: [ref, shimmer],
     props: mergeStyleProps(
       themeProps('section-label', { skeleton }),
       stylex.props(
         reset.base,
         styles.label,
         skeleton && skeletonStyles.bone,
-        skeleton && skeletonStyles.wave,
+        skeleton && skeletonStyles.shimmer,
         skeleton && skeletonStyles.line,
         skeleton && styles.labelSkeleton,
         xstyle,
@@ -298,12 +298,12 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
 ) {
   const skeleton = useInheritedSkeleton(skeletonProp);
   const inHeader = React.useContext(SectionHeaderContext);
-  const wave = useSkeletonWave<HTMLDivElement>(skeleton);
+  const shimmer = useSkeletonShimmer<HTMLDivElement>(skeleton);
 
   return useRender({
     defaultTagName: 'div',
     render,
-    ref: [ref, wave],
+    ref: [ref, shimmer],
     props: mergeStyleProps(
       themeProps('section-description', { skeleton }),
       stylex.props(
@@ -312,7 +312,7 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
         inHeader && styles.headerDescription,
         inHeader && sectionHeaderDescriptionMarker,
         skeleton && skeletonStyles.bone,
-        skeleton && skeletonStyles.wave,
+        skeleton && skeletonStyles.shimmer,
         skeleton && skeletonStyles.line,
         skeleton && styles.descriptionSkeleton,
         xstyle,
diff --git a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
index acc6f7a21cb..e7c7e5c77d2 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
@@ -5,7 +5,7 @@ import { Card } from '../../components/card';
 import { useFlowAutoFocus } from '../../components/flow';
 import { Icon } from '../../components/icon';
 import { Text } from '../../components/text';
-import { useSkeletonWave } from '../../hooks/use-skeleton-wave';
+import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useMessages } from '../../localization';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../../styles/reset.styles';
@@ -153,13 +153,13 @@ export function UserProfileBackupCodesView({
 }
 
 function BackupCodeSkeleton() {
-  const wave = useSkeletonWave<HTMLParagraphElement>(true);
+  const shimmer = useSkeletonShimmer<HTMLParagraphElement>(true);
 
   return (
     <Text
-      ref={wave}
+      ref={shimmer}
       render={<span />}
-      xstyle={[skeletonStyles.bone, skeletonStyles.wave, skeletonStyles.line, styles.skeleton]}
+      xstyle={[skeletonStyles.bone, skeletonStyles.shimmer, skeletonStyles.line, styles.skeleton]}
     />
   );
 }
diff --git a/packages/mosaic/src/hooks/use-skeleton-shimmer.ts b/packages/mosaic/src/hooks/use-skeleton-shimmer.ts
new file mode 100644
index 00000000000..a83713ca074
--- /dev/null
+++ b/packages/mosaic/src/hooks/use-skeleton-shimmer.ts
@@ -0,0 +1,22 @@
+import { useSafeLayoutEffect } from '@clerk/shared/react';
+import { useRef } from 'react';
+
+export function useSkeletonShimmer<T extends HTMLElement>(enabled: boolean) {
+  const ref = useRef<T | null>(null);
+
+  useSafeLayoutEffect(() => {
+    const element = ref.current;
+    if (!enabled || !element) {
+      return;
+    }
+    element.style.setProperty('--_cl-skeleton-state', 'running');
+    for (const animation of element.getAnimations?.({ subtree: true }) ?? []) {
+      animation.startTime = 0;
+    }
+    return () => {
+      element.style.removeProperty('--_cl-skeleton-state');
+    };
+  }, [enabled]);
+
+  return ref;
+}
diff --git a/packages/mosaic/src/hooks/use-skeleton-wave.ts b/packages/mosaic/src/hooks/use-skeleton-wave.ts
deleted file mode 100644
index a2ea399bc95..00000000000
--- a/packages/mosaic/src/hooks/use-skeleton-wave.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { useSafeLayoutEffect } from '@clerk/shared/react';
-import { useRef } from 'react';
-
-const PERIOD_MS = 2000;
-const MS_PER_PX = 2.1;
-
-export function useSkeletonWave<T extends HTMLElement>(enabled: boolean) {
-  const ref = useRef<T | null>(null);
-
-  useSafeLayoutEffect(() => {
-    const element = ref.current;
-    if (!enabled || !element) {
-      return;
-    }
-    const now = Number(document.timeline?.currentTime ?? performance.now());
-    const top = element.getBoundingClientRect().top + window.scrollY;
-    const phase = (((now - top * MS_PER_PX) % PERIOD_MS) + PERIOD_MS) % PERIOD_MS;
-    element.style.setProperty('--_cl-skeleton-delay', `${-phase}ms`);
-    element.setAttribute('data-skeleton-wave', '');
-    return () => {
-      element.style.removeProperty('--_cl-skeleton-delay');
-      element.removeAttribute('data-skeleton-wave');
-    };
-  }, [enabled]);
-
-  return ref;
-}
diff --git a/packages/mosaic/src/styles/skeleton.styles.ts b/packages/mosaic/src/styles/skeleton.styles.ts
index 7201adcdda3..deb684f5fd9 100644
--- a/packages/mosaic/src/styles/skeleton.styles.ts
+++ b/packages/mosaic/src/styles/skeleton.styles.ts
@@ -1,40 +1,55 @@
 import * as stylex from '@stylexjs/stylex';
 
 import { colorVars, easingVars, radiusVars } from '../tokens.stylex';
+import { skeletonVars } from './skeleton.stylex';
 
-const wave = stylex.keyframes({
-  '0%': { opacity: 1 },
-  '28%': { opacity: 0.32 },
-  '56%': { opacity: 1 },
-  '100%': { opacity: 1 },
+const fill = colorVars['--cl-color-neutral-alpha-200'];
+const highlight =
+  'light-dark(color-mix(in oklab, var(--cl-color-neutral) 3%, transparent), color-mix(in oklab, var(--cl-color-neutral) 14%, transparent))';
+const gradient = `linear-gradient(to right, ${fill} 33%, ${highlight}, ${fill} 66%)`;
+
+const shimmer = stylex.keyframes({
+  from: { backgroundPosition: '100% 0' },
+  to: { backgroundPosition: '0% 0' },
 });
 
 export const skeletonStyles = stylex.create({
-  wave: {
-    animationDelay: 'var(--_cl-skeleton-delay, 0ms)',
+  shimmer: {
+    backgroundPosition: '100% 0',
     animationDuration: '2s',
-    animationFillMode: 'both',
     animationIterationCount: 'infinite',
     animationName: {
-      default: 'none',
-      ':where([data-skeleton-wave])': wave,
-      '@media (prefers-reduced-motion: reduce)': { default: 'none', ':where([data-skeleton-wave])': 'none' },
+      default: shimmer,
+      '@media (prefers-reduced-motion: reduce)': 'none',
     },
+    animationPlayState: skeletonVars['--_cl-skeleton-state'],
     animationTimingFunction: easingVars['--cl-ease-in-out'],
+    backgroundImage: gradient,
+    backgroundSize: '300% 100%',
   },
   bone: {
     borderRadius: radiusVars['--cl-radius-md'],
-    backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
     userSelect: 'none',
   },
   line: {
     borderRadius: 0,
-    backgroundColor: 'transparent',
+    animationName: 'none',
+    backgroundImage: 'none',
     display: 'block',
     height: '1lh',
     maxWidth: '100%',
     '::before': {
-      backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
+      backgroundPosition: '100% 0',
+      animationDuration: '2s',
+      animationIterationCount: 'infinite',
+      animationName: {
+        default: shimmer,
+        '@media (prefers-reduced-motion: reduce)': 'none',
+      },
+      animationPlayState: skeletonVars['--_cl-skeleton-state'],
+      animationTimingFunction: easingVars['--cl-ease-in-out'],
+      backgroundImage: gradient,
+      backgroundSize: '300% 100%',
       content: "''",
       display: 'inline-block',
       verticalAlign: 'baseline',
diff --git a/packages/mosaic/src/styles/skeleton.stylex.ts b/packages/mosaic/src/styles/skeleton.stylex.ts
new file mode 100644
index 00000000000..f4be911b35f
--- /dev/null
+++ b/packages/mosaic/src/styles/skeleton.stylex.ts
@@ -0,0 +1,5 @@
+import * as stylex from '@stylexjs/stylex';
+
+export const skeletonVars = stylex.defineVars({
+  '--_cl-skeleton-state': 'paused',
+});
diff --git a/packages/swingset/src/stories/avatar.mdx b/packages/swingset/src/stories/avatar.mdx
index 46d3d7af518..32346b9ceb9 100644
--- a/packages/swingset/src/stories/avatar.mdx
+++ b/packages/swingset/src/stories/avatar.mdx
@@ -49,7 +49,7 @@ import { Avatar } from '@clerk/mosaic/components/avatar';
 
 ### Pending
 
-While an image is still resolving, the fallback carries `data-pending` and pulses. This source holds its response for a minute, so the state is the component's own rather than a pinned attribute — inspect the `.cl-avatar-fallback` element to watch the attribute come and go.
+While an image is still resolving, the fallback carries `data-pending` and shimmers. This source holds its response for a minute, so the state is the component's own rather than a pinned attribute — inspect the `.cl-avatar-fallback` element to watch the attribute come and go.
 
 <Story
   name='Pending'
@@ -67,7 +67,7 @@ Use `render` to compose the avatar onto a button or another trigger without intr
 
 ### Fallback
 
-Once the image fails, the pulse stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.
+Once the image fails, the shimmer stops and the fallback settles into a plain fill. Nothing is on its way for an entity that has no picture, so its mark holds still rather than claiming to be loading one.
 
 <Story
   name='Fallback'
diff --git a/packages/swingset/src/stories/panel.component.mdx b/packages/swingset/src/stories/panel.component.mdx
index 3977eea089b..930ebf6c9ee 100644
--- a/packages/swingset/src/stories/panel.component.mdx
+++ b/packages/swingset/src/stories/panel.component.mdx
@@ -8,8 +8,8 @@ children, `Panel.Title` renders the page's heading, and `Panel.Sections` stacks
 [Profile](/components/profile) page, `Panel.Title` renders nothing: the profile renders the page title,
 and a ref on `Panel.Title` reaches it.
 
-`Panel.Title` takes `skeleton` for a loading state: the heading renders empty as a placeholder in
-the same wave as [Section](/components/section) skeletons, and is hidden from assistive technology.
+`Panel.Title` takes `skeleton` for a loading state: the heading renders empty as a placeholder that
+shimmers in step with [Section](/components/section) skeletons, and is hidden from assistive technology.
 Inside a profile page it has no effect, since the profile's title stays as it is.
 
 ## Example
diff --git a/packages/swingset/src/stories/section.mdx b/packages/swingset/src/stories/section.mdx
index 5003facc90d..cd856a2905b 100644
--- a/packages/swingset/src/stories/section.mdx
+++ b/packages/swingset/src/stories/section.mdx
@@ -55,8 +55,8 @@ description, and actions inside it become placeholders, each the size of the con
 for, and their children are not rendered. A part can also take `skeleton` on its own, or
 `skeleton={false}` to stay as content inside a skeleton card. Skeleton actions draw nothing and hold
 the height of a small control. A skeleton card is inert and hidden from assistive technology, so
-pair it with a visually hidden status message. Placeholders pulse in one wave that travels down the
-page, across every skeleton on it. When to show the skeleton, and for how long, is up to the
+pair it with a visually hidden status message. Placeholders shimmer left to right, in step with
+every other skeleton on the page. When to show the skeleton, and for how long, is up to the
 caller.
 
 `Section.Title` renders at the level from the nearest `HeadingLevelProvider`, or `h2` outside one.

From 3d67f36ee97b01ad8b34213f8eab64fefb9d5333 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Tue, 6 Oct 2026 12:33:38 -0600
Subject: [PATCH 10/14] feat(mosaic): draw skeleton text from mock content with
 a CSS-only shimmer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/skeletons.md | 105 ++++++++----------
 .../mosaic/src/components/avatar/avatar.tsx   |   6 +-
 .../src/components/panel/panel.styles.ts      |   3 -
 .../mosaic/src/components/panel/panel.tsx     |  15 +--
 .../src/components/section/section.styles.ts  |   9 --
 .../src/components/section/section.test.tsx   |   5 +-
 .../mosaic/src/components/section/section.tsx |  54 ++-------
 .../user-profile-backup-codes.view.test.tsx   |   2 +-
 .../user-profile-backup-codes.styles.ts       |   3 -
 .../user-profile-backup-codes.view.tsx        |  15 +--
 .../mosaic/src/hooks/use-skeleton-shimmer.ts  |  22 ----
 packages/mosaic/src/styles/skeleton.styles.ts |  76 ++++++-------
 packages/mosaic/src/styles/skeleton.stylex.ts |   5 -
 packages/mosaic/src/utils/skeleton-text.tsx   |  19 ++++
 .../swingset/src/stories/panel.component.mdx  |   4 +-
 packages/swingset/src/stories/section.mdx     |  15 ++-
 16 files changed, 141 insertions(+), 217 deletions(-)
 delete mode 100644 packages/mosaic/src/hooks/use-skeleton-shimmer.ts
 delete mode 100644 packages/mosaic/src/styles/skeleton.stylex.ts
 create mode 100644 packages/mosaic/src/utils/skeleton-text.tsx

diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
index 00dbdd68280..afdba9bcd96 100644
--- a/.claude/skills/mosaic/references/skeletons.md
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -26,78 +26,71 @@ same fill, `--cl-color-neutral-alpha-200`.
 
 - **Render the real view with mock data.** The view takes `skeleton` and passes it
   to its container (`<Section.Group skeleton={skeleton}>`). Every part inside
-  inherits it and becomes a bone (`skeleton={false}` opts one out), drops its
-  children, and the container turns `inert` and `aria-hidden`. Because the
-  skeleton is the view's own markup, it can't drift from it: change a row and the
-  skeleton changes with it. While `skeleton` is set, the view skips its dialogs and
-  confirmations.
+  inherits it and becomes a bone (`skeleton={false}` opts one out), and the
+  container turns `inert` and `aria-hidden`. Because the skeleton is the view's own
+  markup, it can't drift from it: change a row and the skeleton changes with it.
+  While `skeleton` is set, the view skips its dialogs and confirmations.
 - **The `.skeleton.tsx` is one line** next to the view, rendering it with a
   `PLACEHOLDER_*` constant:
   `<UserProfileActiveDevicesSectionView skeleton devices={PLACEHOLDER_DEVICES} />`
-  (see `user-profile-active-devices-section.skeleton.tsx`). The mock values are
-  never shown; they only decide the shape. A panel's skeleton composes its
-  sections' skeletons.
-- **Mock data decides row count and shape.** Aim it at the most common loaded
-  shape: a typical count (2–3), every line present, and the branch real data
-  usually takes (a current device, not the empty state). When the count is known
-  before the fetch, use it instead: a table moving between pages with a known
-  total shows exactly `min(pageSize, total − offset)` rows, so nothing shifts. A
-  first load or a new search can't know, so it uses the typical count and accepts
-  a shift. The page size is a maximum, not a count.
+  (see `user-profile-active-devices-section.skeleton.tsx`). A panel's skeleton
+  composes its sections' skeletons.
+- **Mock data decides row count, shape, and text length.** Text bones are drawn
+  from the mock strings, so write them at a typical length: a placeholder that
+  wraps to two lines where real text takes one shifts the layout. Aim at the most
+  common loaded shape: a typical count (2–3), every line present, and the branch
+  real data usually takes (a current device, not the empty state). When the count
+  is known before the fetch, use it instead: a table moving between pages with a
+  known total shows exactly `min(pageSize, total − offset)` rows. A first load or a
+  new search can't know, so it uses the typical count and accepts a shift. The page
+  size is a maximum, not a count.
 - **Announce it.** The skeleton is hidden from assistive technology, so the view
   renders a `VisuallyHidden` `role='status'` message ("Loading active devices")
   while `skeleton` is set.
 - **Parts also take `skeleton` standalone**, as does `Panel.Title`, for a bone
   outside a skeleton container.
-- **Fewest nodes:** one element per bone, no wrappers. A bone is the real part
-  rendered empty, so it inherits that part's padding, type size and line height.
-- **A component with its own shape** (a part that needs a skeleton but isn't covered
-  above) composes the pieces in `styles/skeleton.styles.ts` itself:
-  - `skeletonStyles.shimmer`: the gradient fill and its animation. Media and
-    blocks take it on the element; `Avatar.Fallback`, which has its own circle,
-    takes `shimmer` alone.
-  - `skeletonStyles.bone`: radius, for media and blocks (with `shimmer`).
-  - `skeletonStyles.line`: a `1lh` box holding one line of text, whose `::before`
-    bar is `1cap` tall (`0.7em` fallback) on the baseline, square-cornered. It
-    moves the shimmer from the element onto the bar.
-  - plus a `useSkeletonShimmer(enabled)` ref (`hooks/use-skeleton-shimmer.ts`) on
-    the same element. Without it, the shimmer stays paused.
+- **What each part does:** text parts (Title, Label, Description, `Panel.Title`)
+  keep their mock text and wrap it in `SkeletonText`; Media renders empty as a
+  filled block; Actions render nothing and hold a small control's height.
+- **A component with its own shape** composes the pieces in
+  `styles/skeleton.styles.ts` itself:
+  - `SkeletonText` (`utils/skeleton-text.tsx`) around mock text: one inline span
+    whose text is transparent and whose background draws each wrapped line.
+  - `skeletonStyles.bone`: fill and radius, for media and blocks.
+  - `skeletonStyles.shimmer`: the moving highlight for a block, as an `::after`
+    overlay. `Avatar.Fallback`, which has its own fill and circle, takes `shimmer`
+    alone.
 
 ## Sizing
 
-- **Height must match exactly.** Line bones fill one line of the part's own type, so
-  text rows match by construction. Watch anything taller than a line:
+- **Height must match exactly.** Text bones are the text's own line boxes, so text
+  rows match by construction. Watch anything taller than its text:
   `Section.Actions skeleton` exists because a 28px `sm` menu trigger outgrew a 20px
-  line. `Panel.Title skeleton` puts the bone on the inner heading because the outer
-  `div` has a smaller line height.
-- **Width in `ch`**, from the content the bone usually holds, at the short end, so it
-  reads like real text and shrinks with `maxWidth: 100%` on narrow screens: a card or
-  page title `6ch`, a label `12ch`, a description `20ch`, an email `16ch`, a US phone
-  number `15ch`, a backup code `7ch`. Override a part's default with `xstyle`.
-- **Uniform across rows.** Every row uses the same widths; within a row, lines
-  differ.
+  line.
+- **Width and wrapping come from the mock text.** Each line's band is as wide as
+  that line of mock text and as tall as the font's text box (ascender to
+  descender), whatever font is in use. Nothing is measured.
 
 ## The shimmer
 
-Modeled on React Spectrum's `Skeleton`: a highlight sweeps left to right across every
-bone, and every bone on the page sweeps in step.
-
-- The surface is a `linear-gradient` (fill, highlight, fill at 33% / 50% / 66%)
-  sized to `300%` of the bone, and the keyframes move its `background-position`
-  from `100%` to `0%`, so the highlight crosses once per cycle: 2s on
-  `--cl-ease-in-out`, repeating. The highlight is lighter than the fill in both
-  schemes. Off under `prefers-reduced-motion: reduce`, leaving the plain fill.
-- Text bones animate their `::before` bar, so the highlight stays inside the cap
-  band; media animate the element.
-- `useSkeletonShimmer` locks every bone to the document clock: before first paint
-  it sets the private `--_cl-skeleton-state` variable (`styles/skeleton.stylex.ts`)
-  to `running` and sets each of the element's animations (pseudo-elements
-  included) to `startTime = 0`. Bones that mount at different times sweep
-  together.
-- The animation is `paused` until the hook runs, so a server-rendered skeleton
-  holds a static fill until hydration instead of sweeping out of step and jumping.
+Modeled on React Spectrum's `Skeleton`, with no JavaScript: a highlight one bone wide,
+peaking in the middle, sweeps left to right across two bone widths, over 1.6s
+`ease-in-out`, repeating. Off under `prefers-reduced-motion: reduce`, leaving the
+plain fill.
+
+- **Blocks** (media, the avatar) move an `::after` overlay with `transform`
+  (`translateX(-100%)` → `translateX(100%)`), clipped by `overflow: hidden`.
+- **Text** moves its own background, since an overlay can't follow wrapped lines:
+  a gradient `300%` wide (transparent, highlight, transparent at 33% / 50% / 66%)
+  over the fill, from `background-position: 100%` to `0%`, cloned per line with
+  `box-decoration-break`. Same geometry and timing as the overlay.
+- **The highlight** is a wash over the fill, one value in both techniques:
+  background-tinted in light mode, neutral-tinted in dark.
+- **No sync.** Bones that mount together sweep together; a section mounting later
+  runs out of step. CSS animations keep running through hydration, so a
+  server-rendered skeleton doesn't jump.
 - The sweep is relative to each bone's width, so a wide bar's highlight moves
-  faster than a narrow one's, as in Spectrum.
+  faster than a narrow one's.
 
 ## When to show it
 
diff --git a/packages/mosaic/src/components/avatar/avatar.tsx b/packages/mosaic/src/components/avatar/avatar.tsx
index d439687a0c5..ae2f70278e8 100644
--- a/packages/mosaic/src/components/avatar/avatar.tsx
+++ b/packages/mosaic/src/components/avatar/avatar.tsx
@@ -1,9 +1,7 @@
 import { useSafeLayoutEffect } from '@clerk/shared/react';
-import { useMergeRefs } from '@floating-ui/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps, MosaicElementProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
@@ -149,8 +147,6 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
   }, [delayMs]);
 
   const pending = canRender && status === 'loading';
-  const shimmer = useSkeletonShimmer<HTMLSpanElement>(pending);
-  const mergedRef = useMergeRefs([ref, shimmer]);
 
   if (!canRender || status === 'loaded') {
     return null;
@@ -158,7 +154,7 @@ const AvatarFallback = React.forwardRef<HTMLSpanElement, AvatarFallbackProps>(fu
 
   return (
     <span
-      ref={mergedRef}
+      ref={ref}
       {...mergeStyleProps(
         themeProps('avatar-fallback', { pending }),
         stylex.props(
diff --git a/packages/mosaic/src/components/panel/panel.styles.ts b/packages/mosaic/src/components/panel/panel.styles.ts
index 5c2b34fc73a..9d3011e8389 100644
--- a/packages/mosaic/src/components/panel/panel.styles.ts
+++ b/packages/mosaic/src/components/panel/panel.styles.ts
@@ -12,9 +12,6 @@ export const styles = stylex.create({
   title: {
     display: 'block',
   },
-  titleSkeleton: {
-    width: '6ch',
-  },
 
   sections: {
     gap: space['8'],
diff --git a/packages/mosaic/src/components/panel/panel.tsx b/packages/mosaic/src/components/panel/panel.tsx
index d403a6cffff..e0c0364c81c 100644
--- a/packages/mosaic/src/components/panel/panel.tsx
+++ b/packages/mosaic/src/components/panel/panel.tsx
@@ -2,12 +2,11 @@ import { inertProps } from '@clerk/shared/inert';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../../styles/reset.styles';
-import { skeletonStyles } from '../../styles/skeleton.styles';
+import { SkeletonText } from '../../utils/skeleton-text';
 import { Heading, HeadingLevelProvider, useHeadingLevel } from '../heading';
 import { ContentPanelContext, ProfileContext } from '../profile/profile.context';
 import { styles } from './panel.styles';
@@ -31,7 +30,6 @@ const Title = React.forwardRef<HTMLDivElement, PanelTitleProps>(function PanelTi
   ref,
 ) {
   const inProfilePage = React.useContext(ContentPanelContext);
-  const shimmer = useSkeletonShimmer<HTMLHeadingElement>(skeleton && !inProfilePage);
   const profile = React.useContext(ProfileContext);
   const level = useHeadingLevel();
   const pageTitleRef = inProfilePage ? profile?.pageTitleRef : undefined;
@@ -48,19 +46,12 @@ const Title = React.forwardRef<HTMLDivElement, PanelTitleProps>(function PanelTi
         skeleton ? { 'aria-hidden': true, ...inertProps(true) } : {},
         rest,
       ),
-      children: skeleton ? (
-        <Heading
-          ref={shimmer}
-          level={level}
-          size='2xl'
-          xstyle={[skeletonStyles.bone, skeletonStyles.shimmer, skeletonStyles.line, styles.titleSkeleton]}
-        />
-      ) : (
+      children: (
         <Heading
           level={level}
           size='2xl'
         >
-          {children}
+          {skeleton ? <SkeletonText>{children}</SkeletonText> : children}
         </Heading>
       ),
     },
diff --git a/packages/mosaic/src/components/section/section.styles.ts b/packages/mosaic/src/components/section/section.styles.ts
index 2624762f358..b0df1cf6ab9 100644
--- a/packages/mosaic/src/components/section/section.styles.ts
+++ b/packages/mosaic/src/components/section/section.styles.ts
@@ -148,15 +148,6 @@ export const styles = stylex.create({
     lineHeight: typeScaleVars['--cl-text-sm-leading'],
     minWidth: 0,
   },
-  titleSkeleton: {
-    width: '6ch',
-  },
-  labelSkeleton: {
-    width: '12ch',
-  },
-  descriptionSkeleton: {
-    width: '20ch',
-  },
   description: {
     color: colorVars['--cl-color-foreground-secondary'],
     fontSize: typeScaleVars['--cl-text-sm-size'],
diff --git a/packages/mosaic/src/components/section/section.test.tsx b/packages/mosaic/src/components/section/section.test.tsx
index 289260fcdc0..fd3ed5dcbf1 100644
--- a/packages/mosaic/src/components/section/section.test.tsx
+++ b/packages/mosaic/src/components/section/section.test.tsx
@@ -402,7 +402,7 @@ describe('Section', () => {
     expect(screen.getByTestId('item')).toHaveAttribute('data-wrap', '');
   });
 
-  it('turns a skeleton card into inert, empty placeholders', () => {
+  it('turns a skeleton card into inert placeholders', () => {
     render(
       <Section.Root>
         <Section.Group
@@ -434,8 +434,9 @@ describe('Section', () => {
     expect(group).toHaveAttribute('aria-hidden', 'true');
     expect(group).toHaveAttribute('inert');
     expect(group).not.toHaveAttribute('role');
-    expect(group).toHaveTextContent('');
     expect(group.querySelector('button')).toBeNull();
+    expect(screen.getByText('Name')).toHaveAttribute('aria-hidden', 'true');
+    expect(screen.getByText('Description')).toHaveAttribute('aria-hidden', 'true');
     expect(group.querySelectorAll('[data-skeleton]')).toHaveLength(5);
   });
 
diff --git a/packages/mosaic/src/components/section/section.tsx b/packages/mosaic/src/components/section/section.tsx
index d8b28e06797..2e45b3e9e25 100644
--- a/packages/mosaic/src/components/section/section.tsx
+++ b/packages/mosaic/src/components/section/section.tsx
@@ -1,10 +1,8 @@
 import { inertProps } from '@clerk/shared/inert';
 import { useSafeLayoutEffect } from '@clerk/shared/react';
-import { useMergeRefs } from '@floating-ui/react';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useTransition } from '../../primitives/hooks/use-transition';
 import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps } from '../../props';
@@ -14,6 +12,7 @@ import { reset } from '../../styles/reset.styles';
 import { skeletonStyles } from '../../styles/skeleton.styles';
 import { sizes as typographySizes, styles as typographyStyles, truncationStyles } from '../../styles/typography.styles';
 import { FeedbackBody, hasMessage, useHeldMessage, useMessageHeight } from '../../utils/feedback';
+import { SkeletonText } from '../../utils/skeleton-text';
 import { withTruncatableLabel } from '../../utils/truncatable-label';
 import type { HeadingProps } from '../heading';
 import { Heading, useHeadingLevel } from '../heading';
@@ -127,8 +126,6 @@ const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function S
   const setTitleId = React.useContext(SectionGroupContext);
   const generatedId = React.useId();
   const level = useHeadingLevel();
-  const shimmer = useSkeletonShimmer<HTMLHeadingElement>(skeleton);
-  const mergedRef = useMergeRefs([ref, shimmer]);
   const id = skeleton ? undefined : (idProp ?? (setTitleId ? `cl-section-${generatedId}-title` : undefined));
 
   useSafeLayoutEffect(() => {
@@ -142,22 +139,14 @@ const Title = React.forwardRef<HTMLHeadingElement, SectionTitleProps>(function S
 
   return (
     <Heading
-      ref={mergedRef}
+      ref={ref}
       id={id}
       level={level}
       size='base'
-      xstyle={[
-        styles.title,
-        truncationStyles.singleLine,
-        skeleton && skeletonStyles.bone,
-        skeleton && skeletonStyles.shimmer,
-        skeleton && skeletonStyles.line,
-        skeleton && styles.titleSkeleton,
-        xstyle,
-      ]}
+      xstyle={[styles.title, truncationStyles.singleLine, xstyle]}
       {...mergeStyleProps(themeProps('section-title', { skeleton }), rest)}
     >
-      {skeleton ? undefined : children}
+      {skeleton ? <SkeletonText>{children}</SkeletonText> : children}
     </Heading>
   );
 });
@@ -226,12 +215,10 @@ const Media = React.forwardRef<HTMLDivElement, SectionMediaProps>(function Secti
   ref,
 ) {
   const skeleton = useInheritedSkeleton(skeletonProp);
-  const shimmer = useSkeletonShimmer<HTMLDivElement>(skeleton);
-
   return useRender({
     defaultTagName: 'div',
     render,
-    ref: [ref, shimmer],
+    ref,
     props: mergeStyleProps(
       themeProps('section-media', { size, skeleton }),
       stylex.props(
@@ -270,25 +257,14 @@ const Label = React.forwardRef<HTMLDivElement, SectionLabelProps>(function Secti
   ref,
 ) {
   const skeleton = useInheritedSkeleton(skeletonProp);
-  const shimmer = useSkeletonShimmer<HTMLDivElement>(skeleton);
-
   return useRender({
     defaultTagName: 'div',
     render,
-    ref: [ref, shimmer],
-    props: mergeStyleProps(
-      themeProps('section-label', { skeleton }),
-      stylex.props(
-        reset.base,
-        styles.label,
-        skeleton && skeletonStyles.bone,
-        skeleton && skeletonStyles.shimmer,
-        skeleton && skeletonStyles.line,
-        skeleton && styles.labelSkeleton,
-        xstyle,
-      ),
-      { ...rest, children: skeleton ? undefined : withTruncatableLabel(children) },
-    ),
+    ref,
+    props: mergeStyleProps(themeProps('section-label', { skeleton }), stylex.props(reset.base, styles.label, xstyle), {
+      ...rest,
+      children: skeleton ? <SkeletonText>{children}</SkeletonText> : withTruncatableLabel(children),
+    }),
   });
 });
 
@@ -298,12 +274,10 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
 ) {
   const skeleton = useInheritedSkeleton(skeletonProp);
   const inHeader = React.useContext(SectionHeaderContext);
-  const shimmer = useSkeletonShimmer<HTMLDivElement>(skeleton);
-
   return useRender({
     defaultTagName: 'div',
     render,
-    ref: [ref, shimmer],
+    ref,
     props: mergeStyleProps(
       themeProps('section-description', { skeleton }),
       stylex.props(
@@ -311,13 +285,9 @@ const Description = React.forwardRef<HTMLDivElement, SectionDescriptionProps>(fu
         styles.description,
         inHeader && styles.headerDescription,
         inHeader && sectionHeaderDescriptionMarker,
-        skeleton && skeletonStyles.bone,
-        skeleton && skeletonStyles.shimmer,
-        skeleton && skeletonStyles.line,
-        skeleton && styles.descriptionSkeleton,
         xstyle,
       ),
-      { ...rest, children: skeleton ? undefined : children },
+      { ...rest, children: skeleton ? <SkeletonText>{children}</SkeletonText> : children },
     ),
   });
 });
diff --git a/packages/mosaic/src/features/user-profile/__tests__/user-profile-backup-codes.view.test.tsx b/packages/mosaic/src/features/user-profile/__tests__/user-profile-backup-codes.view.test.tsx
index 0b4b663c219..d8657bb4e8a 100644
--- a/packages/mosaic/src/features/user-profile/__tests__/user-profile-backup-codes.view.test.tsx
+++ b/packages/mosaic/src/features/user-profile/__tests__/user-profile-backup-codes.view.test.tsx
@@ -55,7 +55,7 @@ describe('UserProfileBackupCodesView', () => {
     const { props, rerender } = renderView({ codes: [], pendingAction: 'generate' });
     expect(screen.getByRole('progressbar', { name: 'Generating backup codes' })).toBeInTheDocument();
     const loading = screen.getByRole('status', { name: 'Generating backup codes' });
-    expect(loading.textContent).toBe('');
+    expect([...loading.children].every(cell => cell.getAttribute('aria-hidden') === 'true')).toBe(true);
     expect(screen.queryByRole('list')).not.toBeInTheDocument();
     expect(screen.queryByRole('button', { name: 'Copy and close' })).not.toBeInTheDocument();
     expect(screen.queryByRole('button', { name: 'Download', exact: true })).not.toBeInTheDocument();
diff --git a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
index 6e03c8f255d..3db5c01604a 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
+++ b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.styles.ts
@@ -3,9 +3,6 @@ import * as stylex from '@stylexjs/stylex';
 import { colorVars, radiusVars, space } from '../../tokens.stylex';
 
 export const styles = stylex.create({
-  skeleton: {
-    width: '7ch',
-  },
   codes: {
     borderColor: colorVars['--cl-color-border'],
     borderRadius: radiusVars['--cl-radius-md'],
diff --git a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
index e7c7e5c77d2..566d1908cbc 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-backup-codes.view.tsx
@@ -5,13 +5,14 @@ import { Card } from '../../components/card';
 import { useFlowAutoFocus } from '../../components/flow';
 import { Icon } from '../../components/icon';
 import { Text } from '../../components/text';
-import { useSkeletonShimmer } from '../../hooks/use-skeleton-shimmer';
 import { useMessages } from '../../localization';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../../styles/reset.styles';
-import { skeletonStyles } from '../../styles/skeleton.styles';
+import { SkeletonText } from '../../utils/skeleton-text';
 import { styles } from './user-profile-backup-codes.styles';
 
+const PLACEHOLDER_CODE = 'xxxxxxxx';
+
 export interface UserProfileBackupCodesViewProps {
   onCancel: () => void;
   onBack?: () => void;
@@ -153,13 +154,9 @@ export function UserProfileBackupCodesView({
 }
 
 function BackupCodeSkeleton() {
-  const shimmer = useSkeletonShimmer<HTMLParagraphElement>(true);
-
   return (
-    <Text
-      ref={shimmer}
-      render={<span />}
-      xstyle={[skeletonStyles.bone, skeletonStyles.shimmer, skeletonStyles.line, styles.skeleton]}
-    />
+    <Text render={<span />}>
+      <SkeletonText>{PLACEHOLDER_CODE}</SkeletonText>
+    </Text>
   );
 }
diff --git a/packages/mosaic/src/hooks/use-skeleton-shimmer.ts b/packages/mosaic/src/hooks/use-skeleton-shimmer.ts
deleted file mode 100644
index a83713ca074..00000000000
--- a/packages/mosaic/src/hooks/use-skeleton-shimmer.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { useSafeLayoutEffect } from '@clerk/shared/react';
-import { useRef } from 'react';
-
-export function useSkeletonShimmer<T extends HTMLElement>(enabled: boolean) {
-  const ref = useRef<T | null>(null);
-
-  useSafeLayoutEffect(() => {
-    const element = ref.current;
-    if (!enabled || !element) {
-      return;
-    }
-    element.style.setProperty('--_cl-skeleton-state', 'running');
-    for (const animation of element.getAnimations?.({ subtree: true }) ?? []) {
-      animation.startTime = 0;
-    }
-    return () => {
-      element.style.removeProperty('--_cl-skeleton-state');
-    };
-  }, [enabled]);
-
-  return ref;
-}
diff --git a/packages/mosaic/src/styles/skeleton.styles.ts b/packages/mosaic/src/styles/skeleton.styles.ts
index deb684f5fd9..e99d4d89a22 100644
--- a/packages/mosaic/src/styles/skeleton.styles.ts
+++ b/packages/mosaic/src/styles/skeleton.styles.ts
@@ -1,60 +1,60 @@
 import * as stylex from '@stylexjs/stylex';
 
-import { colorVars, easingVars, radiusVars } from '../tokens.stylex';
-import { skeletonVars } from './skeleton.stylex';
+import { colorVars, radiusVars } from '../tokens.stylex';
 
-const fill = colorVars['--cl-color-neutral-alpha-200'];
 const highlight =
-  'light-dark(color-mix(in oklab, var(--cl-color-neutral) 3%, transparent), color-mix(in oklab, var(--cl-color-neutral) 14%, transparent))';
-const gradient = `linear-gradient(to right, ${fill} 33%, ${highlight}, ${fill} 66%)`;
+  'light-dark(color-mix(in oklab, var(--cl-color-background) 62%, transparent), color-mix(in oklab, var(--cl-color-neutral) 7%, transparent))';
 
-const shimmer = stylex.keyframes({
+const translate = stylex.keyframes({
+  from: { transform: 'translateX(-100%)' },
+  to: { transform: 'translateX(100%)' },
+});
+
+const pan = stylex.keyframes({
   from: { backgroundPosition: '100% 0' },
   to: { backgroundPosition: '0% 0' },
 });
 
 export const skeletonStyles = stylex.create({
-  shimmer: {
-    backgroundPosition: '100% 0',
-    animationDuration: '2s',
-    animationIterationCount: 'infinite',
-    animationName: {
-      default: shimmer,
-      '@media (prefers-reduced-motion: reduce)': 'none',
-    },
-    animationPlayState: skeletonVars['--_cl-skeleton-state'],
-    animationTimingFunction: easingVars['--cl-ease-in-out'],
-    backgroundImage: gradient,
-    backgroundSize: '300% 100%',
-  },
   bone: {
     borderRadius: radiusVars['--cl-radius-md'],
+    backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
     userSelect: 'none',
   },
-  line: {
-    borderRadius: 0,
-    animationName: 'none',
-    backgroundImage: 'none',
-    display: 'block',
-    height: '1lh',
-    maxWidth: '100%',
-    '::before': {
-      backgroundPosition: '100% 0',
-      animationDuration: '2s',
+  shimmer: {
+    overflow: 'hidden',
+    position: 'relative',
+    '::after': {
+      inset: 0,
+      animationDuration: '1.6s',
       animationIterationCount: 'infinite',
       animationName: {
-        default: shimmer,
+        default: translate,
         '@media (prefers-reduced-motion: reduce)': 'none',
       },
-      animationPlayState: skeletonVars['--_cl-skeleton-state'],
-      animationTimingFunction: easingVars['--cl-ease-in-out'],
-      backgroundImage: gradient,
-      backgroundSize: '300% 100%',
+      animationTimingFunction: 'ease-in-out',
+      backgroundImage: `linear-gradient(90deg, transparent, ${highlight}, transparent)`,
       content: "''",
-      display: 'inline-block',
-      verticalAlign: 'baseline',
-      height: stylex.firstThatWorks('1cap', '0.7em'),
-      width: '100%',
+      position: 'absolute',
+      transform: 'translateX(-100%)',
     },
   },
+  text: {
+    WebkitTextFillColor: 'transparent',
+    backgroundPosition: '100% 0',
+    animationDuration: '1.6s',
+    animationIterationCount: 'infinite',
+    animationName: {
+      default: pan,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: 'ease-in-out',
+    backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
+    backgroundImage: `linear-gradient(90deg, transparent 33.33%, ${highlight} 50%, transparent 66.67%)`,
+    backgroundRepeat: 'no-repeat',
+    backgroundSize: '300% 100%',
+    boxDecorationBreak: 'clone',
+    color: 'transparent',
+    userSelect: 'none',
+  },
 });
diff --git a/packages/mosaic/src/styles/skeleton.stylex.ts b/packages/mosaic/src/styles/skeleton.stylex.ts
deleted file mode 100644
index f4be911b35f..00000000000
--- a/packages/mosaic/src/styles/skeleton.stylex.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import * as stylex from '@stylexjs/stylex';
-
-export const skeletonVars = stylex.defineVars({
-  '--_cl-skeleton-state': 'paused',
-});
diff --git a/packages/mosaic/src/utils/skeleton-text.tsx b/packages/mosaic/src/utils/skeleton-text.tsx
new file mode 100644
index 00000000000..82495fa86fe
--- /dev/null
+++ b/packages/mosaic/src/utils/skeleton-text.tsx
@@ -0,0 +1,19 @@
+import * as stylex from '@stylexjs/stylex';
+import type React from 'react';
+
+import { skeletonStyles } from '../styles/skeleton.styles';
+
+const webkitClone = { WebkitBoxDecorationBreak: 'clone' } as React.CSSProperties;
+
+export function SkeletonText({ children }: { children: React.ReactNode }) {
+  const props = stylex.props(skeletonStyles.text);
+  return (
+    <span
+      aria-hidden
+      className={props.className}
+      style={{ ...props.style, ...webkitClone }}
+    >
+      {children}
+    </span>
+  );
+}
diff --git a/packages/swingset/src/stories/panel.component.mdx b/packages/swingset/src/stories/panel.component.mdx
index 930ebf6c9ee..7a4bab85fed 100644
--- a/packages/swingset/src/stories/panel.component.mdx
+++ b/packages/swingset/src/stories/panel.component.mdx
@@ -8,8 +8,8 @@ children, `Panel.Title` renders the page's heading, and `Panel.Sections` stacks
 [Profile](/components/profile) page, `Panel.Title` renders nothing: the profile renders the page title,
 and a ref on `Panel.Title` reaches it.
 
-`Panel.Title` takes `skeleton` for a loading state: the heading renders empty as a placeholder that
-shimmers in step with [Section](/components/section) skeletons, and is hidden from assistive technology.
+`Panel.Title` takes `skeleton` for a loading state: its text renders as a placeholder bar, like
+[Section](/components/section) skeletons, and is hidden from assistive technology.
 Inside a profile page it has no effect, since the profile's title stays as it is.
 
 ## Example
diff --git a/packages/swingset/src/stories/section.mdx b/packages/swingset/src/stories/section.mdx
index cd856a2905b..c91c856c5c3 100644
--- a/packages/swingset/src/stories/section.mdx
+++ b/packages/swingset/src/stories/section.mdx
@@ -50,14 +50,13 @@ fixed leading slot sized to the text, for a provider logo or a lock.
 than `26rem`. `sectionCompactStyles.hidden` and `sectionCompactStyles.only` toggle inline content at
 the same width.
 
-`Section.Group skeleton` turns a card into its loading state. The title, media, label,
-description, and actions inside it become placeholders, each the size of the content it stands in
-for, and their children are not rendered. A part can also take `skeleton` on its own, or
-`skeleton={false}` to stay as content inside a skeleton card. Skeleton actions draw nothing and hold
-the height of a small control. A skeleton card is inert and hidden from assistive technology, so
-pair it with a visually hidden status message. Placeholders shimmer left to right, in step with
-every other skeleton on the page. When to show the skeleton, and for how long, is up to the
-caller.
+`Section.Group skeleton` turns a card into its loading state, drawn from placeholder content you
+pass in. The title, label, and description render their text as bars, one per line, as wide as the
+text. Media render as a filled block, and actions draw nothing and hold the height of a small
+control. A part can also take `skeleton` on its own, or `skeleton={false}` to stay as content inside
+a skeleton card. A skeleton card is inert and hidden from assistive technology, so pair it with a
+visually hidden status message. A highlight sweeps left to right across each placeholder. When to
+show the skeleton, and for how long, is up to the caller.
 
 `Section.Title` renders at the level from the nearest `HeadingLevelProvider`, or `h2` outside one.
 On a page, put the sections in `Panel.Sections` so the card titles sit one level below the page

From a0c8577ab73bcb19d94af0b5dafcdd687f88169f Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Tue, 6 Oct 2026 12:54:06 -0600
Subject: [PATCH 11/14] feat(mosaic): round skeleton text bands and leave a gap
 between lines

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/skeletons.md | 10 +++++++---
 packages/mosaic/src/styles/skeleton.styles.ts | 18 +++++++++---------
 2 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
index afdba9bcd96..78e3ceb2f8d 100644
--- a/.claude/skills/mosaic/references/skeletons.md
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -68,14 +68,18 @@ same fill, `--cl-color-neutral-alpha-200`.
   `Section.Actions skeleton` exists because a 28px `sm` menu trigger outgrew a 20px
   line.
 - **Width and wrapping come from the mock text.** Each line's band is as wide as
-  that line of mock text and as tall as the font's text box (ascender to
-  descender), whatever font is in use. Nothing is measured.
+  that line of mock text. Nothing is measured.
+- **Band height:** 75% of the font's text box (ascender to descender), centered on
+  each line, so stacked lines keep a visible gap. A pill radius on the span softens
+  the ends; CSS can't shrink an inline box itself, and `clip-path` clips the whole
+  span rather than each line, so a sized background layer is the only per-line
+  option.
 
 ## The shimmer
 
 Modeled on React Spectrum's `Skeleton`, with no JavaScript: a highlight one bone wide,
 peaking in the middle, sweeps left to right across two bone widths, over 1.6s
-`ease-in-out`, repeating. Off under `prefers-reduced-motion: reduce`, leaving the
+`--cl-ease-in-out`, repeating. Off under `prefers-reduced-motion: reduce`, leaving the
 plain fill.
 
 - **Blocks** (media, the avatar) move an `::after` overlay with `transform`
diff --git a/packages/mosaic/src/styles/skeleton.styles.ts b/packages/mosaic/src/styles/skeleton.styles.ts
index e99d4d89a22..16961ad6381 100644
--- a/packages/mosaic/src/styles/skeleton.styles.ts
+++ b/packages/mosaic/src/styles/skeleton.styles.ts
@@ -1,6 +1,6 @@
 import * as stylex from '@stylexjs/stylex';
 
-import { colorVars, radiusVars } from '../tokens.stylex';
+import { colorVars, easingVars, radiusVars } from '../tokens.stylex';
 
 const highlight =
   'light-dark(color-mix(in oklab, var(--cl-color-background) 62%, transparent), color-mix(in oklab, var(--cl-color-neutral) 7%, transparent))';
@@ -11,8 +11,8 @@ const translate = stylex.keyframes({
 });
 
 const pan = stylex.keyframes({
-  from: { backgroundPosition: '100% 0' },
-  to: { backgroundPosition: '0% 0' },
+  from: { backgroundPosition: '100% 50%, 0 50%' },
+  to: { backgroundPosition: '0% 50%, 0 50%' },
 });
 
 export const skeletonStyles = stylex.create({
@@ -32,7 +32,7 @@ export const skeletonStyles = stylex.create({
         default: translate,
         '@media (prefers-reduced-motion: reduce)': 'none',
       },
-      animationTimingFunction: 'ease-in-out',
+      animationTimingFunction: easingVars['--cl-ease-in-out'],
       backgroundImage: `linear-gradient(90deg, transparent, ${highlight}, transparent)`,
       content: "''",
       position: 'absolute',
@@ -41,18 +41,18 @@ export const skeletonStyles = stylex.create({
   },
   text: {
     WebkitTextFillColor: 'transparent',
-    backgroundPosition: '100% 0',
+    backgroundPosition: '100% 50%, 0 50%',
+    borderRadius: radiusVars['--cl-radius-full'],
     animationDuration: '1.6s',
     animationIterationCount: 'infinite',
     animationName: {
       default: pan,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
-    animationTimingFunction: 'ease-in-out',
-    backgroundColor: colorVars['--cl-color-neutral-alpha-200'],
-    backgroundImage: `linear-gradient(90deg, transparent 33.33%, ${highlight} 50%, transparent 66.67%)`,
+    animationTimingFunction: easingVars['--cl-ease-in-out'],
+    backgroundImage: `linear-gradient(90deg, transparent 33.33%, ${highlight} 50%, transparent 66.67%), linear-gradient(${colorVars['--cl-color-neutral-alpha-200']}, ${colorVars['--cl-color-neutral-alpha-200']})`,
     backgroundRepeat: 'no-repeat',
-    backgroundSize: '300% 100%',
+    backgroundSize: '300% 75%, 100% 75%',
     boxDecorationBreak: 'clone',
     color: 'transparent',
     userSelect: 'none',

From e1589a58fa7a4798165aee94da3b6df4cd13ece1 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Tue, 6 Oct 2026 13:04:08 -0600
Subject: [PATCH 12/14] feat(mosaic): size skeleton text bars from mock text at
 cap height

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/skeletons.md | 35 +++++++------
 packages/mosaic/src/styles/skeleton.styles.ts | 49 ++++++++++++-------
 packages/mosaic/src/utils/skeleton-text.tsx   |  8 +--
 packages/swingset/src/stories/section.mdx     |  4 +-
 4 files changed, 56 insertions(+), 40 deletions(-)

diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
index 78e3ceb2f8d..dbadfa8a9a0 100644
--- a/.claude/skills/mosaic/references/skeletons.md
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -54,8 +54,8 @@ same fill, `--cl-color-neutral-alpha-200`.
   filled block; Actions render nothing and hold a small control's height.
 - **A component with its own shape** composes the pieces in
   `styles/skeleton.styles.ts` itself:
-  - `SkeletonText` (`utils/skeleton-text.tsx`) around mock text: one inline span
-    whose text is transparent and whose background draws each wrapped line.
+  - `SkeletonText` (`utils/skeleton-text.tsx`) around mock text: one span, one
+    line, as wide as its transparent text, drawing a bar with its `::before`.
   - `skeletonStyles.bone`: fill and radius, for media and blocks.
   - `skeletonStyles.shimmer`: the moving highlight for a block, as an `::after`
     overlay. `Avatar.Fallback`, which has its own fill and circle, takes `shimmer`
@@ -67,27 +67,32 @@ same fill, `--cl-color-neutral-alpha-200`.
   rows match by construction. Watch anything taller than its text:
   `Section.Actions skeleton` exists because a 28px `sm` menu trigger outgrew a 20px
   line.
-- **Width and wrapping come from the mock text.** Each line's band is as wide as
-  that line of mock text. Nothing is measured.
-- **Band height:** 75% of the font's text box (ascender to descender), centered on
-  each line, so stacked lines keep a visible gap. A pill radius on the span softens
-  the ends; CSS can't shrink an inline box itself, and `clip-path` clips the whole
-  span rather than each line, so a sized background layer is the only per-line
-  option.
+- **The bar is cap height on the baseline.** `SkeletonText` is one line of the
+  part's own type (`1lh` tall, so heights match), and its `::before` bar is `1cap`
+  tall (`0.7em` fallback), sitting on the baseline with a pill radius. It covers
+  the same band as the text's capitals in any font, with nothing measured, and
+  stacked lines keep a natural gap.
+- **Width comes from the mock text.** The span is `width: fit-content` around its
+  transparent mock text, and the bar fills it (a `-100%` end margin keeps the bar
+  from taking space in the line, so it shares the text's baseline). So each bar is
+  exactly as long as the text it stands in for. Mock text is held to one line
+  (`nowrap`, clipped at the part's width), so a long placeholder can't wrap and
+  shift the layout; keep placeholders to one line of real content. With no mock
+  text, the bar falls back to `12ch`.
 
 ## The shimmer
 
 Modeled on React Spectrum's `Skeleton`, with no JavaScript: a highlight one bone wide,
 peaking in the middle, sweeps left to right across two bone widths, over 1.6s
-`--cl-ease-in-out`, repeating. Off under `prefers-reduced-motion: reduce`, leaving the
-plain fill.
+`ease-in-out` (the CSS keyword, not a token), repeating. Off under
+`prefers-reduced-motion: reduce`, leaving the plain fill.
 
 - **Blocks** (media, the avatar) move an `::after` overlay with `transform`
   (`translateX(-100%)` → `translateX(100%)`), clipped by `overflow: hidden`.
-- **Text** moves its own background, since an overlay can't follow wrapped lines:
-  a gradient `300%` wide (transparent, highlight, transparent at 33% / 50% / 66%)
-  over the fill, from `background-position: 100%` to `0%`, cloned per line with
-  `box-decoration-break`. Same geometry and timing as the overlay.
+- **Text bars** are themselves a pseudo-element, so they move their own
+  background instead: a gradient `300%` wide (transparent, highlight, transparent
+  at 33% / 50% / 66%) over the fill, from `background-position: 100%` to `0%`.
+  Same geometry and timing as the overlay.
 - **The highlight** is a wash over the fill, one value in both techniques:
   background-tinted in light mode, neutral-tinted in dark.
 - **No sync.** Bones that mount together sweep together; a section mounting later
diff --git a/packages/mosaic/src/styles/skeleton.styles.ts b/packages/mosaic/src/styles/skeleton.styles.ts
index 16961ad6381..1a4cd50d782 100644
--- a/packages/mosaic/src/styles/skeleton.styles.ts
+++ b/packages/mosaic/src/styles/skeleton.styles.ts
@@ -1,6 +1,6 @@
 import * as stylex from '@stylexjs/stylex';
 
-import { colorVars, easingVars, radiusVars } from '../tokens.stylex';
+import { colorVars, radiusVars } from '../tokens.stylex';
 
 const highlight =
   'light-dark(color-mix(in oklab, var(--cl-color-background) 62%, transparent), color-mix(in oklab, var(--cl-color-neutral) 7%, transparent))';
@@ -11,8 +11,8 @@ const translate = stylex.keyframes({
 });
 
 const pan = stylex.keyframes({
-  from: { backgroundPosition: '100% 50%, 0 50%' },
-  to: { backgroundPosition: '0% 50%, 0 50%' },
+  from: { backgroundPosition: '100% 0, 0 0' },
+  to: { backgroundPosition: '0% 0, 0 0' },
 });
 
 export const skeletonStyles = stylex.create({
@@ -32,7 +32,7 @@ export const skeletonStyles = stylex.create({
         default: translate,
         '@media (prefers-reduced-motion: reduce)': 'none',
       },
-      animationTimingFunction: easingVars['--cl-ease-in-out'],
+      animationTimingFunction: 'ease-in-out',
       backgroundImage: `linear-gradient(90deg, transparent, ${highlight}, transparent)`,
       content: "''",
       position: 'absolute',
@@ -41,20 +41,35 @@ export const skeletonStyles = stylex.create({
   },
   text: {
     WebkitTextFillColor: 'transparent',
-    backgroundPosition: '100% 50%, 0 50%',
-    borderRadius: radiusVars['--cl-radius-full'],
-    animationDuration: '1.6s',
-    animationIterationCount: 'infinite',
-    animationName: {
-      default: pan,
-      '@media (prefers-reduced-motion: reduce)': 'none',
-    },
-    animationTimingFunction: easingVars['--cl-ease-in-out'],
-    backgroundImage: `linear-gradient(90deg, transparent 33.33%, ${highlight} 50%, transparent 66.67%), linear-gradient(${colorVars['--cl-color-neutral-alpha-200']}, ${colorVars['--cl-color-neutral-alpha-200']})`,
-    backgroundRepeat: 'no-repeat',
-    backgroundSize: '300% 75%, 100% 75%',
-    boxDecorationBreak: 'clone',
+    overflow: 'hidden',
     color: 'transparent',
+    display: 'block',
     userSelect: 'none',
+    whiteSpace: 'nowrap',
+    maxWidth: '100%',
+    width: {
+      default: 'fit-content',
+      ':empty': '12ch',
+    },
+    '::before': {
+      backgroundPosition: '100% 0, 0 0',
+      borderRadius: radiusVars['--cl-radius-full'],
+      animationDuration: '1.6s',
+      animationIterationCount: 'infinite',
+      animationName: {
+        default: pan,
+        '@media (prefers-reduced-motion: reduce)': 'none',
+      },
+      animationTimingFunction: 'ease-in-out',
+      backgroundImage: `linear-gradient(90deg, transparent 33.33%, ${highlight} 50%, transparent 66.67%), linear-gradient(${colorVars['--cl-color-neutral-alpha-200']}, ${colorVars['--cl-color-neutral-alpha-200']})`,
+      backgroundRepeat: 'no-repeat',
+      backgroundSize: '300% 100%, 100% 100%',
+      content: "''",
+      display: 'inline-block',
+      marginInlineEnd: '-100%',
+      verticalAlign: 'baseline',
+      height: stylex.firstThatWorks('1cap', '0.7em'),
+      width: '100%',
+    },
   },
 });
diff --git a/packages/mosaic/src/utils/skeleton-text.tsx b/packages/mosaic/src/utils/skeleton-text.tsx
index 82495fa86fe..b6e1551c9dd 100644
--- a/packages/mosaic/src/utils/skeleton-text.tsx
+++ b/packages/mosaic/src/utils/skeleton-text.tsx
@@ -3,15 +3,11 @@ import type React from 'react';
 
 import { skeletonStyles } from '../styles/skeleton.styles';
 
-const webkitClone = { WebkitBoxDecorationBreak: 'clone' } as React.CSSProperties;
-
-export function SkeletonText({ children }: { children: React.ReactNode }) {
-  const props = stylex.props(skeletonStyles.text);
+export function SkeletonText({ children }: { children?: React.ReactNode }) {
   return (
     <span
       aria-hidden
-      className={props.className}
-      style={{ ...props.style, ...webkitClone }}
+      {...stylex.props(skeletonStyles.text)}
     >
       {children}
     </span>
diff --git a/packages/swingset/src/stories/section.mdx b/packages/swingset/src/stories/section.mdx
index c91c856c5c3..4339d7a7e61 100644
--- a/packages/swingset/src/stories/section.mdx
+++ b/packages/swingset/src/stories/section.mdx
@@ -51,8 +51,8 @@ than `26rem`. `sectionCompactStyles.hidden` and `sectionCompactStyles.only` togg
 the same width.
 
 `Section.Group skeleton` turns a card into its loading state, drawn from placeholder content you
-pass in. The title, label, and description render their text as bars, one per line, as wide as the
-text. Media render as a filled block, and actions draw nothing and hold the height of a small
+pass in. The title, label, and description each render one bar, as wide as their text (held to one
+line). Media render as a filled block, and actions draw nothing and hold the height of a small
 control. A part can also take `skeleton` on its own, or `skeleton={false}` to stay as content inside
 a skeleton card. A skeleton card is inert and hidden from assistive technology, so pair it with a
 visually hidden status message. A highlight sweeps left to right across each placeholder. When to

From 4afa651bd37a17d6326c3212ff527d971770062c Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Tue, 6 Oct 2026 13:06:28 -0600
Subject: [PATCH 13/14] docs(repo): point the motion skill at the shimmer's
 ease-in-out keyword

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/motion.md | 27 +++++++++++-----------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/.claude/skills/mosaic/references/motion.md b/.claude/skills/mosaic/references/motion.md
index 99e91f66eac..d3ba4e1816d 100644
--- a/.claude/skills/mosaic/references/motion.md
+++ b/.claude/skills/mosaic/references/motion.md
@@ -5,17 +5,17 @@ Token semantics live in `packages/mosaic/src/tokens.stylex.ts`, above
 how-to layer: the rules that decide a transition's shape, and how to check one
 rather than eyeball it.
 
-| Token                   | Value                                   | For                                                      |
-| ----------------------- | --------------------------------------- | -------------------------------------------------------- |
-| `--cl-duration-instant` | `0s`                                    | hover and press arrival                                  |
-| `--cl-duration-fast`    | `0.1s`                                  | exits                                                    |
-| `--cl-duration-base`    | `0.15s`                                 | entrances, hover exit                                    |
-| `--cl-duration-slow`    | `0.25s`                                 | larger surfaces                                          |
-| `--cl-duration-slower`  | `0.35s`                                 | —                                                        |
-| `--cl-ease-default`     | `cubic-bezier(0.175, 0.885, 0.32, 1.1)` | things ARRIVING (Swift Out)                              |
-| `--cl-ease-enter`       | `cubic-bezier(0, 0, 0.2, 1)`            | arrivals that must not overshoot                         |
-| `--cl-ease-exit`        | `cubic-bezier(0.55, 0.085, 0.68, 0.53)` | things LEAVING (In Quad)                                 |
-| `--cl-ease-in-out`      | `cubic-bezier(0.645, 0.045, 0.355, 1)`  | rest-to-rest layout, the skeleton shimmer (In Out Cubic) |
+| Token                   | Value                                   | For                                |
+| ----------------------- | --------------------------------------- | ---------------------------------- |
+| `--cl-duration-instant` | `0s`                                    | hover and press arrival            |
+| `--cl-duration-fast`    | `0.1s`                                  | exits                              |
+| `--cl-duration-base`    | `0.15s`                                 | entrances, hover exit              |
+| `--cl-duration-slow`    | `0.25s`                                 | larger surfaces                    |
+| `--cl-duration-slower`  | `0.35s`                                 | —                                  |
+| `--cl-ease-default`     | `cubic-bezier(0.175, 0.885, 0.32, 1.1)` | things ARRIVING (Swift Out)        |
+| `--cl-ease-enter`       | `cubic-bezier(0, 0, 0.2, 1)`            | arrivals that must not overshoot   |
+| `--cl-ease-exit`        | `cubic-bezier(0.55, 0.085, 0.68, 0.53)` | things LEAVING (In Quad)           |
+| `--cl-ease-in-out`      | `cubic-bezier(0.645, 0.045, 0.355, 1)`  | rest-to-rest layout (In Out Cubic) |
 
 Named curves come from [easing.dev](https://www.easing.dev) (Lochie Axon's Easing
 Graphs). Take one from there rather than inventing a bezier, so the catalog stays
@@ -54,8 +54,9 @@ slower approach to full opacity — is left.
 
 ## Loading skeletons
 
-Loading placeholders shimmer in sync on `--cl-ease-in-out`. How to build them, size
-them, and tune the shimmer is in `skeletons.md`.
+Loading placeholders shimmer: a highlight sweeps across each one over 1.6s on the
+plain `ease-in-out` keyword, not a token. How to build them, size them, and tune the
+shimmer is in `skeletons.md`.
 
 ## A curve has a direction — don't run the entrance curve backwards
 

From 22a1f3643c74f2548264cad706db4355ec94b6d2 Mon Sep 17 00:00:00 2001
From: Max Yinger <max.yinger@clerk.dev>
Date: Tue, 6 Oct 2026 13:10:48 -0600
Subject: [PATCH 14/14] fix(mosaic): hide content nested in skeleton text and
 drop device badges from the skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/mosaic/references/skeletons.md               | 5 ++++-
 .../user-profile-active-devices-section.view.tsx            | 6 +++++-
 packages/mosaic/src/styles/skeleton.styles.ts               | 4 ++--
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/mosaic/references/skeletons.md b/.claude/skills/mosaic/references/skeletons.md
index dbadfa8a9a0..f2797f6dda5 100644
--- a/.claude/skills/mosaic/references/skeletons.md
+++ b/.claude/skills/mosaic/references/skeletons.md
@@ -55,7 +55,10 @@ same fill, `--cl-color-neutral-alpha-200`.
 - **A component with its own shape** composes the pieces in
   `styles/skeleton.styles.ts` itself:
   - `SkeletonText` (`utils/skeleton-text.tsx`) around mock text: one span, one
-    line, as wide as its transparent text, drawing a bar with its `::before`.
+    line, as wide as its text, drawing a bar with its `::before`. The span is
+    `visibility: hidden` and only the bar is visible, so anything nested in the
+    mock text (a badge, a link, an icon) keeps its width but never draws. Leave
+    badges out of mock rows entirely; a skeleton doesn't draw them.
   - `skeletonStyles.bone`: fill and radius, for media and blocks.
   - `skeletonStyles.shimmer`: the moving highlight for a block, as an `::after`
     overlay. `Avatar.Fallback`, which has its own fill and circle, takes `shimmer`
diff --git a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
index 707e2ccd9f9..948e5a8715c 100644
--- a/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
+++ b/packages/mosaic/src/features/user-profile/user-profile-active-devices-section.view.tsx
@@ -92,6 +92,7 @@ export function UserProfileActiveDevicesSectionView({
                   <DeviceItem
                     key={device.id}
                     device={device}
+                    skeleton={skeleton}
                     triggerRef={device.id === currentDevices[0]?.id ? currentDeviceTrigger : undefined}
                     onViewDetails={device => deviceDetails.open(device)}
                   />
@@ -107,6 +108,7 @@ export function UserProfileActiveDevicesSectionView({
                 <DeviceItem
                   key={device.id}
                   device={device}
+                  skeleton={skeleton}
                   triggerRef={removalFocus.registerTrigger(device.id)}
                   onSignOut={openSignOut}
                   onViewDetails={device => deviceDetails.open(device)}
@@ -174,11 +176,13 @@ function DeviceItem({
   triggerRef,
   onViewDetails,
   onSignOut,
+  skeleton = false,
 }: {
   device: UserProfileDevice;
   triggerRef?: Ref<HTMLButtonElement>;
   onViewDetails: (device: UserProfileDevice) => void;
   onSignOut?: (device: UserProfileDevice) => void;
+  skeleton?: boolean;
 }) {
   const m = useMessages('userProfileActiveDevices');
   const actions: ActionMenuAction[] = [{ label: m.viewDetails, onClick: () => onViewDetails(device) }];
@@ -193,7 +197,7 @@ function DeviceItem({
       <Section.Content>
         <Section.Label>
           {device.name}
-          {deviceBadges(device, m).map(label => (
+          {(skeleton ? [] : deviceBadges(device, m)).map(label => (
             <Badge
               key={label}
               color='neutral'
diff --git a/packages/mosaic/src/styles/skeleton.styles.ts b/packages/mosaic/src/styles/skeleton.styles.ts
index 1a4cd50d782..42bc81f9b40 100644
--- a/packages/mosaic/src/styles/skeleton.styles.ts
+++ b/packages/mosaic/src/styles/skeleton.styles.ts
@@ -40,11 +40,10 @@ export const skeletonStyles = stylex.create({
     },
   },
   text: {
-    WebkitTextFillColor: 'transparent',
     overflow: 'hidden',
-    color: 'transparent',
     display: 'block',
     userSelect: 'none',
+    visibility: 'hidden',
     whiteSpace: 'nowrap',
     maxWidth: '100%',
     width: {
@@ -68,6 +67,7 @@ export const skeletonStyles = stylex.create({
       display: 'inline-block',
       marginInlineEnd: '-100%',
       verticalAlign: 'baseline',
+      visibility: 'visible',
       height: stylex.firstThatWorks('1cap', '0.7em'),
       width: '100%',
     },