timeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: timeline

Component HTML/CSS/JS thuần (không framework) — danh sách mốc dọc, mỗi mốc có ngày + tiêu đề + nguồn, cuộn tới đâu hiện tới đó.

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

WHAT

内容

Purpose và context

目的与上下文

Purpose: đưa vào trang đích một timeline dọc MỘT trục thời gian (mốc ngày + tiêu đề + nguồn), cuộn-hiện dần, responsive mobile→desktop ở 768px, dữ liệu thật.
Trigger (when to use):
- Trang cần liệt kê MỐC THEO THỜI GIAN: changelog, lịch sử dự án, roadmap, writing archive, timeline sự kiện.
- User nói "làm timeline", "dòng thời gian", "lịch sử dạng timeline".
Non-goals: KHÔNG dùng cho sơ đồ quan hệ/luồng (đó là
```
/diagram
```
) hay biểu đồ dữ liệu số (đó là
```
dataviz
```
) — đây chỉ là MỘT trục thời gian tuyến tính.

目的： 将一个单一时间轴的垂直 timeline 引入目标页面（日期里程碑 + 标题 + 来源），滚动时渐显，在 768px 处从移动端响应式切换到桌面端，并使用真实数据。
触发条件（何时使用）：
- 需要按时间列出里程碑的页面：changelog、项目历史、roadmap、写作归档、事件 timeline。
- 用户说“制作 timeline”“时间线”“timeline 形式的历史”。
非目标： 不要用于关系/流程图（使用
```
/diagram
```
）或数值图表（使用
```
dataviz
```
）——这里只处理一条线性时间轴。

Mental model

心智模型

dữ liệu mốc thật (API/markdown/CMS) → <li class="timeline__item"> (time + a + small) → IntersectionObserver gắn timeline__item--in → CSS transition hiện dần

. Asset mẫu là điểm xuất phát để ADAPT, không phải bản copy.

真实里程碑数据（API/markdown/CMS）→ <li class="timeline__item">（<time> + <a> + <small>）→ IntersectionObserver 添加 timeline__item--in → CSS transition 渐显

。示例素材是适配的起点，不是可照搬的版本。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	trang đích	có	nơi gắn timeline
In	dữ liệu mốc thật	có	ngày (ISO) + tiêu đề + link + nguồn; thiếu thì chưa wire được (chỉ có demo faker)
In	`design.md` / token dark-mode-maker	không	có thì đổi class/token theo hệ design dự án
Out	HTML/CSS/JS đã adapt	có	không còn import faker, class BEM khớp CSS và JS
Out	bằng chứng verify	có	ảnh chụp + cuộn thử qua `playwright-verify`

	字段	是否必填？	含义
In	目标页面	是	安装 timeline 的位置
In	真实里程碑数据	是	日期（ISO）+ 标题 + 链接 + 来源；缺失时无法完成接入（只能使用 faker demo）
In	`design.md` / dark-mode-maker token	否	如有，可根据项目的设计体系调整 class/token
Out	已适配的 HTML/CSS/JS	是	不再导入 faker，BEM class 与 CSS/JS 一致
Out	验证证据	是	截图 + 通过 `playwright-verify` 进行滚动测试

Rules và capabilities

规则与能力

RULE-01 (MUST): assets/timeline.js
dòng 1 import
faker
từ
esm.sh
chỉ để SINH DỮ LIỆU GIẢ cho demo (
```
generateArticles()
```
) — khi wire vào dự án thật, XOÁ import đó +
```
generateArticles()
```
, thay
```
this.articles
```
bằng dữ liệu THẬT (API/markdown/CMS) trước khi build(). Để nguyên import faker trong production là phụ thuộc thừa + lộ dữ liệu giả.
RULE-02 (MUST): Class đặt tên theo BEM (
```
timeline__item-time
```
...) — đổi tên class thì đổi cả CSS lẫn JS
```
querySelector
```
, đừng đổi một bên.
RULE-03 (MUST): Ngưỡng
```
threshold: 1
```
của
```
IntersectionObserver
```
nghĩa là mốc phải vào khung nhìn TOÀN BỘ mới hiện — mốc cao hơn viewport (nội dung dài) sẽ không bao giờ đạt threshold 1, hạ xuống
```
0.5
```
nếu mốc có nội dung dài.
RULE-04 (MUST): Verify bằng
```
playwright-verify
```
(chụp + cuộn thử) sau khi wire dữ liệu thật, không tự khen "chạy được" chỉ vì không lỗi console.
Capabilities: đọc asset mẫu của skill; ghi file front-end của trang đích; chạy trình duyệt headless để chụp/cuộn kiểm.

