GridProof
OfficialGridProof
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.
Related MCP server: vibecraft-mcp
The loop
agent generates UI → gp_audit(url) → JSON violations with fix hints
→ agent edits source → gp_audit(url) → clean report = doneThe 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 chromiumRegister in Claude Code
claude mcp add gridproof -- npx -y gridproofFrom a local checkout:
npm install && npm run build
claude mcp add gridproof -- node /absolute/path/to/gridproof/dist/index.jsThree 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 375x812The 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 |
| 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 |
| Off-scale arbitrary Tailwind classes | warn |
|
| Siblings in a flex/grid container spaced inconsistently when | warn | Set |
| 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;
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 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
Available Tools
4 toolsgp_auditGridproof: audit a URLARead-only
Render a running frontend and audit its spacing/grid geometry against the spacing-scale and arbitrary-value rules. Returns a structured AuditReport (violations with fix hints) plus a text summary.
Inputs: url (required), rules, selector, viewport, +1 more.
gp_check_elementGridproof: re-check one elementARead-only
Re-check a single element's subtree after a fix, without re-running the full audit. Returns the violations found under that selector.
Inputs: url (required), selector (required), viewport.
gp_get_configGridproof: get resolved configARead-only
Return the effective Gridproof configuration (defaults merged with gridproof.config.json if present): baseUnit, allowedValues, canonicalSizes, minTapTarget, rule severities, suppressions.
Inputs: cwd.
gp_reportGridproof: audit + write HTML reportA
Render a URL, audit its spacing/grid geometry, and WRITE a self-contained HTML report to disk (default ./gridproof-report.html). Returns the file path plus the same AuditReport JSON as gp_audit.
Inputs: url (required), rules, selector, viewport, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: gp_audit runs a full audit, gp_check_element re-checks a specific subtree, gp_get_config retrieves configuration, and gp_report writes an HTML report. No two tools overlap in purpose, so an agent can confidently choose the right one.
All tools follow a consistent gp_ verb_noun pattern (gp_audit, gp_check_element, gp_get_config, gp_report), with the verb indicating the action and the noun indicating the target. This uniformity makes the toolset predictable and easy to navigate.
Four tools is an ideal size for a focused auditing server. Each tool addresses a distinct need without redundancy or bloat, and the count is well within the recommended 3–15 range.
The toolset covers the full workflow: run an audit, re-check a single element after fixes, retrieve effective configuration, and generate a standalone HTML report. There are no obvious dead ends, and configuration management is appropriately delegated to the config file.
Maintenance
Related MCP Connectors
UX guidelines and audits for coding agents. Paid plans start audits, heatmaps and user simulations.
Checks UI code for AI-default design patterns and gives the fix. By Precious Studio.
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
Run accessibility, contrast, and design token audits and file QA issues from your AI coding tool.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables AI coding agents to inspect a project's design tokens and component catalog, audit React/Tailwind files against seven static UI quality rules, score overall UI health, and apply auto-fixes that are re-audited and reverted on regression. It works both locally over filesystem access and remotely on raw TSX/JSX or CSS snippets passed directly as strings.-
- AlicenseAqualityCmaintenanceProvides deterministic UI/UX intelligence and systems performance auditing tools for AI coding agents, enabling generation of accessible, well-designed React/Tailwind interfaces and elimination of backend anti-patterns like N+1 queries and sequential waterfalls.7MIT
- AlicenseAqualityCmaintenanceEnables AI agents to audit and fix CSS for generic AI-built design patterns, covering fonts, palettes, contrast, and type scales.646 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to audit rendered web pages for design and UI defects by measuring geometry, styles, contrast and motion in a local browser and judging them against evidence-tiered rules. Findings come back as short, fixable items expressed in the project's own design tokens, while only sanitized numeric measurements leave the machine.Apache 2.0