feat(cli): 新增视觉漂移审计门禁与幂等迁移脚本

- 新增 lib/visual-rules.mjs 作为规则表单一来源:字号阶梯、时长三档、
  阴影四档、焦点环收敛、圆角档位的判定与改写集中在一处,迁移与审计共用
- 新增 lib/visual-audit.mjs + ua audit:visual:按五类统计硬编码视觉字面量,
  支持 --json 与 --baseline,默认与 .ua/visual-baseline.json 棘轮比对,
  超基线退出码 1 并按 git 历史倒推疑似引入提交
- 新增 scripts/visual-migrate.mjs:幂等迁移 ui.css(重复运行零 diff),
  另带 --seed 灌视觉欠账、--backfill-domain 回填域字段
- 实跑迁移:283 处降到 35 处(字号 27→5、时长 170→9、阴影 56→17、
  圆角 2→0、焦点环 28→4),159 行逐行等价替换,括号/分号/行数不变
- package.json 把 audit:visual 追加到 check 链末尾,并补 visual:migrate
This commit is contained in:
HIsheR
2026-10-26 16:49:40 +08:00
parent 5a1d5ba6d7
commit f125369744
10 changed files with 833 additions and 174 deletions
+35 -5
View File
@@ -1,6 +1,6 @@
# @ui-arch 组件库 Agent 文档(无图形版)
> 自动生成于 2026-10-26T08:29:05.311Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。
> 自动生成于 2026-10-26T08:48:09.549Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。
> 组件 = 普通函数,传 props 返回 DOM;状态用 signal 双向绑定:读 signal() 写 signal(v)。
## 快速上手
@@ -40,12 +40,13 @@
### @ui-arch/cli
1. 装好依赖后先跑 npm run check 确认基线全绿(build → demo → style → typecheck → smoke → index → verify)
1. 装好依赖后先跑 npm run check 确认基线全绿(build → demo → style → typecheck → smoke → index → verify → lint-iterations → audit:visual)
2. 查组件:ua list 看全量,ua search <关键词> 按 id/标题/参数名/参数说明/步骤模糊找(「处理中」这类说明里的词也能搜到,命中非 id 标题时会标出命中字段;拼错会回相近 id),ua info <组件id> 看 props/步骤/示例(ua info <包名> 看单包 api 与约定,加 --json 出原始清单)
3. 查配方:ua recipes 列全量(编号 / 标题 / 用到的组件),ua recipes <编号> 看骨架代码与要点(--json 给脚本用;MCP 里对应 list_recipes / get_recipe)
4. 查令牌:ua tokens 打印全部 --ua-* 变量(颜色带暗色值),--json 输出结构化数组;写样式前先查,禁止硬编码
4. 查令牌:ua tokens 打印全部 --ua-* 变量(颜色带暗色值),--json 输出结构化数组;写样式前先查,禁止硬编码。令牌分十组:颜色 / 圆角 / 间距 / 字号 / 字重行高 / 边框 / 阴影 / 动效 / 焦点环 / 控件高度 / 层级,弹层阴影用 --ua-shadow-1..4,过渡用 --ua-duration-* + --ua-ease,焦点环用 --ua-focus-ring(_inset)
5. 改完清单跑 npm run docs:同时刷新人类文档站与 llms-full.txt(Agent 首选喂料)
6. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后,Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe
6. 改完样式跑 npm run audit:visual:五类硬编码计数不得高于 .ua/visual-baseline.json(棘轮只减不增);字面量可用 npm run visual:migrate 幂等改写成令牌
7. 在 ~/.workbuddy/mcp.json 注册 ua mcp 后,Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe
## @ui-arch/ui(skin-dom)v0.1.0
@@ -2087,12 +2088,13 @@ API 速览:
- ua style:注释规范门禁(导出必须 /*** ***/、接口字段行尾注释、行注释中文),违规退出码 1
- ua verify:清单一致性门禁(id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在)
- 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
一行用法:
```
node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens|style|verify|commit-lint|mcp>;仓库内等价于 npm run index / docs / style / verify
node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens|style|verify|commit-lint|audit:visual|mcp>;仓库内等价于 npm run index / docs / style / verify / audit:visual
```
约定:
@@ -2123,9 +2125,37 @@ node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id>|docs|tokens
- --ua-space-3: 12px
- --ua-space-4: 16px
- --ua-space-table-cell: var(--ua-space-2) var(--ua-space-3)
- --ua-font-size-xs: 11px
- --ua-font-size-sm: 12px
- --ua-font-size-md: 13px
- --ua-font-size-lg: 14px
- --ua-font-size-xl: 16px
- --ua-font-size-2xl: 18px
- --ua-weight-normal: 400
- --ua-weight-medium: 500
- --ua-weight-semibold: 600
- --ua-leading-tight: 1.35
- --ua-leading-normal: 1.55
- --ua-border-subtle: color-mix(in srgb, var(--ua-color-border) 60%, transparent)
- --ua-shadow-1: 0 1px 2px rgba(0, 0, 0, 0.06)(暗色 0 1px 2px rgba(0, 0, 0, 0.3))
- --ua-shadow-2: 0 4px 12px rgba(0, 0, 0, 0.1)(暗色 0 4px 12px rgba(0, 0, 0, 0.4))
- --ua-shadow-3: 0 10px 28px rgba(0, 0, 0, 0.12)(暗色 0 10px 28px rgba(0, 0, 0, 0.45))
- --ua-shadow-4: 0 18px 44px rgba(0, 0, 0, 0.14)(暗色 0 18px 44px rgba(0, 0, 0, 0.5))
- --ua-duration-fast: 0.15s
- --ua-duration-base: 0.2s
- --ua-duration-slow: 0.25s
- --ua-ease: cubic-bezier(0.2, 0.8, 0.2, 1)
- --ua-ease-out: cubic-bezier(0.16, 1, 0.3, 1)
- --ua-focus-ring: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 22%, transparent)
- --ua-focus-ring-inset: inset 0 0 0 2px color-mix(in srgb, var(--ua-color-accent) 40%, transparent)
- --ua-control-h-sm: 28px
- --ua-control-h-md: 34px
- --ua-control-h-lg: 40px
- --ua-z-dropdown: 100
- --ua-z-sticky: 200
- --ua-z-overlay: 300
- --ua-z-modal: 400
- --ua-z-toast: 500
皮肤包只允许消费这些变量:写死 #hex 会被 verify 拦截,拼错变量名会被令牌引用校验拦截。