Letter Avatar

Basic

There is no colour prop. Pass a name; the tone follows. Two people with the same tone is fine and expected — the colour is a memory aid, never an identifier.

Sizes

The stack overlap in AvatarGroup is per size, not one constant. The approved pattern is -space-x-2 on a 40px avatar — a 20% overlap. Applying that to xs (24px) would be a 33% overlap, and with the 2px ring on top the hidden edge reaches 10px while the first initial starts about 5.5px in: the letter disappears. Holding the ratio near 20% keeps every size readable at the density the design calls for.

People are round, things are square

square swaps rounded-full for rounded-md. Shape is the only signal separating a person from a workspace or an app in a dense list, so keep the convention absolute.

Photo, with initials as the fallback

When src is set the image fills the avatar and the tone classes are not applied at all — a photo never picks up a tint. The image is a plain <img> with loading="lazy", not next/image: the . entry has to run under Vite, Storybook and test runners as well as Next, so optimisation is the app's job — pass a URL that already went through your CDN or loader.

PreviewCode

Trần Thị Maisrc set

TMTrần Thị Maisrc = null

Comitor Taskssquare + src

The eight tones, and how a name picks one

getAvatarToneIndex(name) is an FNV-1a hash of the name — trimmed and lowercased with the vi-VN locale — modulo eight. It runs over code points rather than bytes so accented names hash identically on the server and in the browser. The hash function itself is not exported: handing it out only invites apps to build a second tone-picking scheme, which is precisely how one person ends up two colours.

The palette is the accent set plus the chart ramp, not the semantic tokens. These are identity colours, not status colours — assigning --success to a human being would be a category error, and the accent and chart groups are the only tokens with eight distinct hues that also have a dark-mode counterpart.

Because the seed is normalised, the same person written three ways lands on the same tone:

Classes for the DOM, hex for everything else

The tone table exists once, in a module neither entry point exports. It is reached through exactly two doors, and which one you use depends on whether Tailwind is present: getAvatarToneClasses(name) returns the class string for the DOM, and getAvatarToneColors(name, mode) in @comitor/ui/tokens returns opaque hex for canvas, PDF and email HTML. Both call the same getAvatarToneIndex, so web and email agree by construction rather than by discipline. The hex is pre-composited: most tones are alpha tints over --card, and there is nothing to composite against inside an email client, so the mixing is done ahead of time — which is why mode is a parameter.

The swatches above are inline hex on purpose — they are literally what getAvatarToneColors hands a canvas or an email template, so both theme columns are shown side by side rather than following this page's theme. Inside a Tailwind app, never do this: use getAvatarToneClasses and let the tokens flip with the theme and with the high-contrast palette.

Overriding the tone

toneClassName is the supported way to colour an avatar by something other than its name — an app's accent, a workspace colour. Pass token classes, never a hex, or the avatar is pinned to one palette and wrong in the other.

Vietnamese initials

getVietnameseInitials takes the first character of the first word and the first character of the last word. Vietnamese names are family name first and given name last, and people are addressed by the given name — so the Western “first two words” rule would turn Nguyễn Đức Thành into NĐ, the two characters that identify him least. It is exported on its own, so a table cell or a mention chip can use the same rule without rendering an avatar.

AvatarGroup

Assignees on a task, participants in a chat, followers on a deal. Every avatar is a focusable button that opens a tooltip with the full name and an optional caption — overlapping avatars hide part of the initials, and without the tooltip a stack is decoration that never says who is actually involved. Hover or Tab through the demo. The label prop names the group for screen readers and defaults to the Vietnamese Thành viên.

surfaceClassName — why the group needs to know where it stands

Most avatar tones are alpha tints (bg-teal/15, bg-yellow/25), and a group deliberately overlaps them with -space-x-2. With no opaque layer underneath, the upper avatar's tint composites against the avatar below it instead of the page — three faces blend into one another exactly where they overlap. surfaceClassName supplies both halves of the fix: an opaque background under each avatar and the colour of the ring-2 that separates them. The ring alone is not enough — it draws around the avatar and cannot stop tints compositing inside it.

