agentcss 0.16.0 → 0.24.0

package/02-primitives/choice/choice.css

@@ -234,8 +234,7 @@
   background: var(--accent);
   border-color: var(--accent);
 }
-.choice--radio .choice__input:checked ~ .choice__label .choice__mark::after {
-  transform: scale(1);
+.choice--radio .choice__input:checked ~ .choice__label .choice__mark::after {  transform: scale(1);
 }
 
 /* ============================================================================
@@ -393,3 +392,33 @@
        它是 CSS Level 4，某项目 上 WebView 版本不确定。
        写这一行时已经违反了自己刚定的纪律，已改用相邻兄弟选择器提优先级。
    ========================================================================= */
+
+/* ============================================================================
+   强制色（Windows 高对比度）
+   ============================================================================
+   0.17.0 全库扫描（forced-colors-check.js B3）在这里抓到 2 类 4 处，
+   都是同一个根因，而且**checkbox 的勾恰好没事** —— 这个对比值得记下来：
+
+     · checkbox 的勾：用 `border: solid var(--text-on-accent)` 画
+       ⇒ 强制色把 border-color 换成 CanvasText ⇒ **白底黑勾，看得见**
+     · radio 的圆点：用 `background: var(--text-on-accent)` 画
+       ⇒ 强制色把 background-color 换成 Canvas ⇒ **白底白点，消失**
+     · indeterminate 的横线：用 `background: var(--accent)` 画
+       ⇒ 同上 ⇒ **白底白线，消失**
+
+   ⇒ 规律：**用 background-color 画"前景图形"必死，用 border/color 画则活。**
+     强制色的换色规则是分属性的 —— 背景换背景色、前景换前景色。
+     把图形画在"背景属性"上，就等于把它声明成了背景，自然被换成背景色。
+
+   修法只有一处替换：把这两个 `background` 改成 `CanvasText`（系统前景色）。
+   ⚠️ 不要顺手把 checkbox 的勾也改了 —— 它现在是对的，
+      改成 CanvasText 反而会在暗色高对比度主题下（CanvasText = 浅色）出错。
+   ============================================================================ */
+@media (forced-colors: active) {
+  .choice--radio .choice__mark::after {
+    background: CanvasText;
+  }
+  .choice--checkbox .choice__input:indeterminate ~ .choice__label .choice__mark::after {
+    background: CanvasText;
+  }
+}

package/02-primitives/input/input.css

@@ -187,6 +187,20 @@
   mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2.5' stroke-linecap='round'%3E%3Ccircle cx='12' cy='12' r='10'/%3E%3Cpath d='M12 8v5M12 16.5v.5'/%3E%3C/svg%3E") center/contain no-repeat;
 }
 
+/* 🔴 强制色：与 table__sort::after 同一个模式 —— mask + currentColor 会变成白图标
+   ---------------------------------------------------------------------------
+   实拍（0.17.0）：`.field__error` 只剩「请输入有效金额」，行首的叹号没了。
+   文字本身已经表达了错误，所以这不是信息丢失，是**第二条线索**（给色盲用户的
+   非颜色编码，WCAG 1.4.1）被强制色抹掉了 —— 恰好抹掉的是它存在的理由。
+
+   ⇒ 强制色下改用 CanvasText。判据见 forced-colors-check.js A1。
+   --------------------------------------------------------------------------- */
+@media (forced-colors: active) {
+  .field__error::before {
+    background: CanvasText;
+  }
+}
+
 /* ---------------------------------------------------------------- 成功态
    只在"校验有明确通过语义"时用（如"该用户名可用"）。
    普通输入框加成功态是噪音。

package/02-primitives/progress/progress.css

@@ -29,6 +29,22 @@
   background: var(--surface-sunken);
   border-radius: var(--r-full);   /* 胶囊形 */
   overflow: hidden;