RULE-01 (MUST)：assets/timeline.js
第 1 行从
esm.sh
导入
faker
，仅用于为 demo 生成虚假数据（
```
generateArticles()
```
）——接入真实项目时，必须在 build() 前删除该导入和
```
generateArticles()
```
，并将
```
this.articles
```
替换为真实数据（API/markdown/CMS）。在 production 中保留 faker 导入会造成多余依赖，并暴露虚假数据。
RULE-02 (MUST)：Class 命名遵循 BEM（
```
timeline__item-time
```
等）——修改 class 名称时，必须同步修改 CSS 和 JS 中的
```
querySelector
```
，不能只改一边。
RULE-03 (MUST)：
```
IntersectionObserver
```
的
```
threshold: 1
```
表示里程碑必须完全进入视口才会显示——高度超过 viewport 的里程碑（内容较长）永远无法达到 threshold 1；如果里程碑包含长内容，应将其降至
```
0.5
```
。
RULE-04 (MUST)：接入真实数据后，必须使用
```
playwright-verify
```
进行验证（截图 + 滚动测试）；不能仅因控制台没有错误就自行宣称“能够运行”。
能力：读取 skill 的示例素材；编写目标页面的前端文件；运行 headless 浏览器进行截图和滚动检查。

Failure boundaries

失败边界

Chưa có dữ liệu mốc thật → clarify nguồn dữ liệu; không giao bản còn faker.
Việc thật ra là sơ đồ quan hệ/luồng hoặc biểu đồ số → blocked, chuyển
```
/diagram
```
hoặc
```
dataviz
```
.
Verify playwright thấy mốc không hiện khi cuộn → failed, sửa (vd hạ threshold) rồi verify lại.

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

HOW

方法

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	skill assets	Đọc `assets/timeline.html` + `assets/timeline.css` + `assets/timeline.js`	hiểu cấu trúc	—
W02	judgment	asset, `design.md`	ADAPT vào trang đích: đổi class/token theo hệ design dự án (BEM đồng bộ CSS + JS)	component trong trang	không có design.md → giữ token mẫu
W03	effect	dữ liệu thật	Xoá import faker + `generateArticles()` , thay `this.articles` bằng dữ liệu THẬT trước build()	JS không còn faker	thiếu dữ liệu → clarify
W04	judgment	dự án	Chọn dark-mode: giữ `prefers-color-scheme` hoặc thay bằng token `dark-mode-maker` (B01)	một cơ chế dark duy nhất	—
W05	deterministic	trang	Verify bằng `playwright-verify` : chụp + cuộn thử	ảnh + mốc hiện đủ	mốc không hiện → B02

