渲染设计审计 Viger1/dsh-design

dsh-design

这个生态里唯一在渲染后的页面上测量设计规则的东西。

现有设计工具分两类，而它们留下同一个洞：生成器负责产出，产完就结束；纯提示型技能把规则发给模型，没有任何东西检查它照做没有；静态分析器解析 CSS 文件，而它看不见浏览器真正画出来的东西——与真实背景合成后的 alpha、工具类展开后的结果、运行时主题切换、以及布局后真实的点击框。

dsh-design 渲染页面并测量它，让"看着还行"变成一个可以争论的数字——其中包括没有任何其他插件检查的一类东西：「机器味指纹」。紫色渐变按色相角度判定而非字符串匹配、emoji 冒充图标、字体退回浏览器默认（说明从未做过排版选择）。

同一份需求，两个 agent

一份需求——某个小型 API 监控产品的定价页，中文界面，单个自包含的 index.html。同一个模型、同一个 harness 跑两遍，唯一的差别是这个插件有没有在起作用。

| 不用插件 | 用技能 + 审计闭环 |
| 基线：居中蓝色 SaaS 定价页 | 实验组：暖白底编辑式定价页 |

| 1280px 下实测 | 不用 | 用 |
| 违规项 | 4 | 0 |
| 字号种类 | 11 种 —— 12 13 14 15 16 17 19 20 30 44 46 | 6 种 —— 14 16 20 24 32 40 |
| 脱离栅格的间距值 | 10 个 —— 5 6 10 13 14 15 18 26 30 226 | 0 |
| 小于 24px 的点击区 | 3 | 0 |
| 机器味指纹 | 1 —— logo 上的紫色渐变 | 0 |
| 非中性色 | 1 —— rgb(37, 99, 235) | 1 —— rgb(15, 92, 68) |
| 采样元素 | 71 | 78 |

基线并不难看。它画得挺合格——而这恰恰是问题：它就是你已经见过几百次的那张"居中蓝色 SaaS 页"，并且在没人要求的情况下自己伸手去拿了一个紫色渐变，正是 purple-gradient 这条规则存在的理由。合格的表面之下它一直在即兴：11 种字号，10 个不属于任何尺度的间距值。

实验组是先定后画——一条暖中性灰阶，一个只用在主行动按钮和推荐档位上的墨绿，6 档字号，间距走 4px。然后才审计：第 1 轮 1 项违规（页脚链接命中区只有 22.4px 高），第 2 轮 78 个元素全清。两个页面各自都只花了 1 个强调色——配色这条规则在这里的结论是：两者的问题都不在颜色上。

想自己复现：需求文件和两份产物都在 examples/pricing-page/。各只跑了一遍，所以请把它当作差异的示例，而不是基准测试。另外基线那一轮被要求"写完就停"，它没有得到任何修改机会——"不用技能但允许迭代"这条对照臂，这次比较里是缺失的。

它测什么

| 规则 | 报告内容 |
| contrast | 每一处未达 WCAG AA 的文本，附实测比值与所需比值。文字 alpha 会与真实背景合成，所以「白底浅灰半透明字」逃不掉。 |
| type-scale | 页面实际渲染了几种字号、分别是多少。种类过多说明层次是随手堆的。 |
| spacing-grid | 未落在间距刻度上的 padding/margin/gap，按数值和元素列出。 |
| palette | 非中性色的种类数。灰阶不计入；九种强调色就是失控。 |
| tap-target | 小于 44px 的交互元素，附实测尺寸。 |
| line-length | 超出舒适行宽的正文，附最长行的实测字符数。 |
| default-font | 大部分文本是否退化到浏览器默认字体栈——即从未做过排版选择。 |
| purple-gradient | 紫→品红渐变，按色相判定而非字符串匹配：Tailwind 的 violet-500 色相是 258°，天真地设 260° 起就会漏掉最常见的那个。 |
| emoji-icons | 控件里用 emoji 充当图标。 |

每条发现都点名元素、给出数字。p.muted at 1.62:1 (needs 4.5:1) 是能直接改的；「注意对比度」不是。

其中有几条规则，只有测量渲染后的页面才可能做到：对比度是把文字颜色与采集到的真实背景合成之后才计算的，所以白底浅灰半透明字逃不掉，而深色渐变上的白字不会被误伤——这两种情况 CSS 解析器都看不见。点击区读的是布局后的实际盒子，不是声明的尺寸。

另一半：技能

只做测量，只能发现「偏离了你本来定的系统」。内置的 design-system 技能负责让 agent先把系统定下来，而它围绕的是 AI 界面难看的真正病根——不是品味差，是选择无限：每个元素随手一个色值、想强调就新造一个字号、margin 全凭当下感觉。

所以技能的顺序是先砍自由度：先承诺一个方向，在写组件之前锁死调色板与字号表，先定层次再谈装饰，间距一律走刻度，最后跑审计。结尾是一份具体的「机器味指纹」清单，并要求 agent 在宣称完成前先跑 design_audit。

安装

dsh plugin --profile web add dsh-design

自动使用已装的 Chrome / Edge；都没有就执行一次 npx playwright install chromium 并设 browserChannels: [chromium]。需要 Node ^22.19 || >=24。

使用

design_audit { target: "http://localhost:3000/pricing" }
design_audit { target: "dist/index.html", viewportWidth: 390 }

