error-handling-recovery

エラー処理と復旧

あらゆる失敗を、次に進むための案内に変えましょう。アプリで起こりうる失敗をすべて見つけ、それぞれに具体的なユーザー向けメッセージ、適切な表示場所、少なくとも1つの復旧アクションを用意します。最優先の指針：ユーザーを責めず、行き止まりにしないでください。すべてのエラー状態に、解決への道筋を用意します。 エラー状態のマトリックスには、失敗の種類、実装するコンポーネント、表示文言を網羅してください。メッセージ作成のガイドラインだけでは不十分です。

使う場合／使わない場合

次の場合に使います：エラーメッセージの文言、バリデーション UX、ネットワーク／オフライン時のエラー処理、権限拒否や 404 ページ、復旧ワークフロー、グレースフルデグラデーション、エラーのアクセシビリティ。

実際のニーズが次の場合は、別のスキルに引き継ぎます。

• 待機や失敗をそもそも防ぐ（パフォーマンスとしての再試行、楽観的更新のロールバックの仕組み） → skills/frontend-design/performance-optimization
• 非同期ライフサイクルのローディング部分（スケルトン、スピナー、空状態） → skills/frontend-design/loading-states — このスキルは、ローディングが 失敗した ときの処理を担当します
• エラーアニメーションのタイミング → skills/frontend-design/interaction-physics
• エラー画面以外も含むアクセシビリティの全面監査 → skills/frontend-design/accessibility-excellence

ステップ 0 — コードベースを調べ、推測できないことだけを質問する