Chi tiết từng bước (nguồn chân lý cho W01–W05):

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	deterministic	skill 示例素材	读取 `assets/timeline.html` + `assets/timeline.css` + `assets/timeline.js`	理解结构	—
W02	judgment	asset、 `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

— đọc rồi ADAPT vào trang đích (đổi class/token theo hệ design của dự án nếu đã có

design.md

), không copy máy móc y nguyên.

assets/timeline.html

assets/timeline.css

assets/timeline.js

——读取后适配到目标页面；如果项目已有

design.md

，则根据其设计体系调整 class/token，不要机械照搬。

Cơ chế

机制

Mỗi mốc là
```
<li class="timeline__item">
```
chứa
```
<time>
```
(ngày,
```
datetime
```
attr chuẩn ISO) +
```
<a>
```
tiêu đề +
```
<small>
```
nguồn.
```
IntersectionObserver
```
gắn class
```
timeline__item--in
```
khi mốc cuộn vào khung nhìn → CSS transition làm nó "hiện dần" (opacity + translateX), KHÔNG animate bằng JS trực tiếp.
Responsive: mobile — chấm mốc + đường nối bên trái, ngày nằm trong dòng.
```
≥768px
```
— ngày tách ra cột riêng bên trái (
```
position: absolute
```
).
Dark theme qua
```
@media (prefers-color-scheme: dark)
```
— đổi 3 biến
```
--bg/--fg/--primary
```
; nếu dự án đã có
```
dark-mode-maker
```
(toggle chủ động, không chỉ theo OS) thì thay khối này bằng biến token của
```
dark-mode-maker
```
, đừng để hai cơ chế dark-mode chỏi nhau.

每个里程碑都是
```
<li class="timeline__item">
```
，包含
```
<time>
```
（日期，使用标准 ISO
```
datetime
```
属性）+
```
<a>
```
标题 +
```
<small>
```
来源。
```
IntersectionObserver
```
在里程碑滚入视口时添加 class
```
timeline__item--in
```
→ CSS transition 使其“渐显”（opacity + translateX），不要直接使用 JS 做动画。
响应式布局：移动端——左侧显示里程碑圆点和连接线，日期位于行内。
```
≥768px
```
——日期拆分到左侧独立列（
```
position: absolute
```
）。
Dark theme 通过
```
@media (prefers-color-scheme: dark)
```
实现——更改 3 个变量
```
--bg/--fg/--primary
```
；如果项目已有
```
dark-mode-maker
```
（可主动切换主题，而不只是跟随 OS），则用
```
dark-mode-maker
```
的 token 变量替换该代码块，不要让两种 dark mode 机制相互冲突。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	dự án đã có `dark-mode-maker`	thay khối `prefers-color-scheme` bằng biến token của `dark-mode-maker`	không có → giữ khối mẫu	W05
B02	recovery	mốc có nội dung dài, cao hơn viewport, không bao giờ hiện	hạ `threshold: 1` xuống `0.5` (RULE-03)	vẫn không hiện → failed, báo user	W05

ID	类型	守卫条件	行为	跳过/失败	汇合点
B01	conditional_required	项目已有 `dark-mode-maker`	用 `dark-mode-maker` 的 token 变量替换 `prefers-color-scheme` 代码块	不存在 → 保留示例代码块	W05
B02	recovery	里程碑内容较长、高度超过 viewport，始终无法显示	将 `threshold: 1` 降至 `0.5` （RULE-03）	仍然不显示 → failed，向用户报告	W05

Validation và stopping

验证与停止条件

Xong khi: grep không còn

faker

generateArticles

trong JS trang đích, class CSS và JS khớp, và

playwright-verify

chụp được mọi mốc hiện sau khi cuộn. Không lỗi console chưa đủ để kết luận (RULE-04).

完成条件：目标页面的 JS 中 grep 不到

faker

generateArticles

，CSS 与 JS 的 class 一致，并且

playwright-verify

能够在滚动后截取到所有已显示的里程碑。仅无控制台错误不足以得出结论（RULE-04）。

Examples

示例

Positive: "làm changelog timeline từ CHANGELOG.md" → adapt 3 asset, dữ liệu parse từ markdown thay
```
this.articles
```
, xoá faker → playwright cuộn thấy mọi mốc có class
```
timeline__item--in
```
, desktop ≥768px ngày nằm cột trái.
Boundary/failure: mốc roadmap mô tả dài hơn chiều cao màn hình → với
```
threshold: 1
```
mốc đứng opacity 0 mãi → B02 hạ
```
0.5
```
, verify lại thấy hiện.

正向示例：“根据 CHANGELOG.md 制作 changelog timeline”→ 适配 3 个素材，从 markdown 解析数据以替代
```
this.articles
```
，删除 faker → Playwright 滚动后，每个里程碑都带有 class
```
timeline__item--in
```
；在桌面端
```
≥768px
```
时，日期位于左列。
边界/失败： roadmap 里程碑的描述长于屏幕高度 → 使用
```
threshold: 1
```
时，里程碑会一直保持 opacity 0 → B02 将其降至
```
0.5
```
，重新验证后即可显示。

Origin

来源

Nén từ
```
llmwiki/patterns/timeline/
```
(snippet tham khảo chưa gắn skill nào, chưa từng track git) thành skill thật theo yêu cầu user 2026-09-17 — cùng đợt với
```
blur
```
.

压缩自
```
llmwiki/patterns/timeline/
```
（该参考片段尚未关联任何 skill，也从未纳入 git 跟踪），根据用户在 2026-09-17 的要求整理为正式 skill——与
```
blur
```
同一批次。