Skip to main content
Glama

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.

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 = 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 build
claude 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.

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; 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 tools
gp_auditGridproof: audit a URLA
Read-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 elementA
Read-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 configA
Read-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

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      7
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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