providing-feedback

ユーザーフィードバックと通知の提供

このスキルは、システムの状態の伝達、メッセージの表示、ユーザー確認の処理に一貫したパターンを提供し、ほかのすべてのコンポーネントスキルを強化する包括的なフィードバックおよび通知システムを実装します。

このスキルを使用するタイミング

次のような場合に、このスキルを有効にしてください。

• トースト通知やスナックバーを実装する
• 成功、エラー、警告、情報のメッセージを表示する
• モーダルダイアログや確認ダイアログを作成する
• 進捗インジケーター（スピナー、プログレスバー、スケルトンスクリーン）を実装する
• 空の状態や検索結果がゼロの場合の表示を設計する
• ツールチップやコンテキストヘルプを追加する
• 通知の表示時間、積み重ね方、配置を決める
• ARIA を使用したアクセシブルなフィードバックパターンを実装する
• システムの状態をユーザーに伝える

フィードバックの種類を選択する判断表

緊急度と必要な注意に基づいて、適切なフィードバック手段を選択します。

Critical + Blocking       → Modal Dialog
Important + Non-blocking  → Alert Banner
Success/Info + Temporary  → Toast/Snackbar
Contextual Help          → Tooltip/Popover
In-progress              → Progress Indicator
No Data                  → Empty State

緊急度別のクイックリファレンス

緊急度	コンポーネント	表示時間	操作をブロックする
重大	モーダルダイアログ	操作するまで	はい
重要	アラートバナー	閉じるまで	いいえ
標準	トースト	3～7 秒	いいえ
コンテキスト依存	インラインメッセージ	常時表示	いいえ
ヘルプ	ツールチップ	ホバー中	いいえ
進捗	スピナー／バー	処理中	任意

実装方法

ステップ 1：フィードバックの種類を決定する

次の基準に基づいて状況を評価します。

1. 緊急度：情報はどの程度重要ですか？
2. 表示時間：どのくらい表示し続ける必要がありますか？
3. 必要な操作：ユーザーの応答は必要ですか？
4. コンテキスト：特定の UI 要素に関連していますか？

ステップ 2：実装パターンを選択する

トースト／スナックバーの場合：

• 配置：右下（推奨）
• 表示時間：3～4 秒（成功）、5～7 秒（警告）、7～10 秒（エラー）
• 最大スタック数：3～5 件
• 詳しいパターンについては、references/toast-patterns.md を参照してください

モーダルダイアログの場合：

• フォーカス管理：モーダル内にフォーカスを閉じ込めます
• アクセシビリティ：ESC キーで閉じられるようにし、適切な ARIA ラベルを設定します
• 背景：外側をクリックして閉じる（任意）
• 実装については、references/modal-patterns.md を参照してください

進捗インジケーターの場合：

• 100ms 未満：インジケーターは不要です
• 100ms～5 秒：メッセージ付きのスピナー
• 5～30 秒：プログレスバー（可能であれば進捗を数値で表示）
• 30 秒超：プログレスバー＋所要時間の見積もり＋キャンセル
• パターンについては、references/progress-indicators.md を参照してください

空の状態の場合：

• 含める内容：イラスト、見出し、本文、CTA
• 種類：初回利用、検索結果なし、エラー、権限なし
• デザインについては、references/empty-states.md を参照してください

ステップ 3：推奨ライブラリを使用して実装する

モダンな React スタック（推奨）：

npm install sonner @radix-ui/react-dialog

トーストの場合 - Sonner を使用：

import { Toaster, toast } from 'sonner';

// In your app root
<Toaster position="bottom-right" />

// Trigger notifications
toast.success('Changes saved successfully');
toast.promise(saveData(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Failed to save'
});

モーダルの場合 - Radix UI を使用：

import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

代替ライブラリや選定基準については、references/library-comparison.md を参照してください。

ステップ 4：アクセシビリティパターンを適用する

通知用 ARIA ライブリージョン：

<div role="status" aria-live="polite">
  File uploaded successfully
</div>


<div role="alert" aria-live="assertive">
  Error: Failed to save
</div>

モーダルのフォーカス管理：

1. 開く前に現在のフォーカスを保存します
2. モーダル内の最初の操作可能な要素にフォーカスを移動します
3. フォーカスをモーダル内に閉じ込めます（Tab キーで循環）
4. 閉じるときに、起動元の要素にフォーカスを戻します

