coastdigitalgroup/coastai-skills

タイムラインアクティビティシステム

目的

タイムラインアクティビティシステムは、時系列のイベント、履歴ログ、ロードマップを設計するための方法論を提供します。ユーザーが進捗を追跡し、時間的な関係を理解し、履歴データを効率的に読み取れるようにします。このシステムは情報密度と空間リズムのバランスをとり、すべてのビューポートで「いつ」「何が」というナラティブが明確になるようにします。

ユースケース

• SaaSダッシュボードのアクティビティフィードの設計（例：プロジェクト履歴）
• プロダクトロードマップやリリースノートの構造化
• 会社の歴史や「About Us」のマイルストーンの整理
• Eコマースの注文追跡や配送履歴の実装
• マルチステージプロセスの可視化の管理（例：申請ステータス）

使用すべきでないケース

• リニアなステップ進行: ユーザーがリアルタイムで完了する必要がある単純な手順のシーケンスには、step-progress-systemを使用してください。
• 純粋な表形式データ: 多くの列で並べ替えやフィルタリングが主な目的の場合（例：完全な財務監査ログ）、data-table-ui-systemを使用してください。
• グローバルナビゲーション: サイト全体の構造には、site-navigation-systemを使用してください。
• シンプルなブログフィード: 視覚的な「スレッド」や時間的マーカーがなくても、標準的なカードのグリッドやリストで十分な場合。

入力

1. イベントインベントリ: イベント、タイムスタンプ、関連メタデータのリスト。
2. 時間分解能: ユーザーは秒、日、年のどの単位を気にしているか？
3. イベントタイプ: イベントのカテゴリ分類（例：情報、成功、警告、エラー、マイルストーン vs. マイナーアクション）。
4. 空間制約: タイムラインはサイドバー、全画面ビュー、狭いカードのどの場所に配置されるか？
5. ブランドトークン: 色、タイポグラフィスケール、スペーシングトークン。

出力

1. タイムライン構造仕様: 「スレッド」（垂直/水平線）、「ノード」（マーカー）、「コンテンツブロック」の定義。
2. グループ化戦略: イベントをクラスタリングするルール（例：「今日」「昨日」「2023年10月」）。
3. 状態とステータスマトリックス: 異なるイベントタイプとインタラクティブ状態に対する視覚的な処理。
4. レスポンシブ設計図: 中央寄せや交互レイアウトからモバイルのシングルカラムビューへのタイムラインの適応方法。

ワークフロー

1. 時間スレッドと向きの定義

時間の方向を決定します：

• 垂直方向（標準）: 可変のコンテンツ長や長い履歴に最適。
• 水平方向: 水平スペースが十分にある高レベルのロードマップや短いプロセスに最適。

「スレッド」（イベントを接続する線）を確立し、一貫した視覚的な重みと色（通常はニュートラルな落ち着いたトーン）を確保します。

2. イベントノードとマーカーの確立

各イベントの視覚的なアンカーを設計します：

• シンプルノード: マイナーアクション用の小さなドットや円。
• アイコンノード: イベントタイプを示す円の中のアイコン（例：「完了」のチェックマーク）。
• 日付マーカー: ノードの横または上にフローティングするラベル。

3. 空間リズムとグループ化の適用

イベントを期間でグループ化して視覚的乱雑さを避けます：

• 相対グループ化: 「たった今」「2時間前」。
• 絶対グループ化: 「2023年10月23日（月）」、「2023年9月」。

fluid-spacing-systemを使用して、イベント間の垂直方向のギャップを一定に保ちます。優先度の高いマイルストーンには、マイナーなアクティビティ項目よりも多くの余白を設定します。

4. コンテンツブロックの整理

各ノードに隣接するコンテンツにvisual-hierarchy-systemを適用します：

• タイトル: コアアクションまたはイベント名。
• メタデータ: タイムスタンプ、アクター（ユーザーアバター/名前）、カテゴリ。
• 本文/説明: オプションの詳細または展開コンテンツ。
• アクション: コンテキストボタン（例：「詳細を見る」「元に戻す」）。

5. レスポンシブ適応の計画

• 交互レイアウト（Zパターン）: デスクトップでは、イベントがスレッドの左右に交互に配置されます。モバイルでは、シングルカラムに折りたたまれます（スレッドは左、コンテンツは右）。
• 片側レイアウト: 読みやすさを最大化するために、モバイルでは「スレッド-左、コンテンツ-右」を標準化します。

決定ルール

• 「スレッド」ルール: 時間的なギャップや「さらに読み込む」アクションがない限り、線を途切れさせてはいけません。
• グループ化のしきい値: 同じ日に5件以上のイベントが発生する場合は、重複するテキストを減らすために単一の日付見出しの下にグループ化します。
• 「ノード」の階層: 「マイルストーン」には大きなノードやブランドカラーを使用し、「アクティビティ」には小さくニュートラルなノードを使用します。
• タイムスタンプの位置: 垂直タイムラインでは、最も速くスキャンできるように、タイムスタンプをスレッドの左側（デスクトップ）またはタイトルのすぐ下（モバイル）に配置します。

制約

• アクセシビリティ: タイムラインはリスト（<ul>または<ol>）としてナビゲート可能でなければなりません。アイコンを含むノードには、スクリーンリーダー用にaria-labelまたは非表示テキストが必要です。タイムスタンプは<time datetime="...">要素でラップし、相対ラベル（「2時間前」）が機械可読のままになるようにします。ライブ更新されるアクティビティフィードでは、新しいエントリをaria-live="polite"領域（リスト全体ではなく）内に追加し、スクリーンリーダーユーザーが場所を見失わずに新しいイベントを聞けるようにします。
• レスポンシブ性: タイムラインはビューポートをはみ出してはいけません。水平タイムラインは、モバイルでは垂直に切り替えるか、水平スクロールを使用する必要があります。
• 視覚的コントラスト: スレッドとノードは、背景に対して3:1のコントラスト比を満たす必要があります。

よくある失敗パターン

• 途切れたスレッド: 垂直線が恣意的に開始・終了し、シーケンスを追跡しにくくなる。
• 情報過多: すべてのイベントに本文テキストを詰め込みすぎて、タイムラインがテキストの壁になる。
• 不整合な配置: 明確なロジックなしに、同じタイムライン内で中央揃えと左揃えのテキストを混在させる。
• モバイルでの詰め込み: モバイルで交互（左/右）レイアウトを維持しようとし、テキスト用の狭いカラムが残る。

検証基準

• イベントが明確で一貫した時系列順（昇順または降順）に従っている。
• 視覚マーカー（ノード）と接続スレッドが一貫してスタイル設定されている。
• 時間的グループ化（例：「今日」）を使用して認知的負荷を軽減している。
• レスポンシブ動作（例：シングルカラムへの折りたたみ）が定義され、機能している。
• アクセシビリティ：タイムラインがセマンティックリストとしてマークアップされ、タイムスタンプが<time datetime="...">を使用している。
• リアルタイムフィードが、スコープ設定されたaria-live="polite"領域を介して新しいエントリを通知し、スクリーンリーダーのフォーカスを妨げない。
• 主要なマイルストーンが二次的なアクティビティと視覚的に区別されている。