ユーザー・チームメンバー・ブランドなどのエンティティを小さな画像チップで視覚的に識別するUIコンポーネント。プロフィール写真がない場合のイニシャル表示・フォールバックアイコンの設計と、複数人を重ねて表示する Avatar Group まで扱う。
この記事を読むと、フォールバック設計（画像エラー時のイニシャル・アイコン）・サイズ体系・Avatar Group のオーバーラップ設計・スクリーンリーダー向けの alt テキストが自分でできるようになります。
1. UI例（Preview / Live）
このアバターは、デザインシステム GUNJO の Avatar 実装です。画像・イニシャルのフォールバック、オンライン状態、重ね表示を確認できます（右上 Code で編集可）。
実装で見る（GunjoUI）
この部品を、デザインシステム GUNJO の実装で確かめられます。
2. 定義（Definition）
ユーザー・組織・ブランドなどのエンティティを小さな円形または正方形の画像チップで表現するUIコンポーネント。画像が読み込めない場合のフォールバック（イニシャル・デフォルトアイコン）と、複数のアバターを重ねて表示する Avatar Group を含む。
Iconとの違い：Iconはシステムの機能や操作を表す記号。Avatarは特定のユーザーやエンティティを表す識別子。Iconはコンテンツに依存しないがAvatarはデータに依存する。
Thumbnailとの違い：Thumbnailはコンテンツ（記事・動画・商品）の縮小プレビュー。AvatarはPersonまたはEntityの識別子。
3. 使い分け（When to use / When NOT to use）
3.1 When to use
- コメント・チャット・レビューで誰が投稿したかを視覚的に示す
- メンバー一覧・チームページで複数の人物を並べて表示する
- ナビゲーションバーのログインユーザー自身を示す（プロフィールメニューのトリガー）
- タスク・チケットの担当者をコンパクトに表示する
- Avatar Groupでプロジェクト参加メンバーを省スペースで示す
3.2 When NOT to use
- コンテンツのサムネイル →
Image / Mediaを使う - 汎用的な機能アイコン →
Iconを使う - 会社ロゴ・サービスロゴの表示 → Logoコンポーネント or
<img>を直接使う
3.3 代替UI（Alternatives）
- 記事・動画の縮小表示 →
Image / Media（アスペクト比固定のサムネイル） - ファビコン・サービスアイコン →
<img>+object-fit: contain
4. 設計判断の核（Decision Principles）
Avatarは「誰か」を伝える——画像が読み込めなくてもイニシャルで識別できるフォールバック設計が必須。
判断の優先順位：① フォールバック設計 → ② サイズ選択 → ③ alt / aria-label → ④ Avatar Group の上限
- フォールバックを必ず設計する：
<img>のonErrorでイニシャル表示に切り替える。「壊れた画像アイコン」が表示されるのは最悪のUX - イニシャルの文字数は1〜2文字：3文字以上は小さいサイズで読めなくなる。日本語は「姓の1文字」か「姓+名のイニシャル（山T）」にする
- サイズは用途で決める：リスト内はMD(40px)、コメント内はSM(32px)、プロフィールページはLG以上、Avatar GroupはSM(32px)が基準
- Avatar Groupは最大5件 + 残数表示：6件以上を重ねると視認性が落ちる。
+Nで残りを示す
5. 状態設計（States）
5.1 必須状態（Required）
- Default（画像あり）：プロフィール写真を表示
- Fallback（画像エラー）：イニシャルまたはデフォルトアイコンを表示
5.2 条件付き状態（Conditional）
- Online indicator：オンライン・オフライン状態を右下の色点で示す
- Hover：クリッカブルなAvatarでホバー時の視覚フィードバック
- Loading（Skeleton）：データ取得中はスケルトンUIで円形のプレースホルダーを表示
- Avatar Group overflow：5件以上は
+Nで省略
5.3 State Gallery
| 状態 | 必須 | 何を伝えるか |
|---|---|---|
| Default（画像） | ✅ | エンティティの顔 |
| Fallback（イニシャル） | ✅ | 画像なしでも誰かを識別できる |
| Fallback（アイコン） | ✅ | 名前も画像もない場合の最終フォールバック |
| Online indicator | — | 現在のオンライン状態 |
| Skeleton | — | データ読み込み中 |
| Avatar Group overflow | — | 5件以上のメンバーを省略表示 |
6. バリエーション設計（Variants）
Avatarのバリアントは「形状」と「フォールバック種別」で分かれる。
| バリアント | 目的 |
|---|---|
| 円形（Circle） | 人物・ユーザーの識別（最も一般的） |
| 角丸正方形（Rounded Square） | ブランド・組織・ボットの識別 |
| イニシャルアバター | 画像なしユーザーの識別 |
| アイコンアバター | 匿名・削除済みユーザーの最終フォールバック |
| Avatar Group | 複数ユーザーのコンパクト表示 |
禁止パターン：Avatar Groupで全員を重ねて表示し、誰が誰か分からない状態にする → 最大4〜5件 + 残数表示（+N）にして、ホバー時にTooltipで名前を表示する。
7. パターン集（Good / Bad / How to fix）
7.0 よく崩れる設計パターン（3つ）
- フォールバック未設計：画像が404になると壊れた画像アイコンが表示され、誰が誰か分からなくなる
- alt属性なし：スクリーンリーダーが
user-photo-3748.jpgなどのファイル名を読み上げる - Avatar Groupを無制限に重ねる：20人以上のアバターを全員重ねると視覚的な意味がなくなり、レイアウトも崩れる
7.1 Bad（典型3つ）
<img src={user.avatar} />のみでonErrorハンドラーもaltも設定せず、画像エラー時に壊れた画像アイコンが表示される- Avatar Groupで15人全員を
-ml-3で重ね、どのアバターも識別できない - オンラインインジケーターの色点に
aria-labelがなく、色のみでオンライン状態を伝えている
7.2 Good（対になる3つ）
<img src={user.avatar} alt={${user.name}のプロフィール写真} onError={() => setShowFallback(true)} />でエラー時にイニシャル表示へ切り替える- Avatar Groupは最大4件 +
+Nの残数表示にし、ホバーで全員の名前をTooltipで表示する <span class="online-dot" aria-label="オンライン" />で色点にaria-labelを付与し色だけに頼らない
7.3 How to fix（手順）
<img>にonErrorハンドラーを追加し、エラー時はイニシャルコンテナを表示する<img>にalt={${name}のプロフィール写真}を付与する- Avatar Groupの表示上限を5件に設定し、超過分は
+Nボタンにする - オンラインインジケーターに
aria-labelを付与する
7.4 GUNJO 実装で見る（Bad / Good）
同じ GUNJO の Avatar を、フォールバック無しの崩れた使い方と正しい使い方で対比。
8. ルール（Must / Better）
Must（守らないと壊れる）
Better（品質が跳ねる）
9. アクセシビリティ要件（必須）
Keyboard
- クリッカブルなAvatar（プロフィールメニューのトリガーなど）は
Tabキーでフォーカスできること Enter/Spaceでアクションが実行されること
Focus
- クリッカブルなAvatarにのみフォーカスリングを表示する（非インタラクティブなAvatarには不要）
Screen Reader
<img>には必ずalt={${name}のプロフィール写真}を付与する- 装飾的なオンラインインジケーター（色点）は
aria-hidden="true"にしつつ、ステータス情報はaria-labelで別途伝える - Avatar GroupのオーバーフローボタンはDivではなく
<button aria-label="他N名のメンバー">+N</button>にする
<!-- 単体アバター（画像あり） -->
<img
src="/users/yamada.jpg"
alt="山田 太郎のプロフィール写真"
class="avatar"
onError="handleFallback()"
/>
<!-- フォールバック（イニシャル） -->
<span class="avatar-initials" aria-label="山田 太郎">山T</span>
<!-- Avatar Group -->
<div role="group" aria-label="5名のメンバー">
<img src="..." alt="山田 太郎" />
<img src="..." alt="佐藤 花子" />
<button aria-label="他3名のメンバー">+3</button>
</div>
Touch / Pointer
- クリッカブルなAvatarのタップ領域は最低44×44pxを確保する（Avatarが小さい場合は透明な padding で拡張する）
- 非インタラクティブなAvatarに
cursor: pointerを付けない
Contrast / Readability
- イニシャルアバターのテキストと背景色のコントラスト比は4.5:1以上を確保する
- 薄い背景色（パステル系）には濃いテキスト色を組み合わせる
10. 実装メモ（Implementation Notes）
- shadcn/ui の
AvatarコンポーネントはAvatarImage・AvatarFallbackの組み合わせで実装済み。AvatarFallbackは画像読み込みエラー時に自動表示される - イニシャルの背景色を一貫させるには、名前やIDの文字コードの合計を
COLORS.lengthで割った余りでインデックスを決める（ハッシュ方式） - Avatar Groupの
z-indexはCSSのisolation: isolate+ 後の要素に小さいz-indexを割り当てる方法で重なり順を制御する - スケルトンUIは
animate-pulseクラス（Tailwind）+ 円形のdivで実装できる
11. 関連リンク
- 関連するUIデザイン原則: 視覚的階層 (Visual Hierarchy), スキャンしやすさ (Scannability)
- 用語集（定義）: 視覚的階層 (Visual Hierarchy), 可読性 (Readability)
- 関連するUIコンポーネント（横）: Badge（バッジ）, Card（カード）, List（リスト）, Tooltip（ツールチップ）
12. まとめ
Avatarの設計は「フォールバックを必ず用意する」と「alt / aria-label で誰かを伝える」の2点が最低ラインです。迷ったら 4. 設計判断の核 に戻り、フォールバック優先順位（画像 → イニシャル → デフォルトアイコン）とサイズ体系（用途ごとに統一）を確認してください。Avatar Groupは「最大5件 + 残数表示」が乱れにくい設計の基準点です。
