Avatar

Usage

Overview

Avatar represents a person, team, or entity with a photo when one exists and with initials or a placeholder otherwise. It carries more visual weight than a plain Circle or a bare icon; reach for it when recognition and human presence matter—chat headers, assignment lists, supervisor directories. Avatars set the expectation that someone (or some entity) is behind the object. Don't attach them to anonymous rows or system actors.

When to use

Assignees, authors, or participants where photos speed scanning.
Entity branding where design supplies structured artwork (organizations, agencies).
Active-speaker or live-role emphasis using Accent styling, sparingly.

When not to use

Anonymous or system actors—use an Icon or a typographic label.
Ultra-dense tables where every row would carry an avatar—initials in Circle or plain text scan better.
Non-identity counts—use Badge or a numeric column.

Sizes and shapes

Size. Small in dense rows; Regular as default; Large for profile headers or spotlight cards.
Shape. Circular for people; square for organizations or structured entities when brand guidance requires.
Color. Default is the baseline; Accent only for live or active emphasis, and only in conjunction with a state text label.

Content guidelines

Initials derive from display names with inclusive rules for localization. Don't expose raw email local-parts when they would mislead.
Alt text or accessible names identify the person or entity—never "Avatar".

Behavior and states

Loading. Use a skeleton or placeholder until the image resolves; never flash a broken-image icon.
Failure fallback. Fall back to initials on image load failure; do not retry silently on every render.

Best practices

Respect privacy. Only show photos that operators are allowed to see under policy.
Keep avatar size consistent with row height so the list doesn't look uneven.

Don't

Use avatars as the only status indicator. Pair presence with text when decisions depend on state.
Mix arbitrary shapes inside one list without design intent.

Accessibility

Decorative avatars next to redundant text can be hidden from screen readers per implementation; unique identity must remain present in accessible text. Focusable avatar buttons need explicit names. See Accessibility for the full contract.

Status dot for presence.
Message for chat layouts using avatars.

Attachment / Accessibility

Avatar / API and Development

On this page

Avatar

Usage

Overview

When to use

Assignees, authors, or participants where photos speed scanning.
Entity branding where design supplies structured artwork (organizations, agencies).
Active-speaker or live-role emphasis using Accent styling, sparingly.

When not to use

Anonymous or system actors—use an Icon or a typographic label.
Ultra-dense tables where every row would carry an avatar—initials in Circle or plain text scan better.
Non-identity counts—use Badge or a numeric column.

Sizes and shapes

Size. Small in dense rows; Regular as default; Large for profile headers or spotlight cards.
Shape. Circular for people; square for organizations or structured entities when brand guidance requires.
Color. Default is the baseline; Accent only for live or active emphasis, and only in conjunction with a state text label.

Content guidelines

Initials derive from display names with inclusive rules for localization. Don't expose raw email local-parts when they would mislead.
Alt text or accessible names identify the person or entity—never "Avatar".

Behavior and states

Loading. Use a skeleton or placeholder until the image resolves; never flash a broken-image icon.
Failure fallback. Fall back to initials on image load failure; do not retry silently on every render.

Best practices

Respect privacy. Only show photos that operators are allowed to see under policy.
Keep avatar size consistent with row height so the list doesn't look uneven.

Don't

Use avatars as the only status indicator. Pair presence with text when decisions depend on state.
Mix arbitrary shapes inside one list without design intent.

Accessibility

Status dot for presence.
Message for chat layouts using avatars.

Attachment / Accessibility

Avatar / API and Development

On this page