npm - agentcss - Versions diffs - 0.11.9 → 0.11.11 - Mend

agentcss 0.11.9 → 0.11.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

package/01-tokens/page.css +71 -0
package/02-primitives/badge/README.md +14 -0
package/02-primitives/button/demo.html +5 -15
package/02-primitives/card/README.md +1 -1
package/02-primitives/card/demo.html +3 -13
package/02-primitives/choice/demo.html +1 -0
package/02-primitives/combobox/README.md +15 -0
package/02-primitives/combobox/demo.html +38 -0
package/02-primitives/date-range/README.md +11 -0
package/02-primitives/date-range/demo.html +36 -0
package/02-primitives/input/demo.html +5 -16
package/02-primitives/popover/README.md +27 -1
package/02-primitives/popover/demo.html +45 -0
package/02-primitives/progress/README.md +4 -0
package/02-primitives/progress/demo.html +25 -0
package/02-primitives/select/README.md +12 -0
package/02-primitives/select/demo.html +46 -0
package/02-primitives/separator/README.md +3 -1
package/02-primitives/skeleton/demo.html +28 -0
package/02-primitives/switch/README.md +14 -0
package/03-patterns/accordion/README.md +17 -0
package/03-patterns/content/demo.html +20 -0
package/03-patterns/drawer/README.md +12 -0
package/03-patterns/drawer/demo.html +36 -0
package/03-patterns/dropdown/README.md +15 -0
package/03-patterns/dropdown/demo.html +39 -0
package/03-patterns/list/demo.html +48 -0
package/03-patterns/nav/demo.html +34 -1
package/03-patterns/overlay/README.md +3 -3
package/03-patterns/pagination/README.md +14 -0
package/03-patterns/pagination/demo.html +40 -0
package/03-patterns/reveal/README.md +15 -0
package/03-patterns/reveal/demo.html +24 -0
package/03-patterns/states/README.md +1 -1
package/03-patterns/states/demo.html +25 -1
package/03-patterns/tabs/README.md +15 -0
package/03-patterns/tooltip/README.md +13 -0
package/03-patterns/tooltip/demo.html +27 -0
package/03-patterns/tree/README.md +16 -0
package/03-patterns/tree/demo.html +43 -0
package/04-recipes/analysis-report/README.md +16 -0
package/04-recipes/analysis-report/demo.html +34 -0
package/04-recipes/data-showcase/README.md +12 -0
package/04-recipes/data-showcase/demo.html +29 -0
package/04-recipes/detail-page/README.md +13 -0
package/04-recipes/detail-page/demo.html +28 -0
package/04-recipes/report/README.md +13 -0
package/04-recipes/report/demo.html +24 -0
package/04-recipes/table/README.md +38 -0
package/04-recipes/table/demo.html +39 -0
package/CHANGELOG.md +90 -0
package/CONTRIBUTING.md +8 -1
package/ai/components.json +38 -10
package/dist/01-tokens/page.css +1 -1
package/dist/COSTS.md +1 -1
package/index.html +1 -1
package/package.json +1 -1

package/02-primitives/separator/README.md CHANGED Viewed

@@ -47,7 +47,7 @@
 **这就是"不要一档打天下"的实测依据。**
-## 两个反例
+## 反例
 **① 语义分隔用装饰色** —— 分隔"基本信息"与"高级设置"是两类不同的东西，
 但 1.26:1 的线在低视力与暗色下几乎看不见，而读屏只念"分隔符"、
@@ -57,6 +57,8 @@
 **什么都没有**。语义分隔必须用 `<hr>` 或 `role="separator"`，
 装饰性的才可以用纯 div。
+- ❌ **自己用 `box-shadow` 画分隔线** —— 1px 的线在部分浏览器上会取整成 2px；本库用 border 就是为了这个（`separator.css` 里写了原因）
 ## 细节
 用 `border` 而不是 `box-shadow` 画线 —— 1px 的线用 box-shadow

package/02-primitives/skeleton/demo.html CHANGED Viewed

