gridproof/gridproof

**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
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
Register in Claude Code
From a local checkout:
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 — one-shot CLI.** No MCP client needed;
useful for a quick manual check or scripting.
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 | warn (icons) / **error** (tap targets) | Snap to canonical size; WCAG 2.5.8 |
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;