What is GridProof?
GridProof is an MCP server with two tools: gp_audit, which checks a running dev server's computed geometry against spacing-scale, arbitrary-value, gap-consistency and canonical-size rules and returns JSON violations with fix hints, and gp_report, which adds a shareable HTML report. It needs a Playwright-installed Chromium and works best against Tailwind CSS pages.
GridProof checks whether a rendered page actually follows its own spacing rules. It uses Playwright to load a running dev server, reads the computed geometry of every element, and compares that against a spacing and grid rule set.
It works from real computed geometry, not a screenshot or a vision model, and it works best on Tailwind CSS pages; pages without Tailwind still get the accessibility-related tap-target check.
The four rules it checks
| Rule | What it flags |
|---|---|
| spacing-scale | Margin, padding or gap not aligned to the base unit, 4px by default |
| arbitrary-value | Off-scale arbitrary Tailwind utility classes in the rendered DOM |
| gap-consistency | Inconsistent spacing between sibling flex or grid items with no explicit gap |
| canonical-size | Icons off a canonical size scale, and tap targets under the 44px WCAG 2.5.8 floor |
What it deliberately does not do
GridProof does not run computer-vision or screenshot analysis, does not act as a CI build gate with pass or fail exit codes, and does not edit source files itself. An agent reads its JSON output and makes the fix.
Who it is for
Best for
- Tailwind projects where an agent keeps writing off-scale spacing values that a human reviewer would otherwise have to catch by eye.
- Teams who want a tap-target accessibility floor checked automatically alongside spacing consistency.
- Workflows that want a shareable HTML report of spacing issues, not just a terminal log.
Not for
- If the bug is clipped text or a contrast failure caught from rendered pixels rather than spacing math, Squint MCP checks those pixels against the DOM and CSS instead.
- When the comparison target is a Figma frame rather than a spacing rule set, Designfit MCP checks that geometry and those tokens against the frame directly.
- If what you want is a line-level design linter across many weighted dimensions rather than four spacing rules, UI UX Suite MCP scores a project and cites the exact line to fix.
- When the reference is a whole page's contract rather than a spacing scale, pixelpact MCP Server measures that reference and returns the properties to fix.
Use it with UiChemy
GridProof checks spacing on a page you already built and can run locally. UiChemy Composer builds that page's structure inside Elementor or Gutenberg in the first place. Click Get Started on uichemy.com.
Connect GridProof MCP: Audit Spacing and Grid Rules With Playwright to your AI client
claude mcp add gridproof -- npx -y gridproofInstall Chromium for Playwright
Run
npx playwright install chromiumonce, since GridProof renders pages with Playwright rather than a plain HTTP fetch.Add the MCP server
Run
claude mcp add gridproof -- npx -y gridproof, or add the config block above to another client's MCP settings.Start your dev server
gp_audit and gp_report both need a running frontend URL, such as http://localhost:5173, to render and measure.
Optionally add a config file
Create gridproof.config.json at the project root to set your own base unit, canonical sizes, tap target minimum or per-rule severity.
Suppress a known exception
Add a data-gp-ignore attribute to an element, or a suppress entry in the config, for a spacing choice you are keeping on purpose.
Client configuration
{
"mcpServers": {
"gridproof": {
"command": "npx",
"args": ["-y", "gridproof"]
}
}
}Endpoints and ports
npm install gridproofInstalls the package alongside the Playwright Chromium build.npx gridproof --report http://localhost:5173Writes a standalone gridproof-report.html without going through an agent at all.gridproof.config.jsonOptional project-root file for base unit, canonical sizes, tap target minimum and rule severities.What you can do with it
- Real computed geometryMeasurements come from the rendered DOM's actual computed styles, not a screenshot or a vision model guessing at pixels.
- Four spacing and grid rulesspacing-scale, arbitrary-value, gap-consistency and canonical-size cover the most common AI-generated spacing mistakes.
- Tap-target accessibility floorcanonical-size enforces a 44px minimum tap target per WCAG 2.5.8, even on pages that otherwise skip other rules.
- Fix hints in the outputViolations come back with a suggested fix, such as snapping py-[13px] to py-3, instead of a bare error.
- Shareable HTML reportgp_report writes a standalone HTML file so a spacing review can be shared or archived outside the agent session.
- Config-driven tolerancesA project-level config file sets the base unit, canonical sizes, tap target minimum and per-rule severity, with per-element suppression for intentional exceptions.
Tools it exposes
gp_audit
Renders the given dev server URL with Playwright and returns JSON violations with fix hints for an agent to act on directly.
gp_report
Runs the same audit as gp_audit, then also writes a self-contained, shareable HTML report file to disk.
Frequently asked questions
What is GridProof?
It is an MCP server that renders a running frontend with Playwright, measures the real computed geometry of every element, and checks it against spacing, gap and tap-target rules, returning JSON violations with fix hints for an agent.
How do I set up the GridProof MCP server?
Run npx playwright install chromium once, then claude mcp add gridproof -- npx -y gridproof, or add a server entry with command npx and args -y and gridproof to another MCP client's config.
What is the difference between gp_audit and gp_report?
gp_audit returns JSON violations with fix hints for an agent to act on in the loop. gp_report runs the same audit but also writes a standalone, shareable HTML file to disk for a visual review.
Does GridProof work without Tailwind CSS?
Partially. Full rule coverage needs Tailwind CSS, since several rules check utility class values directly. Non-Tailwind pages still get the canonical-size rule's tap-target accessibility check, just not the spacing-scale or gap checks.
Can GridProof fail a CI build?
No. The project states plainly that it does not act as a CI or build-gate tool and has no pass or fail exit codes; it is meant to feed an agent's in-loop fixes, not block a pipeline on its own.
Can I suppress a spacing exception on purpose?
Yes. Add a data-gp-ignore attribute to an element, naming specific rules if needed, or list a selector or value in the suppress array of gridproof.config.json along with a short reason for the record.
Does GridProof edit my code for me?
No. It only reports violations and fix hints in its JSON output; an agent or developer decides whether and how to apply the suggested fix to the actual source files.


