GridProof your UI — automated spacing & grid QA in the agent loop.
GridProof is an MCP server that renders your
running frontend with Playwright, measures the geometry of every
element, checks it against a spacing/token rule set, and hands back a
structured fix report — so a coding agent can close the loop itself: generate,
audit, fix, re-audit.
Spacing & grid QA for AI-generated UIs, in the agent loop. MCP server that audits computed geometry and returns fix hints.
2026-10-28
ดาว
4
เครื่องมือ
—
อัปไทม์
—
computed
The problem
AI coding agents are good at generating UI and bad at keeping it on a grid:
py-[13px] instead of py-3, sibling cards with three different gaps,
icons at 17px next to 24px. None of it breaks anything, so it ships —
because nothing in the agent loop checks for it. GridProof is that check.
npm install && npm run build
claude mcp add gridproof -- node /absolute/path/to/gridproof/dist/index.js
Three ways to use it
1. gp_audit — inside the agent loop. The agent calls this MCP tool
directly against your running dev server and gets back structured JSON
(violations + fix hints) to act on.
2. gp_report — MCP tool that also writes an HTML report. Same inputs as
gp_audit, plus it writes a self-contained, shareable HTML file to disk.
3. npx gridproof --report <url> — one-shot CLI. No MCP client needed;
useful for a quick manual check or scripting.
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
The rules
Four rules. All report warn by default — nothing blocks, nothing has
exit-code semantics. Suggest, don't forbid; the one exception is tap
targets, which error because it's an accessibility floor, not a style opinion.
Rule
Detects
Severity
Example fix
spacing-scale
Computed margin/padding/gap that isn't a multiple of the base unit (default 4px) and isn't an allowed value
warn
Snaps to the nearest valid value
arbitrary-value
Off-scale arbitrary Tailwind classes
warn
py-[13px] → py-3
gap-consistency
Siblings in a flex/grid container spaced inconsistently when gap isn't set
warn
Set gap-4 on the container instead of per-child margins
canonical-size
Icon/interactive-element sizes off the canonical scale, and interactive elements below the tap-target minimum
GridProof is built for Tailwind projects — that's where all four rules apply,
since spacing-scale, arbitrary-value, and gap-consistency reason about
Tailwind's spacing scale and utility classes.
On a page it doesn't detect as Tailwind, it auto-falls-back to
accessibility-only checks: canonical-size still runs (tap targets, icon
sizes), the three Tailwind-specific rules are skipped, and the report says so
explicitly rather than silently under-reporting. You can force this with
assumeTailwind: false in config.
Configuration
Optional gridproof.config.json at your project root (all fields optional;
defaults shown):
Inline suppression: data-gp-ignore (all rules) or
data-gp-ignore="spacing-scale gap-consistency" on any element skips its
subtree for those rules. Suppressed findings are counted, never listed.
What it deliberately does NOT do
No computer vision / screenshot analysis. It reads computed geometry,
not pixels. A screenshot is attached to the HTML report, not analyzed.
No CI runner. It's an in-loop tool for an agent, not a merge gate — no
exit codes, nothing fails a build.
No source editing. The server measures and suggests; the agent (which
has your codebase) makes the edits.
No auth, no SaaS, no billing. It's a local MCP server and a CLI.
Not yet (v2 candidates, not implemented): column-grid clustering,
cross-breakpoint alignment drift, Figma token import.
How it works
Playwright renders the target page headless, a single in-page script walks the
DOM and collects computed geometry (margins, padding, gap, rects), and the
rule engine checks each value against your config and emits violations with
selectors, actual/expected values, and fix hints. It's tuned against roughly
60 real-world sites to keep false positives low — a subpixel rounding
tolerance, an allowed-values list, and severity defaults all come out of that
calibration, not guesswork.
Development
npm install
npm run build # tsc → dist/
npm test # vitest (unit + Playwright integration)
npm run dev # run the server from TypeScript (tsx)
License
MIT — v0.1.0
G
Gridproof
gridproof·4 ดาว·
Spacing & grid QA for AI-generated UIs, in the agent loop. MCP server that audits computed geometry and returns fix hints.
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
Gridproof ต้องใช้ API key ไหม?
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Gridproof ใช้ทรานสปอร์ตแบบใด?
Gridproof ทำงานแบบโลคัลผ่าน stdio
Gridproof ถูกตรวจสอบล่าสุดเมื่อใด?
ตรวจสอบล่าสุดเมื่อ 2026-10-28 Spacing & grid QA for AI-generated UIs, in the agent loop. MCP server that audits computed geometry and returns fix hints.