agentcss 0.13.2 → 0.15.0

package/docs/ACCESSIBILITY.md

@@ -5,8 +5,8 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.13.2` |
-| 声明日期 | 2026-10-29 |
+| 声明适用版本 | agentcss `0.15.0` |
+| 声明日期 | 2026-10-30 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |
 | 不在范围 | 使用者拿这些组件拼出来的业务页面（那是你的无障碍责任，不是库的） |
@@ -26,7 +26,7 @@
 | SC | 名称 | 状态 | 证据 / 边界 |
 |---|---|---|---|
 | 1.1.1 | 非文本内容 | ◐ | 图标一律 `aria-hidden`，语义由文字或 `aria-label` 承担；图表类组件要求调用方给替代文本，**库替不了使用者** |
-| 1.3.1 | 信息与关系 | ✅ | `a11y-scan`（axe）+ 页面结构判据：单一 `h1`、`main`、`lang`、标题不跳级 |
+| 1.3.1 | 信息与关系 | ✅ | `a11y-scan`（axe `heading-order` / `page-has-heading-one` / `empty-heading`）+ `a11y.py` 静态层级 + **96 页运行时大纲实测（887 个标题）**：每页恰好一个 `h1`、无跳级、无空名；三条规则都做过破坏实验，确认不是"没查" |
 | 1.3.2 | 有意义的顺序 | ✅ | DOM 顺序 = 视觉顺序，无 `order` / 绝对定位重排 |
 | 1.3.3 | 感官特性 | ✅ | 说明文字不以"左边的按钮""圆形图标"指代 |
 | 1.3.4 | 方向 | ✅ | 无 `orientation` 锁定，横竖屏均可用 |
@@ -82,6 +82,7 @@
 |---|---|---|
 | `axe-core`（`a11y-scan.js`） | 39 页（37 组件 demo + 2 个非组件页） | **0 类违规**，991 条规则通过 |
 | 反向控制（注入 5 类典型违规） | 证明上一条不是"没查" | 5 类全部抓到 |
+| `heading-outline.js`（人工工具） | **全部 HTML：96 页 / 887 个标题** | 0 处跳级 · 每页恰好 1 个 `h1` · DOM 标题数 == 无障碍树 heading 数 |
 | `a11y-ax.js` 可访问性树 | **全部 `demo.html`（现 40 个）**；清单与磁盘不一致即红 | 0 个无名控件；40 份朗读序列快照在 `10-review/a11y-tree/` |
 | `contrast.py` / `dark-contrast.js` | 亮 / 暗两套，逐对实算 | 正文 ≥ 4.5:1 |
 | `zoom-reflow.js` | 40 页 × 3 条 AA 硬项 | 320px 不横滚 · 200% 不裁字 · 焦点不被遮挡 |
@@ -91,16 +92,19 @@
 
 自动化的天花板必须说清楚：**axe 只能覆盖约 30–40% 的 WCAG 问题**，而且它听不见。
 
-2026-10-30 用 NVDA 2026.3 + Edge（Windows 10 22H2）跑了一轮：把 NVDA 的朗读日志写到
+2026-10-30 用 NVDA 2026.3 + Edge（Windows 10 22H2）跑了两轮：把 NVDA 的朗读日志写到
 文件，逐条取它交给语音合成器的原文。九页结果见
 [无障碍人工测试协议](A11Y-MANUAL-PROTOCOL.md) 第三节。
 
+第一轮覆盖 Tab 遍历、禁用态、错误说明与浮层焦点；第二轮补的是**标题层级**——
+用读屏的「下一个标题」跳（`H`），逐页核对它念出的级别与页面结构是否一致。
+同一轮里把机器侧的结构扫描从 9 页扩到全站 96 页（887 个标题）。
+
 **它证明的是"NVDA 念了什么"，不等于"人听着顺不顺"。** 仍然缺：
 
 1. **人耳旁听** —— 证据是日志文本；语气、打断、重复播报这类问题不在其中。
 2. **macOS VoiceOver / Android TalkBack** —— 一条记录都没有。
-3. **标题层级（`H` 键逐级跳）** —— 本轮没做，协议表里写着"未执行"。
-4. **9 处「待人工」结论**（例如图表的替代文本是否真的描述了数据）。
+3. **9 处「待人工」结论**（例如图表的替代文本是否真的描述了数据）。
 
 这一轮还确认并修掉了一条真缺陷：`table` 的列头按钮会把排序符号 `↕` 念出来
 （来源是 `table.css` 的 `::after` 伪元素文本，Chromium 把它算进了可访问名）。
@@ -139,6 +143,7 @@
 # 一条命令跑完全部无障碍相关判据（含反向控制）
 npm run gate:fast                       # 静态层：结构 / 契约 / 文档事实
 node 05-audit/a11y-scan.js              # axe（需要本地静态服务 :8000）
+node 05-audit/heading-outline.js        # 全站标题大纲：96 页 / 887 个标题（同一服务）
 node 05-audit/a11y-ax.js                # 可访问性树 + 名称判据
 node 05-audit/zoom-reflow.js            # 200% / 320px / 焦点遮挡
 node 05-audit/rtl-render.js             # RTL 渲染 + 阿/希膨胀 + 字形镜像

package/docs/CONVENTIONS.md

@@ -194,6 +194,11 @@
 - **方向必须有非颜色的载体**：`delta` 用 `+` / `−`（U+2212）符号，
   且符号必须真的进可访问性树（CSS `::before` 生成的字符不在元素 name 里，
   但会作为独立 StaticText 出现 —— 换空串/背景图/`visibility:hidden` 就会没）。
+  ⚠️ 别把这条推广成"伪元素文本永远不影响可访问名"：**`name-from-contents` 的元素
+  （`<button>` / `<a>`）会把伪元素文本算进名字** —— `table` 的列头就是这样被念出
+  「公司 · ↕ · 按钮」的（三个引擎都实测过，见
+  [无障碍人工测试协议](A11Y-MANUAL-PROTOCOL.md)）。装饰性符号别挂在按钮上，
+  或者用 `mask` 画。
 - **容器不许再加一套方向类**。表格里只有会计正负（`num--pos` / `num--neg`），
   市场涨跌一律嵌 `<span class="delta delta--up">`
   —— 否则 `table` 会有四组颜色类，调用方每列都要记"这列用哪组"。
@@ -213,6 +218,10 @@
 | 亮/暗两套对比度达标 | `contrast.py`、`dark-contrast.js`、`component-contrast.py` |
 | 焦点环存在且不是 `outline:none` | `focus-ring-check.js` |
 | 关掉弹层后焦点回到触发点 | `focus-return-check.js` |
+| 弹层**打开那一刻**焦点就进弹层（不是等 Tab 才进） | `overlay-check.js` ③b、`drawer-check.js` ① |
+| **每条**关闭路径都要归还焦点（Esc / 点遮罩 / 关闭按钮） | `overlay-check.js` ⑤b（遮罩）+ ⑤（Esc） |
+| 装饰符号不许进可访问名（伪元素有文本就会被算进 `name-from-contents`） | `table-check.js` ⑨b |
+| 浮层类组件的每条输入路径都要测（键盘 / 点击 / 读屏合成点击） | `opener-path-check.js`（三条路径 × 五个组件一张矩阵，带 `--selftest` 证明分得清路径）+ `dropdown-check` ①b、`overlay-check` ③b、`drawer-check` ① |
 | 键盘可达（Tab 顺序、Esc 关闭） | `keyboard-nav.js` |
 | 减少动效策略双向一致 | `motion.py --reduced-audit` |
 | 逻辑属性全覆盖 | `rtl-check.js` |

package/index.html

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

package/package.json

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