iter(g186): 固化视觉回归抽查清单

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T09:45:15.809Z",
+  "generatedAt": "2026-10-26T09:47:35.873Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -3728,7 +3728,7 @@
           "ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单",
           "ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
           "ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
-          "ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）",
+          "ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
           "ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
           "ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数",
           "ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe"

AGENTS.md

@@ -29,6 +29,8 @@
 
 **门禁一条龙**：`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual，提交前必过。`ua audit:visual` 统计皮肤包里五类硬编码视觉字面量（字号 / 动效时长 / 阴影 / 圆角 / 焦点环）并与 `.ua/visual-baseline.json` 做棘轮：任一类超过基线即退出码 1 并指出疑似引入的提交；迁移脚本 `npm run visual:migrate` 可把字面量幂等改写成令牌。`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.`），检查皮肤包样式表无硬编码颜色（`#hex` 一律禁止，必须走 `--ua-*` 令牌）与令牌引用有效（`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量）、核对每个 `--ua-color-*` 都在 `[data-theme='dark']` 里有覆盖值且暗色块没有凭空多出的变量名（新增颜色令牌漏写暗色值直接报错），核对 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 六段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥18 条且五维度全覆盖——视觉类条目收尾前照单过一遍，改清单时别把条目删漏。
+
 **变更日志**：`CHANGELOG.md` 由 git 提交史生成（`npm run changelog`），**不进 `npm run check`**——它包含每个提交自身，提交后必然与历史差一条，只能作为「发版前刷新」步骤；`npm run changelog:check` 用于确认是否漂移。
 
 **提交信息规范**：`COMMITTING.md`（`<type>(<scope>): <中文祈使句>`），`ua commit-lint` + commit-msg 钩子自动校验，迭代提交用 `iter(<条目id>): <subject>`。

ITERATION.md

@@ -64,6 +64,60 @@ qa/probe ──门禁通过──▶ qa/stable ──人工审阅──▶ main
 2. **视觉欠账优先**：只要存在 `status === "open"` 且 `domain === "visual"` 的条目，它的优先级高于 `domain === "new"` 的条目——先清视觉欠账，再加新组件（视觉地基不牢，新组件只是把漂移再复制一份）。
 3. **新增组件的入库门槛**：`domain === "new"` 的条目，验收标准里必须写明「样式只消费 `--ua-*` 令牌，禁止新增硬编码阴影/时长/字号」，否则该条不得入库。视觉类改进的验收标准要能落到 `npm run audit:visual` 的计数上（涨了就是没做完）。
 