+  /* 🔴 强制色模式下的边界预留（0.17.0 实拍：没有它进度条整体消失）
+     ---------------------------------------------------------------------
+     Windows 高对比度下 `background` 被强制成 Canvas，轨道与填充条**同色**
+     ⇒ 735×6 的面积全白，用户完全看不出进度。
+
+     `outline: 1px solid transparent` 是这里的正解，不是笔误：
+       · 正常态：transparent ⇒ 看不见，且 outline **不占布局**，胶囊形不变
+       · 强制色下：浏览器把 transparent 替换成 CanvasText
+         ⇒ 自动显出一条 1px 实线，轨道因此有了轮廓
+     ⚠️ 别改成 `border: 1px solid transparent`：border 在 border-box 下会
+        吃掉 2px 内容高，`--progress-h: 4px` 的细条就只剩 2px 了。
+     ⚠️ 也别用 `box-shadow: 0 0 0 1px transparent` 兜底 —— 实测无效，
+        box-shadow 在强制色下整个被移除，透明的也一样。
+     判据见 05-audit/forced-colors-check.js A2/A3。 */
+  outline: 1px solid transparent;
+  outline-offset: -1px;          /* 画在内侧，不与相邻元素抢位置 */
   /* ⚠️ 不用 <progress> 原生标签的原因：它在部分浏览器里无法设成胶囊形，
      且 ::-webkit-progress-value 的圆角行为不一致。 */
 }
@@ -49,6 +65,27 @@
 .progress--warning .progress__bar { background: var(--warning); }
 .progress--danger  .progress__bar { background: var(--danger); }
 
+/* 🔴 强制色：填充条必须换「系统高亮色」，不能靠作者色
+   ---------------------------------------------------------------------------
+   强制色模式下所有作者写的 background-color 都被替换成 Canvas（白/黑）
+   ⇒ 填充条与轨道同色，进度归零。实测 735×6 全白，一个像素都不剩。
+
+   为什么用 `Highlight` 而不是别的系统色：
+     · 它是**唯一**语义为"被选中的一段/重点区域"的系统色，正好对应填充条
+     · 系统色关键字**不被强制替换** —— 实测 `Highlight` 在模拟下解析为
+       rgb(55,0,110)，`CanvasText` 为 rgb(0,0,0)，都保持自己的身份
+     ⚠️ 但**别在判据里断言具体 RGB**：模拟色板与真实高对比度主题不是同一套
+        （实测 `GrayText` 在模拟下是 rgb(96,0,0) 深红，真实系统下是灰）。
+        判据只能问"是不是等于 Canvas"。
+
+   为什么选择器是 `.progress .progress__bar` 而不是 `.progress__bar`：
+     上面三个变体是 0,2,0 优先级。用 0,1,0 会被它们压掉 ⇒ 危险态仍然不可见。
+     这里必须同权或更高，且写在变体之后。
+   --------------------------------------------------------------------------- */
+@media (forced-colors: active) {
+  .progress .progress__bar { background: Highlight; }
+}
+
 /* 尺寸变体 */
 .progress--lg { --progress-h: 10px; }
 .progress--sm { --progress-h: 4px; }
@@ -90,6 +127,25 @@
 .progress-ring--success { background: conic-gradient(var(--success) calc(var(--progress-num, 0) * 1%), var(--surface-sunken) 0); }
 .progress-ring--danger  { background: conic-gradient(var(--danger)  calc(var(--progress-num, 0) * 1%), var(--surface-sunken) 0); }
 
+/* 🔴 强制色：conic-gradient 整条被移除，环会"凭空不见"只剩一个数字
+   ---------------------------------------------------------------------------
+   实测（0.17.0）：`.progress-ring` 在 forced-colors 下 `background-image`
+   变成 none ⇒ 只截到居中的 "72%"，环一个像素都没有。
+   信息本身没丢（中心 label 里就是百分比数字），丢的是"这是个环"的形状。
+
+   ⇒ 用 outline 补一个圈。**不用 border**：label 是
+      `calc(100% - var(--ring-thickness) * 2)`，border 会挤小它，
+      在 --ring-size 较小时数字会被裁。
+   ⚠️ 也不能指望 `background: canvas` 之类的替换 —— 环是**渐变**，
+      强制色下 gradient 不区分颜色，整条 background-image 直接丢弃。 */
+@media (forced-colors: active) {
+  .progress-ring {
+    background: none;
+    outline: 2px solid CanvasText;
+    outline-offset: -2px;        /* 内侧描边，外径不变 */
+  }
+}
+
 /* ============================================================================
    3 · 不确定进度（不知道要多久）
    ============================================================================

package/02-primitives/skeleton/skeleton.css

@@ -81,6 +81,24 @@
   .skeleton::after { animation: none; opacity: 0; }
 }
 
+/* 🔴 强制色：骨架块会被抹成 Canvas，与页面同色 ⇒ 整个占位区消失
+   ---------------------------------------------------------------------------
+   实拍（0.17.0）：729×10 的骨架条在强制色下**完全空白**。
+   危险之处在于它"看起来像加载完成了"—— 用户看到空行，会以为内容就是空的。
+
+   ⇒ 用 `GrayText`。它是系统色关键字（不被再次强制替换），语义正好是
+     "disabled / 占位 / 非正文"，与骨架屏的含义一致。
+   ⚠️ 别断言它的具体 RGB：模拟色板下是 rgb(96,0,0) 深红，真实高对比度
+      主题下是灰。判据只问"是否等于 Canvas"。
+   ⚠️ shimmer（`::after` 的 linear-gradient）在强制色下会被移除 ——
+      这是**正确**行为，高对比度用户不需要动效，不需要补偿。
+   --------------------------------------------------------------------------- */
+@media (forced-colors: active) {
+  .skeleton {
+    background: GrayText;
+  }
+}
+
 /* ---------------------------------------------------------------------------
    组合件：列表骨架（最常用的形态）
    --------------------------------------------------------------------------- */

