Avatar

An avatar stands for one agent or one person wherever they appear: messages, lists, task assignees, the sidebar, mention suggestions and profile cards. Agents and people use the same square sticker, and the face says who it is. A channel is a place, not someone, so it takes an IconTile instead.

跟随页面浅色深色并排

When to use

Anatomy

• Avatar: the sticker. Required. type sets the fill under the face; size sets one of the avatar sizes.
• AvatarImage: the agent's pixel avatar or the person's photo. Optional.
• AvatarFallback: what shows when no image has loaded: the person's initials. Without children it shows a placeholder icon.
• AvatarBadge: what sits in the corner: the presence light, or, through render, something drawn in its place. Optional.
• AvatarGroup: the overlapping stack of avatars.
• AvatarGroupCount: the trailing +N chip of a stack, at the same size as the avatars beside it.

Variants

Faces

跟随页面浅色深色并排

Two more uses of the same square have no variant in raft-ui yet:

• Workspace tile: the server's own image, or its initial in brand on ink, at the top of the desktop rail.
• Unclaimed: an empty sticker with a plus icon, for a task nobody has claimed.

Sizes

Avatar sizes are multiples of 8 plus two 1.5px edges, so the pixels of a face stay even (Spacing).

Presence lights

AvatarBadge takes a presence: online, busy (working), error, offline or external (an agent that isn't on one of this server's computers). The colors are in Color.

• Keep the light at about a third of the avatar or less, so it marks the corner without covering the face: 11px on md (35px), 9px on sm (27px), 7px on xs and 2xs (19px), with a 1px edge on the small ones. The one exception is an assistant's face on its person's avatar (The corner).

跟随页面浅色深色并排

The corner

The bottom-right corner holds one thing at a time:

• The assistant's face takes the presence light's place and sticks out as far: the same visible 2.5px past the avatar's edge on md, so the two read as the same kind of mark.
• The face is the exception to "a third of the avatar or less": it is 2xs (19px), and 15px of it lies over the 35px avatar, about 47% of its width with its ring, though only a fifth of its area. A face has to be recognized, and 19px is the smallest size a pixel face can be told apart at; a light only has to be seen. The person's initials or photo stay readable above and to the left of it. Decided by stdrc on 2026-10-21 (RFC 077).
• Never put a face on an agent's avatar: its corner is its presence light, and a face there would hide whether the agent is working (Identity and presence).

States

• Editable (your own avatar, your server's, an agent you manage): on hover, on keyboard focus and while uploading, cover the whole sticker with layer-backdrop and the icon of the action (upload or edit). Use this one overlay for every action, and show it on focus as well as hover, so keyboard users can tell the avatar is editable. raft-ui has no part for this yet; compose it around Avatar.

Behavior

• AvatarImage stays hidden while it loads or fails to load, and AvatarFallback shows in its place.
• In AvatarGroup, each avatar overlaps the one before it by 5px. How many faces a "who is working" stack shows is in Working agents.
• When someone joins or leaves a stack, the faces slide and fade (Motion).
• In dark mode the avatar keeps its colors and gains the die-cut edge (Dark mode).

Content

• Show a person without a photo by their initials on lavender, not by a person icon: an icon says only "this is a person", and initials let people be told apart without photos.
• Write 1 or 2 initials; write only 1 at xs, 2xs and sm, where 2 don't fit.
• Don't set the size of the initials: AvatarFallback takes it from the avatar's size (Typography).
• In examples, Wug's pixel avatar is crown and Bugen's is mushroom.

Accessibility

Avatar wraps Base UI's Avatar, which tracks whether the image has loaded. raft-ui adds the sizes, the fill and the presence light.

• Give AvatarImage an alt: the name when the avatar stands alone, empty when the name is next to it, so it isn't read twice.
• Give a presence light role="img" and an aria-label that says the state (Online, Working, Error, Offline, External agent), unless the word is next to it.
• Give an avatar stack an accessible name with the full count ("5 agents working"), since AvatarGroupCount shows only "+3".
• Make an editable avatar a <button> with an aria-label that names the action ("Change avatar"), and show its overlay on keyboard focus too: otherwise only mouse users learn that it can be changed.

Rules

• Don't tell agents and people apart by shape. When it must be explicit, add the agent tag after the name (Status).
• Use one pixel avatar per agent, everywhere in the product.
• Keep a pixel avatar and its fill together: a new pixel avatar brings its own fill. Don't give an agent a color of its own.
• Use only the five avatar sizes. Don't make a 32px or 40px avatar: the pixels of the face stop being even. 3xs (14px) is outside the scale.
• Never make a presence light blink or breathe (Motion).
• Put one thing in the corner: a presence light, or an assistant's face on a person's avatar, never both (The corner).
• Fill the gap around a presence light with the surface the avatar sits on (card, sidebar, frame, popover), so the light reads as cut out of it.