| name | grid-review |
| description | Read-only audit of a web page's layout grid. Measures column adherence, baseline rhythm, and optical ink alignment in pixels (Müller-Brockmann), then critiques grid appropriateness, type scale, flush-left, white space, measure, and color-as-identifier (Vignelli). Mechanical px violations first, principled critique second, each with a minimal fix -- never rewrites. Works rigorously on pages with a declared CSS grid; falls back to inferred-grid plus principled checks on arbitrary pages. Use when the user mentions grid review, grid audit, layout grid, column alignment, baseline grid, is my grid aligned, Swiss grid, Müller-Brockmann, or Vignelli. |
Grid Review
Audit a page's layout grid and report what's measurably off and what's principally wrong. The
differentiator vs. a generic UI review: this skill measures in pixels — it runs a harness and
returns numbers, not a vibe. Qualitative judgment sits on top of the measured facts, never instead of
them.
Discipline and fix catalog live in grid-discipline.md; the output shape is
report-template.md.
Critical rules
- Read-only. Report, don't fix. Produce findings ready to apply by hand. Never edit the page.
- Measure first, opine second. Section 1 of the report is px violations from the harness.
Section 2 is the Vignelli critique, explicitly built on those measured signals.
- Two modes, stated honestly. An explicit grid (declared CSS Grid) is audited at ~2px rigor; an
inferred grid (clustered element edges) is an estimate — down-rank its column findings one level
and say so. Never present inferred drift as if it were the page's stated intent.
- Minimal diffs only. Every fix is the smallest change that resolves the violation — a CSS value,
a
grid-column, a line-height. No structural rewrites (matches this repo's house style).
- Don't prescribe a grid the content doesn't want. Before reporting drift, judge whether the
content wants the grid it has (Vignelli §2.1). A two-column essay isn't broken for not being 12-up.
What it measures
| Signal | Law | Output field |
|---|
| Column adherence (both edges) | M-B §1.1 | columnViolations |
| Baseline rhythm (line-height multiples) | M-B §1.2 | baseline, baselineViolations |
| Optical ink alignment of display type | M-B §1.3 | opticalViolations |
| Type scale / contrast | Vignelli §2.2 | principled.distinctTextSizes, headBodyRatio |
| Flush-left vs justified | Vignelli §2.3 | principled.justifiedSelectors |
| Measure (chars/line) | Vignelli §2.4 | principled.avgMeasureCh |
| Color as identifier | Vignelli §2.5 | principled.accentHues |
Workflow
Phase 1 — Gather
Get the URL or file path to audit, and the quality bar (MVP / production / flagship — sets how
strict to be on principled findings). If the user gave a URL in the prompt, skip the question.
Phase 2 — Run the audit
Audit at multiple widths (default 1440, 1180, 768) — centered-container drift only appears wider
than the max-width, and column collapse only appears narrow. Two interchangeable paths share the same
measurement core (scripts/grid_audit_core.js):
Path A — Chrome MCP / browser-eval (preferred, no install). Use when a browser-eval MCP tool is
connected (Chrome MCP / Claude-in-Chrome / Preview). This runs in a real browser with the page's real
fonts, so optical-ink numbers are trustworthy.
- Navigate to the URL; resize to each width.
- Wait for fonts: eval
await document.fonts.ready.
- Eval the entire contents of
scripts/grid_audit_core.js (defines window.__gridAudit).
- Eval
JSON.stringify(window.__gridAudit({ displayMinPx: 40 })) and parse the result. displayMinPx
is the font-size floor (px) for the optical-ink check — lower it for small-display pages.
- Repeat per width.
Path B — headless script (CI / no browser MCP). One command, auto-detects a driver
(playwright → puppeteer → puppeteer-core with CHROME=<binary>):
node scripts/audit_grid.mjs <url|file> --widths=1440,1180,768 --json /tmp/grid.json
If no driver is installed it prints the install/MCP fallback and exits — the audit logic needs no
install, only a way to drive a page. Install the driver at the repo root (npm i -D playwright) so the
script resolves it by walking up from scripts/. Headless without the page's webfont makes optical-ink
numbers unreliable (see grid-discipline §1.3); prefer Path A when optical findings matter.
Phase 3 — Synthesize
Read grid-discipline.md and turn the JSON into the report:
- Section 1 (measured): list real
columnViolations / baselineViolations / opticalViolations,
worst offset first, each with its law citation and a one-line fix. A clean width is a finding too —
say it passed. In inferred mode, prefix column findings with the confidence and the estimate
caveat.
- Section 2 (principled): judge
principled.* against the Vignelli laws — scale soup past ~6
sizes, weak contrast below ~1.5×, measure outside 45–75ch, 3+ accent hues, justified text. Lead
with the appropriateness question.
- Top 3 moves: the smallest changes with the most effect.
Use the severity mapping at the bottom of grid-discipline.md. Fill report-template.md.
Phase 4 — Deliver
Present the report in chat (or write to a file if long). Nothing was changed; findings are
copy-paste-ready. Offer to apply the top fixes only if the user asks.
Scope
- In: auditing the grid/layout discipline of a rendered web page (declared or arbitrary).
- Out: generating a grid from scratch (that's a scaffold generator, not this); fixing the page;
non-grid UI concerns like a11y, perf, or copy — route those to
ui-review, benchmark, etc.
grid-review is the deep, measured layout specialist those broader reviews can defer to.
Attribution
Measurement laws adapted from the muller-brockmann-grid-systems skill; principled laws from
vignelli-canon-design-system — both from
hyperagent-public-skills,
re-cast here as a read-only auditor. Design-corpus credit to Josef Müller-Brockmann (Grid Systems in
Graphic Design) and Massimo Vignelli (The Vignelli Canon).