package/02-primitives/switch/switch.css

@@ -227,7 +227,17 @@
      --surface 两套模式都有定义（浅色 #fff / 暗色 #1C2024），
      滑块作为「浮在轨道上的圆盘」用它是语义正确的。 */
   background: var(--surface);
-  border: 0;
+  /* 🔴 原来是 `border: 0`。0.17.0 强制色实拍：滑块变成**完全不可见** ——
+     白底（Canvas）+ 阴影被移除（box-shadow 在强制色下整个丢弃）+ 无边框，
+     开关只剩一个空心胶囊，**开与关看不出区别**。
+
+     `1px solid transparent` 在这里同时满足两件事：
+       · 正常态：transparent ⇒ 与 `border: 0` 视觉等效（下面已标 box-sizing: border-box，
+         外径仍是 --sw-thumb，滑块尺寸不变）
+       · 强制色下：transparent 被替换成 CanvasText ⇒ 自动获得 1px 描边
+     ⚠️ 不要为了"省一层"把箱模型改成 content-box —— 那会让滑块外径多 2px，
+        与 `--sw-gap` 的推导值脱钩，圆圈又歪回去（真机踩过一次）。 */
+  border: 1px solid transparent;
   /* 阴影里的 rgba 是**阴影本身**的物理属性（不是主题色），
      它在浅色与暗色下都该是黑色 —— 换令牌反而会变灰。 */
   box-shadow: 0 1px 2px rgba(0, 0, 0, .28);
@@ -254,7 +264,11 @@
                                  - var(--sw-inset) * 2 - var(--sw-pad) * 2
                                  - (var(--sw-h) - var(--sw-inset) * 2
                                     - var(--sw-pad) * 2)));
-  border-color: var(--accent);
+  /* ⚠️ 原来是 `var(--accent)`。那时 border 是 0，这条**从来没生效过**。
+     0.17.0 给滑块补了 `border: 1px solid transparent` 之后它会突然显形，
+     在蓝底上多出一圈品牌色描边 ⇒ 必须显式写 transparent，
+     让「正常态无描边 / 强制色下自动变 CanvasText」这条规则只有一个真相来源。 */
+  border-color: transparent;
 }
 
 /* 焦点环在**看得见**的元素上（原生 outline 被 clip 了，看不见）。
@@ -368,3 +382,48 @@
                                  - (var(--sw-h) - var(--sw-inset) * 2
                                     - var(--sw-pad) * 2)));
 }
+
+/* ============================================================================
+   强制色（Windows 高对比度）
+   ============================================================================
+   0.17.0 实拍：加上滑块的 transparent 边框后，滑块已经**看得见**了，
+   但"开"与"关"仍然只能靠滑块的左右位置分辨 —— 因为开态轨道原本铺的是
+   `--switch-on` 品牌色，强制色下同样被抹成 Canvas。
+
+   ⇒ 开态改用系统 `Highlight`。这样：
+       关 = 白底胶囊 + 黑描边 + 左侧空心圆
+       开 = 高亮底胶囊 + 右侧实心圆
+     两重线索（底色 + 位置），不依赖任何作者色。
+
+   ⚠️ 选择器必须与上面开态规则**完全同权**（0,3,0）并写在它之后，
+      否则会被 `--switch-on` 压掉。
+   ============================================================================ */
+@media (forced-colors: active) {
+  .switch__input:checked ~ .switch__track {
+    background: Highlight;
+  }
+
+  /* 🔴 禁用态必须与「可用的关态」不同 —— 否则等于骗人
+     ------------------------------------------------------------------------
+     实拍（0.17.0）：修好滑块之后，禁用态与正常关态在强制色下**完全一致**
+     （track 白 + 1px 黑边、thumb 白 + 1px 黑边、都在左侧）。
+     高对比度用户会以为这个开关还能点。
+
+     原来靠 `--surface-sunken`（灰底）与 `--text-tertiary`（灰字）表达禁用，
+     这两者在强制色下都被抹成 CanvasText/Canvas。
+
+     ⇒ 用 `GrayText`：它的系统语义就是 "disabled / 不可操作"，
+       在真实高对比度主题下是灰。三处一起换，保持"轨道-滑块-文字"同一套语义。
+     ⚠️ 模拟色板里 GrayText 解析为 rgb(96,0,0) 深红，看着像"危险"不像"禁用"。
+        这是 Chromium 模拟的偏差，不是这条规则的问题 —— 判据只判"≠ Canvas"。
+     ------------------------------------------------------------------------ */
+  .switch__input:disabled ~ .switch__track {
+    border-color: GrayText;
+  }
+  .switch__input:disabled ~ .switch__track .switch__thumb {
+    border-color: GrayText;
+  }
+  .switch__input:disabled ~ .switch__label {
+    color: GrayText;
+  }
+}

