agentcss 0.11.10 → 0.11.11

package/01-tokens/page.css

@@ -216,6 +216,77 @@
   background: var(--surface-sunken);
 }
 
+/* ============================================================================
+   6. 对错对照 `.cmp`（并排两栏：错写法 / 本库写法）
+   ----------------------------------------------------------------------------
+   为什么要收编（量过才写的，不是凭印象）：
+     3 个页面（button / card / input）各自写了一遍，**语义完全相同**，
+     但参数各是各的 —— `grid-template-columns` 都是 1.55fr 1fr（这一条一致，
+     说明它确实是个固定意图），而 gap 是 sp-4 还是 sp-5、断点是 640 还是 700，
+     三页三种。这不是"各页局部排布"，是同一个东西的无意分叉。
+     判据与 `.row` 的区别就在这里：
+       `.row`  15 页 14 种写法 —— **语义**都不一样（有的是工具条、有的是按钮排），不收；
+       `.cmp`   3 页 3 种写法 —— **语义**一样，差的只是手抖，收。
+     另外 21 个页面缺"能看见的反例"，补上之后若不收编，就是 24 份副本。
+
+   为什么列宽是 1fr 1fr（而不是原来那三页的 1.55fr 1fr）：
+     那三页的左栏是"一大段解释 + 示例"，右栏只是一句话，所以给左栏 1.55。
+     现在每一栏都是"一个小示例 + 一句理由"，两栏等宽才不会让人以为
+     某一栏更重要。真需要不等宽时用 `.cmp--wide-first`，别在页面里重写栅格。
+   ========================================================================= */
+.page .cmp {
+  display: grid;
+  /* ⚠️ 必须是 `minmax(0, 1fr)`，不能写 `1fr`：`1fr` 的下限是 `auto`（= 内容最小宽度），
+     一栏里只要有不换行的长串（`.ls-clip` 的 nowrap、`.ar-long` 的股票代码、宽表格），
+     两栏就一起被顶宽 ⇒ **整页**横向溢出。
+     实测代价：本库 4 个页面在 320px / 834px / RTL 阿拉伯语膨胀后溢出 81–155px，
+     `zoom-reflow` `rtl-render` `responsive` 三道门禁同时红。
+     ——这条正是 `04-recipes/analysis-report` 那一页在教别人的东西，
+       我写这个收编的时候照着旧三页抄了 `1fr`，把要讲的坑又踩了一遍。 */
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: var(--sp-4);
+  /* 不写 align-items: start —— 两栏等高（stretch）边框才对得齐；
+     start 会让短的那栏提前结束，看起来像"没写完"。 */
+}
+.page .cmp--wide-first {
+  grid-template-columns: minmax(0, 1.55fr) minmax(0, 1fr);
+}
+/* 断点 640 而不是 720：文档页里的活标本 iframe 实测只有 734px 宽
+   （guide/xxx.html 里那个框），720 的断点意味着"再窄一点就叠成单栏"——
+   而叠成单栏，"并排"这件事就不存在了。留出 90px 余量。 */
+@media (max-width: 640px) {
+  .page .cmp,
+  .page .cmp--wide-first,
+  .page .cmp--clip { grid-template-columns: minmax(0, 1fr); }
+}
+.page .cmp__pane {
+  padding: var(--sp-4);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-md);
+  background: var(--surface-sunken);
+  /* 栅格项默认 min-width:auto ⇒ 内容最小宽度照样能把栏顶开。 */
+  min-width: 0;
+}
+/* 内容本身就是"宽、且故意不收缩"的页（超长不换行串 / 宽表格）用这个修饰符。
+   ⚠️ 为什么不写进 `.cmp__pane` 全局：`popover` / `tooltip` / `dropdown` 的对照块里
+      气泡是绝对定位伸出栏外的，`overflow: hidden` 会把气泡直接裁掉 ——
+      那几页的演示就没了。裁的是"演示内容越出栏框"，不是"栏内的布局算错"：
+      栏内列的宽度仍按内容算，读者看到的还是被撑宽的那一栏。 */
+.page .cmp--clip .cmp__pane { overflow: hidden; }
+.page .cmp__pane > h3 {
+  margin: 0 0 var(--sp-3);
+  font-size: var(--fs-sm);
+  font-weight: 500;
+}
+.page .cmp__bad > h3 { color: var(--danger); }
+.page .cmp__good > h3 { color: var(--success); }
+.page .cmp__why {
+  margin: var(--sp-3) 0 0;
+  font-size: var(--fs-xs);
+  line-height: 1.6;
+  color: var(--text-secondary);
+}
+
 /* ============================================================================
    反模式（本文件自己的边界）
    ----------------------------------------------------------------------------

package/02-primitives/button/demo.html

@@ -16,16 +16,6 @@
 .cell p { margin: 0 0 var(--sp-4); font-size: var(--fs-xs);
              color: var(--text-tertiary); line-height: 1.55; }
 .row { display: flex; gap: var(--sp-3); flex-wrap: wrap; align-items: center; }
-.cmp { display: grid; gap: var(--sp-4); grid-template-columns: 1.55fr 1fr; }
-@media (max-width: 640px) {.cmp { grid-template-columns: 1fr; }
-
- }
-.cmp>div { padding: var(--sp-4); border-radius: var(--r-md); border: 1px solid var(--border-decor); }
-.bad { background: var(--surface-sunken); }
-.good { background: var(--surface-sunken); }
-.cmp h3 { margin: 0 0 var(--sp-3); font-size: var(--fs-sm); font-weight: 500; }
-.bad h3 { color: var(--danger); }
-.good h3 { color: var(--success); }
 /* 反例演示用 */
 .btn--naive { height: 44px; padding: 0 var(--sp-5); border: none; border-radius: var(--r-sm);
                 background: var(--accent); color: #fff; cursor: pointer; font-size: var(--fs-sm);
@@ -129,27 +119,27 @@
   </p>
 
   <h2 class="rule-bottom">对比：常见的错写法 vs 本库写法</h2>
-  <div class="cmp">
-    <div class="box bad">
+  <div class="cmp cmp--wide-first">
+    <div class="cmp__pane cmp__bad">
       <h3>常见写法（某项目 现状）</h3>
       <div class="row">
         <button class="btn--naive">hover 看我</button>
         <button class="btn--naive" disabled>disabled 看我</button>
       </div>
-      <p style="font-size:var(--fs-xs); margin:var(--sp-3) 0 0; color:var(--text-secondary)">
+      <p class="cmp__why">
         <code>filter: brightness(1.08)</code> —— hover 色是算出来的，无法验证对比度，不同底色表现不一致。<br>
         <code>transform: scale(1.05)</code> —— 按钮"长大"，廉价感。<br>
         <code>opacity: 0.5</code> —— 对比度变成随机数。<br>
         <code>transition: all</code> —— 所有属性一起动画，性能和观感失控。
       </p>
     </div>
-    <div class="good">
+    <div class="cmp__pane cmp__good">
       <h3>本库写法</h3>
       <div class="row">
         <button class="btn btn--md btn--primary">hover 看我</button>
         <button class="btn btn--md btn--primary" disabled>disabled 看我</button>
       </div>
-      <p style="font-size:var(--fs-xs); margin:var(--sp-3) 0 0; color:var(--text-secondary)">
+      <p class="cmp__why">
         明确的 <code>--accent-hover</code> 色值，实测 7.73 AAA。<br>
         active 只下沉 1px。<br>
         disabled 用明确的低对比色组，仍可读。<br>

package/02-primitives/card/demo.html

@@ -12,16 +12,6 @@
 <style>
 p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6; }
 .grid3 { display: grid; gap: var(--sp-4); grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
-.cmp { display: grid; gap: var(--sp-5); grid-template-columns: 1.55fr 1fr; }
-@media (max-width: 700px) {.cmp { grid-template-columns: 1fr; }
-
- }
-.cmp>div { padding: var(--sp-5); border-radius: var(--r-md); border: 1px solid var(--border-decor); }
-.bad { background: var(--surface-sunken); }
-.good { background: var(--surface-sunken); }
-.cmp h3 { margin: 0 0 var(--sp-2); font-size: var(--fs-sm); font-weight: 500; }
-.bad h3 { color: var(--danger); }
-.good h3 { color: var(--success); }
 .cmp .stack { display: flex; flex-direction: column; gap: var(--sp-3); }
 /* ---- 反例卡片：hover 时改 border-width，引起回流 ---- */
 .card-bad { position: relative; background: var(--surface);
@@ -52,8 +42,8 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
     下面<strong>故意放大到 4px</strong>，好让你一次看清楚。请分别把鼠标移到两张卡上。
   </div>
 
-  <div class="cmp">
-    <div class="box bad">
+  <div class="cmp cmp--wide-first">
+    <div class="cmp__pane cmp__bad">
       <h3>反例：hover 改 border-width</h3>
       <p class="small" style="margin:0 0 var(--sp-3)">
         移上来 —— 里面那把尺子和文字整体往下挪了，卡片也变高了。
@@ -71,7 +61,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
       </div>
     </div>
 
-    <div class="good">
+    <div class="cmp__pane cmp__good">
       <h3>本库：transform + box-shadow</h3>
       <p class="small" style="margin:0 0 var(--sp-3)">
         移上来 —— 卡片整体抬起 2px，<strong>里面的内容一个像素都不动</strong>，

package/02-primitives/choice/demo.html

@@ -188,6 +188,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
 
   <h2 class="rule-bottom">反例：用 display:none 隐藏原生控件</h2>
   <div class="box bad">
+    <h3>反例：把原生勾选框 <code>display:none</code> 藏掉</h3>
     <div class="choice choice--checkbox">
       <input class="choice__input" type="checkbox" style="display:none" id="bad1">
       <label class="choice__label" for="bad1">

package/02-primitives/combobox/demo.html

@@ -19,6 +19,15 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
     font-family: var(--mono); font-size: var(--fs-xs);
     color: var(--text-secondary); min-height: 2.8em;
   }
+/* 一次性演示用：把选项摆成静态列表（组件里它是浮层，这里要它躺着） */
+.cb-demo { display: grid; gap: var(--sp-1); }
+.cb-demo__q { font-size: var(--fs-sm); color: var(--text-tertiary); padding: 0 0 var(--sp-1); }
+.cb-demo__list {
+  list-style: none; margin: 0; padding: var(--sp-1);
+  background: var(--surface-raised);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-sm);
+}
 </style>
 </head>
 <body class="page page">