1. 既存のエラー画面を洗い出します。catch、.catch(、onError、error 状態変数、toast.error、alert(、エラーバウンダリーコンポーネント、「error」「failed」「wrong」「invalid」などの文字列リテラルを検索します。実際に表示しているメッセージ文字列を集め、現在の文言を比較用の現状として記録します。
2. アプリにある失敗の種類を整理します。フォーム（バリデーション）、API 呼び出し（ネットワーク／サーバー）、認証が必要なリソース（権限）、ルーティング（404）、およびドメイン固有の項目（決済の拒否、クォータの上限、ファイル形式の拒否など）を確認します。
3. 不足している箇所を特定します。エラーを何も知らせずに握りつぶす catch ブロック、エラー分岐のない fetch、入力欄の枠線を赤くするだけのフォーム、独立したセクションを囲むエラーバウンダリーの欠如、オフライン時の処理がない箇所などです。
4. アクセシビリティの設定を確認します。role="alert"、aria-live、aria-invalid、aria-describedby を検索します。これらがない場合は、自動的に修正項目に加えます。

推測できない場合に限り、ユーザーにまとめて質問します。問い合わせ先（メールアドレス／ヘルプセンター。システムエラーの文言に必要）と、特に慎重な復旧対応が必要な重要度の高い操作（決済、取り消せない操作など）があるかを確認します。回答できない場合は、仮のサポートリンクを使ってその旨を明記し、作業を進めます。

ワークフロー

1. エラー状態のマトリックスを作成する

ステップ 0 で見つかった失敗の種類ごとに、1 行を埋めます。項目は、失敗の種類 → ユーザーが行っていた操作 → メッセージ（何が起きたか／理由／次にすること） → 表示場所 → 復旧アクション → アクセシビリティの設定です。このマトリックスが監査の成果物であり、実装チェックリストになります。

2. 4 つの要素に沿って各メッセージを書く

1. 何が起きたか — 具体的で分かりやすい言葉を使います（「メールアドレスはすでに使用されています」。 「入力が無効です」ではありません）。
2. 理由 — 専門用語を使わず、背景を 1 行で説明します（「CORS ポリシー違反」をユーザーに表示しないでください）。
3. 次にすること — 具体的な次の手順を示します。
4. 問い合わせ先 — システムエラーの場合は問い合わせ先を示し、バックエンドからエラー ID／参照 ID が提供される場合はそれも表示します。

文言のルール：ユーザーを責めないでください（「無効な情報を入力しました」ではなく、「…を入力してください」）。ルールを示すだけでなく、修正方法を伝えます。アプリが実際にデータを保持する場合に限り、メッセージでデータが保持されると約束してください。事実でない限り、「作業内容を保存しました」と伝えてはいけません。

3. 障害クラスごとに表示位置と復旧方法を決める

クラス	表示位置	タイミング	復旧方法
バリデーション	フィールドのすぐ隣にインライン表示	フォーカスが外れたとき、または送信時。不完全な入力の各キー入力では表示しません。修正されたらすぐに消します	修正方法を案内します。可能であればショートカットを用意します（「代わりにサインイン」）
ネットワーク	セクション単位の状態表示またはトースト。ビュー全体が失敗した場合は全体に表示	失敗時	再試行ボタン。入力済みデータを保持します。対応している場合はオフラインでの続行も可能にします
権限	ブロックされたコンテンツを置き換える全体表示	読み込み時または操作時	理由を説明し、「アクセスをリクエスト」または所有者への連絡方法を示します
システム／5xx	セクションまたはページに表示	失敗時	再試行、サポートへの連絡先、エラー ID
404	専用ページ	ルートへのアクセス時	検索と主要な遷移先へのリンク

分岐ルール：

• インライン表示か、モーダルか、ページか： フィールドに関連する場合はインライン表示にします。フローの途中で発生する重大な阻害要因となる失敗（決済の拒否など）は、復旧方法を示すモーダルにします。リソース全体が利用できない場合は、ページまたはセクション全体に状態を表示します。トーストは、ユーザーが現在注目している対象とは無関係な失敗に限って使用し、フォームのバリデーションには決して使いません。
• 自動再試行か手動再試行か： 冪等な読み取りは、バックオフを伴う自動再試行が可能です。変更操作ではユーザーが明示的に再試行を実行するようにし、決済や投稿を無言で再送信してはいけません。
• 破綻させず、縮退させる： 利用できない機能は、非表示にしたりクラッシュさせたりせず、説明を添えて無効にします。独立した UI 領域をエラーバウンダリーで囲み、1 つの障害でページ全体が表示されなくならないようにします。

4. アクセシビリティを組み込んで実装する

• 動的なエラーは、タスクを妨げる場合は role="alert"、バックグラウンドの場合は aria-live="polite" で通知します。
• フィールドには aria-invalid="true" を設定し、aria-describedby でメッセージ要素を参照します。
• 送信に失敗した場合は、最初の無効なフィールド、または各フィールドへのリンクを含むエラーサマリーにフォーカスを移します。
• すべてのインジケーターにアイコン、テキスト、色を使用します。色だけで示してはいけません。
• 各クラスと復旧パターンの標準的なマークアップ／CSS は references/patterns.md にあります。コードを書く際はこれを参照してください。

5. 検証する

各障害を強制的に発生させ（無効な入力、開発者ツールでネットワークをオフラインにする、不正なエンドポイントで 500 を発生させる、不明なルートにアクセスする）、次の点を確認します。メッセージが適切な場所に表示されること、復旧操作が機能すること、入力済みデータが保持されること、スクリーンリーダーで通知が読み上げられること（または通知の仕組みが実装されていること）、何も通知されないまま失敗しないこと。

必須の出力形式

次の 2 つを提出してください。

1. コード — 実装したエラーコンポーネント、表示文言、エラーバウンダリー、アクセシビリティ対応の仕組みを、アプリ既存のコンポーネントやスタイルの規約に沿って組み込んだもの。

2. エラー状態マトリックス（Markdown）：

## Error-state matrix
| # | Failure mode | Class | Message (final copy) | Placement | Recovery | A11y | Status |
| 1 | Signup email taken | validation | "Email already in use…" | inline under field | "Sign in instead" link | aria-invalid + describedby + role=alert | implemented |
| 2 | Feed fetch fails | network | "We couldn't load your feed…" | section state | Retry | polite live region | implemented |
| 3 | Card declined | system | "Your card was declined…" | modal | Try again / other method | alertdialog, focus trapped | implemented |

## Silent failures fixed
| Location | Was | Now |

## Copy changes
| Before | After |

## Assumptions
[Support contact used, failure modes you could not reproduce, etc.]

品質基準（提出前に確認）

• マトリックスのすべての行に復旧操作があり、行き詰まりがない
• ユーザーに責任を押し付けるメッセージがなく、ユーザーに生の技術用語（スタックトレース、ステータスコード、CORSなど）を表示しない
• すべてのメッセージで、問題の説明だけでなく、次に何をすべきかを示している
• バリデーションはフォーカスが外れたとき、または送信時に実行し、修正されたら消える。キー入力ごとに警告しない
• エラーは原因のすぐ近くに表示される（フィールドへのリンクがない孤立したエラーサマリーを作らない）
• すべてのインジケーターにアイコン／テキストと色を使い、色だけに頼らない
• role="alert"／aria-live、aria-invalid、aria-describedby、フォーカス管理を実装している
• 変更したコードに、ユーザー向けの通知やログ記録を伴わずにエラーを握りつぶす catch ブロックがない
• 変更操作を自動再試行せず、変更したフローでは障害発生後もユーザーデータを保持する

厳禁事項：アプリが実現できない復旧を約束しない（永続化されていないのに「作業は保存されています」と伝えない）。破壊的な操作や決済の失敗にユーモアを使わない。開発者が実際のエラーを確認できなくなるようなエラー UI を追加しない。コンソールやテレメトリーへの記録は維持してください。

統合

• skills/frontend-design/loading-states → エラー時と空状態の配置を提供します。それを基に、完全なメッセージと復旧方法を作成してください。読み込みからエラーへの遷移では、同じレイアウト枠を再利用してください。
• skills/frontend-design/performance-optimization → このスキルの楽観的 UI のロールバックでは、バックグラウンド同期が失敗したときに表示するエラートースト／メッセージが必要です。
• skills/frontend-design/component-architecture → エラー用バリアントを追加するフォーム／入力コンポーネントを提供します。そこに共有コンポーネントとして ErrorState を追加してください。
• skills/frontend-design/accessibility-excellence ← ライブリージョンとフォーカスの動作を監査します。最初からその基準に沿って構築してください。

参考資料

• references/patterns.md — 悪い例から良い例へのメッセージの書き換え、各失敗クラス（検証、ネットワーク、権限、システム、404）の完全なマークアップ、インライン／モーダル／段階的な復旧パターン、段階的な機能縮退のスニペット、エラーのスタイル設定用 CSS、アクセシビリティの配線ブロックを掲載しています。コンポーネントと文言を作成する際に参照してください。