feat(Avatar): allow circle, rounded, or square shape options

[saadpocalypse]

Description

Currently, the Avatar component is always a full circle, and there is no supported way to make it square or rounded-square. Overriding --radius-full in a theme squares everything round (badges, status dots, spinners, etc.) rather than just avatars.

This pull request introduces a new shape prop (circle | rounded | square) to the Avatar component, defaulting to circle. The shape is fully token-driven by a new --radius-avatar design token, allowing themes to set the shape globally (e.g., "all avatars in this app are rounded-square") rather than per instance.

Proposed Changes

Design Token Integration

• Registered a new design token --radius-avatar (defaulting to 9999px) in radiusDefaults.
• Added --radius-avatar to the expandRadiusScale utility.

Avatar Shape Control

• Added the shape prop to AvatarProps.
• Mapped the prop to StyleX overrides for --radius-avatar:
  • circle → --radius-full
  • rounded → --radius-element
  • square → 0px (strictly sharp corners)

Status Dot Placement

Implemented a unified CSS positioning formula for the status indicator using calc() and min():

bottom: calc(min(var(--radius-avatar), S/2) * 0.292893);

This automatically positions the status dot correctly for any value of --radius-avatar, whether the avatar is circular, rounded, or square.

Group & Overflow Support

• Updated AvatarGroupOverflow to use --radius-avatar.
• Updated the overlapping group border ring to use --radius-avatar, ensuring consistent shapes throughout avatar groups.

Documentation Updates

• Documented the new shape prop in Avatar.doc.mjs.
• Removed outdated guidance restricting avatars to circular shapes.

Testing & Stories

• Added unit tests in:
  • Avatar.test.tsx
  • expandRadiusScale.test.ts
• Added a new Shapes Storybook story demonstrating:
  • Circle, rounded, and square avatars
  • Fallback avatars
  • Status indicators

Verification

• Ran pnpm test Avatar and pnpm test expandRadiusScale; all tests passed.
• Rebuilt the core package with:

pnpm -F @astryxdesign/core build

to verify successful StyleX and TypeScript compilation.

• Verified visual alignment and behavior in Storybook.

Resolves

Closes #4205

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 22, 2026 8:39pm