すべてのパターンについては、references/accessibility-feedback.md を参照してください。

ステップ 5：デザイントークンを統合する

すべてのフィードバックコンポーネントは、一貫したテーマ設定のために design-tokens スキルを使用します。

/* Example token usage */
.toast {
  background: var(--toast-bg);
  color: var(--toast-text);
  padding: var(--toast-padding);
  border-radius: var(--toast-border-radius);
  box-shadow: var(--toast-shadow);
  animation-duration: var(--toast-enter-duration);
}

使用するトークンのカテゴリ：

• 色：トースト、アラート、モーダル、ツールチップの背景
• 余白：すべてのコンポーネントの内部パディング
• タイポグラフィ：タイトルとメッセージのフォントサイズ
• シャドウ：浮遊する要素の立体感
• モーション：アニメーションの時間とイージング

通知の表示時間に関するガイドライン

自動で閉じるまでの時間：

• 成功：3～4 秒
• 情報：4～5 秒
• 警告：5～7 秒
• エラー：7～10 秒、または手動で閉じる
• アクションボタンがある場合：10 秒以上、または自動で閉じない

進捗インジケーターのしきい値：

• 100ms 未満：インジケーターなし
• 100ms～5 秒：スピナー
• 5～30 秒：プログレスバー
• 30 秒超：プログレスバー＋キャンセルオプション

リソース

スクリプト（トークン不要の実行）

• scripts/generate_toast_manager.js - タイミングとスタッキングを設定したトースト構成を生成します
• scripts/format_messages.py - コンテキストに基づいてユーザー向けメッセージを整形します
• scripts/calculate_timing.js - 自動で閉じるまでの時間を計算します

リファレンス（詳細ドキュメント）

• references/toast-patterns.md - トーストの配置、スタッキング、アニメーション
• references/alert-patterns.md - アラートバナーの実装
• references/modal-patterns.md - フォーカス管理を備えたモーダルダイアログ
• references/progress-indicators.md - 読み込み状態と進捗状況
• references/empty-states.md - データなし、結果なしのパターン
• references/accessibility-feedback.md - ARIA パターンとフォーカス管理
• references/library-comparison.md - ライブラリの詳細な分析

サンプル（実装コード）

• examples/success-toast.tsx - Sonner を使用した成功通知
• examples/confirmation-modal.tsx - Radix UI を使用した削除確認
• examples/progress-upload.tsx - プログレスバーを使ったファイルのアップロード
• examples/inline-validation.tsx - フォームの入力検証エラー

アセット（テンプレートと設定）

• assets/message-templates.json - 再利用可能なメッセージテンプレート
• assets/error-catalog.json - エラーコードとメッセージの対応表
• assets/timing-config.json - タイミングの推奨設定

スキル間の連携

このスキルは、他のすべてのコンポーネントスキルを強化します。

• フォーム：入力検証のフィードバック、成功確認
• データ可視化：読み込み状態、エラーメッセージ
• テーブル：一括操作のフィードバック、アクションの確認
• AI チャット：ストリーミングインジケーター、レート制限の警告
• ダッシュボード：ウィジェットの読み込み、システムの状態
• 検索／フィルター：検索結果なし、検索の進捗状況
• メディア：アップロードの進捗状況、処理状態
• デザイントークン：すべてのビジュアルスタイルをトークンシステムで管理

ライブラリの簡易比較

ライブラリ	種類	サイズ	最適な用途
Sonner	トースト	小	モダンな React 18 以降、アクセシビリティ
react-hot-toast	トースト	<5KB	バンドルサイズの最小化
react-toastify	トースト	~16KB	RTL サポート、モバイル
Radix UI	モーダル	小	デザインシステム、ヘッドレス
Headless UI	モーダル	小	Tailwind プロジェクト

プロジェクトの要件に基づいて選択してください。詳細な分析については、references/library-comparison.md を参照してください。

主な原則

1. 緊急度に応じて注意を促す：重要度の低い情報にモーダルを使わないでください
2. 一貫性を保つ：類似するアクションには同じ種類のフィードバックを使ってください
3. 状況を説明する：何が起きたのか、次に何をすべきかを説明してください
4. 復旧手段を用意する：元に戻す、再試行する、ヘルプを利用するための選択肢を含めてください
5. ユーザーの設定を尊重する：モーションを減らす設定を反映してください
6. アクセシビリティをテストする：スクリーンリーダーとキーボードで確認してください