iter(g288): 文档步骤下限提到 4 条

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T15:17:13.022Z",
+  "generatedAt": "2026-10-26T15:18:04.340Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -1051,7 +1051,8 @@
             "steps": [
               "纯状态文案直接传 label，配 variant 定语义色",
               "要显示数量传 count（如未读数），超过 max（缺省 99）自动渲染成 99+",
-              "只提示「有更新」用 dot: true，配合 label 给出读屏名（如「有未读消息」）"
+              "只提示「有更新」用 dot: true，配合 label 给出读屏名（如「有未读消息」）",
+              "不要给 badge 挂点击：它不是按钮（无 tabindex 也无键盘响应）；「点角标进消息中心」应当把 badge 塞进 button 里，让按钮承担语义"
             ]
           },
           {
@@ -1658,7 +1659,8 @@
             "steps": [
               "在区块之间插入 divider 划分内容层次",
               "传 label 在水平线上显示居中文案，如「更多信息」",
-              "工具栏内用 vertical: true 的行内竖线，dashed: true 切虚线弱化分隔感"
+              "工具栏内用 vertical: true 的行内竖线，dashed: true 切虚线弱化分隔感",
+              "分割线是纯视觉件：没有 role 也没有焦点，读屏不会播报它。真要让读屏理解分组，用 heading 或 section，别指望横线"
             ]
           },
           {
@@ -4039,7 +4041,8 @@
             "steps": [
               "传字符串展示单键帽：kbd({ keys: \"Esc\" })，适合文档里说明单个按键",
               "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）",
-              "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感"
+              "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感",
+              "组件只画键帽，不做平台映射：Ctrl 与 ⌘ 的替换由调用方按平台判断后传进来（写死 Ctrl 在 Mac 上就是错的）"
             ]
           },
           {
@@ -4064,7 +4067,8 @@
             "steps": [
               "传 text + keyword 即可，命中片段以淡黄 mark 底展示，适合搜索结果 / 补全列表的匹配说明",
               "两个入参都接受信号：搜索框输入实时联动高亮，无需手动重渲染",
-              "大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略"
+              "大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略",
+              "keyword 为空或纯空白时原样返回文本，既不抛错也不全高亮：搜索框清空那一刻不用特判"
             ]
           },
           {

AGENTS.md

@@ -27,7 +27,7 @@
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html
 - `apps/docs`：文档站，纯产物（ua docs 生成）
 
-**门禁一条龙**：`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual + audit:contrast + audit:motion，提交前必过。其中 `smoke` 是三段断言：`@ui-arch/frame` 14 条（信号读写与同值短路、effect 注销与条件分支重追踪、computed 链式派生、多订阅者扇出）+ `@ui-arch/table-core` 31 条（排序 / 筛选 / 分页 / 选择的派生管线 + setRows 换源与失效行剔除 + 越界页码回写）+ `@ui-arch/ui` 8 条（皮肤层纯逻辑：行级差异的剪前后缀 / LCS 对齐 / 忽略空白 / 超限退化，跑的是 dist/diffKit.js）；改内核语义或纯逻辑前先跑它，别靠组件 demo 肉眼验。`ua audit:visual` 统计皮肤包里十四类硬编码视觉字面量（字号 / 动效时长 / 阴影 / 圆角 / 焦点环 / 内距 / 控件高度 / 字重 / 行高 / 层级 / 边框色 / 混色浓度 / transform 位移 / 焦点描边）并与 `.ua/visual-baseline.json` 做棘轮：任一类超过基线即退出码 1 并指出疑似引入的提交；迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`ua audit:contrast` 走另一条线：把令牌里 18 组「前景色 × 底色」配对（正文/次级/辅助文字 × 页面底/表面/凹陷底、强调色与其反白、语义三色、禁用态豁免档、焦点描边 × 页面底/表面）按 WCAG 公式算成对比度（支持 `color-mix` 与 `var()` 求值，半透明底先压到页面底色上），亮 / 暗 × 常规 / 高对比四套主题各算一遍，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）即退出码 1；`--json` 出逐对明细，`--list` 只列配对表。改任一颜色令牌后它会立刻告诉你「改完谁读不清了」，不必等人工目测暗色。`ua audit:motion` 守的是动效面，两类必查：① 带 `infinite` 的动画是否在 `prefers-reduced-motion: reduce` 块里被 `animation: none` 关掉——循环动画是前庭敏感用户的硬伤，漏一条整页就在抖（它抓出过转圈与不确定态进度两处漏网）；② 悬停 / 按压的位移（`translate`）是否在减少动效下归零——位移最容易诱发前庭不适，且只提供手感、不表达状态（一条 `ua-` 类通配的 `transform: none !important` 兜住全站 14 处，新增组件不用各自补）。③ 旋转 / 缩放这类第三类空间动效（折叠箭头、按压缩放）是否有「只留颜色过渡」的收窄兜底——空间变换即时到位、状态仍看得见（一条通配 `transition-property` 收窄兜住全站 35 处）。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致（docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、每个文档字段名必须在组件实现源码里真实出现（改名后忘改文档会直接报错）、反向也校验 `src/types.ts` 里 `<组件>Props`（可用清单的 `propsType` 覆盖接口名，`false` 表示无入参）每个字段都在文档 props 表登记（新加字段忘了写文档会报错）、demo 锚点必须在 `apps/demo/main.ts` 中存在，且该组件必须被 demo 真实调用 `id(` / `id.`），反向也查孤儿演示（demo 里用 section() 定义的每个区块都必须被某个组件的 demo 字段认领，加了区块忘登记会直接报错），检查皮肤包样式表无硬编码颜色（`#hex` 一律禁止，必须走 `--ua-*` 令牌）与令牌引用有效（`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量）、核对每个 `--ua-color-*` 都在 `[data-theme='dark']` 里有覆盖值且暗色块没有凭空多出的变量名（新增颜色令牌漏写暗色值直接报错）、核对 `tokens.json` 的 `color` 键与 tokens.css 的 `--ua-color-*` 同名同值（名字按 camelCase → kebab 折算，亮色值与暗色值都比，双向查漏——只改一处时文档色板会凭空多/少一个令牌，过去只能靠人眼发现）、核对 `@keyframes` 没有「帧体完全相同但名字不同」的复制粘贴（同一段动效只该有一份声明，改名复制会让方向 / 时长各写各的，翻转态就出现过「朝反方向入场」），核对 README 的 `<!-- ua:components -->` 区块与「分组：」行都覆盖清单组件集合（漏写/多写/重复都报错），并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应（另外查 backlog id 不重复、g 编号严格递增、同一 id 只有一条 done 留痕，且留痕 ts 带 +08:00、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑）；配方还要求编号连续、每条都有代码块与要点，且代码块里至少认出一个已注册组件 id（拼错组件名时 `ua recipes` 会把它列成空组件表）。
+**门禁一条龙**：`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual + audit:contrast + audit:motion，提交前必过。其中 `smoke` 是三段断言：`@ui-arch/frame` 14 条（信号读写与同值短路、effect 注销与条件分支重追踪、computed 链式派生、多订阅者扇出）+ `@ui-arch/table-core` 31 条（排序 / 筛选 / 分页 / 选择的派生管线 + setRows 换源与失效行剔除 + 越界页码回写）+ `@ui-arch/ui` 8 条（皮肤层纯逻辑：行级差异的剪前后缀 / LCS 对齐 / 忽略空白 / 超限退化，跑的是 dist/diffKit.js）；改内核语义或纯逻辑前先跑它，别靠组件 demo 肉眼验。`ua audit:visual` 统计皮肤包里十四类硬编码视觉字面量（字号 / 动效时长 / 阴影 / 圆角 / 焦点环 / 内距 / 控件高度 / 字重 / 行高 / 层级 / 边框色 / 混色浓度 / transform 位移 / 焦点描边）并与 `.ua/visual-baseline.json` 做棘轮：任一类超过基线即退出码 1 并指出疑似引入的提交；迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`ua audit:contrast` 走另一条线：把令牌里 18 组「前景色 × 底色」配对（正文/次级/辅助文字 × 页面底/表面/凹陷底、强调色与其反白、语义三色、禁用态豁免档、焦点描边 × 页面底/表面）按 WCAG 公式算成对比度（支持 `color-mix` 与 `var()` 求值，半透明底先压到页面底色上），亮 / 暗 × 常规 / 高对比四套主题各算一遍，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）即退出码 1；`--json` 出逐对明细，`--list` 只列配对表。改任一颜色令牌后它会立刻告诉你「改完谁读不清了」，不必等人工目测暗色。`ua audit:motion` 守的是动效面，两类必查：① 带 `infinite` 的动画是否在 `prefers-reduced-motion: reduce` 块里被 `animation: none` 关掉——循环动画是前庭敏感用户的硬伤，漏一条整页就在抖（它抓出过转圈与不确定态进度两处漏网）；② 悬停 / 按压的位移（`translate`）是否在减少动效下归零——位移最容易诱发前庭不适，且只提供手感、不表达状态（一条 `ua-` 类通配的 `transform: none !important` 兜住全站 14 处，新增组件不用各自补）。③ 旋转 / 缩放这类第三类空间动效（折叠箭头、按压缩放）是否有「只留颜色过渡」的收窄兜底——空间变换即时到位、状态仍看得见（一条通配 `transition-property` 收窄兜住全站 35 处）。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致（docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、steps 至少 4 条（少于 4 条说明这组件还没想清楚边界）、每个文档字段名必须在组件实现源码里真实出现（改名后忘改文档会直接报错）、反向也校验 `src/types.ts` 里 `<组件>Props`（可用清单的 `propsType` 覆盖接口名，`false` 表示无入参）每个字段都在文档 props 表登记（新加字段忘了写文档会报错）、demo 锚点必须在 `apps/demo/main.ts` 中存在，且该组件必须被 demo 真实调用 `id(` / `id.`），反向也查孤儿演示（demo 里用 section() 定义的每个区块都必须被某个组件的 demo 字段认领，加了区块忘登记会直接报错），检查皮肤包样式表无硬编码颜色（`#hex` 一律禁止，必须走 `--ua-*` 令牌）与令牌引用有效（`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量）、核对每个 `--ua-color-*` 都在 `[data-theme='dark']` 里有覆盖值且暗色块没有凭空多出的变量名（新增颜色令牌漏写暗色值直接报错）、核对 `tokens.json` 的 `color` 键与 tokens.css 的 `--ua-color-*` 同名同值（名字按 camelCase → kebab 折算，亮色值与暗色值都比，双向查漏——只改一处时文档色板会凭空多/少一个令牌，过去只能靠人眼发现）、核对 `@keyframes` 没有「帧体完全相同但名字不同」的复制粘贴（同一段动效只该有一份声明，改名复制会让方向 / 时长各写各的，翻转态就出现过「朝反方向入场」），核对 README 的 `<!-- ua:components -->` 区块与「分组：」行都覆盖清单组件集合（漏写/多写/重复都报错），并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应（另外查 backlog id 不重复、g 编号严格递增、同一 id 只有一条 done 留痕，且留痕 ts 带 +08:00、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑）；配方还要求编号连续、每条都有代码块与要点，且代码块里至少认出一个已注册组件 id（拼错组件名时 `ua recipes` 会把它列成空组件表）。
 
 `ua verify` 另外校验 `ITERATION.md` 的《视觉回归抽查清单》：button / textField / select / modal / dataTable / toast / layout / jsonViewer / diffView / codeBlock / signaturePad / heatmap / sparkline 十三段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥39 条（下限由段数 × 3 推导，加抽查位不必手改）且五维度全覆盖——视觉类条目收尾前照单过一遍，改清单时别把条目删漏。
 
@@ -76,7 +76,7 @@
 | 3 | `packages/skin/ui/src/index.ts` | 末尾追加 `export { xxx } from './xxx.js';` |
 | 4 | `packages/skin/ui/ui.css` | 样式只消费 `--ua-*`（禁 `#hex`），动效要带 `prefers-reduced-motion` 兜底；**禁止新增硬编码 `box-shadow` / 动效时长 / `font-size` 字面值**，一律用 elevation（`--ua-shadow-1..4`）/ motion（`--ua-duration-*` + `--ua-ease`）/ 字号（`--ua-font-size-*`）令牌，焦点环用 `--ua-focus-ring`，`npm run audit:visual` 会让计数上涨的提交直接红 |
 | 5 | `packages/skin/ui/ua.manifest.json` → `api.exports` | 一行 `xxx(props)：一句话说明` |
-| 6 | 同上 → `docs.components` | `{ id, title, demo, props[], example, steps[] }`：props 里每个字段名必须在实现源码里真实出现，且 `<组件>Props` 的字段一个都不能漏（verify 双向校验） |
+| 6 | 同上 → `docs.components` | `{ id, title, demo, props[], example, steps[] }`：props 里每个字段名必须在实现源码里真实出现，且 `<组件>Props` 的字段一个都不能漏（verify 双向校验）；`steps` 至少 4 条（怎么传 / 怎么联动 / 边界行为 / 什么时候别用它） |
 | 7 | `apps/demo/main.ts` | 新增 `section('<demo 锚点>', ...)` 并**真实调用**该组件（verify 会查） |
 | 8 | `README.md` | `<!-- ua:components -->` 区块补 id、「分组：」行补归组（数字交给下一步自动同步） |
 | 9 | `npm run sync-counts` | 自动把三份文档里的「N 个组件 / 共 N 个」改成清单实际数量（幂等；漏改时 verify 报行号） |

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T15:17:13.022Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T15:18:04.340Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -471,6 +471,7 @@ badge({ label: '成功', variant: 'success' })
 1. 纯状态文案直接传 label，配 variant 定语义色
 2. 要显示数量传 count（如未读数），超过 max（缺省 99）自动渲染成 99+
 3. 只提示「有更新」用 dot: true，配合 label 给出读屏名（如「有未读消息」）
+4. 不要给 badge 挂点击：它不是按钮（无 tabindex 也无键盘响应）；「点角标进消息中心」应当把 badge 塞进 button 里，让按钮承担语义
 
 现场演示：apps/docs/demo.html#sec-feedback
 
@@ -833,6 +834,7 @@ divider({ label: '更多信息' }) / divider({ vertical: true })
 1. 在区块之间插入 divider 划分内容层次
 2. 传 label 在水平线上显示居中文案，如「更多信息」
 3. 工具栏内用 vertical: true 的行内竖线，dashed: true 切虚线弱化分隔感
+4. 分割线是纯视觉件：没有 role 也没有焦点，读屏不会播报它。真要让读屏理解分组，用 heading 或 section，别指望横线
 
 现场演示：apps/docs/demo.html#sec-divider
 
@@ -2127,6 +2129,7 @@ kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] })
 1. 传字符串展示单键帽：kbd({ keys: "Esc" })，适合文档里说明单个按键
 2. 传数组展示组合键：kbd({ keys: ["Ctrl", "K"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）
 3. 常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感
+4. 组件只画键帽，不做平台映射：Ctrl 与 ⌘ 的替换由调用方按平台判断后传进来（写死 Ctrl 在 Mac 上就是错的）
 
 现场演示：apps/docs/demo.html#sec-kbd
 
@@ -2148,6 +2151,7 @@ highlight({ text: 'Alpha Beta', keyword: 'beta' })
 1. 传 text + keyword 即可，命中片段以淡黄 mark 底展示，适合搜索结果 / 补全列表的匹配说明
 2. 两个入参都接受信号：搜索框输入实时联动高亮，无需手动重渲染
 3. 大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略
+4. keyword 为空或纯空白时原样返回文本，既不抛错也不全高亮：搜索框清空那一刻不用特判
 
 现场演示：apps/docs/demo.html#sec-highlight
 

packages/skin/ui/ua.manifest.json

@@ -922,7 +922,8 @@
         "steps": [
           "纯状态文案直接传 label，配 variant 定语义色",
           "要显示数量传 count（如未读数），超过 max（缺省 99）自动渲染成 99+",
-          "只提示「有更新」用 dot: true，配合 label 给出读屏名（如「有未读消息」）"
+          "只提示「有更新」用 dot: true，配合 label 给出读屏名（如「有未读消息」）",
+          "不要给 badge 挂点击：它不是按钮（无 tabindex 也无键盘响应）；「点角标进消息中心」应当把 badge 塞进 button 里，让按钮承担语义"
         ]
       },
       {
@@ -1529,7 +1530,8 @@
         "steps": [
           "在区块之间插入 divider 划分内容层次",
           "传 label 在水平线上显示居中文案，如「更多信息」",
-          "工具栏内用 vertical: true 的行内竖线，dashed: true 切虚线弱化分隔感"
+          "工具栏内用 vertical: true 的行内竖线，dashed: true 切虚线弱化分隔感",
+          "分割线是纯视觉件：没有 role 也没有焦点，读屏不会播报它。真要让读屏理解分组，用 heading 或 section，别指望横线"
         ]
       },
       {
@@ -3910,7 +3912,8 @@
         "steps": [
           "传字符串展示单键帽：kbd({ keys: \"Esc\" })，适合文档里说明单个按键",
           "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）",
-          "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感"
+          "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感",
+          "组件只画键帽，不做平台映射：Ctrl 与 ⌘ 的替换由调用方按平台判断后传进来（写死 Ctrl 在 Mac 上就是错的）"
         ]
       },
       {
@@ -3935,7 +3938,8 @@
         "steps": [
           "传 text + keyword 即可，命中片段以淡黄 mark 底展示，适合搜索结果 / 补全列表的匹配说明",
           "两个入参都接受信号：搜索框输入实时联动高亮，无需手动重渲染",
-          "大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略"
+          "大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略",
+          "keyword 为空或纯空白时原样返回文本，既不抛错也不全高亮：搜索框清空那一刻不用特判"
         ]
       },
       {

packages/tools/cli/bin/ua.js

@@ -1591,7 +1591,7 @@ function cmdVerify() {
       if (seen.has(c.id)) issues.push(`${tag}: id 重复`);
       seen.add(c.id);
       if (!c.example) issues.push(`${tag}: 缺少 example`);
-      if ((c.steps ?? []).length < 3) issues.push(`${tag}: steps 少于 3 条`);
+      if ((c.steps ?? []).length < 4) issues.push(`${tag}: steps 少于 4 条（每件至少给 4 步：怎么传 / 怎么联动 / 边界行为 / 什么时候别用它）`);
       if (!exports.some((e) => e.startsWith(`${c.id}(`) || e.startsWith(`${c.id}.`))) {
         issues.push(`${tag}: api.exports 中没有以「${c.id}(」或「${c.id}.」开头的条目`);
       }