feat(avatar): AvatarGroup with clipped separation and inherited sizing

[pasqualevitiello]

Summary

AvatarGroup and AvatarGroupCount are new. Overlapping avatars are separated by masking each one with its neighbour's circle, so the gap is transparent rather than a coloured ring. A stack now holds its shape on gradients, photographs and translucent panels, where ring-2 ring-background does not.

Avatar takes every dimension from one inherited custom property, --avatar-size (default 32px). Font size scales with it, and a group derives overlap, gap and the initials nudge from it.

<AvatarGroup topmost="last">
  <Avatar>…</Avatar>
  <AvatarGroupCount>+2</AvatarGroupCount>
</AvatarGroup>

Technique

The cut is a vector circle composited out of the avatar's own circle:

mask-image: url("data:image/svg+xml,…<circle>…"), url(…same…)
mask-composite: subtract

Both layers are SVG, so the whole silhouette comes from one vector rasterisation. Three earlier approaches were rejected against real rendering:

approach	failure
ring-2 ring-background	wrong on any non-solid surface — the reason for this PR
radial-gradient with a 1px feather	a CSS-pixel feather scales under browser zoom, so the cut edge blurs
radial-gradient with a hard stop	gradient stops are not antialiased, so the edge stair-steps as the avatar grows

Masked children also carry rounded-none. With border-radius left on, its antialiased rim survives subtract and leaves a hairline ghost of the full circle — reproduced on a bare div, independent of Avatar.

Browser support

mask-composite is Baseline 2023: Chrome/Edge 120, Firefox 53, Safari 15.4. Against Tailwind v4's own floor (Chrome 111, Safari 16.4, Firefox 128) only Chrome and Edge 111–119 are exposed.

There the declaration is dropped and the two layers composite with add, turning the bite into a union — avatars render as hard-edged squares. An @supports guard gates both the mask and rounded-none, so those browsers get a plain overlap with no gap instead.

Visual changes to existing avatars

Existing Avatar JSX needs no edits, but two defaults changed:

• AvatarFallback uses bg-border (black/8%) instead of bg-muted (black/4%). Every fallback is twice the contrast.
• Avatar no longer paints bg-background. Visible only behind a transparent image with no fallback.

AvatarImage and AvatarFallback now follow the root radius via rounded-[inherit], so a rounded avatar no longer repeats its radius on the fallback.

Validation

• bunx tsc --noEmit in apps/ui
• bunx biome check on every changed file
• bun run registry:validate-deps and registry:build in apps/ui
• Rendered checks in the dev app at 16–208px, both topmost modes, LTR and RTL, light and dark, over page/muted/gradient/photo surfaces, and at 4× browser zoom
• render={<button>} / render={<a>} verified to emit real BUTTON and A elements with accessible names; group tooltips verified to open with clipping intact

Merge Danger

Door: two-way

Blast Radius: @coss/avatar and its consumers

Any app rendering AvatarFallback sees the darker surface after updating. Group clipping is new API, so nothing regresses there. Nine particles across select, combobox, button, skeleton and group moved from size-* to --avatar-size; their boxes are unchanged but fallback type now scales, so combobox and select avatars show 7.5px initials where they showed a hand-set 10px.

Rollback

Revert the five commits; avatar.tsx and packages/ui/src/components/avatar.tsx return to the ring-based stack.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
coss-com	Ready	Preview	Oct 18, 2026 6:29pm UTC
coss-com-ui	Ready	Preview	Oct 18, 2026 6:29pm UTC
coss-examples-calcom	Ready	Preview	Oct 18, 2026 6:29pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
coss-com-origin	Skipped		Oct 18, 2026 6:29pm UTC

[pasqualevitiello]

I tested this on cal in calcom/cal#11066, copying avatar.tsx over cal's vendored coss-ui verbatim. Then I planned the migration for all 73 Avatar importers and the 37 consumers of cal's UserAvatar composite. The swap on its own is visually safe. An unmigrated size-N call site keeps its 12px initials, because --avatar-size stays unset and the font resolves to 32px × 0.375. The six points below show up only once call sites follow the migration notes.

1. Derived initials are too small below 32px. After migration, initials are N × 1.5px, so size-4 gives 6px, size-5 7.5px and size-6 9px. Cal already pins about ten size-5 avatars to text-[.625rem] (10px), and its size-4 ones to text-[8px]. The design consistently wants a floor of about 8–10px. A floor in the base class would remove most of those overrides, for example text-[max(--spacing(2.5),calc(var(--avatar-size,--spacing(8))*0.375))]. Otherwise, the docs could say that small sizes need a fallback override.

2. The changelog's stack diff reverses which avatar sits on top. In a flex -space-x-2 stack, later siblings paint on top, so the last avatar is the whole one. The diff converts that stack to <AvatarGroup> with the default topmost="first", which flips it. All twelve of cal's stacks need topmost="last". Either add topmost="last" to the changelog diff and the agent migration prompt, or make "last" the default.

3. Interactive group children need a documented pattern. Six of cal's twelve stacks wrap each avatar in a <Link>, an <a>, an <li> or a tooltip <span>. That wrapper becomes the group's direct child, so it gets masked instead of the avatar. The fix is to make the avatar the element itself, for example TooltipTrigger render={<Avatar render={<Link href=… />} />}, which is the nesting cal's public booking page needs. A short example of that next to "Group Avatars" would save consumers the guesswork.

4. AvatarGroup has no render prop. Two cal stacks are <ul>/<li> lists and lose that semantics when they become a <div>. In another, the whole stack is a DialogTrigger button, so the group has to sit inside the button instead of becoming it. useRender on AvatarGroup would cover both cases.

5. Groups only overlap horizontally. Cal's app-shell header overlaps the org and user avatars side by side on lg, then stacks them vertically on md and in the collapsed sidebar. Group geometry is horizontal only, so that stack stays hand-made. That may be fine as a non-goal, but it's worth saying in the docs.

6. The new background defaults are visible. The bg-muted → bg-border change and the root's lost bg-background both show in cal:

• transparent team, org and OAuth-client logos now show the surface behind them, including over a banner image;
• fallback-only avatars read darker.

This matches the changelog, so nothing needs to change upstream. The note about setting those classes back explicitly is the important part, and it might deserve a line in the agent migration prompt about logos specifically.

[linear-code]

ENG-6435