@@ -66,6 +75,35 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
   </div>
 </div>
 
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：结果不高亮</h3>
+        <div class="cb-demo" aria-hidden="true">
+          <div class="cb-demo__q">半导体</div>
+          <ul class="cb-demo__list">
+            <li class="combo__opt">设备</li>
+            <li class="combo__opt">材料</li>
+            <li class="combo__opt">封测</li>
+          </ul>
+        </div>
+      <p class="cmp__why">输入"半导体"之后三条都留下了，但三条长得一模一样 —— 用户说不出<b>凭什么</b>是这三条，只会觉得"顺序乱了"。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：命中片段高亮</h3>
+        <div class="cb-demo" aria-hidden="true">
+          <div class="cb-demo__q">半导体</div>
+          <ul class="cb-demo__list">
+            <li class="combo__opt"><mark>半导体</mark>设备</li>
+            <li class="combo__opt"><mark>半导体</mark>材料</li>
+            <li class="combo__opt"><mark>半导体</mark>封测</li>
+          </ul>
+        </div>
+      <p class="cmp__why">高亮用的是本库的 <code>combo__opt mark</code>：accent 色 + 下划线，<b>不用</b>浏览器默认的黄底 —— 黄底与文字的对比度不可控，深色主题下更糟。</p>
+    </div>
+  </div>
 </main>
 
 <script src="combobox.js"></script>

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

