重要な情報・警告・エラー・成功をページ内のインライン位置に表示するUIコンポーネント。Toastと異なり画面上に固定表示され続け、ユーザーが自発的に閉じるまで（または状態が解消されるまで）消えない。フォームのバリデーションエラー・サービス障害の告知・操作成功の確認などに使われる。
この記事を読むと、Toast・Modal・Bannerとの使い分け・4種類のセマンティック（info/success/warning/error）の使い分け・role="alert" と aria-live の適切な使い方が自分でできるようになります。
1. UI例（Preview / Live）
このアラートは、デザインシステム GUNJO の Alert 実装です。意味に応じた variant（info / success / warning / destructive）を、色＋アイコン＋テキストで確認できます（右上 Code で編集可）。
実装で見る（GunjoUI）
この部品を、デザインシステム GUNJO の実装で確かめられます。
2. 定義（Definition）
重要な情報・警告・エラー・成功をページ内のインライン位置または上部バナーとして表示するUIコンポーネント。ユーザーが明示的に閉じる（または状態が解消される）まで表示し続ける。Toastと異なり自動消去されないことが最大の特徴。
Alert の4種類のセマンティック：
| 種類 | 色 | 用途 | ARIA |
|---|---|---|---|
| Info | 青 | 中立的な情報・告知 | aria-live="polite" |
| Success | 緑 | 操作成功の確認 | aria-live="polite" |
| Warning | 黄 | 注意が必要な状態 | aria-live="polite" |
| Error | 赤 | エラー・操作失敗 | role="alert" |
Toast との違い：Toastは一定時間後に自動消去される一時的な通知。Alertはユーザーが閉じるまたは状態が解消されるまで表示し続ける永続的な通知。エラーや重要な警告はAlertを使い、軽微な成功通知はToastを使う。
3. 使い分け（When to use / When NOT to use）
3.1 When to use
- フォームバリデーションエラー：送信失敗時にエラーの詳細をフォーム上部に表示
- サービス障害・メンテナンス告知：ページ上部にinfoバナーとして表示
- 重要な警告（ストレージ残量少・セキュリティ警告）
- 操作成功の確認：保存・公開・削除が完了したことをインラインで示す
3.2 When NOT to use
- 軽微な操作成功の通知（「コピーしました」など）→ Toastで十分
- ユーザーの注意を強制的に集める確認・選択 → Modal / Alert Dialogを使う
- エラーの詳細が不要な短い通知 → Toastを使う
3.3 代替UI（Alternatives）
- 一時的な成功通知 →
Toast - 確認が必要な操作 →
Alert Dialog - フィールドレベルのエラー → インラインエラーテキスト（入力欄の下に直接表示）
4. 設計判断の核（Decision Principles）
Alertの核は「セマンティック（意味）の一貫性」——色・アイコン・ARIAの3つが同じ意味を語ることで、ユーザーは瞬時に重要度を判断できる。
判断の優先順位：① セマンティック選択（info/success/warning/error）→ ② 閉じられるか否か → ③ ARIA設定 → ④ 次のアクション
- error には必ず
role="alert"を付与する：role="alert"は暗黙のaria-live="assertive"を持ち、スクリーンリーダーが読み上げ中のコンテンツを中断してすぐに読み上げる。エラー以外（info/success/warning）に使うと音声ユーザーの操作を過度に中断するため、error のみに使い、他はaria-live="polite"を使う - 警告・エラーには必ず次のアクションを添える：「ストレージが不足しています」だけでは行動できない。「プランをアップグレード」「サポートに連絡」などのリンク・ボタンをAlertに含めることで、問題解決への導線を作る
- 閉じるボタンの要否を使用文脈で決める：サービス障害のinfoバナーは障害解消まで閉じてはいけない場合がある（閉じるボタンなし）。任意の通知は閉じるボタンを提供する
5. 状態設計（States）
5.1 必須状態（Required）
- Visible（表示中）：デフォルト状態
- Dismissed（閉じた状態）：閉じるボタンで非表示
5.2 条件付き状態（Conditional）
- Loading：Alert内容をサーバーから取得中（スケルトン）
- Resolved：警告・エラーの状態が解消されてAlertが自動的に消える
5.3 State Gallery
| 状態 | 必須 | 何を伝えるか |
|---|---|---|
| Visible | ✅ | 重要度と内容 |
| Dismissed | — | ユーザーが確認済み |
6. バリエーション設計（Variants）
セマンティックと表示位置の組み合わせで使い分ける。
| バリアント | 配置 | 閉じるボタン | 使用例 |
|---|---|---|---|
| インラインAlert | フォーム上部・セクション内 | ✅ | フォームエラー・設定変更結果 |
| ページバナー | ページ上部固定 | △ | サービス障害・告知 |
| コンテキストAlert | カード内・モーダル内 | ✅ | 部分的な警告 |
禁止パターン：全種類に同じ色（赤）を使う → info/success が「エラー」として誤読され、ユーザーが必要以上に不安になる。
7. パターン集（Good / Bad / How to fix）
7.0 よく崩れる設計パターン（3つ）
- 全Alertに
role="alert"を付与する：スクリーンリーダーが操作中のコンテンツを中断して読み上げ、音声ユーザーにとって非常に煩わしい体験になる - エラーAlertにアクションリンクがない：「エラーが発生しました」だけ表示して何をすればいいかわからない
- 色だけでセマンティックを伝える：色覚特性のあるユーザーには warning（黄）と success（緑）が区別できない。アイコンと文言で必ず補完する
7.1 Bad（典型3つ）
<div role="alert">保存しました ✓</div>— 成功通知にrole="alert"を使い、スクリーンリーダーが読み上げを中断する- 赤背景のAlertに「エラーが発生しました」だけ表示し、次のアクションへの導線がない
- 背景色のみで種類を区別し、アイコンも文言でのラベルもない（色覚特性のあるユーザーが区別できない）
7.2 Good（対になる3つ）
- 成功・情報・警告には
aria-live="polite"を使い、エラーのみrole="alert"（=aria-live="assertive"）を使う - エラーAlertに「カード情報を確認する」「サポートに連絡」のリンクボタンを添えて、問題解決への導線を作る
- アイコン（✓ / ⚠ / ✕ / ℹ）+ 色 + 見出しテキストの3つを組み合わせてセマンティックを多重に伝える
7.3 How to fix（手順）
- Alertの種類を判断：エラーなら
role="alert"、それ以外はaria-live="polite"を付与する - アイコンを追加：
aria-hidden="true"を付けて装飾扱いにし、意味はテキストで伝える - 警告・エラーには次のアクションへのボタン/リンクを
<Alert>内に含める - 閉じるボタンには
aria-label="[タイトル]のアラートを閉じる"を付与する
7.4 GUNJO 実装で見る（Bad / Good）
同じ GUNJO の Alert を、重大度（severity）の崩れた使い方と正しい使い方で対比。
8. ルール（Must / Better）
Must（守らないと壊れる）
Better（品質が跳ねる）
9. アクセシビリティ要件（必須）
Keyboard
TabでAlert内のリンク・ボタン（閉じるボタン含む）にフォーカスEnter/Spaceでボタンを操作
Screen Reader
<!-- エラー（即座に読み上げ） -->
<div role="alert">
<p>支払い処理に失敗しました</p>
<p>カード情報を確認してください。</p>
</div>
<!-- 成功・情報・警告（現在の読み上げが終わってから） -->
<div aria-live="polite" aria-atomic="true">
<p>変更を保存しました</p>
</div>
aria-atomic="true" を付けるとAlert全体をひとまとまりとして読み上げる（部分更新時の途中読み上げ防止）。
Contrast / Readability
- 各セマンティックの背景色と文字色のコントラストは4.5:1以上
- アイコンは装飾扱い（
aria-hidden="true"）とし、意味はテキストで伝える
10. 実装メモ（Implementation Notes）
- shadcn/ui の
Alertはrole="alert"がデフォルトで付与されている。成功・情報・警告にはroleを削除してaria-live="polite"を付与するか、カスタムコンポーネントとして実装する - フォームバリデーションエラーのAlertは、フォームの
onSubmitで失敗した直後に DOM に追加することでrole="alert"の読み上げが発火する。既存のAlertの文言を変更するだけではrole="alert"が再発火しないため、Alertを一度削除して再追加するかkeyprop を更新して強制再マウントする - アニメーション付き表示：
data-state="open"/data-state="closed"+ CSS Keyframesでフェードインとフェードアウトを実装する
11. 関連リンク
- 関連するUIデザイン原則: フィードバック (Feedback), 状態の可視化 (Visibility of System Status)
- 用語集（定義）: アクセシビリティ (Accessibility), フィードバック (Feedback)
- 関連するUIコンポーネント（横）: Toast（トースト通知）, Alert Dialog（警告ダイアログ）, Notification Center（通知センター）, Status Bar（ステータスバー）
12. まとめ
Alertの設計で最重要なのは「セマンティックの一貫性」です。迷ったら 4. 設計判断の核 に戻り、「error のみ role="alert" か」「色+アイコン+テキストの3つで種類を伝えているか」「警告・エラーに次のアクションが添えられているか」の3点を確認してください。ToastとAlertの選択基準は「自動消去してよいか」——消えても問題ない軽微な通知はToast、ユーザーが確認するまで残すべき重要な通知はAlertです。
