agentcss 0.25.1 → 0.25.3

package/03-patterns/dropdown/demo.html

@@ -61,6 +61,11 @@
     </ul>
   </div>
   <div class="log" id="log">（选中项会显示在这里）</div>
+  <p class="small">
+    菜单里的那条<strong>分隔线</strong>只写 <code>data-dd-sep</code> 就行：
+    <code>role="separator"</code> 与 <code>.dd__sep</code> 由组件补。
+    方向键会跳过它 —— 分隔线不是可选项，让它能被"选中"是错的。
+  </p>
 </div>
 
 <h2>2 · 带勾选（选中性不只靠颜色）</h2>

package/03-patterns/dropdown/dropdown.js

@@ -359,6 +359,14 @@
         li.className = li.className ? (li.className + ' dd__item') : 'dd__item';
       }
       if (li.hasAttribute('data-dd-sep')) {
+        /* 🔴 和上面的 dd__item 同一个道理：分隔线那 1px 的高度与背景
+           全在 `.dd__sep` 这条规则里。作者只写 `data-dd-sep` 而不写类名时，
+           量到的渲染高度是 **0px**（实测），两组菜单项直接贴着 ——
+           看上去像"漏了一条分隔线"，而且没有任何报错。
+           ⇒ 由组件补类，不指望每个使用者记得写。 */
+        if (String(li.className).indexOf('dd__sep') < 0) {
+          li.className = li.className ? (li.className + ' dd__sep') : 'dd__sep';
+        }
         li.setAttribute('role', 'separator');
         li.setAttribute('aria-hidden', 'true');
       } else if (!li.hasAttribute('role')) {

package/03-patterns/form-validation/demo.html

@@ -21,6 +21,8 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
 .good { background: var(--surface-sunken); }
 .bad h3 { color: var(--danger); }
 .good h3 { color: var(--success); }
+/* 校验中示例只放一个字段，别撑满整行 —— 撑满了会让人以为"整页都在查" */
+.checking-box { max-width: 460px; }
 .btn { display:inline-flex; align-items:center; justify-content:center; height:44px;
          padding:0 var(--sp-5); border:1px solid transparent; border-radius:var(--r-sm);
          font-size:var(--fs-sm); font-weight:500; cursor:pointer; font-family:inherit;
@@ -91,6 +93,24 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
     而且把逻辑硬塞进样式层不可测。控制权交给 JS 加 <code>data-dirty</code> 属性。
   </div>
 
+  <h3 class="rule-bottom">第三种状态：异步校验中（<code>field--checking</code>）</h3>
+  <div class="box checking-box">
+    <div class="field field--checking">
+      <label class="field__label" for="uname">用户名</label>
+      <input class="field__input" id="uname" value="data_team" autocomplete="username"
+             aria-describedby="uname-checking">
+      <span class="field__checking-hint" id="uname-checking">正在检查是否可用…</span>
+    </div>
+    <p class="small" style="margin-top:var(--sp-3)">
+      🔴 <strong>校验中绝不能把输入框置灰或禁用</strong> —— 用户会以为"不让打字了"，
+      于是停在那里等，而其实他完全可以接着改。
+      正确做法只有一条：<strong>保持可输入</strong>，旁边给一个小的 pending 指示。
+      <br>这个指示器是<strong>原地旋转</strong>（12px），不是全屏 spinner：
+      它只说明"这一项在查"，不代表"整个页面在忙"。
+      <code>prefers-reduced-motion</code> 下放慢到 1.2s 但不停（停了会被当成卡死）。
+    </p>
+  </div>
+
   <h2 class="rule-bottom">二、完整表单：提交后出错误汇总</h2>
   <p class="small">什么都不填，直接点提交。焦点会移到汇总上，汇总里每条可点击跳转。</p>
 

package/03-patterns/list/demo.html

@@ -47,6 +47,9 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
   </div>
 
   <ul class="list" id="list" role="list"></ul>
+  <!-- 列表末尾的一行小字：说明"这个列表本身"（条数、排序、口径），
+       不是空状态。空状态用 states 的 .state--empty（见下面）。 -->
+  <p class="list__note" id="note" aria-live="polite">共 0 条</p>
 
   <!-- 空状态：删光后显示，容器位置不变所以不跳动 -->
   <div id="empty" hidden>
@@ -165,6 +168,8 @@ var EXTRA = [
 
 var list = document.getElementById('list');
 var emptyBox = document.getElementById('empty');
+var note = document.getElementById('note');
+var mode = '插入顺序';
 var data = SEED.slice();
 var seq = 100;
 
@@ -210,6 +215,7 @@ function paint() {
   for (var i = 0; i < data.length; i++) { html += rowHtml(data[i]); }
   list.innerHTML = html;
   emptyBox.hidden = data.length > 0;
+  note.textContent = '共 ' + data.length + ' 条 · ' + mode;
 }
 
 function repaint(mutate) {
@@ -219,6 +225,7 @@ function repaint(mutate) {
     for (var i = 0; i < data.length; i++) { html += rowHtml(data[i]); }
     list.innerHTML = html;
     emptyBox.hidden = data.length > 0;
+    note.textContent = '共 ' + data.length + ' 条 · ' + mode;
   });
 }
 
@@ -254,12 +261,14 @@ document.getElementById('add').onclick = function () {
 };
 
 document.getElementById('sort').onclick = function () {
+  mode = '按记录数降序';
   repaint(function () {
     data.sort(function (a, b) { return b.rec - a.rec; });
   });
 };
 
 document.getElementById('reverse').onclick = function () {
+  mode = '按名称排序';
   repaint(function () {
     data.sort(function (a, b) { return a.name.localeCompare(b.name, 'zh-Hans-CN'); });
   });
@@ -270,6 +279,7 @@ document.getElementById('clear').onclick = function () {
 };
 
 document.getElementById('reload').onclick = function () {
+  mode = '插入顺序';
   data = SEED.slice();
   for (var i = 0; i < data.length; i++) { data[i].id = 'r' + (++seq); }
   paint();

package/03-patterns/overlay/overlay.js

@@ -252,6 +252,19 @@
      🔴 绝不抢焦点。role="status" 会被屏幕阅读器自动播报，
         focus() 会打断用户当前正在做的事。
   */
+  /* 变体 ⇒ 类名。🔴 两个理由，都不是"为了好看"：
+     ① **白名单**：`toast({variant:'warn'})` 原本会拼出 `toast--warn`，
+        没有任何 CSS 命中 ⇒ 一条本该是黄色的警示条渲染成普通白条，
+        不报错、控制台干净。现在未知值退回无变体（至少不假装有语义）。
+     ② **写完整字面量**：`'toast--' + variant` 在源码里搜不到
+        `toast--success`，覆盖率门禁认不出"谁在用这个类"
+        （实测 success / warning 因此长期躺在"只被 README 认领"名单里）。 */
+  var TOAST_VARIANT = {
+    success: 'toast--success',
+    error:   'toast--error',
+    warning: 'toast--warning'
+  };
+
   function toast(opts) {
     opts = opts || {};
 
@@ -266,7 +279,7 @@
     }
 
     var el = document.createElement('div');
-    el.className = 'toast' + (opts.variant ? ' toast--' + opts.variant : '');
+    el.className = 'toast' + (TOAST_VARIANT[opts.variant] ? ' ' + TOAST_VARIANT[opts.variant] : '');
 
     var body = document.createElement('div');
     body.className = 'toast__body';

package/03-patterns/pagination/demo.html

@@ -121,6 +121,23 @@ th { font-size: var(--fs-xs); color: var(--text-secondary); font-weight: 500; }
 
 
 
+  <h2 class="rule-top">7 · 表格页脚里的精简分页（不占一行位置）</h2>
+  <p class="note">
+    数据表底部通常只有一两行的空间：<b>状态文字可以省，播报区不能省</b>。
+    <br>做法是把 <code>data-pg-live</code> 挂在一个 <code>.pagination__sr</code> 上 ——
+    <b>视觉上不占位，读屏照常播报</b>（用 <code>clip</code> 裁掉，不是 <code>display:none</code>；
+    后者会把整块移出无障碍树，播报就没了）。
+    <br>⚠️ 省略 <code>data-pg-status</code> 是允许的（JS 里有判空）；
+    省略 <code>data-pg-live</code> 则等于"翻页了但不告诉读屏"。
+  </p>
+  <div class="demo-box">
+    <nav class="pagination" aria-label="明细表分页"
+         data-pagination data-total="248" data-page-size="20" data-page="7" id="pg2">
+      <ul class="pagination__list" data-pg-list></ul>
+      <p class="pagination__sr" data-pg-live aria-live="polite"></p>
+    </nav>
+  </div>
+
   <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
   <div class="cmp">
     <div class="cmp__pane cmp__bad" data-bad="li.pagination__item|count|>7">
@@ -200,6 +217,12 @@ pg.onChange = function (page) {
   }
 };
 load(pg.page);
+
+/* 精简分页（页脚用）：没有 data-pg-status，播报区挂在 .pagination__sr 上 */
+var pg2 = Pagination.create(document.getElementById('pg2'));
+pg2.onChange = function (page) {
+  document.getElementById('pg2').setAttribute('data-page', String(page));
+};
 </script>
 </body>
 </html>

package/03-patterns/states/demo.html

@@ -56,6 +56,12 @@ p.lead { color: var(--text-secondary); }
  }
 .lbl { font-size: var(--fs-xs); color: var(--text-tertiary);
          margin-bottom: var(--sp-2); display: block; }
+/* 列表项骨架：头像 + 两行 —— 结构与真实行一致（.row 的 padding 与 gap 对齐） */
+.sk-list { border: 1px solid var(--border-decor); border-radius: var(--r-sm);
+             padding: var(--sp-2) 0; max-width: 420px; }
+.sk-row { display: flex; align-items: center; gap: var(--sp-3);
+            padding: var(--sp-3) var(--sp-4); }
+.sk-lines { flex: 1; min-width: 0; }
 </style>
 </head>
 <body class="page">
@@ -140,6 +146,31 @@ p.lead { color: var(--text-secondary); }
 
   <hr class="rule">
 
+  <h2>列表项的骨架：头像占位 + 两行文字</h2>
+  <p>
+    <code>skeleton--avatar</code> 是 40×40 的全圆占位，专门配 <code>skeleton--text</code>
+    做「头像 + 姓名 + 副标题」这种列表项。宽度节奏要跟真内容一致，
+    否则内容到位时头像会把文字挤走 —— 那正是骨架屏要避免的事。
+  </p>
+  <div class="sk-list" role="status" aria-live="polite" aria-label="正在加载公司列表">
+    <div class="sk-row">
+      <div class="skeleton skeleton--avatar" aria-hidden="true"></div>
+      <div class="sk-lines">
+        <div class="skeleton skeleton--text" aria-hidden="true"></div>
+        <div class="skeleton skeleton--text" aria-hidden="true"></div>
+      </div>
+    </div>
+    <div class="sk-row">
+      <div class="skeleton skeleton--avatar" aria-hidden="true"></div>
+      <div class="sk-lines">
+        <div class="skeleton skeleton--text" aria-hidden="true"></div>
+        <div class="skeleton skeleton--text" aria-hidden="true"></div>
+      </div>
+    </div>
+  </div>
+
+  <hr class="rule">
+
   <h2>300ms：不显示比闪一下好</h2>
   <p>
     请求在 300ms 内返回时<strong>不要显示加载态</strong>。骨架屏闪一下比不显示更糟 ——
@@ -218,7 +249,14 @@ var VIEWS = {
       '<div class="state__action">' +
       '<button class="btn btn--sm btn--primary" type="button">重试</button>' +
       '<button class="btn btn--sm btn--secondary" type="button">复制诊断信息</button>' +
-      '</div></div>';
+      '</div>' +
+      /* 技术细节放这里、并且折叠起来：主文案说"我该怎么办"，
+         细节留给要把它贴给技术支持的人。默认摊开会把所有人都吓一遍。 */
+      '<details class="state__more">' +
+      '<summary>诊断信息</summary>' +
+      '<div class="state__detail">sqlite3 · SELECT … FROM financial_facts WHERE ws=19 · err: SQLITE_BUSY (database is locked) · 12,480 ms · trace 8f2c41a7</div>' +
+      '</details>' +
+      '</div>';
   }
 };
 

package/03-patterns/tabs/demo.html

@@ -13,6 +13,10 @@
 <style>
 .log { font-family: var(--mono); font-size: var(--fs-xs);
          color: var(--text-secondary); min-height: 1.5em; }
+/* 键帽：用真正的 <kbd> 元素，不是 span+class（后者会被 refs 判成"未定义的类"） */
+kbd { display: inline-block; padding: 2px 7px; border: 1px solid var(--border-control);
+        border-bottom-width: 2px; border-radius: 5px; background: var(--surface);
+        font-family: var(--mono); font-size: 11px; color: var(--text-primary); }
 </style>
 </head>
 <body class="page">
@@ -86,6 +90,36 @@
     </div>
   </div>
 
+  <h2 class="rule-top">纵向（设置页侧栏那种）</h2>
+  <p class="note">
+    加 <code>.tabs--vertical</code>，并把 tablist 的
+    <code>aria-orientation</code> 改成 <code>vertical</code> ——
+    <strong>两件事必须同时做</strong>：只改 CSS 的话，键盘仍然是
+    <code>←</code> <code>→</code> 切换，而屏幕阅读器被告知"横向"，
+    于是它提示用户按左右键；用户按上下键，没反应。
+  </p>
+  <div class="tabs tabs--vertical" data-tabs>
+    <div class="tabs__list" role="tablist" aria-orientation="vertical" aria-label="账户设置">
+      <button class="tabs__tab" role="tab" id="v1" aria-controls="vp1"
+              aria-selected="true">基本资料</button>
+      <button class="tabs__tab" role="tab" id="v2" aria-controls="vp2"
+              aria-selected="false">安全</button>
+      <button class="tabs__tab" role="tab" id="v3" aria-controls="vp3"
+              aria-selected="false">通知</button>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="vp1" aria-labelledby="v1">
+      <p>头像、显示名、所属工作区。</p>
+      <p><button class="btn btn--md btn--secondary">修改头像（可 Tab 到）</button></p>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="vp2" aria-labelledby="v2" hidden>
+      <p>两步验证、登录设备、API 令牌。</p>
+    </div>
+    <div class="tabs__panel" role="tabpanel" id="vp3" aria-labelledby="v3" hidden>
+      <p>周报邮件、异常告警的接收范围。</p>
+    </div>
+  </div>
+  <p class="log">试 <kbd>↓</kbd> <kbd>↑</kbd>：选中线应该在<strong>文字右侧</strong>（RTL 下换到左侧）。</p>
+
   <h2 class="rule-top">键盘契约（APG / Radix）</h2>
   <div class="box">
     <p>

package/03-patterns/tooltip/tooltip.js

@@ -157,10 +157,14 @@ var flDismissable = function (opts) {
     return r;
   }
 
-  /* 逻辑方位 ⇒ 类名后缀。CSS 里只有 --inset-inline-start / --inset-inline-end */
+  /* 逻辑方位 ⇒ 完整类名。CSS 里只有 --inset-inline-start / --inset-inline-end。
+     🔴 为什么写整串而不是 `'tooltip--' + CLS[pos]`：拼出来的名字
+     在源码里 grep 不到，改 CSS 时无法反查谁在用；覆盖率门禁也只能看到
+     一段前缀，于是四个方位长期被记成"只被 README 认领"
+     —— 而它们其实每次 hover 都在渲染。 */
   var CLS = {
-    top: 'top', bottom: 'bottom',
-    start: 'inset-inline-start', end: 'inset-inline-end',
+    top: 'tooltip--top', bottom: 'tooltip--bottom',
+    start: 'tooltip--inset-inline-start', end: 'tooltip--inset-inline-end',
   };
 
   /**
@@ -195,7 +199,7 @@ var flDismissable = function (opts) {
     var id = 'tt' + (++uid);
     var tip = document.createElement('div');
     tip.id = id;
-    tip.className = 'tooltip tooltip--' + CLS[pos];
+    tip.className = 'tooltip ' + CLS[pos];
     tip.setAttribute('role', 'tooltip');
     tip.textContent = text;
 

package/04-recipes/app-shell/demo.html

@@ -316,6 +316,33 @@
 <p class="note">只做纯图标栏、不接抽屉的话，第 4 节那种写法（图标 + <code>aria-label</code>）
 也成立；但只要你会用 <code>data-shell-nav</code>，就把文字留在 DOM 里 ——
 一份标记同时满足两种形态。</p>
+  <h2>8 · 平面外壳（<code>shell--flat</code>）：融进纸面，不画第二层框</h2>
+  <div class="demo" style="padding:0">
+    <div class="shell shell--flat shell-demo--short">
+      <header class="shell__topbar">
+        <h2 class="shell__title">内嵌在报告里的外壳</h2>
+      </header>
+      <nav class="shell__side" aria-label="主导航（平面外壳）">
+        <ul class="shell__side-group">
+          <li><a class="shell__link" href="#" aria-current="page">概览</a></li>
+          <li><a class="shell__link" href="#">明细</a></li>
+        </ul>
+      </nav>
+      <div class="shell__main">
+        <div class="shell__content">
+          <div class="ph">外壳底色改回纸色（--paper）</div>
+          <div class="ph">主区边线透明 ⇒ 不与外层的卡片边框重影</div>
+        </div>
+      </div>
+    </div>
+  </div>
+  <p class="note">
+    什么时候用：外壳<strong>本身已经在卡片 / 弹窗 / 报告版式里</strong>。
+    这时它再自带一层底色和左边线，就会和外层边框形成"双重描边" ——
+    两条相距 1px 的线，看上去像渲染错位。
+    <br>什么时候别用：外壳是整页容器。那时它需要自己的边界，
+    <code>--flat</code> 会让侧栏和主区糊成一片。
+  </p>
 
 </main>
 <!-- shell-nav.js 依赖 Drawer（抽屉的行为层）。顺序不能反：

package/04-recipes/table/demo.html

@@ -122,6 +122,40 @@
 
 
 
+  <h2 class="rule-top">7 · 缺失值与紧凑密度（对账表这种"一屏二十行"的场合）</h2>
+  <p class="note">
+    <code>table--compact</code> 把字号降到 <code>--fs-xs</code>、内边距收到
+    <code>--sp-1 --sp-2</code> —— <strong>只给数字表、对账表用</strong>，
+    正文表格用了会读不动。
+    <br><code>cell--na</code> 是缺失值的统一写法：灰色、居中、不留空。
+    <strong>空格子和 0 是两件事</strong>：空格子读者分不清"没有数据"还是"漏了"，
+    0 会被当成真实数值参与心算。
+  </p>
+  <div class="table table--compact">
+    <table>
+      <caption class="table__cap">表 G · 银行对账明细（示例，含缺失值）</caption>
+      <thead>
+        <tr>
+          <th scope="col">科目</th>
+          <th scope="col" class="num">期初</th>
+          <th scope="col" class="num">本期发生</th>
+          <th scope="col" class="num">期末</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr><th scope="row">银行存款</th><td class="num">1,204,300</td><td class="num">318,200</td><td class="num">1,522,500</td></tr>
+        <tr><th scope="row">应收账款</th><td class="num">884,120</td><td class="cell--na">—</td><td class="num">884,120</td></tr>
+        <tr><th scope="row">其他应收款</th><td class="cell--na">N/A</td><td class="num">12,400</td><td class="num">12,400</td></tr>
+        <tr><th scope="row">预付账款</th><td class="num">46,700</td><td class="num">3,100</td><td class="num">49,800</td></tr>
+      </tbody>
+    </table>
+  </div>
+  <p class="table__foot">
+    两处缺失值用了两种写法（<code>—</code> 与 <code>N/A</code>）：
+    会计表里 <code>—</code> 表示"本期无发生"，<code>N/A</code> 表示"未取到数"。
+    混用会让人以为两者是同一件事 —— <strong>选一种并在表注里说明</strong>。
+  </p>
+
   <h2 class="rule-bottom">对比：错写法 vs 本库写法</h2>
   <div class="cmp">
     <div class="cmp__pane cmp__bad" data-bad="td.num--pos|glyphs|=5">

package/09-assets/bar/bar.js

@@ -23,8 +23,12 @@
   var NS = 'http://www.w3.org/2000/svg';
   var uid = 0;
   /* 分类色 5 个（bar.css 里的 .bar__s0..s4），与 scientific-plot 的 ramp 对齐。
-     超过 5 个系列请由调用方给 `series[i].cls` 自定义 —— 颜色循环会造成误读。 */
-  var SERIES_STYLES = 5;
+     超过 5 个系列请由调用方给 `series[i].cls` 自定义 —— 颜色循环会造成误读。
+     🔴 写成**完整类名数组**而不是 `'bar__s' + n`：
+        拼串在源码里搜不到 `bar__s4`，改配色时无法反查谁在用；
+        也让 .bar__s4 一直躺在覆盖率门禁的"只被 README 认领"名单里。 */
+  var SERIES_CLS = ['bar__s0', 'bar__s1', 'bar__s2', 'bar__s3', 'bar__s4'];
+  var SERIES_STYLES = SERIES_CLS.length;
 
   /* ==================================================================== *
    * 铁律二的核心：哪些点值得标数字
@@ -193,7 +197,7 @@
         yy = padT + plotH - vt;
 
         rect = el('rect', {
-          'class': 'bar__bar bar__s' + (s % SERIES_STYLES) +
+          'class': 'bar__bar ' + SERIES_CLS[s % SERIES_STYLES] +
                    (series[s].cls ? ' ' + series[s].cls : ''),
           x: x, y: yy, width: barW, height: vt - vb,
         });
@@ -277,7 +281,7 @@
         var li = document.createElement('li');
         li.className = 'bar__legend-item';
         var sw = document.createElement('span');
-        sw.className = 'bar__legend-swatch bar__s' + (si % SERIES_STYLES) +
+        sw.className = 'bar__legend-swatch ' + SERIES_CLS[si % SERIES_STYLES] +
                        (se.cls ? ' ' + se.cls : '');
         /* 🔴 用 textContent，不用 innerHTML —— 系列名来自调用方的数据 */
         li.appendChild(sw);

package/09-assets/bar/demo.html

@@ -82,6 +82,16 @@
 <button class="btn" id="try">不给 max，看会发生什么</button>
 <div id="err"></div>
 
+<h2>5 · 五个系列 = 五档分类色；第 6 个必须自带 <code>cls</code></h2>
+<p class="note">
+  <code>bar.css</code> 只提供 <code>.bar__s0</code>–<code>.bar__s4</code> 五档分类色
+  （与 <code>scientific-plot</code> 的 ramp 对齐）。超过五个系列时，本库
+  <b>不会循环取色</b>——循环会让两个不同的系列拿到同一个颜色，读者会以为它们是同一类。
+  <br>⇒ 第 6 个系列起，请由调用方给 <code>series[i].cls</code>。
+  下面这张图正好用满五档：五根柱子五种颜色，都能在基线截图里逐色核对。
+</p>
+<div class="bar" id="b5"></div>
+
 </main>
 
 <script src="bar.js"></script>
@@ -156,6 +166,23 @@
     ariaLabel: '每日 09:00 前的事项数，含阈值线 1',
   });
 