@@ -18,6 +18,8 @@
     font-family: var(--mono); font-size: var(--fs-xs);
     color: var(--text-secondary); min-height: 2.8em;
   }
+/* 反例专用：只改颜色 */
+.dr-bad-field .drange__input { border-color: var(--danger); }
 </style>
 </head>
 <body class="page page">
@@ -74,6 +76,40 @@
   <div class="log" id="log2">（试着填一个 2019 年或 2027 年 ⇒ 会报错）</div>
 </div>
 
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：错误只改边框颜色</h3>
+        <div class="drange" aria-hidden="true">
+          <div class="drange__field">
+            <label class="drange__label" for="dr-b1">开始</label>
+            <input id="dr-b1" class="drange__input" type="date" value="2026-01-10" readonly tabindex="-1">
+          </div>
+          <div class="drange__field dr-bad-field">
+            <label class="drange__label" for="dr-b2">结束</label>
+            <input id="dr-b2" class="drange__input" type="date" value="2026-01-03" readonly tabindex="-1">
+          </div>
+        </div>
+      <p class="cmp__why">结束日期早于开始日期，界面上只是"红了一圈"：色觉障碍用户看不出来，灰度打印也看不出来，而且<b>没有一句话</b>告诉你错在哪。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：左侧竖线 + 一句话说明</h3>
+        <div class="drange" aria-hidden="true">
+          <div class="drange__field">
+            <label class="drange__label" for="dr-g1">开始</label>
+            <input id="dr-g1" class="drange__input" type="date" value="2026-01-10" readonly tabindex="-1">
+          </div>
+          <div class="drange__field">
+            <label class="drange__label" for="dr-g2">结束</label>
+            <input id="dr-g2" class="drange__input" type="date" value="2026-01-03" readonly tabindex="-1">
+          </div>
+          <div class="drange__error">结束日期早于开始日期</div>
+        </div>
+      <p class="cmp__why">形状（左侧竖线）与文字一起承担信息，颜色只是辅助 —— 这是 WCAG 1.4.1 的要求。同时 JS 会给两个字段打 <code>aria-invalid</code> 并用 <code>aria-describedby</code> 指到这句话。</p>
+    </div>
+  </div>
 </main>
 
 <script src="date-range.js"></script>

