Avatar

When to use

• To help coaches recognise a client or teammate at a glance: in the client list, a check-in thread, a chat, the account menu.
• To show who is in a group: the clients in a bootcamp, the coaches on a team.

When not to use

• For the SuperCoach or Coach logo: use the logo tile from Brand. Brand avatars may use the chamfered corner; avatars of people are always round (Shape).
• For progress photos or exercise images: those are content, not identity. Show them at full size, for example in a Carousel.
• As the only way to identify someone. Put the name next to the avatar, or give the avatar a name.

Anatomy

Variants

States

Avatars are not interactive. When an avatar opens a profile, the link around it (with the name) gets the focus ring.

Sizes

sm (24px) in dense tables and comment threads. default (32px) in lists and menus. lg (40px) in headers and cards. The badge and group count scale with the avatar. There are no sizing tokens yet; these are steps of the 4px spacing unit (QUESTIONS Q5).

Usage guidelines

• Show the same person with the same avatar everywhere: the photo if there is one, otherwise the same initials.
• In a group, show at most 3 avatars and a count. More becomes noise.
• Use the badge for one status. Two badges on one avatar can't be told apart at 8px.

Content guidelines

• Initials: the first letter of the first name and of the family name, skipping the article "Al-" or "ال": Sara Al-Otaibi is "SO", Khalid Al-Qahtani is "KQ". Two letters at most, in capitals.
• Arabic initials: the same rule: سارة العتيبي is "س ع". Arabic letters join, so put a zero-width non-joiner (U+200C) between the two letters. Without it, "سع" reads as a word.
• Use the script the name was entered in. Don't transliterate a name to make initials.
• Alt text: when the name is next to the avatar, the image is decorative: alt="" and aria-hidden on the avatar. When the avatar stands alone, give it the person's name: role="img" and aria-label="Sara Al-Otaibi". Never "avatar", "profile picture" or the file name.
• Group count: "+3", and the group's accessible name says "and 3 more clients".

Accessibility

Avatars are not focusable and have no keyboard interaction.

• An avatar next to a name is hidden from screen readers (aria-hidden), so the name isn't read twice.
• A standalone avatar has role="img" and an aria-label with the name, so it is announced as "Sara Al-Otaibi, image", whether the photo or the initials show.
• A group has one name for the whole stack: "Sara Al-Otaibi, Omar Haddad, Khalid Al-Qahtani and 3 more clients, image". The "+3" alone means nothing when read out.
• A badge's meaning is written nearby or included in the avatar's name ("Omar Haddad, checked in today"). Color alone fails WCAG 1.4.1.
• Initials use text-muted-foreground on bg-muted (5.28:1).

RTL

• The badge sits on the bottom end corner (end-0), so it moves to the bottom left.
• Groups overlap toward the end: -space-x-2 uses logical margins, so the first avatar is on the right and the count on the left.
• Photos don't mirror. Initials follow the script of the name.

Tokens used

Read from components/ui/avatar.tsx at build time, so this list changes when the component does. Opacity modifiers such as /90 are shadcn hover and focus tints on top of the token.

• Layerz-(--z-raised)
• Radiusrounded-full
• Typetext-sm
• Typetext-xs

Props

Replaces in coach-admin

Related

Data table, Badge, Shape, Content.