+  /* 5 · 五系列 = 五档分类色（.bar__s0..s4 全部真的渲染出来） */
+  Bar.draw({
+    host: document.getElementById('b5'),
+    mode: 'group',
+    max: 9,
+    height: 190,
+    labels: LBL.slice(0, 6),
+    series: [
+      { name: '受理', values: [3, 4, 5, 2, 6, 4] },
+      { name: '审核', values: [2, 3, 4, 5, 3, 6] },
+      { name: '放款', values: [4, 2, 3, 4, 5, 3] },
+      { name: '对账', values: [5, 5, 2, 3, 4, 2] },
+      { name: '归档', values: [1, 6, 6, 1, 2, 5] },
+    ],
+    ariaLabel: '六天五个环节的并列分组柱状图，五档分类色',
+  });
+
   /* 4 · 演示"量程必填" */
   document.getElementById('try').addEventListener('click', function () {
     var box = document.getElementById('err');

package/API.md

@@ -29,23 +29,31 @@
 除了 `<script src>`，16 个交互组件的脚本还有一个 ESM 入口：
 
 ```js
-// 只要一个
+// 只要一个（推荐：只引入这一个脚本，体积最小）
 import { Accordion } from 'agentcss/esm/accordion.mjs';
 
-// 或者一次拿全（体积更大，Vite/Rollup 会按需摇树）
+// 或者一次拿全 —— ⚠️ 不会摇树，17 个行为脚本全部进产物
 import { Accordion, Tabs, Select } from 'agentcss/esm';
 ```
 
-三条容易踩的：
+四条容易踩的：
 
 1. **入口是包装，不是第二份实现**。`esm/*.mjs` 只做
    「导入副作用 + 把全局上那个对象 re-export」，所以
    `Accordion === window.Accordion` 恒成立（门禁 `behavior-api` 断言这一点）。
    它由 `05-audit/gen-esm.py` 生成，改源码后要重新生成，`esm-gen` 门禁会拦住漂移。
-2. **无 DOM 环境可以直接 import**（SSR 安全）。但自动初始化会被跳过 ——
+2. **聚合入口不会摇树**（0.25.3 更正）。`esm/*.mjs` 的形式是
+   「先 `import` 目标脚本（副作用：把对象挂到全局），再把它 re-export」——
+   模块体本身就有副作用，打包器无法判断哪个导出没被用到，只能整包收下。
+   实测（esbuild）：`import { Select } from 'agentcss/esm'` 产物 **190 KB**，
+   而 `import { Select } from 'agentcss/esm/select'` 只有 **20.8 KB**（约 9 倍）。
+   `package.json` 的 `sideEffects` 把 `**/*.js` / `**/*.mjs` 标成有副作用，
+   **这是按事实写的、是对的** —— 错的是 0.25.2 之前本文档那句"会按需摇树"。
+   ⇒ 要体积就逐个 `import 'agentcss/esm/<组件>'`。
+3. **无 DOM 环境可以直接 import**（SSR 安全）。但自动初始化会被跳过 ——
    服务端没有 DOM 可扫，到浏览器里再调 `init()`/构造函数。16 个脚本
    在 Node 里 `require` 全部成功（门禁的判据 A）。
-3. **重复初始化是安全的**。`init()` 与构造函数都做了幂等处理：
+4. **重复初始化是安全的**。`init()` 与构造函数都做了幂等处理：
    同一 root 只会有一个实例，不会出现「点一次切换两次」。
 
 ### 四种接入形态