package/02-primitives/timeline/README.md

@@ -0,0 +1,70 @@
+# timeline · 时间轴
+
+一串按时间排的事件：**一个时点、一句标题、可选一段正文**。
+公告列表、大事记、版本记录都是它 —— 共同点不是"有日期"，而是**顺序本身就是信息**。
+
+```html
+<link rel="stylesheet" href="02-primitives/timeline/timeline.css">
+
+<ol class="timeline">
+  <li class="timeline__item timeline__item--latest">
+    <time class="timeline__time num" datetime="2026-10-29">2026-10-29</time>
+    <h3 class="timeline__title">2026 年三季报披露</h3>
+    <p class="timeline__body">营业总收入 1,294.06 亿元，同比 +12.40%。</p>
+  </li>
+  <li class="timeline__item">
+    <time class="timeline__time num" datetime="2026-08-27">2026-08-27</time>
+    <h3 class="timeline__title">2026 年半年报披露</h3>
+  </li>
+</ol>
+```
+
+## 类
+
+| 类 | 作用 |
+|---|---|
+| `.timeline` | 根。`<ol>`（顺序即信息），用 `<ul>` 或 `<div>` 也能渲染 |
+| `.timeline__item` | 一条事件。`position: relative` + 左侧留出 `--sp-5` 的槽 |
+| `.timeline__time` | 时点。默认块级、tertiary 色、`--fs-xs` |
+| `.timeline__title` | 标题。`margin: 0`，不受浏览器默认标题边距影响 |
+| `.timeline__body` | 正文，可选 |
+| `.timeline__item--latest` | 最新一条：圆点 8 → 12px、标题 600 |
+| `.timeline--compact` | 紧凑档：条目间距 `--sp-4` → `--sp-2`，时间回到标题同一行 |
+
+## 三条硬规矩
+
+1. **用 `<ol>`，不是 `<div>`**。读屏会念「第 2 项，共 4 项」；
+   `<div>` 堆出来的时间轴在无障碍树里只是一串没有关系的段落。
+   时间用 `<time datetime="…">`：屏幕显示"10-29"，机器仍拿到完整日期。
+2. **状态不在这里表达**。要区分「已披露 / 待披露 / 停牌」，用 `badge` 配文字。
+   本组件**故意不给状态配色** —— 绿色和灰色在强制色模式、色盲、打印三种情况下会同时失效，
+   而状态文字不会。
+3. **"最新一条"靠尺寸和字重，不靠颜色**。`timeline__item--latest` 只改两件非颜色的事：
+   圆点直径与标题字重。颜色在强制色里会被替换掉，只靠"最新那条是蓝的"等于没标。
+
+## 反例
+
+- **拿字符画圆点** `content: "●"` 视觉上看不出区别，但那是一个**文字**：它会进 `textContent`、能被选中复制、也会被算进链接名（读屏念「圆点 季报披露」）。用 `content: ""` + 盒子画。
+- **最后一条也画连接线** 列表下方会多出一截悬空的线，看起来像「还有一个事件没加载出来」。收尾靠选择器（`:not(:last-child)`），不靠给最后一条设透明边框 —— 透明边框在强制色里会显形。
+- **连接线用 `inset-block: 0`** 第一条的线会从条目顶端开始，在圆点上方留一小截 —— 同样像"上面还有内容"。线应该从**自己的圆心**画到下一个的圆心。
+- **圆点对齐整块的中心** 正文一长，圆点就往下滑，同屏几条圆点高低不齐。要对齐的是**首行行盒**的中心。
+- **只给一条事件也套时间轴** 那不是时间轴，是一段话。连接线和圆点只会让人以为还有下文。
+
+## 为什么它值得是一个组件
+
+四个必须一起做对的量，交给调用方"记得做"必然漏：
+
+| 量 | 错了会怎样 |
+|---|---|
+| 圆心 / 连接线中心 / 首行中心 **三心合一** | 差 1–2px，说不清哪里不对，但一眼就是歪的 |
+| 连接线**只画到下一个圆心** | 首尾各多一小截，像"内容没加载完" |
+| 最后一条**不留底距、不画线** | 列表下方凭空多一块空白 |
+| 圆点**不用 border 画** | 本库 `box-sizing` 是选配（挂在 `.page *` 上）⇒ 有它时圆点缩水一半 |
+
+前三条由 `timeline-check.js` 的 B 组守着（含反向控制），第四条是 `--tl-dot` 只作用于宽高。
+
+## 什么时候不该用它
+
+- **要表达"进行到第几步"**：那是步骤条，有"当前"和"未到"的语义；本组件只表示"发生过"。
+- **事件之间有嵌套/分支**：时间轴是线性的。要分支用树，要并行用表格。
+- **只是"更新时间"一行字**：不需要圆点和连接线，一行 `small` 就够。

