AVATAR: User identity display — initials, photos, or placeholder icons
SIZES: XS (24px) | SM (32px) | MD (40px, default) | LG (48px) | XL (64px)
TYPES: Initials (gradient) | Image | Icon placeholder | Status dot
Avatars represent users across the platform. Initials avatars use gradient backgrounds from a set of 6 color families. Status dots indicate online/offline/busy/away state.
Sizes
Sizes: Five sizes from XS (24px) to XL (64px). Default is MD (40px).
Use .tw-avatar-xs, .tw-avatar-sm, .tw-avatar-lg, or .tw-avatar-xl to override.
XS (24px)
SM (32px)
MD (40px)
LG (48px)
XL (64px)
<div class="tw-avatar tw-avatar-sm tw-avatar-primary" role="img" aria-label="Jane Doe"><span>JD</span></div>
Initials with Colors
Colors: Six color families for initials avatars, plus a neutral.
Application logic hashes the user's name to pick a color.
Each uses a light tinted background with darker text.
.tw-avatar-neutral is the deliberate opt-out — use it where an avatar must
not compete (a system actor, an unassigned slot, a dense staff list); it exists because
pages were re-tinting .tw-avatar with their own page CSS.
Its neutral-700 text sits at 5.93:1 on the translucent ground — neutral-600 would fail AA once
the 8% tint composites, so do not lighten it.
Primary
Blue
Green
Red
Orange
Magenta
Neutral
<div class="tw-avatar tw-avatar-blue" role="img" aria-label="Claire Davies"><span>CD</span></div><div class="tw-avatar tw-avatar-neutral" role="img" aria-label="Unassigned"><i class="tw-avatar-icon fa-regular fa-user" aria-hidden="true"></i></div>
Image Avatars
Images: Place an <img> with .tw-avatar-image inside the
.tw-avatar wrapper. The image is cropped to a circle via object-cover
and rounded-full.
XS
SM
MD
LG
XL
<div class="tw-avatar"><img class="tw-avatar-image" src="..." alt="User Name"></div>
Icon Placeholder
Fallback: When no image or initials are available, use .tw-avatar-icon
for a neutral gray placeholder with a user icon.
XS
SM
MD
LG
XL
<div class="tw-avatar tw-avatar-icon" role="img" aria-label="User"><i class="fa-solid fa-user"></i></div>
Status Dots
Presence indicators: Add a .tw-avatar-status span inside the avatar
with a status modifier. Dot size scales automatically with avatar size.
Status Types
Online
Offline
Busy
Away
Dot Scaling with Size
XS
SM
MD
LG
XL
<div class="tw-avatar tw-avatar-blue" role="img" aria-label="Sam Collins, Online"><span>SC</span><span class="tw-avatar-status tw-avatar-status-online"><span class="tw:sr-only">Online</span></span></div>
Mixed Row
Realistic usage: A mix of initials, image, and icon avatars with various sizes and status indicators, as they would appear in a user list or team view.
Avatar Group
Group: Overlapping stack for shared records — siblings, assigned staff, attendees.
Each avatar is ring-separated; a trailing .tw-avatar-group-more avatar carries the "+N" overflow count.
The wrapper takes role="group" + aria-label naming the set; the "+N" chip is aria-hidden.
Consolidates the hand-rolled tw:-space-x-* stacks (DR-2026-12).
<div class="tw-avatar-group" role="group" aria-label="6 assigned staff"> … <div class="tw-avatar tw-avatar-group-more" aria-hidden="true"><span>+2</span></div></div>
Status dot placement
Top placement: .tw-avatar-status-top moves the dot to the top-right for list rows
where the bottom edge is crowded. Default stays bottom-right.
<span class="tw-avatar-status tw-avatar-status-top tw-avatar-status-online">…</span>