{
"markdown": "# GridProof\n\n[](https://www.npmjs.com/package/gridproof)\n[](./LICENSE)\n\n**GridProof your UI — automated spacing & grid QA in the agent loop.**\n\nGridProof is an [MCP](https://modelcontextprotocol.io) server that renders your\nrunning frontend with Playwright, measures the **computed** geometry of every\nelement, checks it against a spacing/token rule set, and hands back a\nstructured fix report — so a coding agent can close the loop itself: generate,\naudit, fix, re-audit.\n\n![\"GridProof](\"https://raw.githubusercontent.com/gridproof/gridproof/master/docs/report-screenshot.png\")
\n\n## The problem\n\nAI coding agents are good at generating UI and bad at keeping it on a grid:\n`py-[13px]` instead of `py-3`, sibling cards with three different gaps,\nicons at 17px next to 24px. None of it breaks anything, so it ships —\nbecause nothing in the agent loop checks for it. GridProof is that check.\n\n## The loop\n\n```text\nagent generates UI → gp_audit(url) → JSON violations with fix hints\n→ agent edits source → gp_audit(url) → clean report = done\n```\n\nThe server never touches your source files. It measures a rendered page and\npoints; the agent (which has your codebase open) makes the edit.\n\n## Quickstart\n\n```bash\n# One-time: install the Chromium build Playwright uses (~150MB)\nnpx playwright install chromium\n```\n\n### Register in Claude Code\n\n```bash\nclaude mcp add gridproof -- npx -y gridproof\n```\n\nFrom a local checkout:\n\n```bash\nnpm install && npm run build\nclaude mcp add gridproof -- node /absolute/path/to/gridproof/dist/index.js\n```\n\n### Three ways to use it\n\n**1. `gp_audit` — inside the agent loop.** The agent calls this MCP tool\ndirectly against your running dev server and gets back structured JSON\n(violations + fix hints) to act on.\n\n**2. `gp_report` — MCP tool that also writes an HTML report.** Same inputs as\n`gp_audit`, plus it writes a self-contained, shareable HTML file to disk.\n\n**3. `npx gridproof --report ` — one-shot CLI.** No MCP client needed;\nuseful for a quick manual check or scripting.\n\n```bash\nnpx gridproof --report http://localhost:5173\n# writes ./gridproof-report.html, prints its path\n\nnpx gridproof --report http://localhost:5173 --out ./qa/report.html --viewport 375x812\n```\n\n## The rules\n\nFour rules. All report `warn` by default — nothing blocks, nothing has\nexit-code semantics. **Suggest, don't forbid**; the one exception is tap\ntargets, which error because it's an accessibility floor, not a style opinion.\n\n| Rule | Detects | Severity | Example fix |\n|------|---------|----------|-------------|\n| `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 |\n| `arbitrary-value` | Off-scale arbitrary Tailwind classes | warn | `py-[13px]` → `py-3` |\n| `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 |\n| `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](https://www.w3.org/WAI/WCAG21/Understanding/target-size-minimum.html) |\n\n## Tailwind, and non-Tailwind pages\n\nGridProof is built for Tailwind projects — that's where all four rules apply,\nsince `spacing-scale`, `arbitrary-value`, and `gap-consistency` reason about\nTailwind's spacing scale and utility classes.\n\nOn a page it doesn't detect as Tailwind, it auto-falls-back to\naccessibility-only checks: `canonical-size` still runs (tap targets, icon\nsizes), the three Tailwind-specific rules are skipped, and the report says so\nexplicitly rather than silently under-reporting. You can force this with\n`assumeTailwind: false` in config.\n\n## Configuration\n\nOptional `gridproof.config.json` at your project root (all fields optional;\ndefaults shown):\n\n```json\n{\n \"baseUnit\": 4,\n \"allowedValues\": [1, 2],\n \"canonicalSizes\": [12, 14, 16, 20, 24, 32, 40, 48],\n \"minTapTarget\": 44,\n \"tapTargetBreakpoint\": 768,\n \"iconTolerance\": 2,\n \"assumeTailwind\": \"auto\",\n \"rules\": {\n \"spacing-scale\": \"warn\",\n \"arbitrary-value\": \"warn\",\n \"gap-consistency\": \"warn\",\n \"canonical-size\": \"error\"\n },\n \"suppress\": [\n { \"selector\": \".hero-art *\", \"rules\": [\"spacing-scale\"] },\n { \"value\": \"13px\", \"reason\": \"optical correction, logo lockup\" }\n ]\n}\n```\n\nInline suppression: `data-gp-ignore` (all rules) or\n`data-gp-ignore=\"spacing-scale gap-consistency\"` on any element skips its\nsubtree for those rules. Suppressed findings are counted, never listed.\n\n## What it deliberately does NOT do\n\n- **No computer vision / screenshot analysis.** It reads computed geometry,\n not pixels. A screenshot is attached to the HTML report, not analyzed.\n- **No CI runner.** It's an in-loop tool for an agent, not a merge gate — no\n exit codes, nothing fails a build.\n- **No source editing.** The server measures and suggests; the agent (which\n has your codebase) makes the edits.\n- **No auth, no SaaS, no billing.** It's a local MCP server and a CLI.\n- **Not yet (v2 candidates, not implemented):** column-grid clustering,\n cross-breakpoint alignment drift, Figma token import.\n\n## How it works\n\nPlaywright renders the target page headless, a single in-page script walks the\nDOM and collects computed geometry (margins, padding, gap, rects), and the\nrule engine checks each value against your config and emits violations with\nselectors, actual/expected values, and fix hints. It's tuned against roughly\n60 real-world sites to keep false positives low — a subpixel rounding\ntolerance, an allowed-values list, and severity defaults all come out of that\ncalibration, not guesswork.\n\n## Development\n\n```bash\nnpm install\nnpm run build # tsc → dist/\nnpm test # vitest (unit + Playwright integration)\nnpm run dev # run the server from TypeScript (tsx)\n```\n\n## License\n\nMIT — v0.1.0\n",
"bytes": 6150,
"sha": "c7b67482c90eed52c03c9ae9d3845dbec0fcacd31bf64fd08d996b3a175bb822",
"repo_slug": "gridproof/gridproof",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_gridproof_gridproof_b725b395/readme"
}