timeline

スキル：timeline

純粋な HTML/CSS/JS のコンポーネント（フレームワーク不使用）— 縦方向のマイルストーン一覧です。各マイルストーンには日付＋タイトル＋出典があり、スクロールに応じて表示されます。

WHAT

目的とコンテキスト

• 目的： 単一の時間軸（日付＋タイトル＋出典）を持つ縦型タイムラインをランディングページに追加します。スクロールに応じて順次表示され、768px でモバイルからデスクトップへレスポンシブに切り替わり、実データを使用します。
• トリガー（使用する場面）：
  • changelog、プロジェクトの歴史、ロードマップ、執筆アーカイブ、イベントのタイムラインなど、時間順にマイルストーンを列挙する必要があるページ。
  • ユーザーが「タイムラインを作って」「時間軸」「タイムライン形式の履歴」と言った場合。
• 対象外： 関係図／フロー図（それには /diagram を使用）や数値データのグラフ（それには dataviz を使用）には使用しません。これは単一の線形時間軸専用です。

メンタルモデル

実際のマイルストーンデータ（API/markdown/CMS）→ <li class="timeline__item">（time + a + small）→ IntersectionObserver が timeline__item--in を付与 → CSS transition で順次表示。サンプルアセットは ADAPT の出発点であり、そのままコピーするものではありません。

入力と出力の契約

	フィールド	必須？	意味
In	ランディングページ	はい	タイムラインを設置する場所
In	実際のマイルストーンデータ	はい	日付（ISO）＋タイトル＋リンク＋出典。不足している場合はまだ接続できません（faker のデモのみになります）
In	design.md / token dark-mode-maker	いいえ	あれば、プロジェクトのデザインシステムに合わせてクラス／トークンを変更します
Out	適応済み HTML/CSS/JS	はい	faker のインポートがなく、BEM クラスが CSS と JS で一致している状態
Out	検証の証拠	はい	スクリーンショット＋playwright-verify によるスクロールテスト

ルールと機能

• RULE-01（必須）：assets/timeline.js の 1 行目で esm.sh から faker をインポートしているのは、デモ用の偽データを生成するためだけです（generateArticles()）。実プロジェクトに接続する際は、このインポートと generateArticles() を削除し、build() の前に this.articles を実データ（API/markdown/CMS）に置き換えてください。本番環境に faker のインポートを残すと、不要な依存関係となり、偽データが露出します。
• RULE-02（必須）：クラス名は BEM に従います（timeline__item-time...）。クラス名を変更する場合は、CSS と JS の querySelector の両方を変更してください。片方だけ変更してはいけません。
• RULE-03（必須）：IntersectionObserver の threshold: 1 は、マイルストーン全体がビューポートに入って初めて表示されることを意味します。ビューポートより高いマイルストーン（長いコンテンツ）は threshold 1 に到達できないため、マイルストーンに長いコンテンツがある場合は 0.5 に下げてください。
• RULE-04（必須）：実データを接続した後、playwright-verify（スクリーンショット撮影＋スクロールテスト）で検証してください。コンソールエラーがないというだけで「動作する」と判断してはいけません。
• 機能：スキルのサンプルアセットを読み取る、ランディングページのフロントエンドファイルを編集する、ヘッドレスブラウザーを実行してスクリーンショット撮影／スクロール検証を行う。

失敗時の境界

• 実際のマイルストーンデータがない → データソースを clarify します。faker が残った状態で納品してはいけません。
• 実際には関係図／フロー図または数値グラフである → blocked とし、/diagram または dataviz に切り替えます。
• playwright による検証でスクロールしてもマイルストーンが表示されない → failed とし、修正（例：threshold を下げる）してから再検証します。

HOW

主なワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	skill assets	assets/timeline.html + assets/timeline.css + assets/timeline.js を読む	構造を理解する	—
W02	judgment	asset, design.md	ランディングページに ADAPT する：プロジェクトのデザインシステムに合わせてクラス／トークンを変更する（BEM を CSS + JS で統一）	ページ内のコンポーネント	design.md がない → サンプルトークンを維持
W03	effect	実データ	faker のインポートと generateArticles() を削除し、build() の前に this.articles を実データに置き換える	JS に faker が残っていない	データがない → clarify
W04	judgment	プロジェクト	ダークモードを選択する：prefers-color-scheme を維持するか、dark-mode-maker のトークン（B01）に置き換える	ダークモードの方式が 1 つ	—
W05	deterministic	ページ	playwright-verify で検証する：スクリーンショット撮影＋スクロールテスト	スクリーンショット＋すべてのマイルストーンが表示される	マイルストーンが表示されない → B02

各ステップの詳細（W01〜W05 の基準となる情報源）：

アセット

assets/timeline.html + assets/timeline.css + assets/timeline.js — 読み込んでからランディングページに ADAPT してください（プロジェクトに design.md がある場合は、プロジェクトのデザインシステムに合わせてクラス／トークンを変更します）。そのまま機械的にコピーしてはいけません。

仕組み

• 各マイルストーンは、<time>（日付、ISO 標準の datetime 属性）＋<a> のタイトル＋<small> の出典を含む <li class="timeline__item"> です。
• IntersectionObserver は、マイルストーンがビューポートに入ると timeline__item--in クラスを付与します。CSS transition によって「徐々に表示」（opacity + translateX）されます。JS で直接アニメーションさせないでください。
• レスポンシブ対応：モバイルでは、マイルストーンの点と接続線を左側に配置し、日付を行内に表示します。≥768px では、日付を左側の独立した列に分けて配置します（position: absolute）。
• ダークテーマは @media (prefers-color-scheme: dark) を使い、3 つの変数 --bg/--fg/--primary を変更します。プロジェクトに dark-mode-maker（OS の設定に従うだけでなく、ユーザーが切り替えられる機能）がすでにある場合は、このブロックを dark-mode-maker のトークン変数に置き換えてください。2 つのダークモード機能が競合しないようにしてください。

分岐

ID	種別	条件	動作	スキップ／失敗	再合流
B01	conditional_required	プロジェクトに dark-mode-maker がすでにある	prefers-color-scheme ブロックを dark-mode-maker のトークン変数に置き換える	ない場合 → サンプルブロックを維持	W05
B02	recovery	マイルストーンの内容が長く、ビューポートより高いため、表示されない	threshold: 1 を 0.5 に下げる（RULE-03）	それでも表示されない → 失敗としてユーザーに報告	W05

検証と完了条件

完了条件：対象ページの JS に faker／generateArticles が残っていないこと、CSS と JS のクラスが一致していること、スクロール後にすべてのマイルストーンが表示される様子を playwright-verify でキャプチャできることです。コンソールエラーがないだけでは、完了と判断できません（RULE-04）。

例

• 成功例：「CHANGELOG.md から changelog timeline を作成して」→ 3 つのアセットを適用し、this.articles の代わりに Markdown からデータを解析して faker を削除 → playwright でスクロールし、すべてのマイルストーンに timeline__item--in クラスが付くことを確認。デスクトップでは、≥768px のとき日付が左側の列に表示されます。
• **境界条件／失敗例：**ロードマップのマイルストーンの説明が画面の高さより長い → threshold: 1 ではマイルストーンが opacity 0 のまま表示されない → B02 に従って 0.5 に下げ、再検証すると表示されます。

起源

• llmwiki/patterns/timeline/（参考用スニペットで、どのスキルにも紐づいておらず、git で追跡されたこともありません）を、2026-09-17 のユーザーの要望に基づいて実際のスキルにまとめました。blur と同じタイミングです。