接受 URL（localhost 永远放行）或本地 HTML 文件。传 viewportWidth 可测指定断点——移动端正是点击区和行长最容易翻车的地方。

配置

- id: design
name: dsh-design
config:
headless: true
browserChannels: [chrome, msedge, chromium]
viewportWidth: 1280
viewportHeight: 900
navigationTimeoutMs: 15000
spacingBasePx: 4 # 间距必须是它的倍数 maxTypeSizes: 6 # 超过几种字号算层次失控 maxPaletteColors: 8 # 超过几种非中性色算配色漂移 neutralChroma: 0.18 # 低于此彩度视为中性色，不计入配色预算 minTapTargetPx: 24 # WCAG 2.2 AA；触控优先的产品可提到 44 maxCharsPerLine: 75
allowedHosts: [] # 允许审计的额外主机名
registerSkill: true

每个阈值都是部署选择——密集的运维控制台和营销落地页不该用同一套上限。

设计要点

- 浏览器只负责量，Node 负责判。 页内采集脚本只收集计算样式；所有规则都是对这份快照的纯函数，所以阈值、WCAG 计算、套路检测都能脱离浏览器做单元测试。
- 解析不了的颜色语法跳过，不猜。 页面用了 oklch() 时，那些元素不计入对比度统计，而不是编一个比值出来。
- 对比度要有真实背景。 采集脚本会向上遍历祖先直到第一个不透明背景——对着 rgba(0,0,0,0) 算比值毫无意义。
- 中性色不计入配色数，而「中性」按彩度判定。 灰阶是结构，强调色才是选择，需要节制的只有后者。用彩度而不用 HSL 饱和度，是因为饱和度的分母在明度两端会塌向 0——它给 #FAF8F2 打 0.44 分，而纸面不是强调色。

用真实应用做过校准

拿 dsh 官方自己的 Web UI（一个专业设计的产品）来审，才是真正有意义的检验——此前所有靶子都是我们照着规则反向构造的。两条阈值在它上面干净通过（4 种字号对上限 6、2 种非中性色对上限 8），这才是「阈值不是拍脑袋定的」的证据。另有三条规则错了，已修：

- 描边不是节奏。 1px、2px 是边框、焦点环和视觉微调；拿间距刻度去要求它们纯属噪音。低于基准值的间距现在豁免；而当所有越界值都能被一个更细的刻度整除时，报告会直接指出并给出建议值，而不是要求一个本来就自洽的项目放弃自己的体系。
- 44px 是触控指南，不是 AA 标准。 把 28×28 的桌面图标按钮判为不合格，是拿移动端标准套鼠标界面。默认值现已改为 WCAG 2.2 AA（2.5.8，24px），触控优先的产品可自行调高。
- 中性色该按彩度判，不是按饱和度判。 配色规则原本用 HSL 饱和度，而饱和度的分母在明度两端会塌向 0——于是只带一点点色调的近白、近黑会被算成高饱和色。结果是一条有色调的灰阶，每一级都被计进配色预算：光一条 Tailwind slate 就能在还没有任何强调色时吃掉全部 8 个名额，而这个界面自己的灰白背景和近黑正文也被算成了强调色。这等于规则在惩罚自家技能教的做法（技能明确要求「用一条同色相的 5–7 级灰阶」）。现在按绝对彩度判定，不随明度漂移。

同一个界面上，报告从 3 条违规降到 2 条，而留下的那条——两个次要标签 3.55:1——是真实的无障碍问题。配色数从 5 种降到 2 种，且都是这个产品的蓝色。

本插件自审改掉了什么

dsh-review 审查了这份源码，找出六个缺陷并全部修复。最要命的一条：背景遍历原本把渐变当作「这里没画东西」继续向上找，最后兜底成白色——于是深色渐变 hero 上的白字（最常见的落地页写法）会被报成一条根本不存在的对比度违规。一个在最常见布局上狼来了的 linter 会被直接关掉，所以这条是「有用工具」和「负资产」的分界线。现在背景测不到就报「无法测量」并跳过该元素，与前景路径遵守同一条规矩：要么量出来，要么不说话。

其余五条：背景里无法解析的颜色语法改为跳过而非假设白色；本地目标经 realpath 规范化后必须落在工作区内且为 HTML 文件（渲染器会执行它加载的东西）；取消现在覆盖浏览器启动全过程，而不只是启动之后；主机策略在重定向后重新校验；祖先 opacity: 0 的内容不再计为可见。

已知限制

- 一次只测一个视口宽度；要看移动端就再跑一次，别假设。
- 只采样前 400 个可见元素，够看一个页面，不够看整个应用外壳。
- 行长按平均字宽估算，是信号而非精确排版测量。
- 它只判定可测量的东西。一个页面可以全部合规却依然别扭——配合 dsh-preview 让 agent 也能亲眼看看。

同系插件

| 插件 | 给 agent 的能力 |
| dsh-preview | 👁 眼睛——验证自己写的页面：打开、读取、截图、自检 |
| dsh-pilot | ✋ 手——按无障碍 ref 操作任意页面，带原生权限模型 |
| dsh-review | 🔍 判断力——找出缺陷，并在报告前逐条尝试推翻它 |
| dsh-design（本仓库） | 🎨 品味——先约束选择，再实测结果有没有守住 |

协议

MIT © Viger1