package/02-primitives/input/demo.html

@@ -22,17 +22,6 @@
 .cell h3 { margin: 0 0 var(--sp-1); font-size: var(--fs-sm); font-weight: 500; }
 .cell p { margin: 0 0 var(--sp-3); font-size: var(--fs-xs);
             color: var(--text-tertiary); line-height: 1.55; }
-.cmp { display: grid; gap: var(--sp-4); grid-template-columns: 1.55fr 1fr; }
-@media (max-width: 620px) {.cmp { grid-template-columns: 1fr; }
-
- }
-.cmp>div { padding: var(--sp-4); border-radius: var(--r-md); border: 1px solid var(--border-decor); }
-.bad { background: var(--surface-sunken); }
-.good { background: var(--surface-sunken); }
-.cmp h3 { margin: 0 0 var(--sp-3); font-size: var(--fs-sm); font-weight: 500; }
-.bad h3 { color: var(--danger); }
-.good h3 { color: var(--success); }
-.cmp p { font-size: var(--fs-xs); margin: var(--sp-3) 0 0; line-height: 1.6; }
 /* 反例演示 */
 .bad-input { width: 100%; box-sizing: border-box; height: 44px; padding: 0 var(--sp-3);
                font-size: 14px; border: 1px solid #ccc; border-radius: var(--r-sm); }
@@ -118,8 +107,8 @@
   </div>
 
   <h2 class="rule-bottom">对比：常见写法 vs 本库写法</h2>
-  <div class="cmp">
-    <div class="box bad">
+  <div class="cmp cmp--wide-first">
+    <div class="cmp__pane cmp__bad">
       <h3>常见写法</h3>
       <input class="bad-input err" value="abc" aria-hidden="true" tabindex="-1">
       <!-- 🔴 加 aria-hidden。
@@ -129,21 +118,21 @@
            反例对人要可见（不能 display:none），
            但对辅助技术应当隐藏 —— aria-hidden 正合适。 -->
       <p class="bad-err" aria-hidden="true">格式错误</p>
-      <p>
+      <p class="cmp__why">
         <code>placeholder 当 label</code> —— 一输入就消失<br>
         <code>只把边框变红</code> —— WCAG 1.4.1 禁止只靠颜色传达信息<br>
         <code>font-size: 14px</code> —— iOS Safari 会自动放大整个页面<br>
         错误文字没有 <code>aria-describedby</code> —— 屏幕阅读器读不到
       </p>
     </div>
-    <div class="good">
+    <div class="cmp__pane cmp__good">
       <h3>本库写法</h3>
       <div class="field">
         <label class="field__label" for="g1">金额</label>
         <input class="field__input" id="g1" value="abc" aria-invalid="true" aria-describedby="g1-err" inputmode="decimal" name="amount-g1" autocomplete="off"/>
         <span class="field__error" id="g1-err" role="alert">请输入有效金额</span>
       </div>
-      <p>
+      <p class="cmp__why">
         有可见 label，不会消失<br>
         红边框 + 图标 + 文字，三条线索<br>
         <code>font-size: 16px</code> —— iOS 不缩放<br>

package/02-primitives/popover/README.md

@@ -88,4 +88,19 @@ Popover.current;      // 当前开着的实例（没有则null）
 - ❌ **同时开两个 popover** —— 两个叠着，用户不知道该关哪个，也不知道点空白处关的是哪一个
 - ❌ **把箭头塞进带 `overflow: hidden` 的容器** —— 箭头会被裁掉；所以本组件不用 overflow 方式隐藏
 
+## 已知局限：不做落点检测
+
+浮层靠 CSS 定位（`--bottom` / `--top` / `--start` / `--end` 四个方向类），
+**不测量、不在运行时判断空间够不够**。这是刻意的取舍：
+
+- 好处：没有布局抖动、没有"打开瞬间先闪一下再翻位"、不依赖 `getBoundingClientRect`
+- 代价：锚点右边真的没有空间时，`--end` / `--bottom` 仍会朝那个方向弹出去
+
+所以**调用方要给浮层留位置**：靠边的按钮用 `--start` 而不是 `--end`；
+演示页里那一栏就是给气泡留了 `max-width` 的口子，而不是让气泡自己算。
+
+- ❌ **指望组件"自动翻边"** —— 它不会。库里没有落点检测，也不会加：
+  一旦按测量定位，滚动、旋转屏幕、软键盘弹起都要重新算，代价比收益大
+
+
 ---

package/02-primitives/popover/demo.html

@@ -31,6 +31,17 @@
 table { width: 100%; border-collapse: collapse; font-size: var(--fs-sm); }
 td, th { text-align: left; padding: var(--sp-2); border-bottom: 1px solid var(--border-decor); }
 th { font-weight: 600; }
+/* 一次性演示用：给浮层一个定位舞台（组件里它挂在触发元素的锚点上） */
+.pp-stage { position: relative; min-height: 210px; --popover-min-w: 0; }
+/* 气泡不设最小宽度：320px 下栏内宽只有约 256px，`min-width:200px` + 起点 120px
+   会直接顶出视口（实测溢出 33px）。宽度改由 max-width 向栏内收。 */
+/* 🔴 反例块里的气泡是"静态摆拍"，**不接行为**，所以用 data-demo-open，
+   不能用 data-open：`data-open[='true']` 是组件真实的"开着"状态，
+   `Popover.closeAll()` 和契约门禁都按它判断 —— 演示块一旦写了它，
+   门禁里「Esc 关闭后必须没有开着的浮层」就永远为假（实测两个条目连红）。 */
+.pp-stage .popover[data-demo-open] { opacity: 1; visibility: visible; }
+.pp-stage .popover__desc { margin: var(--sp-1) 0 0; font-size: var(--fs-xs); color: var(--text-secondary); }
+.pp-stage .popover__title { margin: 0; font-size: var(--fs-sm); font-weight: 500; }
 </style>
 </head>
 <body class="page page">
@@ -145,6 +156,40 @@ demo('bad1', 'bottom',
   '<button class="btn btn--sm btn--danger">删除</button>' +
   '</div>', '反面示例');
 </script>
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：两个浮层同时开着</h3>
+        <div class="pp-stage" aria-hidden="true">
+          <button class="btn btn--sm btn--ghost" type="button" tabindex="-1">筛选</button>
+          <div class="popover popover--bottom" data-demo-open="true"
+               style="top:36px; inset-inline-start:8px; max-width:calc(100% - 16px); transform:none">
+            <p class="popover__title">筛选条件</p>
+            <p class="popover__desc">按板块过滤，可多选。</p>
+          </div>
+          <div class="popover popover--bottom" data-demo-open="true"
+               style="top:84px; inset-inline-start:38%; max-width:52%; transform:none">
+            <p class="popover__title">排序方式</p>
+            <p class="popover__desc">按涨跌幅。</p>
+          </div>
+        </div>
+      <p class="cmp__why">两个都开着：点空白处到底关的是哪一个？读屏用户按 Esc 也不知道关掉的是哪个，而两个浮层的内容还叠在一起。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：同一时刻只开一个</h3>
+        <div class="pp-stage" aria-hidden="true">
+          <button class="btn btn--sm btn--ghost" type="button" tabindex="-1">筛选</button>
+          <div class="popover popover--bottom" data-demo-open="true"
+               style="top:36px; inset-inline-start:8px; max-width:calc(100% - 16px); transform:none">
+            <p class="popover__title">筛选条件</p>
+            <p class="popover__desc">按板块过滤，可多选。</p>
+          </div>
+        </div>
+      <p class="cmp__why"><code>popover.js</code> 的 <code>open()</code> 会先关掉当前打开的那个 —— 不是"约定"，是写死在实现里的。</p>
+    </div>
+  </div>
 </main>
 </body>
 </html>

package/02-primitives/progress/demo.html

@@ -23,6 +23,8 @@
          font-variant-numeric: tabular-nums; min-width: 3.2em; text-align: right; }
 .bad-demo { background: var(--danger-bg); border-color: var(--danger); }
 .bad { color: var(--danger); }