@@ -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/02-primitives/switch/README.md CHANGED Viewed

@@ -63,3 +63,17 @@ Space 键、焦点样式、状态播报 —— **三件事漏一件就坏**，
 - 滑块位移随状态变化 · axe 0 违规 / 24 条通过
 判别力验证：去掉 `role` 与 `label` ⇒ 4 项立即被抓。
+## 反例
+- ❌ **让 Enter 也能切换** —— APG 的 Switch 只认 Space。Enter 会**双重切换**：
+  读屏自己会发一次，你的处理器再切一次，用户看到的是"按了没反应"
+- ❌ **用 `aria-label` 代替 `<label for>`** —— 视觉标签点了没反应，用户以为坏了。
+  标签不可见时用 `switch__label--sr`：看得见可以没有，听得到必须有
+- ❌ **把 switch 当 checkbox 用** —— switch 的语义是"**立刻生效**"，checkbox 是"随表单一起提交"。
+  用开关做"我已阅读条款"，用户勾完就以为已经生效了
+- ❌ **给开关加 `error` 或 `readonly`** —— 开关没有中间态可校验；readonly 对开关等于 disabled（用户改不了），
+  留着它只会让复用者以为"这个能校验"
+- ❌ **只把小滑块做成可点区域** —— `switch__input` 要铺满整块；只点滑块，触屏上漏点率很高
+---

package/03-patterns/accordion/README.md CHANGED Viewed

@@ -119,3 +119,20 @@ APG 警告：
 - axe 0 违规 / 29 条通过
 判别力验证：注入 keydown 双触发 ⇒ **2 项立即被抓**。
+## 反例
+- ❌ **给折叠标题加方向键 / Home / End** —— APG 的 Accordion 只要求 Tab + Enter/Space。
+  加了会和页面滚动抢方向键；本组件**刻意不监听 `keydown`**，这是设计不是遗漏
+- ❌ **用 `max-height` 做展开动画** —— 你必须猜内容有多高：猜小了裁字，猜大了结尾拖一段空白。
+  本库用 `grid-template-rows` 从 `0fr` 到 `1fr`，不需要知道高度
+- ❌ **收起时直接 `display: none`** —— 关闭前必须**先量到高度再收**，否则量到 0，
+  动画"啪"一下消失（`accordion.js` 里那条注释说的就是这个）
+- ❌ **给 `accordion__panel` 加 `overflow: hidden`** —— 会裁掉里面控件的焦点环；
+  收的过程交给 grid 的 `0fr` 完成
+- ❌ **每一项都套 `role="region"`** —— APG 有 ≤6 的地标上限，超过就是"地标泛滥"，
+  读屏的地标列表反而失去导航价值
+- ❌ **把 `--acc-h` 挪进全局令牌表** —— 它只对本组件有意义（`accordion.css` 里写了为什么不进 `tokens.css`），
+  进全局表会让所有人以为那是个通用尺寸
+---

package/03-patterns/content/demo.html CHANGED Viewed

@@ -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/README.md CHANGED Viewed

@@ -74,6 +74,18 @@ Drawer.open({ place: 'right' });   // 默认就是 right
 |---|---|
 | `dismissable:manual` | 点遮罩关闭是手写的，不是统一机制 |
+## 反例
+- ❌ **打开抽屉时不给背景加 `inert` / `aria-hidden`** —— 抽屉是**模态**：读屏会把抽屉与背景
+  一起念出来（"双重朗读"），用户听到两套内容叠在一起
+- ❌ **省掉焦点陷阱** —— Tab 会跑到抽屉外面，键盘用户在看不见的内容上操作，还以为抽屉坏了
+- ❌ **`drawer__close` 做得很小** —— 它是独立目标，要 44px。抽屉滑进来之后，用户第一件事就是找关闭
+- ❌ **在插入 DOM 之后才记录 `document.activeElement`** —— 记到的是新节点，
+  关闭时焦点"归还"到一个已经不存在的位置，等于没还
+- ❌ **嵌套抽屉不用锁计数** —— 内层关掉时会把外层的滚动锁一起解开，外层还在，背景却能滚了
+---
 ## 门禁
 `05-audit/drawer-check.js`

