agentcss 0.11.12 → 0.11.14

package/01-tokens/page.css

@@ -241,6 +241,15 @@
      两栏的断言必须**互斥**且各自成立 —— 能同时成立的两条断言，
      什么也证明不了。这两个属性不影响渲染，但缺了它们，
      这块对照就退化成"看着像错的"，`demo-claim` 门禁会报红。
+
+   反例栏里还得有**标本**：真渲染出来的控件或内容。只有一段
+   `<p class="small">` 描述"别这么做"，不算反例 —— 读者看不见那个"错"。
+   摆不出来的（运行时行为 / 读屏输出 / 这页没有图表实例）写在块上：
+     `<div class="cmp__pane cmp__bad" data-prose="为什么摆不出来">`
+   单栏的 `box bad` 块没有成对结构，**在块上**写清为什么：
+     `<div class="box bad" data-claim-skip="为什么写不出互斥断言">`
+   合法的两种典型：两栏在视觉上必然相同（差别只在无障碍树里）、
+   差别是对比度（那件事由 `contrast.py` 单独测）。理由会被逐条打印。
    ========================================================================= */
 .page .cmp {
   display: grid;

package/02-primitives/badge/demo.html

@@ -63,7 +63,7 @@
   </p>
 
   <h2 class="rule-top">反例</h2>
-  <div class="box bad">
+  <div class="box bad" data-claim-skip="两栏画出来的都是同一批色块，尺寸与位置完全相同 —— 差别是暗色下 2.72:1 与 6.39:1 的对比度，而 demo-claim 没有对比度指标（那件事由 contrast.py 单独测，本页正文引的就是它的数）">
     <h3>反例：饱和底 + 白字</h3>
     <div class="row">
       <span class="badge badge--solid-success">已披露</span>
@@ -79,13 +79,21 @@
     </p>
   </div>
 
-  <div class="box bad">
+  <div class="box bad" data-claim-skip="可点的正例本该是一个 a / button，但本库 badge 门禁要求所有可点元素命中区 ≥44px，而徽标本体只有 24px 高 —— 摆一个过得了门的正例，要么改组件，要么给演示塞内联样式把高度撑起来（那是拿样式骗门禁）。⇒ 配不成对的原因不是量不了，是组件本身还没解决这个冲突，见 CHANGELOG「已知冲突」">
     <h3>反例：用 badge 装可点的东西</h3>
+    <div class="row">
+      <div class="badge badge--info">待复核</div>
+      <span class="small">← 它和上面的 badge 长得一模一样，但 Tab 一遍就会发现焦点跳过了它</span>
+    </div>
     <p class="small">
       <code>&lt;div class="badge badge--info" onclick="..."&gt;待复核&lt;/div&gt;</code>
       —— div 加 onclick 对读屏是<strong>「没有角色的按钮」</strong>：
       读不出来它是能点的，键盘也 Tab 不到。
       要能点就用 <code>&lt;button&gt;</code> 或 <code>&lt;a&gt;</code>，样式照抄 <code>.badge</code>。
+      <br><br>
+      ⚠️ <strong>但这句建议目前有个坑</strong>：换成 button/a 之后，
+      本库 badge 门禁会判「命中区 54×24 &lt; 44px」—— 徽标本体的高度不够。
+      <strong>这个问题还没解决</strong>，不是演示写错了。
     </p>
   </div>
 

package/02-primitives/choice/demo.html

@@ -186,22 +186,39 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
     </p>
   </div>
 
-  <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">
-        <span class="choice__mark"></span>
-        <span>我看起来正常，但 Tab 到不了这里</span>
-      </label>
+  <h2 class="rule-bottom">对照：把原生勾选框藏起来的两种写法</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="input|focus|=0">
+      <h3>❌ display:none：看不见，也 Tab 不到</h3>
+      <div class="choice choice--checkbox">
+        <input class="choice__input" type="checkbox" style="display:none" id="bad1">
+        <label class="choice__label" for="bad1">
+          <span class="choice__mark"></span>
+          <span>我看起来正常，但 Tab 到不了这里</span>
+        </label>
+      </div>
+      <p class="cmp__why">
+        <strong>按一次 Tab 就知道：焦点直接跳过它。</strong>
+        <code>display:none</code> 把这个 input 从 tab 顺序里删掉了，
+        键盘用户彻底到不了 —— 而鼠标点仍然有效，所以这个 bug 用鼠标永远测不出来。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="input|focus|=1">
+      <h3>✅ opacity:0 + 绝对定位：看不见，但还在 Tab 顺序里</h3>
+      <div class="choice choice--checkbox">
+        <input class="choice__input" type="checkbox" id="good1">
+        <label class="choice__label" for="good1">
+          <span class="choice__mark"></span>
+          <span>同一行字，看起来一模一样，但 Tab 停得住</span>
+        </label>
+      </div>
+      <p class="cmp__why">
+        本库的 input 是 <code>opacity:0</code> 铺满整个 label：
+        你看得见的是 <code>.choice__mark</code>，焦点环也画在它身上
+        （<code>:focus-visible + .choice__mark</code>）。
+      </p>
     </div>
-    <p class="small" style="margin-top:var(--sp-3)">
-      <strong>用 Tab 试试——焦点会直接跳过它。</strong>
-      <code>display:none</code> 把它从 tab 顺序里移除了，键盘用户彻底到不了这里。
-      鼠标点击还正常，所以这种 bug 用鼠标测不出来。<br><br>
-      本库的 input 用的是 <code>opacity:0</code> + 绝对定位：<strong>看不见，但仍在 tab 顺序里</strong>。
-    </p>
   </div>
 
   <h2 class="rule-bottom">焦点环必须画在看得见的地方</h2>

package/02-primitives/separator/demo.html

@@ -60,8 +60,13 @@
   </div>
 
   <h2>反例</h2>
-  <div class="box bad">
+  <div class="box bad" data-claim-skip="两栏都会画出一条 1px 的线，高度与宽度完全相同 —— 差别是 1.26:1 与 3.42:1 的对比度，而 demo-claim 没有对比度指标（那件事由 contrast.py / component-contrast.py 单独测）">
     <h3>反例：语义分隔用装饰色</h3>
+    <div style="max-width:32em">
+      <p class="small" style="margin:0">基本信息</p>
+      <hr class="separator separator--tight">
+      <p class="small" style="margin:0">高级设置</p>
+    </div>
     <p class="small">
       分隔"基本信息"与"高级设置"——这是<strong>两类不同的东西</strong>，
       但如果用 <code>--border-decor</code>（1.26:1），
@@ -71,13 +76,33 @@
     </p>
   </div>
 
-  <div class="box bad">
-    <h3>反例：用 div + border-bottom 代替 hr</h3>
-    <p class="small">
-      <code>&lt;div class="line"&gt;</code> 对读屏是<strong>什么都没有</strong>。
-      语义分隔必须用 <code>&lt;hr&gt;</code>（或 <code>role="separator"</code>），
-      装饰性的才可以用纯 div。
-    </p>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="hr|count|=0">
+      <h3>❌ div + border-bottom</h3>
+      <div>
+        <p class="small" style="margin:0">基本信息</p>
+        <div style="border-top:1px solid var(--border-decor); margin:var(--sp-4) 0"></div>
+        <p class="small" style="margin:0">高级设置</p>
+      </div>
+      <p class="cmp__why">
+        线画得一模一样 —— 连颜色都对齐了。但读屏走到这里是
+        <strong>两段独立的文字，中间什么都没有</strong>：
+        它不知道这两段被分成了一组。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="hr|count|=1">
+      <h3>✅ hr（或 role="separator"）</h3>
+      <div>
+        <p class="small" style="margin:0">基本信息</p>
+        <hr class="separator separator--tight">
+        <p class="small" style="margin:0">高级设置</p>
+      </div>
+      <p class="cmp__why">
+        同一条线，读屏会念「分隔符」。<strong>0 个 <code>&lt;hr&gt;</code> 与 1 个</strong>，
+        就是"看得见"和"念得出"的全部差别。
+      </p>
+    </div>
   </div>
 </main>
 </body>

package/02-primitives/switch/demo.html

@@ -82,18 +82,42 @@
   </div>
 
   <h2 class="rule-top">反例</h2>
-  <div class="box bad">
-    <h3>反例：用 div + role="switch"，自己管所有状态</h3>
-    <p class="small">
-      常见写法是 <code>&lt;div role="switch" tabindex="0" onclick="..."&gt;</code>，
-      然后手写 <code>aria-checked</code> 切换。这需要自己处理：
-      Space 键、焦点样式、状态播报。<strong>三件事漏一件就坏</strong>，
-      而且测试工具（axe）只看得见 DOM，看不见你的 JS 有没有绑对。
-    </p>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="input|count|=0">
+      <h3>❌ div + role="switch"，自己管所有状态</h3>
+      <div class="switch" role="switch" aria-checked="false" tabindex="0">
+        <span class="switch__track"><span class="switch__thumb"></span></span>
+        <span class="switch__label">开启动价推送</span>
+      </div>
+      <p class="cmp__why">
+        <strong>看起来和下面那个一模一样 —— 这正是坑所在。</strong>
+        常见写法是 <code>&lt;div role="switch" tabindex="0" onclick="…"&gt;</code>
+        再手写 <code>aria-checked</code> 切换，于是 Space 键、焦点样式、状态播报
+        三件事都得自己管，<strong>漏一件就坏</strong>。
+        而 axe 只看得见 DOM，看不见你的 JS 有没有绑对。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="input|count|=1">
+      <h3>✅ 原生 checkbox + role="switch"</h3>
+      <span class="switch">
+        <input class="switch__input" type="checkbox" role="switch" id="s6">
+        <span class="switch__track"><span class="switch__thumb"></span></span>
+        <label class="switch__label" for="s6">开启动价推送</label>
+      </span>
+      <p class="cmp__why">
+        同一个外观，但键盘响应、焦点环、状态播报<strong>全部由浏览器给</strong> ——
+        少写的那部分不是"省事"，是"少了一个会忘的地方"。
+      </p>
+    </div>
   </div>
 
-  <div class="box bad">
+  <div class="box bad" data-claim-skip="两栏在视觉上必须完全相同 —— 那正是这一块要教的：差别只在无障碍树里（sr-only 的 label 仍在树中，display:none 的不在），可见部分都只有滑块那么大，写不出互斥断言。证据在 10-review/a11y-tree/switch.txt">
     <h3>反例：给 label 加 display:none</h3>
+    <div class="switch">
+      <span class="switch__track"><span class="switch__thumb"></span></span>
+      <label class="switch__label" style="display:none">自动续订</label>
+    </div>
     <p class="small">
       为了"只留滑块"而把 <code>&lt;label&gt;</code> 隐藏掉，
       开关就<strong>失去了可点击的文字区域</strong>，也失去了语义名字 ——

package/03-patterns/accordion/demo.html

@@ -199,23 +199,76 @@ p { margin: 0 0 var(--sp-3); }
     </p>
   </div>
 
-  <h2 class="rule-top">反例</h2>
-  <div class="box bad">
-    <h3>反例：用 div 当 trigger</h3>
-    <p class="small">
-      <code>&lt;div class="accordion__trigger"&gt;</code> 键盘上 Tab 不到、
-      也不响应 Enter/Space。<strong>APG 要求 header 里是
-      <code>role="button"</code> 的元素</strong>，用原生
-      <code>&lt;button&gt;</code> 最省事也最可靠。
-    </p>
+  <h2 class="rule-top">对照：两处最容易写错的地方</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="button|count|=0">
+      <h3>❌ 用 div 当 trigger</h3>
+      <div class="accordion">
+        <div class="accordion__item">
+          <div class="accordion__heading">
+            <div class="accordion__trigger">
+              <span class="accordion__label">数据源与口径</span>
+              <span class="accordion__marker" aria-hidden="true"></span>
+            </div>
+          </div>
+        </div>
+      </div>
+      <p class="cmp__why">
+        <code>&lt;div class="accordion__trigger"&gt;</code> 键盘上 Tab 不到、
+        也不响应 Enter/Space —— 它<strong>一个 button 都不是</strong>。
+        APG 要求 header 里是 <code>role="button"</code> 的元素，
+        用原生 <code>&lt;button&gt;</code> 最省事也最可靠。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="button|count|=1">
+      <h3>✅ heading 包住原生 button</h3>
+      <div class="accordion">
+        <div class="accordion__item">
+          <h3 class="accordion__heading">
+            <button class="accordion__trigger" aria-expanded="false">
+              <span class="accordion__label">数据源与口径</span>
+              <span class="accordion__marker" aria-hidden="true"></span>
+            </button>
+          </h3>
+        </div>
+      </div>
+      <p class="cmp__why">
+        同一个外观，一个按钮元素。Enter / Space 由浏览器负责 ——
+        本组件的 JS <strong>一行 keydown 都没写</strong>，写了反而会双触发。
+      </p>
+    </div>
   </div>
-  <div class="box bad">
-    <h3>反例：折叠时只用 max-height: 0</h3>
-    <p class="small">
-      内容在无障碍树里<strong>仍然存在</strong> —— 读屏会念出「折叠」区域里的全部文字，
-      键盘也能 Tab 进去。<strong>必须用 <code>hidden</code> 或
-      <code>display:none</code></strong>，让它真正离开无障碍树。
-    </p>
+
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="a|focus|=1">
+      <h3>❌ 折叠时只用 max-height: 0</h3>
+      <div id="acc-bad" style="max-height:0; overflow:hidden">
+        <p class="small" style="margin:0 0 var(--sp-2)">这一整段文字，读屏此刻仍然念得出来。</p>
+        <a href="#acc-bad">里面的这个链接，Tab 也仍然进得去</a>
+      </div>
+      <p class="cmp__why">
+        <strong>这一栏看起来和右边一样空 —— 差别不在视觉上，在第 1 次按 Tab 之后。</strong>
+        这块的高度被压成了 <code>0</code>，你<strong>看不见它</strong>，
+        但按一下 Tab，焦点会停在里面的链接上；读屏也会把那句"仍然念得出来"念完。
+        内容在无障碍树里<strong>仍然活着</strong>，只是视觉上消失。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="a|focus|=0">
+      <h3>✅ hidden / display:none</h3>
+      <p class="small" style="margin:0 0 var(--sp-2)">
+        （这一栏故意是空的：内容被 <code>hidden</code> 之后连占位都不留，这正是重点。）
+      </p>
+      <div hidden>
+        <p class="small" style="margin:0 0 var(--sp-2)">这一整段文字，读屏此刻仍然念得出来。</p>
+        <a href="#acc-good">里面的这个链接，Tab 也仍然进得去</a>
+      </div>
+      <p class="cmp__why">
+        同样看不见，但内容<strong>真的离开了无障碍树</strong>：
+        Tab 到不了、读屏也不念。折叠面板收起时必须这样。
+      </p>
+    </div>
   </div>
 </main>
 <script src="accordion.js"></script>

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

@@ -55,7 +55,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
   </p>
 
   <div class="grid2" style="margin-top:var(--sp-4)">
-    <div class="box bad">
+    <div class="box bad" data-claim-skip="差别是「什么时候报错」—— 时序。两个输入框在任何一个静态时刻的几何与文本都相同，只有交互过程中才分得出来，而 demo-claim 量的是静态 DOM">
       <h3>反例：oninput 立即报错</h3>
       <div class="field">
         <label class="field__label" for="naive">金额</label>
@@ -126,11 +126,11 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
 
   <h2 class="rule-bottom">三、错误文案：给建议，不给判断</h2>
   <div class="grid2">
-    <div class="box bad">
+    <div class="box bad" data-claim-skip="两栏都是三条错误文案（uniq 都是 3、字号行高全同），差别只在措辞本身 —— 机器判不了哪句更清楚，只能人读">
       <h3>反例</h3>
-      <p style="font-size:var(--fs-sm); color:var(--danger); margin:0 0 var(--sp-2)">格式错误</p>
-      <p style="font-size:var(--fs-sm); margin:0 0 var(--sp-2)">非法输入</p>
-      <p style="font-size:var(--fs-sm); margin:0">值不合法</p>
+      <p class="naive-error">格式错误</p>
+      <p class="naive-error">非法输入</p>
+      <p class="naive-error" style="margin-bottom:0">值不合法</p>
       <p class="small" style="margin-top:var(--sp-3)">
         WCAG 3.3.3 要求给修正建议。这三句用户读完还是不知道该改成什么。
       </p>

package/03-patterns/overlay/demo.html

@@ -92,7 +92,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
         <strong>点遮罩不关闭</strong>。误点遮罩的代价太大。
       </p>
     </div>
-    <div class="box bad">
+    <div class="box bad" data-prose="焦点落在哪颗按钮上、点遮罩关不关，都是运行时行为：要摆出「错的那一版」得真的渲染一个会抢焦点的对话框，而演示页里放一个真 modal 会盖住整页">
       <h3 style="margin:0 0 var(--sp-3); font-size:var(--fs-sm); font-weight:500">常见做法</h3>
       <p class="small" style="margin:0">
         焦点默认落在"删除"上，用户看清标题之前就按了 Enter。<br><br>
@@ -111,9 +111,15 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
 
   <h2 class="rule-bottom">用错比做丑严重得多</h2>
   <div class="two">
-    <div class="box bad aside-col">
+    <div class="box bad aside-col" data-claim-skip="左栏是一个 toast 标本，右栏是一条判断规则（没有人能数的话）—— 两栏根本不是同一种东西，没有可比的量；而且「该 toast 还是 dialog」取决于要不要用户先确认，没有阈值可划">
       <h3 style="margin:0 0 var(--sp-3); font-size:var(--fs-sm); font-weight:500; color:var(--danger)">
         ❌ 错用</h3>
+      <div class="toast toast--error" role="status" style="margin:0 0 var(--sp-3)">
+        <div class="toast__body">
+          <div class="toast__title">文件已删除</div>
+          <div class="toast__desc">3 秒后自动消失，没有撤销</div>
+        </div>
+      </div>
       <p class="small" style="margin:0 0 var(--sp-2)">
         <strong>把"确认删除"做成 toast</strong><br>
         用户可能根本没看见就把文件删了，而且没法撤销。

package/03-patterns/tabs/demo.html

@@ -102,23 +102,82 @@
     </p>
   </div>
 
-  <h2 class="rule-top">反例</h2>
-  <div class="box bad">
-    <h3>反例：用 div 当 tab</h3>
-    <p class="small">
-      <code>&lt;div role="tab"&gt;</code> 键盘上根本<strong>Tab 不到</strong>
-      （除非手写 <code>tabindex</code>），也不会响应 Enter/Space。
-      APG 明确要求 tab 是 <code>&lt;button role="tab"&gt;</code> ——
-      用原生 button，键盘行为免费且必然正确。
-    </p>
+  <h2 class="rule-top">对照：两处最容易写错的地方</h2>
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="[role=tab]|focus|=0">
+      <h3>❌ 用 div 当 tab</h3>
+      <div class="tabs">
+        <div class="tabs__list" role="tablist" aria-label="错例：div 当 tab">
+          <div class="tabs__tab" role="tab" aria-selected="true">基本信息</div>
+          <div class="tabs__tab" role="tab" aria-selected="false">高级设置</div>
+        </div>
+      </div>
+      <p class="cmp__why">
+        这两个 tab <strong>看起来完全正常</strong>，但
+        <code>&lt;div role="tab"&gt;</code> 根本 Tab 不到（除非手写
+        <code>tabindex</code>），也不响应 Enter/Space。
+        APG 要求 tab 是 <code>&lt;button role="tab"&gt;</code>。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="[role=tab]|focus|=2">
+      <h3>✅ button role="tab"</h3>
+      <div class="tabs">
+        <div class="tabs__list" role="tablist" aria-label="正例：button 当 tab">
+          <button class="tabs__tab" role="tab" aria-selected="true">基本信息</button>
+          <button class="tabs__tab" role="tab" aria-selected="false">高级设置</button>
+        </div>
+      </div>
+      <p class="cmp__why">
+        同一个外观，键盘行为免费且必然正确。
+        （这里只演示"能不能聚焦"，roving 见下面那块。）
+      </p>
+    </div>
   </div>
-  <div class="box bad">
-    <h3>反例：每个 tab 都写 tabindex="0"</h3>
-    <p class="small">
-      看起来"都能 Tab 到"，但一排 5 个 tab 就要按 <strong>5 次 Tab</strong>
-      才能进内容区。Tab 键应该是<strong>进出</strong>控件的，
-      组内移动是方向键的活。
-    </p>
+
+  <div class="cmp">
+    <div class="cmp__pane cmp__bad" data-bad="[role=tab]|focus|=3">
+      <h3>❌ 每个 tab 都写 tabindex="0"</h3>
+      <div class="tabs">
+        <div class="tabs__list" role="tablist" aria-label="错例：三个 tab 全是 0">
+          <button class="tabs__tab" role="tab" tabindex="0" aria-selected="true">基本信息</button>
+          <button class="tabs__tab" role="tab" tabindex="0" aria-selected="false">高级设置</button>
+          <button class="tabs__tab" role="tab" tabindex="0" aria-selected="false">日志</button>
+        </div>
+      </div>
+      <p class="cmp__why">
+        看起来"都能 Tab 到"，但一排 3 个 tab 就要按 <strong>3 次 Tab</strong>
+        才能进内容区。Tab 键应该是<strong>进出</strong>控件的，
+        组内移动是方向键的活。
+      </p>
+    </div>
+
+    <div class="cmp__pane cmp__good" data-good="[role=tab]|focus|=1">
+      <h3>✅ roving tabindex：整组只有一个 0</h3>
+      <div class="tabs" data-tabs>
+        <div class="tabs__list" role="tablist" aria-orientation="horizontal" aria-label="正例：roving">
+          <button class="tabs__tab" role="tab" id="rt1" aria-controls="rp1"
+                  aria-selected="true">基本信息</button>
+          <button class="tabs__tab" role="tab" id="rt2" aria-controls="rp2"
+                  aria-selected="false">高级设置</button>
+          <button class="tabs__tab" role="tab" id="rt3" aria-controls="rp3"
+                  aria-selected="false">日志</button>
+        </div>
+        <div class="tabs__panel" role="tabpanel" id="rp1" aria-labelledby="rt1">
+          <p>一次 Tab 就进来，方向键在组内移动。</p>
+        </div>
+        <div class="tabs__panel" role="tabpanel" id="rp2" aria-labelledby="rt2" hidden>
+          <p>方向键到这里。</p>
+        </div>
+        <div class="tabs__panel" role="tabpanel" id="rp3" aria-labelledby="rt3" hidden>
+          <p>方向键到这里。</p>
+        </div>
+      </div>
+      <p class="cmp__why">
+        那个 <code>0</code> 跟着选中项走 —— 由 <code>roving.js</code> 在切换时搬，
+        不是初始化时设一次。只设一次是最常见的 bug。
+      </p>
+    </div>
   </div>
 </main>
 <script src="tabs.js"></script>

package/09-assets/echarts-adapter/demo.html

@@ -147,7 +147,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
   </p>
 
   <h2 class="rule-top">4 · 明确禁止（这些是"看起来专业但会骗人"的）</h2>
-  <div class="box bad">
+  <div class="box bad" data-claim-skip="这一块是「不要做」清单本身（一张表），不是某个组件的错写法 —— 要给它配正例栏，得先真的渲染一张 3D 图与一张 2D 图做对照，而本页没有图表实例可摆；表格尺寸量出来的是排版，不是观点">
     <table>
       <tr><th>不要做</th><th>为什么</th></tr>
       <tr><td class="no">3D 图表</td><td>透视扭曲会<b>误导读数</b>（Tufte 的核心结论）</td></tr>

package/09-assets/sparkline/demo.html

@@ -107,7 +107,7 @@
   </div>
 
   <h2 class="rule-top">🔴 无障碍：它没有可读的文本等价物</h2>
-  <div class="box bad">
+  <div class="box bad" data-prose="这一块说的是原因（为什么刻意不加 role=img），反例是读屏念出来的那句话，不是一个看得见的元素 —— 图形本身在下面那块里已经摆出来了">
     <p>
       纯 SVG 路径对读屏<strong>没有意义</strong> ——
       读屏只会说"图像"，不会说"最近上涨 2.3%"。
@@ -123,7 +123,7 @@
   </div>
 
   <h2 class="rule-top">反例</h2>
-  <div class="box bad">
+  <div class="box bad" data-claim-skip="两栏画的是同一条走势线，差别只在旁边有没有一个数字 —— 而「该不该配数字」本页上文明写取决于数值重不重要（纯装饰小图可以不配），没有一条能划的界线；断言只能去数一个我自己编出来的选择器，那证明的是我编的标记，不是这件事">
     <h3>反例：只放 sparkline，没有数字</h3>
     <p class="small">
       视觉上"很有信息"，但读屏用户<strong>什么都不知道</strong> ——
@@ -131,7 +131,7 @@
     </p>
     <span class="sparkline" data-spark="12,18,15,24,22,31,28" data-spark-height="40"></span>
   </div>
-  <div class="box bad">
+  <div class="box bad" data-prose="「动画有没有被 reduced-motion 关掉」是媒体查询在运行时决定的行为，同一个 sparkline 在两种设置下长得一模一样 —— 静态块摆不出「错的那一版」">
     <h3>反例：动画不管 reduced-motion</h3>
     <p class="small">
       前庭功能障碍者会因动画眩晕（WCAG 2.3.3）。

package/CHANGELOG.md

@@ -16,6 +16,189 @@
 
 （无）
 
+## [0.11.14] - 2026-10-29
+
+**「键盘到不了」这句话，现在能量了。**
+
+0.11.13 结束时，10 个页面仍是单栏反例。其中 5 页的登记里写着一句诚实话：
+「两块都可量，但这一页仍是单栏结构，升级成 cmp 要重排整页 —— 本轮没做，
+已知欠账」。这一版把那 5 页还掉了，并且在做的时候发现：**那句话有一半不准**
+—— 那些"可量"的差别是「按 Tab 能不能停上去」，而当时的指标表里
+根本没有能量它的东西。剩下的只有高度、宽度、字号这些代理量，
+拿来判"键盘到不了"是**间接**的（高度 0 暗示焦点没了，但那只是暗示）。
+
+### 新指标 `focus`
+
+`data-bad="input|focus|=0"` —— 数的是**真的能 Tab 到**的元素个数。
+实现是「`focus()` 成功 **且** `tabIndex >= 0`」，两个信号缺一不可，
+两种错都实测到了：
+
+| 元素 | tabIndex | 聚焦得成 | Tab 到得了 |
+|---|---|---|---|
+| `a[href]` | 0 | ✅ | ✅ |
+| `a`（没有 href） | 0 | ❌ | ❌ ← tabIndex 会撒谎 |
+| `input[disabled]` | 0 | ❌ | ❌ ← tabIndex 会撒谎 |
+| `div[tabindex="-1"]` | -1 | ✅ | ❌ ← 能聚焦 ≠ 能 Tab 到 |
+
+第二条是这一版第一次跑就踩到的：只判 `tabIndex >= 0`，把没有 href 的 `<a>`
+算成可聚焦（自检当场红了）；只判 `focus()`，把 roving tabindex 里
+`-1` 的那几项算成能 Tab 到（tabs 的正例量出 3，应该是 1）。
+两条都留在自检里，各占一条用例。
+
+### 7 个块从单栏改成成对
+
+| 页面 | 反例栏 | 正例栏 | 量的 |
+|---|---|---|---|
+| `choice` | `display:none` 的 input | `opacity:0` + 绝对定位 | `focus` 0 vs 1 |
+| `separator` | `div` + border-top | `<hr>` | `hr` 个数 0 vs 1 |
+| `switch` | `div role="switch"` | 原生 checkbox | `input` 个数 0 vs 1 |
+| `accordion` | `div` 当 trigger | heading 包 button | `button` 个数 0 vs 1 |
+| `accordion` | `max-height:0` | `hidden` | 链接 `focus` 1 vs 0 |
+| `tabs` | `div role="tab"` | `button role="tab"` | `focus` 0 vs 2 |
+| `tabs` | 三个 `tabindex="0"` | roving（只有一个 0） | `focus` 3 vs 1 |
+
+### 已知冲突：可点的徽标过不了自己的命中区门禁
+
+`badge` 本来也要改成成对（`div` 装可点 vs `a` 装可点），做到一半被
+`badge` 组件门禁拦住了：
+
+```
+FAIL ③ 命中区全部 ≥44px：A.badge badge--inf 视觉 54×24 命中 54×24
+```
+
+这不是演示写错 —— **是组件自身的矛盾**：README 说「要能点就用 button/a，
+样式照抄 `.badge`」，而徽标本体只有 24px 高，换上正确元素之后
+命中区就不达标（WCAG 2.5.5 要 44px）。也就是说，
+**本库目前没有任何一种写法能同时满足「可点的徽标」和「44px 命中区」**。
+
+这一版**没有**用内联样式把演示撑到 44px 蒙过门禁 —— 那是拿样式骗判据。
+徽标照旧是单栏，块上写明"配不成对的原因不是量不了，是组件还没解决"。
+真要修得动 `.badge--clickable` 的垂直内边距（或干脆在文档里禁止可点徽标），
+那是破坏性视觉变更，单独一版做。
+
+### 判据改成**按块**登记（原来按页）
+
+单栏块的理由从页面注释 `<!-- demo-claim:skip -->` 搬到块上
+`data-claim-skip="理由"`。原因不是审美，是这一版恰好会造出"混合页"：
+
+```
+separator：一块改成了 cmp（hr vs div），另一块（对比度）改不了
+switch   ：一块改成了 cmp（div vs 原生），另一块（label）改不了
+```
+
+按页判的话，只要加**一个** `cmp` 块，同页剩下的单栏反例就全部"洗白"了 ——
+门禁不看了，也不需要理由。所以先把这个洞堵上再改内容，否则改完就是假绿。
+页面级注释现在会**报错**，不忽略：两套机制并存比没有机制更坏。
+
+顺带：写了 `data-prose`（连标本都摆不出来）的块，不再要求写
+`data-claim-skip` —— 一条声明只覆盖一个问题，别让人把同一句话说两遍。
+
+### 覆盖
+
+- 对照块 **24 → 31**（30 页），每块两栏互斥且各自成立
+- 单栏块登记 **9 个**（逐块，理由是"视觉上必然相同"或"差别是时序/措辞/对比度"）
+- `data-prose` 声明 3 个（不变）
+- `demo-claim` 自检 **32 → 48 条**（29 必须红 + 19 必须绿）
+
+判据**证不了**的那些也没藏着：`switch` 的「label 被藏掉」两栏视觉必然相同，
+差别只在无障碍树里 —— 那一块登记为"写不出互斥断言"，证据指向
+`10-review/a11y-tree/switch.txt`，不是"看着差不多就算了"。
+
+## [0.11.13] - 2026-10-29
+
+**先得有东西可看，才谈得上「两栏不一样」。**
+
+0.11.12 让 24 个对照块各写了一条可证伪的数字断言。但那套判据有个前提：
+块里得有标本。发布后把全部 34 个 demo 页扫了一遍 —— **13 个反例块里
+一个标本都没有**，只有 `<p class="small">` 在**描述**一个反例。
+
+最刺眼的一处：`02-primitives/separator` 的标题写着
+「反例：用 div + border-bottom 代替 hr」，块里只有一段话说
+"`<div class="line">` 对读屏什么都没有"—— **那个 div 根本没被渲染**。
+读者在这一屏里学不到任何看得见的东西。`switch` / `accordion` / `tabs`
+各两处、`badge`、`sparkline`、`form-validation` 同形。
+
+`demo-counterexample-gate.py` 对它们全绿：它判的是"块在、没被藏、
+块后有标题"，一段纯文字全都满足。这是比"反例不成立"更早一层的漏洞 ——
+**没有反例**。
+
+### 新增的两条判据（`05-audit/demo-claim-gate.js`，同一道门禁）
+
+1. **反例块里必须有标本** —— 真渲染出来的控件或内容。判据看标签语义：
+   原生控件/绘图元素算；`h3 p code pre strong` 这些"天生是字"的标签，
+   带**非排版类**时才算（`p.rep-p` 是内容本身，`p.small` 是描述它的文字）。
+   摆不出来的写在块上：`data-prose="为什么摆不出来"`（理由 ≥8 字，
+   逐条打印，可以被反驳）。
+2. **单栏页必须逐页登记** —— 只有 `box bad`、没有 `cmp` 的页，页内要写
+   `<!-- demo-claim:skip 理由 -->`。以前只在末尾打一行"10 页未覆盖"，
+   现在每页的理由都打出来，并且**要求区分"量不了"和"可量但没做"**。
+   既有 `cmp` 又写 `skip` 也算矛盾，同样红。
+
+自检从 10 条加打到 32 条（21 条必须红 + 11 条必须绿）。
+
+### 判据本身走过的两条错路（都留在代码注释与 `internal/ERRORS.md` 里）
+
+- 第一版按「类名是否定义在组件样式里」判标本 → `sparkline.css` 里
+  `.row > .sparkline` 这种后代选择器把排版类收进了类名表（假绿）；
+  而 `separator` 那个 `<div class="line">` 的类定义在 **demo 自己的
+  `<style>`** 里，真标本被判成没标本（假红）。
+- 第二版按「有没有边框/底色」判 → `tooltip`（`div.tt-field`）、
+  `tree`（`div.tree__node`）、`report`（`<p class="rep-p">`）三处
+  **纯文字构成的真标本**被冤枉。这一库有大量反例的差别就在字号、
+  字重、行高、颜色上，这些东西不产生边框。
+
+### 补上的 10 处标本（另有 3 块实在摆不出来，写了 `data-prose`）
+
+`separator` ×2（真渲染 `<hr>` 与 `div` 分隔线）、`switch` ×2（假开关与
+丢了 label 的开关）、`accordion` ×2（div trigger、`max-height:0` 里仍可
+Tab 的链接）、`tabs` ×2（div 当 tab、三个 `tabindex="0"`）、`badge` ×1
+（长得一样但 Tab 不到的 div）、`overlay` ×1（一条「文件已删除」的真 toast）。
+
+### 登记的 10 页（不假装解决）
+
+- **可量但本轮没做（5 页）**：`choice` / `separator` / `switch` /
+  `accordion` / `tabs` —— 差别用 `count` / `h` 就能写成互斥断言
+  （`<hr>` 个数 0 vs 1、`input` 个数 0 vs 1…），缺的是把页面重排成 `cmp`。
+  **这是欠账，不是边界**，理由里原话写着。
+- **量不了（5 页）**：`badge`（对比度与焦点可达性，`demo-claim` 没有这两个
+  指标）、`form-validation`（时序与措辞）、`overlay`（运行时焦点落点）、
+  `echarts-adapter`（没有图表实例可摆）、`sparkline`（读屏输出与
+  `reduced-motion`）。
+
+### 契约变化（一处，如实记录）
+
+`ai/components.json` 里 `switch` 的 `aria.attrs` 从 `[]` 变成 `["checked"]`。
+原因是新加的反例真的写了 `aria-checked`（那一块讲的就是"手写这个属性"），
+而抽取器只取 `aria-` 后面的名字（与 `expanded` 同约定）。原生
+`<input role="switch">` 并不需要它 —— 这条是**反例带进契约**的。
+选择保留并写在这里，而不是悄悄让它躺在 diff 里（`internal/ERRORS.md` E122）。
+
+### 门禁
+
+条数不变（197 道，本轮没有新增门禁文件，只是同一道门禁多了两条判据）。
+
+两处**门禁自身**的改动：
+
+- `a11y-ax` 从 10 页扩到 **11 页**，新增 `accordion`（`button + expanded +
+  受控 region` 这一组关系，与 `tablist` 的 `selected/controls` 不同源；
+  而 `accordion-contract.js` 查的是"属性写得对不对"，查不到"读屏实际念出什么"）。
+  加进去之后顺带证实：`max-height:0` 那块里被裁掉的 `<a>` **仍在无障碍树里**
+  （快照里是 `link "里面的这个链接，Tab 也仍然进得去"`），反例不是嘴上说的。
+- 三页的朗读序列快照更新（`switch` / `tabs` / `overlay`）—— 都是因为新增了
+  真标本：假开关现在会被念成 `switch "开启动价推送"`，假 tablist 会被念成
+  `tablist "基本信息 高级设置"`，`「文件已删除」` 那条 toast 会被念成
+  `status [live=polite atomic=true]`。三处都逐条核过，不是照单全收。
+
+### 自己踩的坑（`internal/ERRORS.md` E119–E123）
+
+- **E119/E120**：判"有没有标本"的两条错路（类名定义表 / 边框底色），
+  两头都有误判实例，都留在代码注释里。
+- **E121**：自检结论把"必须绿"的用例算进了"反向控制"总数 —— 数字对、
+  措辞撒谎。
+- **E122**：反例把 `aria-checked` 带进了对外契约（见上一节）。
+- **E123**：给反例的 `div` 顺手补了 `aria-expanded`，`axe` 报
+  `aria-allowed-attr` —— 反例里写"正确答案"会让反例变成半成品正例。
+
 ## [0.11.12] - 2026-10-29
 
 **反例从「看得见」走到「量得出」**。0.11.11 把 24 个对照块摆了出来，

package/CONTRIBUTING.md

@@ -120,7 +120,24 @@ fix: <一句话说清改了什么、为什么>
    `nav` 的反例长标题根本没换行（`.toc__link` 自带 `nowrap`，只是被裁掉），
    `list` 同形，`dropdown` 的反例写了 `display:flex` 绕开了真实的 24px 坑。
    只判"块在不在"时，这三处全是绿的。
-   ⇒ **写不出断言的块，说明那个反例量化不了，那就别摆出来。**
+   ⇒ **写不出断言的块，先看第 8 条**：要么补标本让它可量，要么写明为什么量不了。
+8. **反例块里必须有标本；摆不出来就写清理由。**
+   `box bad` / `cmp__bad` 里出现"标题 + 一段说明"这种形态，`demo-claim` 会红。
+   这不是假想的洁癖：0.11.12 发布后扫了全部 34 个 demo 页，**13 个反例块
+   一个标本都没有** —— `separator` 标题写着"用 div + border-bottom 代替 hr"，
+   块里连那个 div 都没有，只有一段话在描述它。读者学不到任何看得见的东西。
+   摆不出可见标本的（运行时行为、读屏输出、读者要自己按 Tab 才能发现、
+   页面上没有图表实例），写在块上：
+   `data-prose="为什么摆不出来"`。理由至少 8 个字，会被逐条打印出来，可以被反驳。
+   只有 `box bad` 单栏、配不出 `cmp` 结构的块，要在**块上**写
+   `data-claim-skip="为什么写不出互斥断言"`。
+   **理由要区分"量不了"和"可量但没做"**：后者是欠账，写明白，别混进前者
+   —— 一句"量化不了"掩盖一处没做的活，比不写更糟。
+9. **能配成对的，必须配成对。** `demo-claim` 里有一个指标（`focus`：
+   "按 Tab 能不能停上去"）就是为"键盘到不了"这类反例加的 ——
+   `choice` / `switch` / `accordion` / `tabs` 四页的单栏反例，
+   0.11.14 全部改成了成对结构，因为它们**本来就可量**，差的只是有人去重排。
+   ⇒ 写"量不了"之前先问一句：**是新指标的事，还是我没做？**
 
 ## 提 PR 之前
 

package/ai/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "generatedBy": "05-audit/gen-ai-contract.py",
-  "libraryVersion": "0.11.12",
+  "libraryVersion": "0.11.14",
   "$comment": "机器可读的组件契约。slots = BEM 元素名（在本库里元素名就是插槽名），states.enum = 组件会在 DOM 上写出的 data-* 取值，states.legacyClass = 仍未收敛到 data 属性的历史状态类（INVARIANT I-8 未达标）。",
   "maturityCriteria": {
     "alpha": "缺 demo.html 或缺 05-audit 下的专属门禁 ⇒ 还没被机器验证过，不要用",
@@ -1725,7 +1725,9 @@
         "roles": [
           "switch"
         ],
-        "attrs": []
+        "attrs": [
+          "checked"
+        ]
       },
       "usesOtherNamespaces": [],
       "global": null,

package/dist/COSTS.md

@@ -49,7 +49,7 @@
 ## 三、全库
 
 - 全部组件都用上（min，含 tokens 一份）：**60.0 KB**
-- 源码版（带注释）全库 gzip：290.9 KB
+- 源码版（带注释）全库 gzip：291.2 KB
 
 > ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 66% 是注释，字节口径）。
 > 它的用途只有一个 —— 让人看清"dist 到底省了多少"。

package/index.html

@@ -92,7 +92,7 @@ li a:active { background: var(--surface-sunken); }
   </p>
 </main>
 <footer class="wrap">
-  <p class="note">0.11.12 · 零第三方运行时依赖</p>
+  <p class="note">0.11.14 · 零第三方运行时依赖</p>
 </footer>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcss",
-  "version": "0.11.12",
+  "version": "0.11.14",
   "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
   "keywords": [
     "css",