package/02-primitives/timeline/demo.html

@@ -0,0 +1,161 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="data:,">
+<title>timeline · 时间轴</title>
+<link rel="stylesheet" href="../../01-tokens/tokens.css">
+<link rel="stylesheet" href="../../01-tokens/typography.css">
+<link rel="stylesheet" href="../../01-tokens/page.css">
+<link rel="stylesheet" href="../../02-primitives/timeline/timeline.css">
+<style>
+  .tl-demo { max-width: 36rem; }
+  /* 代码块在 320px 上会横向溢出（实测 scrollWidth 630 > 320）——
+     一行长标记就能把整页撑成横向滚动。这一条只属于 demo，不进组件。 */
+  .tl-code { overflow-x: auto; }
+  .tl-demo .timeline__title { font-size: var(--fs-base); }
+  /* 反例专用：把圆点画成**字符**。这是错的，只为对照演示。 */
+  .timeline--dotchar .timeline__item::after {
+    content: "●";
+    width: auto;
+    height: auto;
+    background: none;
+    color: var(--accent);
+    font-size: 9px;
+    line-height: 1;
+    inset-block-start: 6px;
+  }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+  <h1>timeline · 时间轴</h1>
+  <p class="lede">
+    一串按时间排的事件：<strong>一个时点、一句标题、可选一段正文</strong>。
+    公告列表、大事记、版本记录都是它 —— 它们的共同点不是“有日期”，
+    而是<strong>顺序本身就是信息</strong>。
+  </p>
+
+  <h2 class="rule-top">一个完整的时间轴</h2>
+  <ol class="timeline tl-demo">
+    <li class="timeline__item timeline__item--latest">
+      <time class="timeline__time num" datetime="2026-10-29">2026-10-29</time>
+      <h3 class="timeline__title">2026 年三季报披露</h3>
+      <p class="timeline__body">
+        营业总收入 1,294.06 亿元，同比 +12.40%；经营现金流净额本期未披露。
+      </p>
+    </li>
+    <li class="timeline__item">
+      <time class="timeline__time num" datetime="2026-08-27">2026-08-27</time>
+      <h3 class="timeline__title">2026 年半年报披露</h3>
+      <p class="timeline__body">营业总收入 842.31 亿元，同比 +9.87%。</p>
+    </li>
+    <li class="timeline__item">
+      <time class="timeline__time num" datetime="2026-05-18">2026-05-18</time>
+      <h3 class="timeline__title">2025 年度分红实施</h3>
+      <p class="timeline__body">每 10 股派 12.80 元（含税），除权除息日 2026-05-19。</p>
+    </li>
+    <li class="timeline__item">
+      <time class="timeline__time num" datetime="2026-04-02">2026-04-02</time>
+      <h3 class="timeline__title">2025 年年度报告披露</h3>
+    </li>
+  </ol>
+  <p class="small">
+    第一项带 <code>timeline__item--latest</code>：圆点从 8px 变成 12px、标题加重到 600。
+    <strong>两条都是非颜色线索</strong> —— 强制色模式会把所有作者色替换掉，
+    只靠“最新那条是蓝的”在那里等于没标。
+    <br>
+    连接线是伪元素画的，最后一条由 <code>:not(:last-child)</code> 收掉 ——
+    不是给最后一条设透明边框。<strong>透明边框在强制色里会显形</strong>，
+    本库为此吃过一次亏（0.22.1 的侧栏“当前项”，五条全都长出了竖线）。
+  </p>
+
+  <h2 class="rule-top">紧凑档：侧栏、卡片、弹层里的事记</h2>
+  <div class="box">
+    <ol class="timeline timeline--compact" style="max-width: 22rem">
+      <li class="timeline__item timeline__item--latest">
+        <time class="timeline__time num" datetime="2026-10-31">10-31</time>
+        <span class="timeline__title">0.23.0 发布</span>
+      </li>
+      <li class="timeline__item">
+        <time class="timeline__time num" datetime="2026-10-31">10-31</time>
+        <span class="timeline__title">0.22.1 修强制色当前项</span>
+      </li>
+      <li class="timeline__item">
+        <time class="timeline__time num" datetime="2026-10-31">10-31</time>
+        <span class="timeline__title">0.21.0 发现层</span>
+      </li>
+    </ol>
+  </div>
+  <p class="small">
+    <code>timeline--compact</code> 只做两件事：条目间距从 <code>--sp-4</code> 收到
+    <code>--sp-2</code>，时间挪回标题同一行。**它不改字号** ——
+    在侧栏里把字缩小，等于承认这块内容不重要，而事实往往相反。
+  </p>
+
+  <h2 class="rule-top">反例：拿字符画圆点</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad=".timeline--dotchar .timeline__item|glyphs|=10">
+      <h3>错：<code>content: "●"</code></h3>
+      <!-- ⚠️ 这一条**故意写成一行**：下面那条断言数的是 textContent 的字符数，
+           标签之间换行会带进缩进空白，数字就跟着排版走了。 -->
+      <ol class="timeline timeline--dotchar"><li class="timeline__item"><time class="timeline__time num" datetime="2026-10-29">10-29</time><span class="timeline__title">季报披露</span></li></ol>
+      <p class="small">
+        这一条的字形多 1 个：那个 <code>●</code> 是<strong>文字</strong>。
+        它会出现在 <code>textContent</code> 里、能被选中复制、
+        也会被算进链接名（读屏念“圆点 季报披露”）。
+      </p>
+    </div>
+    <div class="cmp__pane cmp__good" data-good=".timeline .timeline__item|glyphs|=9">
+      <h3>对：空内容 + 盒子</h3>
+      <ol class="timeline"><li class="timeline__item"><time class="timeline__time num" datetime="2026-10-29">10-29</time><span class="timeline__title">季报披露</span></li></ol>
+      <p class="small">
+        <code>content: ""</code> + 8×8 的圆角盒子：视觉一样，字形 0 个。
+        装饰不该占用“读得出来的字符”这个稀缺资源。
+      </p>
+    </div>
+  </div>
+  <p class="cmp__why">
+    两栏的字形数差 1 —— 那 1 个就是圆点。这不是洁癖：
+    <strong>伪元素里的字符会参与可访问名计算</strong>（本库 `internal/ERRORS.md` E189 记过，
+    侧栏当时被念成“圆点 总览”）。要画形状就用盒子，不要用字。
+  </p>
+
+  <h2 class="rule-top">什么时候不该用它</h2>
+  <ul>
+    <li>
+      <strong>状态要区分时</strong>（已披露 / 待披露 / 停牌）：用 <code>badge</code> 配文字。
+      本组件<strong>故意不给状态配色</strong> —— 颜色在强制色、色盲、打印三种情况下会同时失效，
+      而状态文字不会。
+    </li>
+    <li>
+      <strong>要做进度条时</strong>：步骤条（steps）与时间轴不是一回事 ——
+      前者有“当前在第几步”的语义，本组件只表示“发生过”。
+    </li>
+    <li>
+      <strong>只有一条事件时</strong>：那是一个段落，不是时间轴。连接线和圆点在这里只会让人以为还有下文。
+    </li>
+  </ul>
+
+  <h2 class="rule-top">标记结构</h2>
+<pre class="tl-code"><code>&lt;ol class="timeline"&gt;
+  &lt;li class="timeline__item
+       timeline__item--latest"&gt;
+    &lt;time class="timeline__time"
+          datetime="2026-10-29"&gt;
+      2026-10-29
+    &lt;/time&gt;
+    &lt;h3 class="timeline__title"&gt;
+      2026 年三季报披露
+    &lt;/h3&gt;
+  &lt;/li&gt;
+&lt;/ol&gt;</code></pre>
+  <p class="small">
+    <code>&lt;ol&gt;</code> 不只是习惯：读屏会念“第 2 项，共 4 项”，
+    而 <code>&lt;div&gt;</code> 堆出来的时间轴在无障碍树里只是一串没有关系的段落。
+    <code>&lt;time datetime&gt;</code> 同理 —— 显示“10-29”时，机器仍拿到完整日期。
+  </p>
+</main>
+</body>
+</html>

