From 9d441994ff1119b7278a1ff92b4dcd741019ba6d Mon Sep 17 00:00:00 2001 From: HIsheR Date: Mon, 26 Oct 2026 23:40:28 +0800 Subject: [PATCH] =?UTF-8?q?iter(g299):=20=E8=A7=86=E8=A7=89=E6=8A=BD?= =?UTF-8?q?=E6=9F=A5=E6=B8=85=E5=8D=95=E8=A1=A5=E9=BD=90=E4=B8=89=E4=B8=AA?= =?UTF-8?q?=E6=96=B0=E7=BB=84=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .ua/backlog.json | 9 +++++++++ AGENTS.md | 2 +- ITERATION.md | 20 ++++++++++++++++++++ packages/tools/cli/bin/ua.js | 6 +++--- 4 files changed, 33 insertions(+), 4 deletions(-) diff --git a/.ua/backlog.json b/.ua/backlog.json index 5238a80..576ba62 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -3077,6 +3077,15 @@ "motivation": "tokens --unused 报出 2 个令牌无人引用：surface-3（注释写「按下底」，但四处 :active 仍用与悬停同档的 surface-2，于是按下与悬停同色）与 font-size-xl（字号最大档没有任何组件用）。", "acceptance": "① 下拉触发器 / 折叠头 / 分页按钮 / 日历格四处按下态改 surface-3，注释「加深一档」与实现对齐；② .ua-result-title 升到 xl，与弹窗标题 lg 拉开层级；③ ua tokens --unused 归零；④ audit:surface / audit:visual / audit:contrast 全绿。", "notes": "四处 :active 改 surface-3（按下比悬停更实，与注释一致），.ua-result-title 用上 xl；tokens --unused 由 2 个降为 0，三项视觉门禁全绿" + }, + { + "id": "g299", + "domain": "tooling", + "status": "open", + "title": "视觉抽查清单补三段：commandPalette / noticeBar / progressRing", + "motivation": "清单只覆盖到 sparkline，后期新增的命令面板、通知条、环形进度没有抽查位——视觉类条目收尾时「照单过一遍」会直接跳过它们，等于裸奔。", + "acceptance": "① ITERATION.md 新增三段共 11 条，维度落在五类内；② ua.js 的 REQUIRED 从 13 扩到 16、下限自动变 48 条、OK 文案同步；③ AGENTS 的清单描述同步为十六段 ≥48 条；④ npm run verify / check 全绿。", + "notes": "" } ] } \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 3fb67fa..6e5a287 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ **门禁一条龙**：`npm run check` = build + demo + style + typecheck + smoke + index + verify + lint-iterations + audit:visual + audit:contrast + audit:motion + audit:surface，提交前必过。其中 `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 audit:surface` 补的是「底色 vs 底色」这条盲区：把表面阶梯（页面底 → 表面 → 悬停底 → 按下底，外加凹陷底）逐档按亮度比验，相邻档低于 1.04（凹陷档 1.02）即退出码 1。对比度门禁只管文字读不读得清，管不到「悬停有没有反馈」——实测过表面 → 二阶表面只有 1.008，悬停改了等于没改；`--json` 出逐档明细，`--list` 只列阶梯表。`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 的 `` 区块与「分组：」行都覆盖清单组件集合（漏写/多写/重复都报错），并交叉校验 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 推导，加抽查位不必手改）且五维度全覆盖——视觉类条目收尾前照单过一遍，改清单时别把条目删漏。 +`ua verify` 另外校验 `ITERATION.md` 的《视觉回归抽查清单》：button / textField / select / modal / dataTable / toast / layout / jsonViewer / diffView / codeBlock / signaturePad / heatmap / sparkline / commandPalette / noticeBar / progressRing 十六段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥48 条（下限由段数 × 3 推导，加抽查位不必手改）且五维度全覆盖——视觉类条目收尾前照单过一遍，改清单时别把条目删漏。 **变更日志**：`CHANGELOG.md` 由 git 提交史生成（`npm run changelog`），**不进 `npm run check`**——它包含每个提交自身，提交后必然与历史差一条，只能作为「发版前刷新」步骤；`npm run changelog:check` 用于确认是否漂移。 diff --git a/ITERATION.md b/ITERATION.md index f21e61d..254a78a 100644 --- a/ITERATION.md +++ b/ITERATION.md @@ -161,6 +161,26 @@ qa/probe ──门禁通过──▶ qa/stable ──人工审阅──▶ main - [ ] 【边框】折线不被 viewBox 边缘裁掉，末点圆点完整可见（内缩留白够） - [ ] 【过渡】数值全等时折线落在中线而不是贴顶或贴底（除零保护生效） - [ ] 【暗色】暗色下面积填充比折线淡一档，不压过主数值文字 + +### commandPalette + +- [ ] 【阴影】命令面板用最高档投影 + 遮罩，与底下的内容明确分层，不糊成一块 +- [ ] 【过渡】打开时面板轻缩放位移入场，输入过滤结果切换不跳行高 +- [ ] 【焦点环】输入框始终持有焦点，↑↓ 移动只改选中行、光环留在输入框上 +- [ ] 【暗色】暗色下选中行淡色底与未选中行可辨，快捷键角标（kbd）仍读得清 + +### noticeBar + +- [ ] 【边框】左侧语义色只出现在图标与细竖条上，卡片描边不被语义色染透 +- [ ] 【过渡】关闭走淡出退场，收起后下方内容平滑上移、不砸下来 +- [ ] 【暗色】四种语义色（info / success / warning / danger）在暗底上图标与正文都不糊 + +### progressRing + +- [ ] 【边框】轨道环与进度环同宽同圆角端点，交接处不出现缺口或重叠 +- [ ] 【过渡】进度变化时环长平滑过渡，不确定态转圈期间中心文字不抖 +- [ ] 【暗色】暗色下轨道环仍可见（不被页面底吃掉），完成态语义色不刺眼 +- [ ] 【焦点环】可聚焦（带 aria 进度语义）时焦点环贴住整个圆环外缘，不被容器裁掉 ## 人工介入点 - 审阅 `qa/stable` 的提交，确认质量后合入 `main`（PR 或本地 merge 后推送）。 diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js index b08ec62..bca7750 100644 --- a/packages/tools/cli/bin/ua.js +++ b/packages/tools/cli/bin/ua.js @@ -1510,10 +1510,10 @@ function checkPropsDoc(pkg, comps) { return issues; } -/*** 视觉回归抽查清单校验：ITERATION.md 的清单必须十一个代表组件齐全、每条带合法维度标签、条目数达标 ***/ +/*** 视觉回归抽查清单校验：ITERATION.md 的清单必须十六个代表组件齐全、每条带合法维度标签、条目数达标 ***/ function checkVisualChecklist() { const DIMS = ['边框', '阴影', '过渡', '焦点环', '暗色']; // 五个必覆盖维度 - const REQUIRED = ['button', 'textField', 'select', 'modal', 'dataTable', 'toast', 'layout', 'jsonViewer', 'diffView', 'codeBlock', 'signaturePad', 'heatmap', 'sparkline']; // 十一个代表组件：先六个高频，再加「容器 / 数据展示 / 表单录入」三类新组件的抽查位 + const REQUIRED = ['button', 'textField', 'select', 'modal', 'dataTable', 'toast', 'layout', 'jsonViewer', 'diffView', 'codeBlock', 'signaturePad', 'heatmap', 'sparkline', 'commandPalette', 'noticeBar', 'progressRing']; // 十六个代表组件：高频六个 + 容器/数据展示/表单录入三类 + 后期新增的浮层类（命令面板）与反馈类（通知条、环形进度） const MIN_PER_GROUP = 3; // 每个组件至少三条可勾选要点 const MIN_TOTAL = REQUIRED.length * MIN_PER_GROUP; // 总条目下限由组件数推导：加抽查位不用再手改这个数 const file = path.join(ROOT, 'ITERATION.md'); @@ -1630,7 +1630,7 @@ function cmdVerify() { console.error(`${issues.length} violation(s)`); process.exit(1); } - console.log('verify OK (manifest ↔ docs ↔ demo 一致，文档 props ↔ 入参接口双向一致，皮肤无硬编码颜色与未定义令牌、暗色令牌齐全、tokens.json ↔ tokens.css 名字与值双源一致、@keyframes 无复制粘贴的重复帧、滚动容器全在细条规则内，README 组件清单与分组同步，backlog ↔ 留痕一致（编号严格递增、无重复 id、留痕时间线单调且带 +08:00），组合配方结构完整，MCP 工具清单三处一致，视觉回归抽查清单十三组件 × 五维度齐全)'); + console.log('verify OK (manifest ↔ docs ↔ demo 一致，文档 props ↔ 入参接口双向一致，皮肤无硬编码颜色与未定义令牌、暗色令牌齐全、tokens.json ↔ tokens.css 名字与值双源一致、@keyframes 无复制粘贴的重复帧、滚动容器全在细条规则内，README 组件清单与分组同步，backlog ↔ 留痕一致（编号严格递增、无重复 id、留痕时间线单调且带 +08:00），组合配方结构完整，MCP 工具清单三处一致，视觉回归抽查清单十六组件 × 五维度齐全)'); } /*** 校验 git 提交信息是否符合 COMMITTING.md 规范（参数为 message 文件路径或直接 message 文本），违规退出码 1 ***/