Build Assets
UI Component
Avatar
User or entity representation — image, initials fallback, and group stack.
Platform: bothTags: avatar, user, profile, image, initials
Purpose
Represents a person, team, or entity with visual identity. Humanizes interfaces by connecting actions and content to real people. Always has an image fallback (initials or generic icon) for when no photo is available.
Anatomy
- Image: circular crop, border optional
- Initials fallback: 1–2 letters from name, colored background (seeded by name hash)
- Icon fallback: generic user icon when no name available
- Status dot: 8–10px circle, bottom-right (green=online, grey=offline, yellow=away)
- Group stack: overlapping circles with negative margin, +N overflow indicator
States
- Image loaded: circular photo
- Image error/missing: initials on colored background
- No name: generic user icon on grey background
- With status: small colored dot bottom-right
- Group stack: 3–5 visible, "+N more" for overflow
Tokens
spacing
xs: 20pxsm: 28pxmd: 36pxlg: 48pxxl: 64pxgroupOverlap: -8px
sizing
statusDotSize: 10pxborderWidth: 2px
Do
- Always provide an initials or icon fallback — never show a broken image icon
- Generate initials-background colors deterministically from the name so they're consistent
- Show status dots only when real-time presence is a product feature
- In group stacks, show max 4–5 faces before "+N" overflow
Don't
- Use avatars where the person's identity isn't relevant to the task
- Show a blank or grey avatar when initials are available
- Stack more than 5 avatars without an overflow indicator
- Use square avatars for people and circular for entities — pick one system
Accessibility
- img with alt="[Name]'s avatar" or alt="" if decorative alongside a name
- Initials fallback: aria-label="[Name]" on the container
- Status dot: aria-label="[Name], online" or include status in parent element