diff --git a/AGENTS.md b/AGENTS.md index b2d7118..27f1f7a 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` 37 条(排序 / 筛选 / 分页 / 选择的派生管线 + setRows 换源与失效行剔除 + 越界页码回写 + setColumns 换列与失效规则剔除)+ `@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` 走另一条线:把令牌里 24 组「前景色 × 底色」配对(正文/次级/辅助文字 × 页面底/表面/凹陷底、强调色与其反白、语义三色、正文与语义色 × 三块语义淡底、禁用态豁免档、焦点描边 × 页面底/表面)按 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;同一条阶梯还多验两档「半透明 accent 淡底压在表面上」——选中底(`--ua-color-tint-accent`)与悬停底(`-weak`)各要 ≥ 1.04,浓度调低到看不出选中时它会红(实测暗色弱档降到 2% 只有 1.026,正是这条门禁要拦的),外加语义三色淡底(`--ua-color-tint-danger` / `-success` / `-warning`)各一档:这三块底调淡了提示条就退化成普通卡片。对比度门禁只管文字读不读得清,管不到「悬停有没有反馈」——实测过表面 → 二阶表面只有 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.`),外加可访问名扫描(combobox / slider / range 控件必须有 `aria-label` / `aria-labelledby` 或紧邻的 `setAttribute('aria-label')`,缺了读屏用户就摸不到控件),反向也查孤儿演示(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、时间线不回退、不落在未来——都是过去手工插条目/手写时间戳踩过的坑;反向也查:git 里每个 `iter()` 提交都必须有一行留痕,只查「留痕 → 提交」会放过「提交了却忘写留痕」,那种漏记最隐蔽——日志读起来完整,实际少记了一轮产出);配方还要求编号连续、每条都有代码块与要点,且代码块里至少认出一个已注册组件 id(拼错组件名时 `ua recipes` 会把它列成空组件表)。 -`ua verify` 另外校验 `ITERATION.md` 的《视觉回归抽查清单》:button / textField / select / modal / dataTable / toast / layout / jsonViewer / diffView / codeBlock / signaturePad / heatmap / sparkline / commandPalette / noticeBar / progressRing / sortableList / masonry 十八段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥54 条(下限由段数 × 3 推导,加抽查位不必手改)且五维度全覆盖——视觉类条目收尾前照单过一遍,改清单时别把条目删漏。 +`ua verify` 另外校验 `ITERATION.md` 的《视觉回归抽查清单》:button / textField / select / form / modal / dataTable / toast / layout / jsonViewer / diffView / codeBlock / signaturePad / heatmap / sparkline / commandPalette / noticeBar / progressRing / sortableList / masonry 十九段各 ≥3 条可勾选要点、每条维度标签必须落在边框 / 阴影 / 过渡 / 焦点环 / 暗色五类内、合计 ≥57 条(下限由段数 × 3 推导,加抽查位不必手改)且五维度全覆盖——视觉类条目收尾前照单过一遍,改清单时别把条目删漏。 **变更日志**:`CHANGELOG.md` 由 git 提交史生成(`npm run changelog`),**不进 `npm run check`**——它包含每个提交自身,提交后必然与历史差一条,只能作为「发版前刷新」步骤;`npm run changelog:check` 用于确认是否漂移。 diff --git a/ITERATION.md b/ITERATION.md index 4517200..dcbb4a1 100644 --- a/ITERATION.md +++ b/ITERATION.md @@ -97,6 +97,14 @@ qa/probe ──门禁通过──▶ qa/stable ──人工审阅──▶ main - [ ] 【过渡】弹层进出各一次(位移 + 淡入),关闭后不残留一帧 - [ ] 【焦点环】键盘 ↑↓ 唤出弹层时焦点环留在触发器上,不跳到 body +### form + +- [ ] 【边框】校验失败只把边框描红、不常驻光环:未聚焦的失败字段与正常字段粗细一致,只有颜色不同 +- [ ] 【焦点环】失败字段获得焦点时才亮危险色光环,且不与已描红的边框重影成双线 +- [ ] 【过渡】改好一项后错误文案退场、汇总条数字跟着减,字段高度不跳(错误区为空时不留白) +- [ ] 【暗色】暗色下错误文案与红边在表面底上都读得清,不被 danger 淡底吃掉 +- [ ] 【阴影】提交按钮转圈期间投影不叠加,loading 与 hover 同时成立也不出现双层阴影 + ### modal - [ ] 【阴影】弹窗用 `--ua-shadow-4`,与遮罩形成明确层级,不糊成一片 diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js index 07f53fc..925441c 100644 --- a/packages/tools/cli/bin/ua.js +++ b/packages/tools/cli/bin/ua.js @@ -1583,10 +1583,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', 'commandPalette', 'noticeBar', 'progressRing', 'sortableList', 'masonry']; // 十八个代表组件:高频六个 + 容器/数据展示/表单录入三类 + 后期新增的浮层类(命令面板)与反馈类(通知条、环形进度)+ 交互类(拖拽排序)与布局类(瀑布流) + const REQUIRED = ['button', 'textField', 'select', 'form', 'modal', 'dataTable', 'toast', 'layout', 'jsonViewer', 'diffView', 'codeBlock', 'signaturePad', 'heatmap', 'sparkline', 'commandPalette', 'noticeBar', 'progressRing', 'sortableList', 'masonry']; // 十九个代表组件:高频六个 + 表单容器(form) + 容器/数据展示/表单录入三类 + 后期新增的浮层类(命令面板)与反馈类(通知条、环形进度)+ 交互类(拖拽排序)与布局类(瀑布流) const MIN_PER_GROUP = 3; // 每个组件至少三条可勾选要点 const MIN_TOTAL = REQUIRED.length * MIN_PER_GROUP; // 总条目下限由组件数推导:加抽查位不用再手改这个数 const file = path.join(ROOT, 'ITERATION.md'); @@ -1855,7 +1855,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,每个 iter 提交都有留痕),组合配方结构完整,MCP 工具清单三处一致,搜索同义词表目标存在且无歧义,combobox / slider / range 控件都有可访问名,toast 有 live 区域与 alert 抢占播报,表单错误文案被 aria-describedby 关联、重置真复位、错误环只在聚焦时亮、汇总条随校验重算、提交按钮有忙碌态,视觉回归抽查清单十八组件 × 五维度齐全)'); + console.log('verify OK (manifest ↔ docs ↔ demo 一致,文档 props ↔ 入参接口双向一致,皮肤无硬编码颜色与未定义令牌、暗色令牌齐全、tokens.json ↔ tokens.css 名字与值双源一致、@keyframes 无复制粘贴的重复帧、滚动容器全在细条规则内,README 组件清单与分组同步,backlog ↔ 留痕双向一致(编号严格递增、无重复 id、留痕时间线单调且带 +08:00,每个 iter 提交都有留痕),组合配方结构完整,MCP 工具清单三处一致,搜索同义词表目标存在且无歧义,combobox / slider / range 控件都有可访问名,toast 有 live 区域与 alert 抢占播报,表单错误文案被 aria-describedby 关联、重置真复位、错误环只在聚焦时亮、汇总条随校验重算、提交按钮有忙碌态,视觉回归抽查清单十九组件 × 五维度齐全)'); } /*** 校验 git 提交信息是否符合 COMMITTING.md 规范(参数为 message 文件路径或直接 message 文本),违规退出码 1 ***/