package/02-primitives/timeline/timeline.css

@@ -0,0 +1,152 @@
+/* ============================================================================
+   Timeline — 时间轴（公告、大事记、版本记录）
+   ============================================================================
+   一句话：**一串按时间排的事件**，每个事件有一个时点、一句标题、可选一段正文。
+
+   🔴 为什么它是组件，而不是「一个 ol + 几个 margin」
+   ----------------------------------------------------------------------------
+   因为这四件事必须一起做对，少一件就会在真实页面里出错：
+
+     ① **顺序就是内容** —— 用 `<ol>` 而不是 `<div>`。读屏会念「第 3 项，共 7 项」，
+        而 `<div>` 堆出来的时间轴在无障碍树里只是一串没有关系的段落。
+        CSS **只认类名、不认标签**（用 `<ul>` 也能跑），但 demo 与文档一律 `<ol>`。
+     ② **连接线的收尾靠选择器，不靠颜色** —— 见下面「为什么不用 border」。
+     ③ **状态不许只靠颜色** —— 见下面「为什么不给状态配色」。
+     ④ **方向和间距全是逻辑属性** —— `padding-inline-start` 而不是 `padding-left`，
+        否则阿拉伯语页面里圆点会落在文字的右边（本库 40 页 RTL 基线会抓）。
+
+   🔴 为什么连接线用伪元素，不用 border
+   ----------------------------------------------------------------------------
+   最省事的写法是给每个 item 加 `border-inline-start`，再用
+   `border-color: transparent` 收掉最后一条。**这条在本库已经炸过一次**：
+   强制色模式会把 transparent 边框解析成实线（0.21 的侧栏「当前项」，
+   五项全都长出竖线，见 CHANGELOG 0.22.1）。
+
+   ⇒ 这里的收尾是**选择器**的事（`:not(:last-child)`），不是颜色的事。
+     伪元素要么在、要么不在，没有「在但看不见」这种中间态。
+
+   🔴 为什么不给状态配色（已披露 / 待披露 / 停牌）
+   ----------------------------------------------------------------------------
+   因为「绿=已披露、灰=待披露」在三种情况下会同时失效：
+   强制色模式（所有作者色被替换成同一套系统色）、色盲用户、
+   以及打印。而**状态文字本身**不会失效。
+
+   ⇒ 状态留给 `badge`（它带文字）。本组件只管「什么时候、发生了什么」。
+
+   🔴 为什么「最新一条」用尺寸 + 字重，而不是颜色
+   ----------------------------------------------------------------------------
+   同一个道理：颜色在强制色里会消失。这里用**圆点更大 + 标题更重**，
+   两条都是非颜色线索，且都不依赖 `::before` 里的字符
+   （`content: "●"` 会被算进可访问名，读屏念「圆点 …」，见 internal/ERRORS.md E189）。
+   ========================================================================= */
+
+.timeline {
+  /* 三个几何量，全部从这里派生 —— 圆点大小一改，圆心、轴线、连接线一起跟着走，
+     不会出现「圆点变大了但线还在原地」这种只差半像素、却怎么看怎么歪的错位。 */
+  --tl-dot: 8px;             /* 圆点直径（最新一条改成 12px） */
+  --tl-axis: 4px;            /* 轴线：圆点中心与连接线中心都落在这条竖线上 */
+
+  list-style: none;          /* ol 的序号对时间轴是噪声：时间本身就是序号 */
+  margin: 0;                 /* 组件不依赖 page.css 的重置 */
+  padding: 0;
+  min-width: 0;              /* 放进 flex/grid 列时不撑破（长标题会） */
+}
+
+.timeline__item {
+  position: relative;
+  padding-inline-start: var(--sp-5);
+  padding-block-end: var(--sp-4);
+}
+
+/* 最后一条不留尾巴 —— 否则列表下方凭空多出一截空白，
+   而它看起来像「还有一个事件没加载出来」。 */
+.timeline__item:last-child {
+  padding-block-end: 0;
+}
+
+/* 连接线：**从自己的圆心画到下一个的圆心**，两头各由圆点盖住。
+   不用 `inset-block: 0` —— 那样第一条上方会多出一小截悬空的线
+   （从条目顶端到圆点之间），看起来像「上面还有一个事件没渲染出来」。
+   两个端点都写成同一个表达式，圆点尺寸一改两边自动跟上。 */
+.timeline__item:not(:last-child)::before {
+  content: "";
+  position: absolute;
+  inset-inline-start: calc(var(--tl-axis) - 1px);
+  inset-block-start: calc(var(--fs-xs) * var(--lh-base) / 2);
+  inset-block-end: calc(var(--fs-xs) * var(--lh-base) / -2);
+  width: 2px;
+  background: var(--border-decor-str);
+}
+
+/* 圆点：**没有 border**，所以尺寸与 box-sizing 无关
+   （本库的 box-sizing 是选配，挂在 `.page *` 上；组件不能假设它存在）。
+   纵向对齐的是**第一行时间的行盒中心**，不是整块的中心 ——
+   正文长短不一时，后者会让圆点忽上忽下。 */
+.timeline__item::after {
+  content: "";
+  position: absolute;
+  inset-inline-start: calc(var(--tl-axis) - var(--tl-dot) / 2);
+  inset-block-start: calc(var(--fs-xs) * var(--lh-base) / 2 - var(--tl-dot) / 2);
+  width: var(--tl-dot);
+  height: var(--tl-dot);
+  border-radius: var(--r-full);
+  background: var(--accent);
+}
+
+/* 最新一条：圆点 12px。圆心由上面的 calc 自动保持不动 ——
+   否则连接线会在这一条拐个弯，看起来像画错了。 */
+.timeline__item--latest {
+  --tl-dot: 12px;
+}
+
+.timeline__item--latest .timeline__title {
+  font-weight: 600;
+}
+
+.timeline__time {
+  display: block;            /* <time> 默认是行内，不换行会跟标题黏在一起 */
+  line-height: var(--lh-base);   /* 显式给：圆点对齐算的就是这个行盒 */
+  color: var(--text-tertiary);
+  font-size: var(--fs-xs);
+}
+
+/* ⚠️ 日期要等宽对齐（竖着扫）的话，**给它加 class="num"** —— 本库的等宽数字
+   只有一处定义（`typography.css` 的 `.num`），组件自己再声明一遍就会漂移
+   （`numeric-gate.py` 守这一条）。
+   本组件不默认加：`.timeline__time` 也可能放“第三季度”这种非数字文本。 */
+
+.timeline__title {
+  margin: 0;                 /* 标题的 margin 由本组件说了算，不由浏览器默认值 */
+  color: var(--text-primary);
+  font-weight: 500;
+}
+
+.timeline__body {
+  margin: var(--sp-1) 0 0;
+  color: var(--text-secondary);
+  font-size: var(--fs-sm);
+}
+
+/* 紧凑档：时间与标题同一行，用于侧栏、卡片内嵌、弹层里的事记。 */
+.timeline--compact .timeline__item {
+  padding-block-end: var(--sp-2);
+}
+
+.timeline--compact .timeline__time {
+  display: inline;
+  margin-inline-end: var(--sp-2);
+}
+
+/* 强制色：圆点与连接线改用**系统色**。
+   作者色在这里会被统一替换掉 —— 若不显式给系统色，
+   整条时间轴会变成「一排悬空的文字」，而 DOM 顺序还在（信息没丢，
+   但读者看不出这是一个序列）。系统色关键字不会被替换。 */
+@media (forced-colors: active) {
+  .timeline__item::after {
+    background: CanvasText;   /* 主标记：最亮的系统前景色 */
+  }
+
+  .timeline__item:not(:last-child)::before {
+    background: GrayText;     /* 连接线是次要结构，用弱一档的系统色 */
+  }
+}