+.pr-label { margin: 0 0 var(--sp-2); font-size: var(--fs-sm); }
+.pr-note { margin: var(--sp-2) 0 0; font-size: var(--fs-xs); color: var(--text-secondary); }
 </style>
 </head>
 <body class="page page">
@@ -149,6 +151,29 @@ document.querySelectorAll('.progress, .progress-ring, .progress-steps').forEach(
   }
 });
 </script>
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：到 100% 就变绿</h3>
+        <p class="pr-label">导出 6 个文件 · 100%</p>
+        <span class="progress progress--success" role="progressbar" aria-valuenow="100"
+              aria-valuemin="0" aria-valuemax="100" aria-label="导出进度"
+              style="--progress:100%"><span class="progress__bar"></span></span>
+        <p class="pr-note">界面写"导出完成"，条是绿的。</p>
+      <p class="cmp__why">100% 说的是"走到头了"，不是"成功了"。这一批实际有 2 个文件失败，绿条仍然亮着 —— 用户以为可以走了。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：颜色讲结果，数值只讲进度</h3>
+        <p class="pr-label">导出 6 个文件 · 100%</p>
+        <span class="progress progress--danger" role="progressbar" aria-valuenow="100"
+              aria-valuemin="0" aria-valuemax="100" aria-label="导出失败"
+              style="--progress:100%"><span class="progress__bar"></span></span>
+        <p class="pr-note">同样 100%，红了：2 个文件失败。</p>
+      <p class="cmp__why"><code>progress--success</code> / <code>--danger</code> 由调用方按<b>业务结果</b>给，不按数值自动切换 —— 颜色是语义，不是刻度。</p>
+    </div>
+  </div>
 </main>
 </body>
 </html>