+## 视觉回归抽查清单（人工，视觉类条目收尾时逐条过）
+
+视觉改动只能靠人眼验收，凭记忆看一遍必然漏项。本节把六个高频组件的观感要点固化成可勾选项，视觉类条目（`domain === "visual"`）提交前照单过一遍，勾不上的就是没做完。
+
+- **格式约定**：三条横线以下是清单本体，每个组件一个 `### <组件id>` 段，每条以 `- [ ] 【维度】` 开头；维度取值固定五类：`边框` / `阴影` / `过渡` / `焦点环` / `暗色`。
+- **门禁口径**：`ua verify` 校验本节存在、六个组件齐全、每个组件 ≥3 条、合计 ≥18 条、五个维度全覆盖；条目改写或删漏直接报错。
+- **与自动门禁的分工**：`npm run audit:visual` 管「字面量有没有回流成硬编码」，本节管「令牌用对了但观感对不对」——两者都过才算一轮视觉改动完成。
+
+---
+
+### button
+
+- [ ] 【边框】次按钮与描边按钮的 1px 描边在页面底与卡片底上亮度一致，不出现某个按钮偏黑
+- [ ] 【阴影】hover 只上浮 1–2px 且走 elevation 令牌，没有「影子 + 边框」双层叠加
+- [ ] 【过渡】hover 上浮与按下回缩能看出先后，时长不超过 `--ua-duration-fast`
+- [ ] 【焦点环】键盘 Tab 到按钮时环完整贴边不被容器裁切，与描边按钮的描边不重影
+- [ ] 【暗色】暗色下主按钮文字与底色对比仍够，描边按钮的边不消失
+
+### textField
+
+- [ ] 【边框】默认 / hover / 聚焦三态只变色不变粗细（1px 始终 1px）
+- [ ] 【焦点环】聚焦是光环外扩而非描边变粗；带前后缀时环包住整组而不只是输入框
+- [ ] 【过渡】聚焦与失焦的边框色过渡在 `--ua-duration-fast` 内完成，无闪烁感
+- [ ] 【暗色】暗色下占位文字（placeholder）与输入文字都可读，边框仍可见
+
+### select
+
+- [ ] 【边框】触发器与相邻 textField 同高同粗细，并排时基线不歪
+- [ ] 【阴影】下拉弹层用 `--ua-shadow-2` 档，出现在滚动容器内时边缘不被裁成硬边
+- [ ] 【过渡】弹层进出各一次（位移 + 淡入），关闭后不残留一帧
+- [ ] 【焦点环】键盘 ↑↓ 唤出弹层时焦点环留在触发器上，不跳到 body
+
+### modal
+
+- [ ] 【阴影】弹窗用 `--ua-shadow-4`，与遮罩形成明确层级，不糊成一片
+- [ ] 【边框】页头 / 页脚分割线用 `--ua-border-subtle`，观感与卡片页脚一致
+- [ ] 【过渡】弹入有轻微缩放位移，Esc 关闭后无残影、无布局跳动
+- [ ] 【焦点环】打开后焦点落在弹窗内首个可聚焦元素，Tab 不逃出弹窗
+- [ ] 【暗色】暗色下弹窗表面与遮罩可区分，标题与正文层级仍清楚
+
+### dataTable
+
+- [ ] 【边框】行分割线用 `--ua-border-subtle`，连续 20 行不显重，表头下沿不发黑
+- [ ] 【阴影】粘性表头滚动透底无效（背景实色 + 底部 1px 细线贴合）
+- [ ] 【过渡】行 hover 与选中底色过渡柔和，选中行不抢表头与首列的视线
+- [ ] 【暗色】暗色下斑马纹可辨但不突兀，选中行与 hover 行仍能区分
+
+### toast
+
+- [ ] 【阴影】通知用最高档投影，堆叠三条时前后层级清楚
+- [ ] 【边框】通知卡片描边不抢语义色图标，警示色不溢出到边框
+- [ ] 【过渡】进场 / 出场各一次，堆叠时其余条目平滑让位，不出现跳位
+- [ ] 【暗色】四种语义色（info / success / warning / error）在暗底上图标与文字都不糊
+
 ## 人工介入点
 
 - 审阅 `qa/stable` 的提交，确认质量后合入 `main`（PR 或本地 merge 后推送）。

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T09:45:15.809Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T09:47:35.873Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2120,7 +2120,7 @@ API 速览：
 - ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单
 - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
 - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
-- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）
+- ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
 - ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
 - ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数
 - ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe

llms.txt

@@ -133,7 +133,7 @@
   - ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单
   - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
   - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
-  - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）
+  - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）
   - ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
   - ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数
   - ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe

packages/tools/cli/bin/ua.js

@@ -1235,6 +1235,52 @@ function checkPropsDoc(pkg, comps) {
   return issues;
 }
 
