GridProof

GridProof

[npm version] [license]

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 computed 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.

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.

The loop

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

The server never touches your source files. It measures a rendered page and points; the agent (which has your codebase open) makes the edit.

Quickstart

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

Register in Claude Code

claude mcp add gridproof -- npx -y gridproof

From a local checkout:

npm install && npm run buildclaude 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.

Tailwind, and non-Tailwind pages

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):

{  "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" }  ]}

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 installnpm run build   # tsc → dist/npm test        # vitest (unit + Playwright integration)npm run dev     # run the server from TypeScript (tsx)

License

MIT — v0.1.0