package/02-primitives/select/demo.html

@@ -19,6 +19,23 @@
     color: var(--text-secondary); min-height: 3em;
   }
 label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
+/* 一次性演示用：把选项摆成静态列表 */
+.sl-wrap { display: grid; gap: var(--sp-1); }
+.sl-head { font-size: var(--fs-sm); color: var(--text-tertiary); padding: 0 0 var(--sp-1); }
+.sl-list {
+  list-style: none; margin: 0; padding: var(--sp-1);
+  background: var(--surface-raised);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-sm);
+}
+/* 反例专用：把命中区压到 28px */
+.sl-tight {
+  display: flex; align-items: center;
+  min-height: 28px; padding: 0 var(--sp-2);
+  border-radius: var(--r-xs);
+  font-size: var(--fs-sm);
+  cursor: pointer;
+}
 </style>
 </head>
 <body class="page page">
@@ -94,6 +111,35 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
   </div>
 </div>
 
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：选项挤在一起</h3>
+        <div class="sl-wrap" aria-hidden="true">
+          <div class="sl-head">所属板块</div>
+          <ul class="sl-list">
+            <li class="sl-tight">半导体设备</li>
+            <li class="sl-tight">半导体材料</li>
+            <li class="sl-tight">半导体封测</li>
+          </ul>
+        </div>
+      <p class="cmp__why">行高只有 28px：手指点下去必然压到隔壁那一行。鼠标用户感觉不到，触屏用户每点错一次就要重来。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：每项 44px 命中区</h3>
+        <div class="sl-wrap" aria-hidden="true">
+          <div class="sl-head">所属板块</div>
+          <ul class="sl-list">
+            <li class="select__opt">半导体设备</li>
+            <li class="select__opt">半导体材料</li>
+            <li class="select__opt">半导体封测</li>
+          </ul>
+        </div>
+      <p class="cmp__why">命中区 44px 是 AAA 的下限（<code>select.css</code> 里写着这条），与 <code>dropdown</code> 同规格 —— 两个控件的选项高度不该不一样。</p>
+    </div>
+  </div>
 </main>
 
 <script src="select.js"></script>