+/*** 视觉回归抽查清单校验：ITERATION.md 的清单必须六个高频组件齐全、每条带合法维度标签、条目数达标 ***/
+function checkVisualChecklist() {
+  const DIMS = ['边框', '阴影', '过渡', '焦点环', '暗色']; // 五个必覆盖维度
+  const REQUIRED = ['button', 'textField', 'select', 'modal', 'dataTable', 'toast']; // 六个代表组件
+  const MIN_PER_GROUP = 3; // 每个组件至少三条可勾选要点
+  const MIN_TOTAL = 18; // 清单总条目下限
+  const file = path.join(ROOT, 'ITERATION.md');
+  if (!fs.existsSync(file)) return ['视觉回归抽查清单：找不到 ITERATION.md'];
+  const lines = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n').split('\n');
+  const start = lines.findIndex((l) => /^##\s+视觉回归抽查清单/.test(l));
+  if (start === -1) return ['视觉回归抽查清单：ITERATION.md 缺少《视觉回归抽查清单》章节'];
+  const rest = lines.slice(start + 1);
+  const stop = rest.findIndex((l) => /^##\s+/.test(l)); // 下一个二级标题即章节结束
+  const body = stop === -1 ? rest : rest.slice(0, stop);
+  const issues = [];
+  const groups = new Map(); // 组件 id → 该段的维度标签列表
+  let current = null;
+  for (const line of body) {
+    const head = line.match(/^###\s+(\S+)/);
+    if (head) {
+      current = head[1];
+      if (!groups.has(current)) groups.set(current, []);
+      continue;
+    }
+    const item = line.match(/^-\s+\[[ x]\]\s+【([^】]+)】/);
+    if (!item) continue;
+    if (!current) {
+      issues.push(`视觉回归抽查清单：条目「${line.trim().slice(0, 24)}」没有归到任何 ### 组件段下`);
+      continue;
+    }
+    if (!DIMS.includes(item[1])) issues.push(`视觉回归抽查清单：${current} 的条目维度「${item[1]}」不在五类之内（${DIMS.join(' / ')}）`);
+    groups.get(current).push(item[1]);
+  }
+  for (const id of REQUIRED) {
+    const items = groups.get(id);
+    if (!items) issues.push(`视觉回归抽查清单：缺少 ### ${id} 段`);
+    else if (items.length < MIN_PER_GROUP) issues.push(`视觉回归抽查清单：${id} 只有 ${items.length} 条要点，至少 ${MIN_PER_GROUP} 条`);
+  }
+  const total = [...groups.values()].reduce((sum, items) => sum + items.length, 0);
+  if (total < MIN_TOTAL) issues.push(`视觉回归抽查清单：合计 ${total} 条要点，至少 ${MIN_TOTAL} 条`);
+  const covered = new Set([...groups.values()].flat());
+  const missed = DIMS.filter((d) => !covered.has(d));
+  if (missed.length) issues.push(`视觉回归抽查清单：维度未覆盖 ${missed.join(' / ')}（五类都要有）`);
+  return issues;
+}
+
 /*** 清单一致性校验：组件文档块的 id / props 说明 / demo 锚点必须与代码和演示产物对齐 ***/
 function cmdVerify() {
   const issues = [];
@@ -1290,13 +1336,14 @@ function cmdVerify() {
   checkDarkTokens(issues);
   checkLlmsFull(pkgs, issues);
   issues.push(...checkIterations());
+  issues.push(...checkVisualChecklist());
 
   if (issues.length) {
     for (const it of issues) console.error('verify: ' + it);
     console.error(`${issues.length} violation(s)`);
     process.exit(1);
   }
-  console.log('verify OK (manifest ↔ docs ↔ demo 一致，文档 props ↔ 入参接口双向一致，皮肤无硬编码颜色与未定义令牌、暗色令牌齐全，README 组件清单与分组同步，backlog ↔ 留痕一致（编号严格递增、无重复 id、留痕时间线单调且带 +08:00），组合配方结构完整，MCP 工具清单三处一致)');
+  console.log('verify OK (manifest ↔ docs ↔ demo 一致，文档 props ↔ 入参接口双向一致，皮肤无硬编码颜色与未定义令牌、暗色令牌齐全，README 组件清单与分组同步，backlog ↔ 留痕一致（编号严格递增、无重复 id、留痕时间线单调且带 +08:00），组合配方结构完整，MCP 工具清单三处一致，视觉回归抽查清单六组件 × 五维度齐全)');
 }
 
 /*** 校验 git 提交信息是否符合 COMMITTING.md 规范（参数为 message 文件路径或直接 message 文本），违规退出码 1 ***/

packages/tools/cli/ua.manifest.json

@@ -17,7 +17,7 @@
       "ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单",
       "ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
       "ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
-      "ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）",
+      "ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
       "ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
       "ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数",
       "ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe"