coastdigitalgroup/coastai-skills

ファイルアップロードおよび管理システム

目的

ファイルアップロードおよび管理システムは、ユーザーのデバイスからサーバーにファイルを転送するエンドツーエンドの体験を設計するための方法論を提供します。このプロセスが透過的で、復元可能であり、アクセシブルであることを保証します。このシステムは、アップロードトリガー（ドロップゾーン）のインタラクション状態、アップロードキューの空間リズム、および高レイテンシ操作中にユーザーの信頼を維持するために必要なフィードバックループ（進行状況、成功、エラー）を定義します。

ユースケース

• コンテンツ管理システム（CMS）： メディアライブラリやアセットアップローダーの設計。
• SaaS アプリケーション： ドキュメント管理、CSV インポート、ユーザープロフィール添付ファイルの実装。
• プロジェクト管理ツール： タスクやコメント内のファイル添付の構造化。
• クリエイティブツール： 写真、動画、デザインファイルの大量アップローダーの設計。
• クラウドストレージインターフェース： 複雑なフォルダーおよびファイルアップロード操作の管理。

使用すべきでない場合

• 小さなテキスト添付ファイル： 「ファイル」が小さなテキスト断片のみの場合、標準のテキストエリアまたは copy-to-clipboard-implementation を使用します。
• システム自動転送： ユーザーがアップロードをトリガーまたは監視しない場合（例：バックグラウンドテレメトリ）。
• 単一入力のプロフィール写真： このシステムは適用可能ですが、複雑さの低い単一画像更新には、シンプルな「アバター」トリガー（user-avatar-system から）がより適切な場合があります。
• 静的アセット： アイコンやテーマ画像など、サイトのコードの一部であるアセットの場合。これらは開発者のワークフローで管理されます。

入力

1. ファイルタイプとサイズ制約： 許可されるファイルタイプ（PDF、JPG、PNG）と最大サイズは何か？
2. ボリュームの想定： ユーザーは一度に1つのファイルをアップロードするのか、それとも50以上のファイルを一括でアップロードするのか？
3. アップロードのコンテキスト： これはスタンドアロンのタスク（例：「データをインポート」）か、それとも補助的なアクション（例：「メッセージに添付」）か？
4. メタデータ要件： アップロードプロセス中にファイルにタイトル、説明、タグが必要か？
5. システムトークン： 親デザインシステムからのスペース、色、タイポグラフィのスケール。

出力

1. ドロップゾーン構造仕様： アップロードトリガーの視覚的定義（アイドル、ホバー、アクティブ、無効状態）。
2. キューレイアウト設計図： 「保留中」、「アップロード中」、「完了」リストアイテムの空間構成。
3. 進捗とフィードバックマトリックス： プログレスバー、パーセンテージインジケーター、成功/エラー状態の視覚的処理。
4. アクション階層： ファイルリスト内の「キャンセル」、「再試行」、「削除」、「編集」アクションのルール。

ワークフロー

1. アップロードトリガーの設計（ドロップゾーン）

明確なインタラクションの招待を確立します：

• アイドル状態： アイコン（通常はクラウドアップまたはクリップ）と明確な指示（例：「ドラッグ&ドロップまたはクリックしてアップロード」）を伴う点線または実線の境界線を使用します。
• ドラッグオーバー状態： 背景色または境界線のスタイルを変更して、領域がファイルを受け取る準備ができていることを即座にフィードバックします。
• モバイルフォールバック： ドロップゾーンが、ネイティブのシステムファイルピッカーを開く大きなタップ可能なボタン（WCAG 2.2 SC 2.5.8 に従い最小 24x24px、推奨 44x44px）のままであることを確認します。

2. アップロードキューの確立

インターフェースを乱雑にせずに複数のファイルを管理します：

• 即時フィードバック： ファイルが選択されたらすぐに、トリガー内またはその下のリストに追加します。
• ファイル構造： 各リストアイテムには以下を含める必要があります：
  • サムネイル/アイコン： ユーザーがファイルタイプまたは内容を識別できるようにします。
  • ファイル名とサイズ： 正しいファイルが選択されたことを確認します。
  • 進捗インジケーター： アップロード状態を示すバーまたは円。
  • アクション： 進行中のアップロードをキャンセルしたり、完了したアップロードを削除する方法。

3. 詳細なステータスフィードバックの提供

ファイル状態には step-progress-system と interactive-state-system を使用します：