package/02-primitives/skeleton/demo.html

@@ -9,6 +9,7 @@
 <link rel="stylesheet" href="../../01-tokens/typography.css">
 <link rel="stylesheet" href="../../01-tokens/page.css">
 <link rel="stylesheet" href="../button/button.css">
+<link rel="stylesheet" href="../progress/progress.css">
 <link rel="stylesheet" href="skeleton.css">
 <style>
 .demo {
@@ -22,6 +23,9 @@
 /* 反例演示：故意用深色底+白字，说明"骨架屏不该这样用" */
 .bad-demo { background: var(--danger-bg); border-color: var(--danger); }
 .bad { color: var(--danger); }
+.sk-label { margin: 0 0 var(--sp-2); font-size: var(--fs-sm); }
+.sk-pct { margin: 0 0 var(--sp-2); font-size: var(--fs-xs); color: var(--text-secondary); }
+.sk-box { display: flex; flex-direction: column; gap: var(--sp-2); }
 </style>
 </head>
 <body class="page page">
@@ -105,6 +109,30 @@
   </p>
 </div>
 
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：有确切进度却用骨架屏</h3>
+        <p class="sk-label">上传 素材包.zip（3.1 MB）</p>
+        <div class="sk-box" aria-hidden="true">
+          <span class="skeleton skeleton--text" style="width:82%"></span>
+          <span class="skeleton skeleton--text" style="width:61%"></span>
+          <span class="skeleton skeleton--text" style="width:44%"></span>
+        </div>
+      <p class="cmp__why">文件大小是已知的、进度是算得出来的，却只给一片灰条：用户等了 40 秒也不知道还差 3 秒还是 3 分钟。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：确定进度用 progress，不确定才用 skeleton</h3>
+        <p class="sk-label">上传 素材包.zip（3.1 MB）</p>
+        <p class="sk-pct">已传 1.9 MB / 3.1 MB</p>
+        <span class="progress" role="progressbar" aria-valuenow="61"
+              aria-valuemin="0" aria-valuemax="100" aria-label="上传进度"
+              style="--progress:61%"><span class="progress__bar"></span></span>
+      <p class="cmp__why"><code>skeleton</code> 的语义是"<b>不知道</b>要多久"。知道比例就用 <code>progress</code> —— 两者的区别不是好看，是诚实。</p>
+    </div>
+  </div>
 </main>
 </body>
 </html>

package/03-patterns/content/demo.html

@@ -17,6 +17,7 @@
     border-radius: var(--r-sm);
     font-size: var(--fs-sm); color: var(--text-secondary);
   }
