timeline

技能：timeline

纯 HTML/CSS/JS 组件（无框架）——垂直里程碑列表，每个里程碑包含日期 + 标题 + 来源，滚动到哪里就显示到哪里。

WHAT

Purpose 和 context

• **Purpose：**在落地页中加入一条垂直的单轴时间线（日期里程碑 + 标题 + 来源），滚动时逐步显示，在 768px 处适配移动端→桌面端，使用真实数据。
• Trigger（何时使用）：
  • 页面需要按时间列出里程碑：更新日志、项目历史、路线图、写作归档、事件时间线。
  • 用户说“做个时间线”“时间线”“时间线形式的历史记录”。
• **Non-goals：**不要用于关系图／流程图（应使用 /diagram），也不要用于数值数据图表（应使用 dataviz）——这只是单条线性时间轴。

Mental model

真实里程碑数据（API/markdown/CMS）→ <li class="timeline__item">（time + a + small）→ IntersectionObserver 添加 timeline__item--in → CSS transition 逐步显示。示例素材是调整的起点，而不是直接照搬的副本。

Input 和 output contract

	Field	Required?	意义
In	落地页	是	时间线的接入位置
In	真实里程碑数据	是	日期（ISO）+ 标题 + 链接 + 来源；缺少数据就无法接入（只能使用演示用假数据）
In	design.md / token dark-mode-maker	否	如果提供，则按项目设计系统更换 class/token
Out	已调整的 HTML/CSS/JS	是	不再导入 faker，BEM class 与 CSS 和 JS 相匹配
Out	验证证据	是	截图 + 通过 playwright-verify 滚动测试

Rules 和 capabilities

• RULE-01（MUST）：assets/timeline.js 第 1 行从 esm.sh 导入 faker，仅用于为演示生成假数据（generateArticles()）——接入真实项目时，删除该导入和 generateArticles()，在 build() 前将 this.articles 替换为真实数据（API/markdown/CMS）。在生产环境中保留 faker 导入会产生多余依赖，还会暴露假数据。
• RULE-02（MUST）：class 按 BEM 命名（timeline__item-time……）——更改 class 名称时，CSS 和 JS 的 querySelector 都要一并更改，不要只改一边。
• RULE-03（MUST）：IntersectionObserver 的 threshold: 1 表示整个里程碑都必须进入视口后才会显示——高于视口的里程碑（内容较长）永远无法达到 threshold 1；如果里程碑内容较长，应将其降至 0.5。
• RULE-04（MUST）：接入真实数据后，使用 playwright-verify 验证（截图 + 滚动测试），不要只因控制台没有报错就断言“能运行”。
• Capabilities：读取技能示例素材；编写落地页前端文件；运行无头浏览器进行截图／滚动检查。

Failure boundaries

• 尚无真实里程碑数据 → clarify 数据来源；不要交付仍使用 faker 的版本。
• 实际需求是关系图／流程图或数值图表 → blocked，转至 /diagram 或 dataviz。
• Playwright 验证发现滚动时里程碑没有显示 → failed，修复（例如降低 threshold）后重新验证。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	技能素材	阅读 assets/timeline.html + assets/timeline.css + assets/timeline.js	理解结构	—
W02	judgment	素材，design.md	调整并接入落地页：按项目设计系统更换 class/token（BEM 在 CSS + JS 中保持一致）	页面中的组件	没有 design.md → 保留示例 token
W03	effect	真实数据	删除 faker 导入和 generateArticles()，在 build() 前将 this.articles 替换为真实数据	JS 中不再包含 faker	缺少数据 → clarify
W04	judgment	项目	选择 dark-mode：保留 prefers-color-scheme，或替换为 dark-mode-maker token（B01）	仅使用一种 dark-mode 机制	—
W05	deterministic	页面	使用 playwright-verify 验证：截图 + 滚动测试	截图 + 里程碑全部显示	里程碑未显示 → B02

各步骤详情（W01–W05 的权威依据）：

Assets

assets/timeline.html + assets/timeline.css + assets/timeline.js——阅读后调整并接入落地页（如果已有 design.md，按项目设计系统更换 class/token），不要机械地原样复制。

机制

• 每个时间节点都是一个包含 <time>（日期，datetime 属性采用标准 ISO 格式）、标题 <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（主动切换，不只是跟随操作系统），则用 dark-mode-maker 的 token 变量替换此代码块，避免两种暗色模式机制相互冲突。

分支

ID	类型	条件	行为	跳过／失败	重新汇合
B01	conditional_required	项目已有 dark-mode-maker	用 dark-mode-maker 的 token 变量替换 prefers-color-scheme 代码块	不存在 → 保留示例代码块	W05
B02	recovery	时间节点内容较长，高于视口，始终不显示	将 threshold: 1 降至 0.5（RULE-03）	仍不显示 → 失败，告知用户	W05

验证与停止条件

完成条件：页面目标 JS 中不再有 faker/generateArticles，CSS 和 JS 的类名一致，并且 playwright-verify 在滚动后能截取到所有显示的时间节点。控制台无错误并不足以得出结论（RULE-04）。

示例

• 正向：“从 CHANGELOG.md 制作 changelog 时间线” → 调整 3 个资源，将数据改为从 markdown 解析，而不是使用 this.articles，删除 faker → playwright 滚动后可看到所有时间节点都具有 timeline__item--in 类，桌面端 ≥768px 的日期位于左侧列。
• **边界／失败：**路线图时间节点的描述超过屏幕高度 → 使用 threshold: 1 时，节点始终保持 opacity 0 → B02 将其降至 0.5，重新验证后显示正常。

来源

• 根据用户于 2026-09-17 的要求，将 llmwiki/patterns/timeline/（尚未关联任何 skill、从未纳入 git 跟踪的参考代码片段）压缩整理成正式 skill — 与 blur 同期。