package/03-patterns/drawer/demo.html CHANGED Viewed

@@ -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>

package/03-patterns/dropdown/README.md CHANGED Viewed

@@ -73,6 +73,21 @@ menu.setAttribute('role', 'menu');
 | `focus-return:manual` | 关闭后归位是手写的，不是统一机制 |
 | `typeahead:gap` | **没有类型搜索** —— APG 的 Menu Button 不硬性要求，但列表长时体验缺失 |
+## 反例
+- ❌ **菜单里一部分项 `aria-hidden`、一部分不设** —— APG 要求**全设或全不设**。
+  半吊子会让读屏报"1 项中的 0 项"这种不可理解的计数
+- ❌ **禁用项不给 `tabindex="-1"`** —— Tab 会停在点不动的项上，用户以为菜单坏了
+- ❌ **Esc 关闭后焦点不还给 `dd__btn`** —— 焦点掉到 `<body>`，键盘用户要从页面开头重新 Tab（APG 明确要求归还）
+- ❌ **给某个 `dd__item` 设 `tabindex="0"`** —— `role="menu"` 靠方向键步进，多一个 0
+  就多出一个 Tab 停靠点，整个菜单的导航模型就混了
+- ❌ **先写 `aria-controls` 再确保 `dd__menu` 有 id** —— 顺序反了会引用空字符串，
+  读屏拿不到"这个按钮控制哪个菜单"（`dropdown.js` 里为此调过顺序）
+- ❌ **用 `opacity: 0` 或 `visibility` 隐藏 `dd__menu`** —— 关闭态要用 `hidden`：
+  它同时移出无障碍树并不可聚焦，另两种做法都还留着 Tab 停靠点
+---
 ## 门禁
 `05-audit/dropdown-check.js`

package/03-patterns/dropdown/demo.html CHANGED Viewed

@@ -19,6 +19,20 @@
     font-family: var(--font-mono, monospace); font-size: var(--fs-xs);
     color: var(--text-secondary); min-height: 2.6em;
   }
+.dd-cap { margin: 0 0 var(--sp-2); font-size: var(--fs-sm); color: var(--text-tertiary); }
+.dd-demo {
+  list-style: none; margin: 0; padding: var(--sp-1);
+  background: var(--surface-raised);
+  border: 1px solid var(--border-decor);
+  border-radius: var(--r-sm);
+}
+/* 反例专用：24px 一行（本库把它量出来过，见 dropdown.css 的复盘） */
+.dd-bug {
+  display: flex; align-items: center;
+  height: 24px; padding: 0 var(--sp-3);
+  border-radius: var(--r-xs);
+  font-size: var(--fs-sm); cursor: pointer;
+}
 </style>
 </head>
 <body class="page page">
@@ -73,6 +87,31 @@
   </div>
 </div>
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：菜单项只有 24px</h3>
+        <p class="dd-cap">下拉菜单 · 每项高度</p>
+        <ul class="dd-demo" aria-hidden="true">
+          <li class="dd-bug">按涨跌幅</li>
+          <li class="dd-bug">按市值</li>
+          <li class="dd-bug">按成交额</li>
+        </ul>
+      <p class="cmp__why">24px 一行：手指点下去会压到隔壁，触屏用户每点错一次就得重来。本库在这块踩过更隐蔽的坑 —— 写 <code>min-height: 44px</code>，量出来只有 24px（<code>&lt;li&gt;</code> 是 <code>display:list-item</code>），所以现在用的是显式 <code>height</code>。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：显式 <code>height: 44px</code></h3>
+        <p class="dd-cap">下拉菜单 · 每项高度</p>
+        <ul class="dd-demo" aria-hidden="true">
+          <li class="dd__item">按涨跌幅</li>
+          <li class="dd__item">按市值</li>
+          <li class="dd__item">按成交额</li>
+        </ul>
+      <p class="cmp__why">同一个 44，<code>min-height</code> 与 <code>height</code> 在列表项上是两回事。桌面小屏看不出来，只有量了才发现 —— 所以这里把两种结果并排摆出来。</p>
+    </div>
+  </div>
 </main>
 <script src="dropdown.js"></script>

