GridProof

GridProof

用 GridProof 检查你的 UI — 在 Agent 工作流中自动进行间距与网格 QA。

GridProof 是一个 MCP 服务，它使用 Playwright 渲染正在运行的前端，测量每个元素的计算后几何属性，根据间距／令牌规则集进行检查，并返回结构化的修复报告 — 让编码 Agent 能够自行完成闭环：生成、审查、修复、再次审查。

问题

AI 编码 Agent 擅长生成 UI，却不擅长让 UI 保持网格一致：用 py-[13px] 而不是 py-3，相邻卡片之间出现三种不同的间距，17px 的图标旁边是 24px 的图标。这些都不会导致任何功能故障，所以它们就这样被交付了 — 因为 Agent 工作流中没有任何检查来发现这些问题。GridProof 就是这个检查工具。

工作流

agent generates UI → gp_audit(url) → JSON violations with fix hints
→ agent edits source → gp_audit(url) → clean report = done

服务不会接触你的源文件。它只测量渲染后的页面并指出问题；Agent（已打开你的代码库）负责修改。

快速开始

# One-time: install the Chromium build Playwright uses (~150MB)
npx playwright install chromium

在 Claude Code 中注册

claude mcp add gridproof -- npx -y gridproof

从本地检出目录开始：

npm install && npm run build
claude mcp add gridproof -- node /absolute/path/to/gridproof/dist/index.js

三种使用方式

1. gp_audit — 在 Agent 工作流中使用。 Agent 直接调用此 MCP 工具检查正在运行的开发服务，并获取结构化 JSON（违规项及修复提示）以供处理。

2. gp_report — 同时生成 HTML 报告的 MCP 工具。 输入与 gp_audit 相同，此外还会在磁盘上写入一份自包含、可分享的 HTML 文件。

3. npx gridproof --report <url> — 一次性 CLI。 无需 MCP 客户端；适合快速手动检查或编写脚本。

npx gridproof --report http://localhost:5173
# writes ./gridproof-report.html, prints its path

npx gridproof --report http://localhost:5173 --out ./qa/report.html --viewport 375x812

规则

共四条规则。默认情况下，报告的严重级别均为 warn — 不会阻止任何操作，也不具有退出码语义。只建议，不禁止；唯一例外是点击目标，它会报错，因为这是无障碍的底线，而非样式偏好。

规则	检测内容	严重级别	修复示例
spacing-scale	计算后的 margin／padding／gap 不是基础单位（默认为 4px）的倍数，也不是允许的值	warn	调整为最接近的有效值
arbitrary-value	超出间距比例的任意 Tailwind 类	warn	py-[13px] → py-3
gap-consistency	flex／grid 容器未设置 gap 时，相邻元素的间距不一致	warn	在容器上设置 gap-4，而不是为每个子元素单独设置 margin
canonical-size	图标／交互元素的尺寸不符合标准尺寸比例；交互元素尺寸低于点击目标最小值	warn（图标）／error（点击目标）	调整为标准尺寸；WCAG 2.5.8

Tailwind 页面与非 Tailwind 页面

GridProof 面向 Tailwind 项目构建 — 四条规则都适用于这类项目，因为 spacing-scale、arbitrary-value 和 gap-consistency 都基于 Tailwind 的间距比例与工具类进行检查。

对于未检测为 Tailwind 的页面，它会自动回退到仅进行无障碍检查：仍会运行 canonical-size（点击目标、图标尺寸），跳过三条 Tailwind 专属规则，并在报告中明确说明，而不是悄悄少报。你也可以在配置中使用 assumeTailwind: false 强制启用此行为。

配置

可在项目根目录中放置可选的 gridproof.config.json（所有字段均为可选；下方显示默认值）：

{
  "baseUnit": 4,
  "allowedValues": [1, 2],
  "canonicalSizes": [12, 14, 16, 20, 24, 32, 40, 48],
  "minTapTarget": 44,
  "tapTargetBreakpoint": 768,
  "iconTolerance": 2,
  "assumeTailwind": "auto",
  "rules": {
    "spacing-scale": "warn",
    "arbitrary-value": "warn",
    "gap-consistency": "warn",
    "canonical-size": "error"
  },
  "suppress": [
    { "selector": ".hero-art *", "rules": ["spacing-scale"] },
    { "value": "13px", "reason": "optical correction, logo lockup" }
  ]
}

内联抑制：data-gp-ignore（适用于所有规则），或在任意元素上设置 data-gp-ignore="spacing-scale gap-consistency"，即可跳过该元素子树的相应规则检查。被抑制的发现项会计入统计，但不会列出。

它有意不做的事

• 不进行计算机视觉 / 截图分析。 它读取计算后的几何信息， 而非像素。截图会附在 HTML 报告中，但不会被分析。
• 不是 CI 运行器。 它是供 Agent 在循环中使用的工具，而非合并门禁——不会返回 退出代码，也不会导致构建失败。
• 不编辑源代码。 服务负责测量并提供建议；Agent（拥有你的代码库） 负责修改。
• 无身份验证、无 SaaS、无计费。 它是本地 MCP 服务和命令行工具。
• 目前尚不支持（v2 候选功能，尚未实现）： 列网格聚类、 跨断点对齐偏移、Figma 令牌导入。

工作原理

Playwright 会以无头模式渲染目标页面，单个页面内脚本会遍历 DOM 并收集计算后的几何信息（边距、内边距、间距、矩形），规则引擎则会根据你的配置检查每个值，并输出包含 选择器、实际值 / 预期值以及修复提示的违规项。它经过约 60 个真实网站的调优，旨在降低误报率——亚像素舍入 容差、允许值列表和默认严重级别均基于这次 校准，而非凭空猜测。

开发

npm install
npm run build   # tsc → dist/
npm test        # vitest (unit + Playwright integration)
npm run dev     # run the server from TypeScript (tsx)

许可证

MIT — v0.1.0