agentcss 0.16.1 → 0.24.1

package/01-tokens/focus-ring-demo.html

@@ -45,7 +45,7 @@ a { color: var(--accent); }
 .tip { font-size: var(--fs-xs); color: var(--text-tertiary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <div class="wrap">
 
   <h1>焦点环</h1>

package/01-tokens/page.css

@@ -197,6 +197,38 @@
   border-radius: var(--r-xs);
 }
 
+/* ============================================================================
+   4b. 代码块的兜底：任何 <pre> 自己横向滚，不许把页面撑宽
+   ----------------------------------------------------------------------------
+   🔴 为什么需要（0.24.1 实测，不是推演）
+     在 `.page` 环境里放一条 220 字符的长行：
+
+       裸 <pre>                    doc=2048 / vw=375   ❌ 撑破
+       <pre class="code">          doc=2211 / vw=375   ❌ 撑破   （没有 guide.css 时）
+       <div class="prose"><pre>    doc=2048 / vw=375   ❌ 撑破   （没有 content.css 时）
+
+     三种都是 `overflow-x: visible`、`white-space: pre`
+     ⇒ 长行直接顶到页面上，整页横向滚。
+
+     现有 84 个页面之所以没红，是因为每个 pre 恰好都另有来源：
+     `.prose > pre`（content.css）、`pre.code`（guide.css）。**但那是巧合，不是契约**
+     —— 使用者照 page.css 写一页文档、贴一段长代码，就会踩到。
+
+   🔴 为什么用 `:where(.page)` 而不是 `.page`
+     特异性压到 0,0,1（只算 `pre`）⇒ 任何带类的规则都能盖掉它：
+       `.prose > pre`  (0,1,1) 赢
+       `pre.code`      (0,1,1) 赢
+     这条的定位是**兜底**，不是"给所有 pre 定样式"。写成 `.page pre`（0,1,1）
+     会与上面两条**同权重**，胜负取决于加载顺序 —— 那就成了一个随时会翻的脸。
+
+   ⚠️ 只写 `overflow-x`，不写 padding / background / font：
+      那些是"代码块长什么样"，属于 content.css / guide.css 的决定。
+      这里只管"它不许撑破页面"。加了别的属性就会改动已有页面的观感。
+   ========================================================================= */
+:where(.page) pre {
+  overflow-x: auto;
+}
+
 /* ============================================================================
    5. 演示块 `.box`
    ----------------------------------------------------------------------------

package/01-tokens/responsive-demo.html

@@ -29,7 +29,7 @@ p { margin: 0 0 var(--sp-4); }
 .swatch { height: var(--sp-4); background: var(--accent); border-radius: 3px; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 
 <div id="meter">
   <span>视口 <b id="m-w">—</b></span>

package/01-tokens/scrollbar-demo.html

@@ -46,7 +46,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
                 border: 1px solid var(--border-control); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <div class="wrap">
 
   <h1>滚动条</h1>

package/02-primitives/badge/demo.html

@@ -15,7 +15,7 @@
          padding: var(--sp-4) 0; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>badge · 状态标记</h1>
   <p class="lede">

package/02-primitives/button/demo.html

@@ -24,7 +24,7 @@
 .btn--naive:disabled { opacity: 0.5; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>button · 七态矩阵</h1>

package/02-primitives/card/demo.html

@@ -26,7 +26,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
               var(--text-tertiary) 0 1px, transparent 1px 8px); opacity: .5; margin-bottom: var(--sp-2); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>card · hover 无布局跳动</h1>

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/choice/demo.html

@@ -30,7 +30,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
 .log { color: var(--text-tertiary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>checkbox / radio / select</h1>

package/02-primitives/combobox/demo.html

@@ -30,7 +30,7 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
 }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>combobox · 组合框 / 标签输入</h1>

package/02-primitives/date-range/demo.html

@@ -22,7 +22,7 @@
 .dr-bad-field .drange__input { border-color: var(--danger); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>date-range · 日期区间</h1>

package/02-primitives/delta/demo.html

@@ -30,7 +30,7 @@
                      color: var(--text-secondary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>delta · 变化量</h1>
   <p class="lede">

package/02-primitives/input/demo.html

@@ -29,7 +29,7 @@
 .bad-err { color: red; font-size: 13px; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>input · 五态矩阵</h1>

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/metric/demo.html

@@ -17,7 +17,7 @@
          padding: var(--sp-5); background: var(--surface); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>metric · 指标块</h1>
   <p class="lede">

package/02-primitives/popover/demo.html

@@ -44,7 +44,7 @@ th { font-weight: 600; }
 .pp-stage .popover__title { margin: 0; font-size: var(--fs-sm); font-weight: 500; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
      加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。

package/02-primitives/progress/demo.html

@@ -27,7 +27,7 @@
 .pr-note { margin: var(--sp-2) 0 0; font-size: var(--fs-xs); color: var(--text-secondary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
      加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。

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/select/demo.html

@@ -38,7 +38,7 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
 }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>select · 下拉选择</h1>

package/02-primitives/separator/demo.html

@@ -13,7 +13,7 @@
 .row { padding: var(--sp-2) 0; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>separator · 分隔线</h1>
   <p class="lede">

package/02-primitives/skeleton/demo.html

@@ -28,7 +28,7 @@
 .sk-box { display: flex; flex-direction: column; gap: var(--sp-2); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
      加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。

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/demo.html

@@ -16,7 +16,7 @@
            color: var(--text-secondary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>switch · 开关</h1>
   <p class="lede">

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` 就够。