+.ct-p { margin: 0; font-size: var(--fs-sm); }
 </style>
 </head>
 <body class="page page">
@@ -82,6 +83,25 @@
   <p>详细口径见 <a href="#main">内部数据字典</a>。</p>
 </div>
 
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：裸 <code>&lt;hr&gt;</code></h3>
+        <div aria-hidden="true">        <p class="ct-p">本季应收账款周转天数下降 6 天。</p>
+        <hr>
+        <p class="ct-p">下一节：存货跌价准备的计提口径。</p></div>
+      <p class="cmp__why">默认 <code>&lt;hr&gt;</code> 自带上下两条 inset 边框，不清 <code>height</code> 和 <code>border-top</code> 出来就是一条粗双线 —— 而且不同浏览器的厚度还不一样。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：<code>.prose &gt; hr</code></h3>
+        <div class="prose" aria-hidden="true">        <p class="ct-p">本季应收账款周转天数下降 6 天。</p>
+        <hr>
+        <p class="ct-p">下一节：存货跌价准备的计提口径。</p></div>
+      <p class="cmp__why"><code>content.css</code> 把 <code>height</code> 归零、只留一条上边 —— 渲染器（markdown-it）产出的裸 <code>&lt;hr&gt;</code> 直接就是对的。</p>
+    </div>
+  </div>
 </main>
 
 </body>

package/03-patterns/drawer/demo.html

@@ -21,6 +21,21 @@
   }
 ul.demo-list { padding-left: var(--sp-5); color: var(--text-secondary); }
 ul.demo-list li { margin: var(--sp-1) 0; }
+.dr-bar {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: var(--sp-3);
+  padding: var(--sp-2) var(--sp-3);
+  background: var(--surface-raised);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-sm);
+}
+.dr-bar__title { font-size: var(--fs-sm); font-weight: 500; }
+.dr-tiny {
+  width: 24px; height: 24px;
+  display: flex; align-items: center; justify-content: center;
+  background: none; border: 0; border-radius: var(--r-xs);
+  color: var(--text-secondary); font-size: 14px; line-height: 1; cursor: pointer;
+}
 </style>
 </head>
 <body class="page page">
@@ -49,6 +64,27 @@ ul.demo-list li { margin: var(--sp-1) 0; }
   <button class="btn btn--primary" id="b2">打开（焦点落在第二个按钮）</button>
 </div>
 
+
+
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：关闭按钮做小</h3>
+        <div class="dr-bar" aria-hidden="true">
+          <span class="dr-bar__title">筛选</span>
+          <button class="dr-tiny" type="button" tabindex="-1" aria-label="关闭">×</button>
+        </div>
+      <p class="cmp__why">关闭是**独立目标**：抽屉滑进来之后，用户第一件事就是找它。24px 的叉在触屏上要瞄准，点偏了就点到了背后的内容。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：<code>drawer__close</code> 44px</h3>
+        <div class="dr-bar" aria-hidden="true">
+          <span class="dr-bar__title">筛选</span>
+          <button class="drawer__close" type="button" tabindex="-1" aria-label="关闭">×</button>
+        </div>
+      <p class="cmp__why">命中区 44px（<code>drawer.css</code> 里写明"关闭按钮是独立目标，用 44"）—— 字形还是 20px，只是可点范围大了。</p>
+    </div>
+  </div>
 </main>
 
 <script src="drawer.js"></script>