• アップロード中： プログレスバーを表示し、長時間のアップロードの場合はパーセンテージまたは「X of Y MB」アップロード済みを表示します。
• 成功： セマンティックな「成功」色（緑）とチェックマークアイコンを使用します。「表示」または「リンク」アクションを提供します。
• エラー： セマンティックな「エラー」色（赤）を使用します。明確な理由（例：「ファイルが大きすぎます」）と「再試行」ボタンを提供します。

4. ファイル管理の設計（アップロード後）

ユーザーがアップロードしたアセットとどのように対話するかを定義します：

• メタデータの編集： タイトルや説明が必要な場合は、インライン編集または「設定」モーダルを提供します。
• 削除： 破壊的なアクションには確認手順を伴う「ゴミ箱」アイコンを使用します。
• グリッドビューとリストビュー： メディア中心のアップロードにはサムネイルのグリッドビューを提供し、ドキュメント中心のアップロードにはメタデータ密度を高めるためにリストビューを使用します。

5. レスポンシブスタッキングの計画

• コンパクトキュー： モバイルでは、メタデータ（ファイルサイズなど）を折りたたみ、ファイル名とプログレスバーを優先します。
• 全画面フォーカス： 複雑なアップローダー（マッピング付きの CSV インポーターなど）の場合は、全画面オーバーレイを使用して distractions を取り除きます。

決定ルール

• 「インスタントエントリー」ルール： ファイルは、実際のサーバーリクエストがまだ開始されていなくても、ドロップ/選択された瞬間に UI に表示される必要があります。
• 進捗の可視性： アップロードに 1 秒以上かかるファイルにはプログレスバーを使用します。非常に高速なアップロードの場合は、直接「成功」状態に遷移します。
• 一括アクション： ユーザーが 5 つ以上のファイルをアップロードできる場合は、「すべてクリア」または「すべてアップロード」アクションを提供してキューをまとめて管理します。
• 競合管理： 同じ名前のファイルが存在する場合の処理を定義します（例：「両方を保持」、「置き換え」、「スキップ」）。
• 空の状態： メディアライブラリが空の場合は、empty-state-system を使用して、主要な CTA として「アップロード」ボタンを提供します。

制約

• アクセシビリティ：
  • ドロップゾーンはフォーカス可能であり、Space または Enter キーで操作可能でなければなりません。
  • スクリーンリーダーにアップロードの進行状況と完了を通知するために aria-live="polite" を使用します（パーセンテージのティックごとに flood しないようにします）。
  • ファイル入力には、非表示であるがアクセス可能な <label> が必要です。
  • ドロップゾーンまたは進行状況リストの背後にフォーカスが閉じ込められないようにします（WCAG 2.4.11 Focus Not Obscured）。スティッキーヘッダーやトーストはフォーカスされた要素を覆ってはいけません。
  • キャンセル/再試行/削除アクションのタッチターゲットは、少なくとも 24x24px（WCAG 2.2 SC 2.5.8）を満たす必要があります。主要なアクションには 44x44px が推奨されます。
• レスポンシブ性： ドロップゾーンは流動的であり、水平方向のオーバーフローを引き起こしてはいけません。
• コントラスト： プログレスバーとエラーメッセージは、WCAG AA（4.5:1）のコントラスト比を満たす必要があります。

よくある障害パターン

• 「サイレント障害」： アップロードは失敗するが、UI はフィードバックを提供せず、ユーザーを無期限に待たせます。
• 進行状況の消失： アップロードが実際に完了する前にプログレスバーが消え、「後期不安」を引き起こします。
• 小さなドロップゾーン： マウスやサムでヒットするのが難しい小さなターゲットを作成します。
• 「キャンセル」の欠如： ユーザーが大規模な誤ったアップロードを停止できないようにします。
• 不明瞭なエラー： 「Error 500」ではなく、「サーバーがビジー状態です。しばらくしてからもう一度お試しください。」と表示します。

検証基準

• ドロップゾーンに明確なアイドル、ホバー、ドラッグオーバー状態がある。
• キュー内の各ファイルに名前、サイズ、進捗状況が表示される。
• 成功状態とエラー状態が色とアイコンの両方で示される。
• ユーザーはキューからファイルをキャンセルまたは削除できる。
• ARIA ライブリージョンがステータス更新に使用される。
• レイアウトはレスポンシブで、長いファイル名を適切に処理する。
• すべてのインタラクティブ要素が WCAG 2.2 の 24x24px タッチターゲット最小値を満たしている（44x44px 推奨）。