GridProof

GridProof

GridProof で UI を検証 — エージェントのループ内で間隔とグリッドを自動 QA。

GridProof は、実行中のフロントエンドを Playwright でレンダリングし、 すべての要素の計算後のジオメトリを測定し、間隔／トークンのルールセットと 照合して、構造化された修正レポートを返す MCP サーバーです。 これにより、コーディングエージェントが生成、監査、修正、再監査のループを自ら完結できます。

問題点

AI コーディングエージェントは UI の生成は得意ですが、グリッドを保つのは苦手です。 py-3 の代わりに py-[13px] を使ったり、隣接するカードの間隔がそれぞれ異なったり、 24px のアイコンの隣に 17px のアイコンがあったりします。どれも動作を壊すわけではないため、 そのままリリースされます。エージェントのループ内でチェックするものがないからです。 GridProof は、そのチェックを担います。

ループ

agent generates UI → gp_audit(url) → JSON violations with fix hints
→ agent edits source → gp_audit(url) → clean report = done

サーバーがソースファイルに触れることはありません。レンダリングされたページを測定して指摘し、 コードベースを開いているエージェントが編集します。

クイックスタート

# One-time: install the Chromium build Playwright uses (~150MB)
npx playwright install chromium

Claude Code に登録する

claude mcp add gridproof -- npx -y gridproof

ローカルのチェックアウトから実行する場合：

npm install && npm run build
claude mcp add gridproof -- node /absolute/path/to/gridproof/dist/index.js

3 つの使い方

1. gp_audit — エージェントのループ内で使用。 エージェントが実行中の開発サーバーに対して この MCP ツールを直接呼び出し、対応に使える構造化 JSON （違反と修正のヒント）を取得します。

2. gp_report — HTML レポートも書き出す MCP ツール。 入力は gp_audit と同じですが、自己完結型で共有可能な HTML ファイルもディスクに書き出します。

3. npx gridproof --report <url> — 1 回限りの CLI。 MCP クライアントは不要です。 簡単な手動チェックやスクリプトでの利用に便利です。

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

ルール

ルールは 4 つあります。デフォルトではすべて warn として報告され、処理をブロックすることも、 終了コードによる判定を行うこともありません。禁止するのではなく、提案します。 例外はタップターゲットです。これはスタイル上の意見ではなく、アクセシビリティの最低基準であるため、 エラーになります。

ルール	検出内容	重大度	修正例
spacing-scale	基本単位（デフォルトは 4px）の倍数ではなく、許可値でもない計算後の margin／padding／gap	warn	最も近い有効な値にスナップします
arbitrary-value	スケールから外れた任意の Tailwind クラス	warn	py-[13px] → py-3
gap-consistency	gap が設定されていない場合に、flex／grid コンテナー内の隣接要素の間隔が一貫していない状態	warn	子要素ごとに margin を設定する代わりに、コンテナーに gap-4 を設定します
canonical-size	正規スケールから外れたアイコン／インタラクティブ要素のサイズ、およびタップターゲットの最小サイズを下回るインタラクティブ要素	warn（アイコン）／error（タップターゲット）	正規サイズにスナップします。WCAG 2.5.8

Tailwind ページと非 Tailwind ページ

GridProof は Tailwind プロジェクト向けに構築されています。spacing-scale、arbitrary-value、 gap-consistency の 3 つのルールが Tailwind の間隔スケールとユーティリティクラスを対象にしているため、 4 つのルールすべてが適用されるのはそのようなプロジェクトです。

Tailwind として検出されないページでは、アクセシビリティ専用チェックに自動でフォールバックします。 canonical-size（タップターゲット、アイコンサイズ）は引き続き実行され、Tailwind 専用の 3 つのルールは スキップされます。また、レポートでは検出内容を黙って過少報告するのではなく、その旨を明示します。 設定の assumeTailwind: false で、この動作を強制できます。

設定

プロジェクトのルートに任意で gridproof.config.json を配置できます（すべてのフィールドは省略可能です。 以下にデフォルト値を示します）。

{
  "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" }
  ]
}

インラインでの抑制：任意の要素に data-gp-ignore（すべてのルール）または data-gp-ignore="spacing-scale gap-consistency" を指定すると、該当するルールについて その要素以下のサブツリーをスキップします。抑制された検出結果は件数に含まれますが、一覧には表示されません。

意図的に対応していないこと

• コンピュータービジョン／スクリーンショット分析は行いません。 ピクセルではなく、計算済みのジオメトリを読み取ります。スクリーンショットは HTML レポートに添付されますが、分析はされません。
• CI ランナーではありません。 マージをブロックするゲートではなく、エージェントがループ内で使うツールです。終了コードはなく、ビルドが失敗することもありません。
• ソースコードの編集は行いません。 サーバーは計測して提案し、コードベースを把握しているエージェントが編集します。
• 認証、SaaS、課金はありません。 ローカル MCP サーバーと CLI です。
• 未対応（v2 の候補であり、未実装）： カラムグリッドのクラスタリング、ブレークポイント間の配置ずれ、Figma トークンのインポート。

仕組み

Playwright が対象ページをヘッドレスでレンダリングし、ページ内の単一スクリプトが DOM を走査して計算済みのジオメトリ（マージン、パディング、間隔、矩形）を収集します。続いてルールエンジンが各値を設定と照合し、セレクター、実際値／期待値、修正のヒントを含む違反を出力します。誤検出を抑えるため、実際の約 60 サイトを基に調整されています。サブピクセルの丸め許容誤差、許容値のリスト、重大度のデフォルト値は、いずれも推測ではなく、この調整から導かれています。

開発

npm install
npm run build   # tsc → dist/
npm test        # vitest (unit + Playwright integration)
npm run dev     # run the server from TypeScript (tsx)

ライセンス

MIT — v0.1.0