package/03-patterns/list/demo.html CHANGED Viewed

@@ -17,6 +17,9 @@
 p { max-width: var(--measure-prose); margin: 0 0 var(--sp-3); }
 p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.65; }
 .bar { display: flex; gap: var(--sp-2); flex-wrap: wrap; margin-bottom: var(--sp-4); }
+.ls-demo { list-style: none; margin: 0; padding: 0; background: var(--surface-raised);
+           border: 1px solid var(--border-decor); border-radius: var(--r-sm); }
+.ls-clip { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 </style>
 </head>
 <body class="page page">
@@ -85,6 +88,51 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
     这一点与欧美惯例相反，是刻意的——做反了会被当成数据出错。
   </p>
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：长文本直接换行</h3>
+        <ul class="ls-demo" aria-hidden="true">
+          <li class="list__item">
+            <span class="list__main">
+              <span class="list__title">长鑫存储技术有限公司（合肥）2026 年三季报</span>
+              <span class="list__meta">12 条记录 · 半导体</span>
+            </span>
+            <span class="list__value num list__value--up">+3.21%</span>
+          </li>
+          <li class="list__item">
+            <span class="list__main">
+              <span class="list__title">中芯国际集成电路制造</span>
+              <span class="list__meta">8 条记录 · 半导体</span>
+            </span>
+            <span class="list__value num list__value--down">−1.05%</span>
+          </li>
+        </ul>
+      <p class="cmp__why">第一行折成两行，行高就不一样了：一屏能扫到的条目从 8 条掉到 5 条，而且"哪一行对应哪个数字"要重新对。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：单行省略 + <code>title</code></h3>
+        <ul class="ls-demo" aria-hidden="true">
+          <li class="list__item">
+            <span class="list__main">
+              <span class="list__title ls-clip">长鑫存储技术有限公司（合肥）2026 年三季报</span>
+              <span class="list__meta">12 条记录 · 半导体</span>
+            </span>
+            <span class="list__value num list__value--up">+3.21%</span>
+          </li>
+          <li class="list__item">
+            <span class="list__main">
+              <span class="list__title ls-clip">中芯国际集成电路制造</span>
+              <span class="list__meta">8 条记录 · 半导体</span>
+            </span>
+            <span class="list__value num list__value--down">−1.05%</span>
+          </li>
+        </ul>
+      <p class="cmp__why">列表是"扫"的不是"读"的：标题单行截断，完整名称放 <code>title</code>，悬停可看。行高一致，眼睛才能顺着往下扫。</p>
+    </div>
+  </div>
 </main>
 <script src="flip.js"></script>

package/03-patterns/nav/demo.html CHANGED Viewed

@@ -31,6 +31,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.7
 .spacer { height: 55vh; }
           /* 让目录高亮有滚动空间 */
+.toc-clip { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 </style>
 </head>
 <body class="page page">
@@ -112,7 +113,39 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.7
       早期版本用的是它 + <code>rootMargin</code>，结果滚到两节之间时观察区里
       一个 section 都没有，高亮卡住不动 —— 现在改成纯计算，任何滚动位置都有答案。
     </p>
-  </main>
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <!-- 目录项一律指向本页真实小节（`#mem` / `#sched` / `#sim`）：假锚点
+       （`href="#x"`）点下去会跳到页面顶部，读者以为"目录坏了"。
+       第一条故意写得长 —— 真实文档的长章节名就是这样，能不能单行是这条的判据。 -->
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：目录项允许换行</h3>
+        <nav class="toc" aria-label="示例目录" aria-hidden="true">
+          <p class="toc__title">本页</p>
+          <ul class="toc__list">
+            <li><a class="toc__link" href="#mem" tabindex="-1">存储器构成与 2026 年三季度的产能爬坡节奏</a></li>
+            <li><a class="toc__link" href="#sched" tabindex="-1">优先级与准入</a></li>
+            <li><a class="toc__link" href="#sim" tabindex="-1">把它跑起来</a></li>
+          </ul>
+        </nav>
+      <p class="cmp__why">一条目录折成两行，下面两条就都被推下去了 —— 目录的价值是"一眼看到全文结构"，行高一变，结构感就没了。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：单行、超出省略</h3>
+        <nav class="toc" aria-label="示例目录">
+          <p class="toc__title">本页</p>
+          <ul class="toc__list">
+            <li><a class="toc__link toc-clip" href="#mem">存储器构成与 2026 年三季度的产能爬坡节奏</a></li>
+            <li><a class="toc__link" href="#sched">优先级与准入</a></li>
+            <li><a class="toc__link" href="#sim">把它跑起来</a></li>
+          </ul>
+        </nav>
+      <p class="cmp__why">目录项单行、超出省略：宁可截断，也要保住"三条等高"的节奏。读者扫的是结构，不是一个条目的全名。</p>
+    </div>
+  </div>
+</main>
 </div>

package/03-patterns/overlay/README.md CHANGED Viewed

@@ -184,13 +184,13 @@ grep -n '=>\|\bconst\b\|\blet\b' 03-patterns/overlay/overlay.js   # 应无输出
 ## 反例
 - ❌ **toast 抢焦点** —— 通知不该打断当前操作
-- ❌ **用 toast 做需要确认的操作** —— 见上
-- ❌ **dialog 不困住焦点** —— 混乱
+- ❌ **用 toast 做需要确认的操作** —— toast 里没有按钮、也拿不到焦点：用户要么没看见，要么看见了却点不到
+- ❌ **dialog 不困住焦点** —— Tab 会跑到背后的页面上，读屏用户一路读下去，读到的是 dialog 外面的内容
 - ❌ **dialog 关闭后焦点不回去** —— 键盘用户要重新 Tab
 - ❌ **锁滚动不补偿滚动条宽度** —— 页面"闪"一下
 - ❌ **错误 toast 3 秒消失** —— 还没读完就走了
 - ❌ **危险操作初始焦点在"删除"上** —— 条件反射误触
 - ❌ **危险操作点遮罩即关闭** —— 手滑就完了
-- ❌ **dialog 大幅缩放/回弹** —— 廉价感
+- ❌ **dialog 大幅缩放/回弹** —— 大面积位移让前庭敏感的用户不适，而且把注意力从内容移到了动画上
 - ❌ **backdrop 加 `backdrop-filter: blur`** —— 旧 WebView 掉帧
 - ❌ **用自定义 div 替代 `<dialog>` 且不需要自定义动画** —— 原生的 focus trap 更可靠

package/03-patterns/pagination/README.md CHANGED Viewed

@@ -109,6 +109,20 @@ if (q > 0) this.page = Math.min(q, this.pages);
 `ai/components.json` 里 `pagination` 的 `behaviorDebt` 为空。
+## 反例
+- ❌ **把 `role="navigation"` 直接放在 `pagination__list` 上** —— 会**覆盖 `ul` 的列表语义**，
+  读屏不再报告"共 N 项"。要包在 `<nav aria-label>` 里
+- ❌ **用 `aria-selected` 标当前页** —— 那是 tab / option / row 的语义；当前页用 `aria-current="page"`，
+  用错了读屏会说"已选中"，而用户以为自己只是停在第 3 页
+- ❌ **客户端翻页不放 `pagination__live`** —— 页码变了却没有任何播报，读屏用户不知道"内容已经换了"。
+  而且这个 live 区必须**常驻 DOM**：新插入的节点很多读屏不播
+- ❌ **页码无限铺开** —— 槽位一多就撑破窄屏（USWDS 的上限是 7）。该用 `pagination__ellipsis` 收中间
+- ❌ **没跳过页码也显示省略号** —— 用户会以为中间少了页，去点它，什么也不会发生
+- ❌ **禁用态用纯透明表示** —— 半透明会让人以为"再点一下就行"；本库是让它"退到背景里"
+---
 ## 门禁
 `05-audit/pagination-check.js`

package/03-patterns/pagination/demo.html CHANGED Viewed

@@ -30,6 +30,7 @@ th { font-size: var(--fs-xs); color: var(--text-secondary); font-weight: 500; }
 .row .v { font-family: var(--mono); font-variant-numeric: tabular-nums; }
 .live-echo { margin: var(--sp-3) 0 0; font-size: var(--fs-xs); color: var(--text-tertiary); }
 .live-echo b { color: var(--text-secondary); font-family: var(--mono); }
+.pagination__list { flex-wrap: wrap; }
 </style>
 </head>
 <body class="page page">
@@ -118,6 +119,45 @@ th { font-size: var(--fs-xs); color: var(--text-secondary); font-weight: 500; }
     ⇒ <b>不产生横向溢出</b>。
   </p>
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：页码全铺开</h3>
+        <nav aria-label="分页示例" aria-hidden="true">
+          <ul class="pagination__list">
+            <li class="pagination__item"><a class="pagination__link" href="?page=1" aria-label="第 1 页" tabindex="-1">1</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=2" aria-label="第 2 页" tabindex="-1">2</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=3" aria-label="第 3 页" tabindex="-1">3</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=4" aria-label="第 4 页" tabindex="-1">4</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=5" aria-label="第 5 页" tabindex="-1">5</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=6" aria-label="第 6 页" tabindex="-1">6</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=7" aria-label="第 7 页" tabindex="-1">7</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=8" aria-label="第 8 页" tabindex="-1">8</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=9" aria-label="第 9 页" tabindex="-1">9</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=10" aria-label="第 10 页" tabindex="-1">10</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=11" aria-label="第 11 页" tabindex="-1">11</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=12" aria-label="第 12 页" tabindex="-1">12</a></li>
+          </ul>
+        </nav>
+      <p class="cmp__why">12 个页码硬塞进一行，窄屏上要么换行、要么每个都挤到点不中。而 4~10 页其实是读者最不会去点的区间。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：7 个槽位封顶 + 省略号</h3>
+        <nav aria-label="分页示例">
+          <ul class="pagination__list">
+            <li class="pagination__item"><a class="pagination__link" href="?page=1" aria-label="第 1 页">1</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=2" aria-label="第 2 页">2</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=3" aria-label="第 3 页">3</a></li>
+            <li class="pagination__item"><span class="pagination__ellipsis">…</span></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=11" aria-label="第 11 页">11</a></li>
+            <li class="pagination__item"><a class="pagination__link" href="?page=12" aria-label="第 12 页">12</a></li>
+          </ul>
+        </nav>
+      <p class="cmp__why">USWDS 的上限是 7 个槽位：首尾两页 + 当前页邻域，中间用 <code>pagination__ellipsis</code> 收掉。省略号不是装饰，是"这里还有页"的承诺 —— 所以没跳过页码时不许显示它。</p>
+    </div>
+  </div>
 </main>
 <script src="pagination.js"></script>

package/03-patterns/reveal/README.md CHANGED Viewed

@@ -89,3 +89,18 @@ CSS transition 被打断时是 **retarget**：从当前值继续插值，不重
 这条结论立即失效 —— 那时必须重新量，并且很可能需要守卫。
 ⚠️ 这属于**负面结论入档**：写下来是为了下次不要再"看到别人有就照抄一遍"。
+## 反例
+- ❌ **引了脚本就指望内容被藏起来** —— 默认**不接管**：只有显式调 `enable()` 才会把目标设成 `opacity: 0`。
+  隐藏是有代价的决定，必须由页面自己做出
+- ❌ **藏了但没有兜底** —— 任何一步失败都会留下"看不见的内容"，最坏是整页空白。
+  所以隐藏**只在** `<html data-reveal-ready>` 存在时生效，没有它内容就是全可见
+- ❌ **位移超过 8px** —— 内容"飞进来"会打断阅读节奏；本库的位移上限就是 8px
+- ❌ **自己再写一套 keyframes** —— 缓动、时长、延迟会各写一套，最后没人能回答
+  "为什么这个方向和那个方向节奏不一样"。本库是**一条规则撑六种表现**
+- ❌ **时长写裸数值** —— 只走令牌；`05-audit/motion.py` 会查裸时长与自编曲线
+- ❌ **reduced-motion 时把动画一刀切归零** —— 降级是**分级**的：关掉位移不等于关掉一切，
+  透明度的过渡仍然可以留
+---

package/03-patterns/reveal/demo.html CHANGED Viewed

@@ -22,6 +22,12 @@
            border: 1px solid var(--border-subtle); font-size: var(--fs-sm); }
 .rv-note  { font-size: var(--fs-sm); color: var(--text-secondary); }
 .rv-spacer { height: 40px; }
+.rv-card { padding: var(--sp-3); background: var(--surface-raised);
+           border: 1px solid var(--border-decor); border-radius: var(--r-sm); min-height: 64px; }
+.rv-card__t { margin: 0 0 var(--sp-1); font-size: var(--fs-sm); font-weight: 500; }
+.rv-card__d { margin: 0; font-size: var(--fs-xs); color: var(--text-secondary); }
+/* 反例专用：真的藏起来，用来演示"没有兜底"的后果 */
+.rv-hidden { opacity: 0; }
 </style>
 </head>
 <body class="page">
@@ -81,6 +87,24 @@
     ② 手动调 <code>Reveal.enable()</code>（本页就是这种，方便截图与演示）。<br>
     都不写 ⇒ 完全不接管：内容可见、位置不偏。<strong>这是刻意的默认值。</strong>
   </p>
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：藏了但没兜底</h3>
+        <div class="rv-card rv-hidden" aria-hidden="true"></div>
+      <p class="cmp__why">内容真被 <code>opacity: 0</code> 藏着，而脚本没跑起来（被拦、报错、CSP）—— 这一块就永远是空的，读者不知道这里有东西。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：只有 <code>data-reveal-ready</code> 时才藏</h3>
+        <div class="rv-card" aria-hidden="true">
+          <p class="rv-card__t">2026 年三季度回顾</p>
+          <p class="rv-card__d">营收同比 +18%，毛利率 42.1%。</p>
+        </div>
+      <p class="cmp__why">隐藏只在 <code>&lt;html data-reveal-ready&gt;</code> 存在时生效：任何一步失败，内容就是全可见的。动画可以有代价，但代价不能是"看不见内容"。</p>
+    </div>
+  </div>
 </main>
 <script src="../../03-patterns/reveal/reveal.js"></script>

package/03-patterns/states/README.md CHANGED Viewed

@@ -76,7 +76,7 @@ fetch(...).then(r => { clearTimeout(t); showResult(r); });
 - ❌ **empty 和 loading 用同一个样式** —— 用户分不清是"在加载"还是"真没有"
 - ❌ **empty 态不放动作按钮** —— 把用户卡死
-- ❌ **error 态没有重试出口** —— 死路
+- ❌ **error 态没有重试出口** —— 用户唯一的动作只剩刷新页面，而刷新会把已经填好的内容一起丢掉
 - ❌ **结构未知时用骨架屏** —— 撒谎，且内容到位时跳动
 - ❌ **请求 <300ms 也显示骨架屏** —— 闪一下更糟
 - ❌ **把普通操作的成功做成整页 success** —— 成功是过渡态，用 button 的 `data-state="success"`（1.2s 自动消失）

package/03-patterns/states/demo.html CHANGED Viewed

@@ -235,6 +235,30 @@ Array.prototype.forEach.call(document.querySelectorAll('.seg button'), function
 });
 show('content');
