Avatar | Glaze design system

Type

When to use it

Use: A row, message or log line says who did it: a person, an agent, a connected source.
Use: A thread or review shows who is on it: AvatarGroup with +N.
Use: A citation shows where an answer came from: type="source".
Not for: A status or a count on its own. Use Badge.
Not for: A file or an image the person attached. Use Attachment.

7 rules

Must: Set type="agent" for an agent and type="source" for a page or tool; leave type="person" for people. Because round means a person, so an agent drawn round with initials reads as a colleague who did the work.
Must: Pass name on every Avatar, and decorative when the name is written beside it. Because name gives the initials and the accessible name; without decorative a screen reader hears the name twice.
Never: Colour an avatar's fallback by a hash of the name. Because colour means status in Glaze, so a green or coral circle reads as a pass or a failure.
Must: Put more than three avatars in an AvatarGroup with a label and a max. Because the group folds the rest into +N, which names whom it hides, so a long row never pushes the line or hides people.
Must: Set --avatar-cutout on an AvatarGroup that sits on anything but paper, such as the shell or the page. Because the 2px cut between avatars is drawn in that colour, and a paper cut on the grey shell shows as a white ring.
Never: Load a source's icon from a third-party favicon service. Because it tells that service every page the person reads, and the globe fallback already names the source.
Should: Use size="sm" in a line of text, the default in a row and lg in a header. Because a 20px avatar fits the 13px line, 24px sits in a 36px row with room, and 32px holds two initials.

4 checks

: A named avatar is role="img" with the name; a decorative one is aria-hidden.
: Initials are ink on the grey field, 15:1 or better; glyphs are text-2.
: The +N reads "and 3 more" with the hidden names, and opens a hint with them on hover or focus.
: Forced colours draw a CanvasText border so every avatar keeps its shape.

2 keys

6 edge cases

Image fails: The fallback stays: initials, the bot or the globe.
Name in another script: Initials take letters in any script.
One-word name: The first two letters, or one at 20px and smaller.
No name and no image: An empty grey shape; pass name.
Right to left: The group overlaps the other way on logical margins.
Dark theme: The field and the edge flip with the tokens; photos keep their pixels.

8 props

10 tokens