From f202c371bc03b2ffb294b6a58d6b767cfac73e77 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Fri, 11 Sep 2026 15:27:29 -0400
Subject: [PATCH] feat(ui): resize the Mosaic Avatar scale and key square
 radius off size

---
 .changeset/mosaic-avatar-sizing.md            |  2 +
 packages/swingset/src/stories/avatar.mdx      |  2 +-
 .../swingset/src/stories/avatar.stories.tsx   |  6 +--
 .../mosaic/components/avatar/avatar.styles.ts | 40 +++++++++++++++----
 .../src/mosaic/components/avatar/avatar.tsx   |  2 +-
 packages/ui/src/mosaic/tokens.stylex.ts       |  4 +-
 6 files changed, 41 insertions(+), 15 deletions(-)
 create mode 100644 .changeset/mosaic-avatar-sizing.md

diff --git a/.changeset/mosaic-avatar-sizing.md b/.changeset/mosaic-avatar-sizing.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-avatar-sizing.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/swingset/src/stories/avatar.mdx b/packages/swingset/src/stories/avatar.mdx
index d9f3b1f1fb4..9deae63120c 100644
--- a/packages/swingset/src/stories/avatar.mdx
+++ b/packages/swingset/src/stories/avatar.mdx
@@ -58,7 +58,7 @@ While an image is still resolving, the fallback carries `data-pending` and pulse
 
 ### Interactive
 
-Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `xl` avatar and button are both 48×48.
+Use `render` to compose the avatar onto a button or another trigger without introducing a separate wrapper component. The `lg` avatar and button are both 48×48.
 
 <Story
   name='Interactive'
diff --git a/packages/swingset/src/stories/avatar.stories.tsx b/packages/swingset/src/stories/avatar.stories.tsx
index e03aae9cb9c..0344e57fe4f 100644
--- a/packages/swingset/src/stories/avatar.stories.tsx
+++ b/packages/swingset/src/stories/avatar.stories.tsx
@@ -18,7 +18,7 @@ export const meta: StoryMeta = {
   styles: {
     _variants: {
       shape: { circle: {}, square: {} },
-      size: { xs: {}, sm: {}, md: {}, lg: {}, xl: {} },
+      size: { xs: {}, sm: {}, md: {}, lg: {} },
     },
     _defaultVariants: {
       shape: 'circle',
@@ -76,7 +76,7 @@ export function Interactive(props: Record<string, unknown>) {
   return (
     <Avatar.Root
       {...knobsAsProps(props)}
-      size='xl'
+      size='lg'
       render={
         <button
           type='button'
@@ -99,7 +99,7 @@ export function Interactive(props: Record<string, unknown>) {
 export function Sizes(props: Record<string, unknown>) {
   return (
     <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
-      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map(size => (
+      {(['xs', 'sm', 'md', 'lg'] as const).map(size => (
         <Avatar.Root
           key={size}
           {...knobsAsProps(props)}
diff --git a/packages/ui/src/mosaic/components/avatar/avatar.styles.ts b/packages/ui/src/mosaic/components/avatar/avatar.styles.ts
index e68a547bf1a..513c962a570 100644
--- a/packages/ui/src/mosaic/components/avatar/avatar.styles.ts
+++ b/packages/ui/src/mosaic/components/avatar/avatar.styles.ts
@@ -93,19 +93,43 @@ export const styles = stylex.create({
   },
 });
 
-// shape — square shares its radius with Button; circle rounds fully
+// shape — square takes the radius its size sets below; circle rounds fully
 export const shapes = stylex.create({
   circle: { borderRadius: radiusVars['--cl-radius-full'] },
-  square: { borderRadius: radiusVars['--cl-radius-md'] },
+  square: { borderRadius: 'var(--_cl-avatar-radius)' },
 });
 
 // size — square box; font-size is ~0.4x the box, the ceiling at which two initials still clear
 // the circle's clip.
 export const sizes = stylex.create({
-  xs: { fontSize: '0.5rem', height: space['5'], width: space['5'] },
-  sm: { fontSize: '0.6875rem', height: space['7'], width: space['7'] },
-  md: { fontSize: '0.875rem', height: space['9'], width: space['9'] },
-  lg: { fontSize: '1rem', height: space['10'], width: space['10'] },
-  xl: { fontSize: '1rem', height: space['12'], width: space['12'] },
-  fit: { fontSize: '0.75rem', height: '100%', width: '100%' },
+  xs: {
+    '--_cl-avatar-radius': radiusVars['--cl-radius-sm'],
+    fontSize: '0.625rem',
+    height: space['6'],
+    width: space['6'],
+  },
+  sm: {
+    '--_cl-avatar-radius': radiusVars['--cl-radius-md'],
+    fontSize: '0.8125rem',
+    height: space['8'],
+    width: space['8'],
+  },
+  md: {
+    '--_cl-avatar-radius': radiusVars['--cl-radius-lg'],
+    fontSize: '0.9375rem',
+    height: space['9.5'],
+    width: space['9.5'],
+  },
+  lg: {
+    '--_cl-avatar-radius': radiusVars['--cl-radius-lg'],
+    fontSize: '1.125rem',
+    height: space['12'],
+    width: space['12'],
+  },
+  fit: {
+    '--_cl-avatar-radius': radiusVars['--cl-radius-md'],
+    fontSize: '0.75rem',
+    height: '100%',
+    width: '100%',
+  },
 });
diff --git a/packages/ui/src/mosaic/components/avatar/avatar.tsx b/packages/ui/src/mosaic/components/avatar/avatar.tsx
index 1aeeab8de50..011dad90461 100644
--- a/packages/ui/src/mosaic/components/avatar/avatar.tsx
+++ b/packages/ui/src/mosaic/components/avatar/avatar.tsx
@@ -28,7 +28,7 @@ function useAvatarContext(part: string): AvatarContextValue {
 
 export interface AvatarProps extends MosaicComponentProps<'span'> {
   shape?: 'circle' | 'square';
-  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'fit';
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'fit';
 }
 
 const AvatarRoot = React.forwardRef<HTMLSpanElement, AvatarProps>(function MosaicAvatarRoot(
diff --git a/packages/ui/src/mosaic/tokens.stylex.ts b/packages/ui/src/mosaic/tokens.stylex.ts
index 75dccbfb798..d30e5f57f79 100644
--- a/packages/ui/src/mosaic/tokens.stylex.ts
+++ b/packages/ui/src/mosaic/tokens.stylex.ts
@@ -63,8 +63,8 @@ export const colorVars = stylex.defineVars(colorDefaults);
 // =============================================================================
 // Radius Tokens
 // =============================================================================
-// `md` is 6px rather than a 4/8/12 step: it is the control radius (button, avatar
-// square), and neither neighbour sits right on a control.
+// `md` is 6px rather than a 4/8/12 step: it is the control radius (button), and
+// neither neighbour sits right on a control.
 
 const radiusDefaults = {
   '--cl-radius-none': '0rem',