-</script></main>
+</script>
+  <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad">
+      <h3>❌ 常见写法：empty 态没有出口</h3>
+        <div class="state state--empty" aria-hidden="true">
+          <div class="state__icon">□</div>
+          <p class="state__title">这个时间范围下还没有记录</p>
+          <p class="state__desc">把范围放宽到 2023 年试试。</p>
+        </div>
+      <p class="cmp__why">说明写得很清楚，然后呢？用户读完只剩一个动作：刷新，或者退出。一条"没有数据"的提示不构成一个状态，它只是死路。</p>
+    </div>
+    <div class="cmp__pane cmp__good">
+      <h3>✅ 本库：empty 态必须带动作</h3>
+        <div class="state state--empty" aria-hidden="true">
+          <div class="state__icon">□</div>
+          <p class="state__title">这个时间范围下还没有记录</p>
+          <p class="state__desc">把范围放宽到 2023 年试试。</p>
+          <div class="state__action"><button class="btn btn--sm btn--primary" type="button" tabindex="-1">放宽到 2023</button></div>
+        </div>
+      <p class="cmp__why"><code>state__action</code> 是 empty 态的一部分：要么给一条能走的路，要么别显示这个空状态。</p>
+    </div>
+  </div>
+</main>
 </body>
 </html>