The default is bg-card ring-card, which is also the surface getAvatarToneColors assumes when it pre-composites its hex. Move the group to another surface and restate both classes.

One is a Server Component, one is not

LetterAvatar has no 'use client' directive — deliberately. Radix's Avatar primitive must be a client component because it tracks image load state; in a 200-row member table that is 200 pointless islands. This avatar is fully static and renders on the server. AvatarGroup is a client component, because the tooltip needs to be — so reach for it where the hover names earn the island.

// LetterAvatar has NO 'use client' — a 200-row table renders 200 avatars
// straight on the server. Radix Avatar is a client component because it tracks
// image load state; that would be 200 pointless islands here.
import { LetterAvatar } from '@comitor/ui'

export default async function MemberTable() {
  const members = await db.members.findMany()
  return (
    <table>
      <tbody>
        {members.map((m) => (
          <tr key={m.id}>
            <td><LetterAvatar name={m.name} src={m.avatarUrl} size="sm" /></td>
            <td>{m.name}</td>
          </tr>
        ))}
      </tbody>
    </table>
  )
}

// AvatarGroup IS 'use client' — it needs the tooltip. Keep it to the places
// where the hover names are worth the island.

LetterAvatar props

AvatarGroup props

Items are typed as AvatarGroupItem: { id: string; name: string; src?: string | null; caption?: string }.

Accessibility

• The name is announced on every branch. The initials span is aria-hidden — “NT” read aloud is noise — so a sr-only span carries the full name. Without it an avatar with no photo would be a mute coloured square, and inside AvatarGroup that span is what gives each trigger button its accessible name.
• The <img> branch uses alt="" precisely because the same sr-only name is already there — alt={name} would read the person twice.
• title={name} gives a native hover tooltip for sighted mouse users. AvatarGroup passes title={undefined} to suppress it there, so the native tooltip does not race the Radix one.
• The group wrapper is role="group" with aria-label from label, so the stack is announced as one named region rather than a run of loose images.
• Each avatar in a group is a real <button type="button"> with no click handler. That is intentional: a bare <span> receives mouse events only, so the tooltip — and therefore the member's name — would be invisible to keyboard users.
• The focus ring is outline-foreground, not ring. --ring is the brand gold, and #E8B824 is only 1.86:1 against the page in light mode — under the 3:1 that WCAG 1.4.11 / 2.4.11 require of a focus indicator (in dark, #F5D060 reaches 12.67:1, so the naive choice fails for exactly half the users). outline-foreground measures 18.91:1 light and 17.66:1 dark, matching the row focus ring in DataTable.
• Initials clear AA even though they are aria-hidden — sighted users still read them. The first pass put text-teal/green/red straight on a 15% tint and failed in light mode: teal 3.44:1, green 2.69:1 (below even 3:1), red 3.57:1. Fixing it followed the Badge rule — background token for the fill, -ink token for the glyph. Measured on the exact composited hex: #1A6668 on #DDEDEE = 5.54:1, #216A48 on #E0F2E9 = 5.60:1, #9A3537 on #F9E3E3 = 5.83:1, with 7.12 / 7.44 / 5.18:1 for the dark counterparts.
• Tooltip captions run at opacity-80, and that is measured rather than careless: the tooltip is bg-foreground text-background, so 80% still yields 12.15:1 in light and 9.85:1 in dark. Tooltip content is also non-interactive.
• Colour is never the only carrier of identity — the initials and the accessible name always accompany it, and eight tones over any real directory means collisions are routine. Do not use tone to encode state.
• Vietnamese defaults to replace in an English app: label (“Thành viên”) and overflowLabel (“Xem tất cả N thành viên”, the +k chip's sr-only name). Translating label alone leaves the last button in the group speaking Vietnamese.