package/03-patterns/tabs/README.md CHANGED Viewed

@@ -82,3 +82,18 @@ demo 的面板里放了按钮，`Tab` 序列是
 - axe 0 违规 / 30 条通过
 判别力验证：破坏 roving（全部设成 `0`）⇒ **5 项立即被抓**。
+## 反例
+- ❌ **每个 `tabs__tab` 都给 `tabindex="0"`** —— Tab 键要逐个穿过一整排；
+  roving tabindex 只留**一个** 0，其余 -1
+- ❌ **`tabindex="0"` 只在初始化时设一次** —— 这是本组件最常见的 bug：用户切到第 3 个 tab 后，
+  再按 Tab 又回到第 1 个。那个唯一的 0 必须**跟着选中项走**
+- ❌ **禁用项也设 `tabindex="0"`** —— Tab 会停在不可用的项上，用户按了没反应，以为页面卡了
+- ❌ **automatic 模式下 `preventDefault`** —— 会与 button 的默认行为打架，变成"按一次跳两格"；
+  不拦，交给默认行为
+- ❌ **把 `tabs--manual` 当纯样式类用** —— 它是**行为开关**：`tabs.js` 读它决定方向键要不要切面板。
+  只加类不改语义，用户会以为方向键坏了
+- ❌ **`overflow-y` 不写 `hidden`** —— 一个轴设 `auto` 会让另一轴也自动化，选中态的 `border-bottom` 被裁掉
+---

package/03-patterns/tooltip/README.md CHANGED Viewed

@@ -90,6 +90,19 @@ JS 只切`data-state`，显隐与动画全交给 CSS。
 要接统一行为层，得先清这两条债。
+## 反例
+- ❌ **把必须知道的信息只放在 tooltip 里** —— 触屏没有 hover，键盘用户也未必停留。
+  判据很硬：tooltip 的文字**不能**与触发元素的可见文字/`aria-label` 重复 ——
+  一旦重复，说明它承载了本该可见的信息
+- ❌ **只做 hover、不做 focus** —— 键盘用户永远看不到（WCAG 1.4.13 要求 focus 也能出）
+- ❌ **Esc 关不掉** —— WCAG 1.4.13 的硬性要求：hover/focus 出现的内容必须可以关掉
+- ❌ **用 `display: none` 隐藏气泡** —— 读屏读不到；淡入用透明度
+- ❌ **`role="tooltip"` 不给 `aria-label`** —— 光靠内容拿不到可访问名，读屏只会念"提示"（0.8.9 补的）
+- ❌ **触屏只靠 hover 触发** —— 触屏上 hover 会"粘住"不褪；触屏必须走 JS 的 click / focus
+---
 ## 门禁
 `05-audit/tooltip-check.js`（契约 `gates` 里登记的唯一一道）——