critique-partner

A design critic for Claude Code that argues from your rules, not from generic best practice.

Point it at a URL. It looks at the page, grills you about what the page is for and what you want from the crit, then writes a critique where every issue quotes one of your own rules word for word. Then it loops: a script checks every quote and every claim about the page, a second critic tries to knock the serious findings down, and the first critic fixes only what they caught, until the critique holds up.

/crit https://example.com/pricing

Site: bbulman.github.io/critique-partner

Install

You need Claude Code, Node 18 or later, and Playwright with Chromium:

npm i -g playwright && npx playwright install chromium

Then:

git clone https://github.com/bbulman/critique-partner.git
cd critique-partner
./install.sh

It copies the agent to ~/.claude/agents/ and the skill to ~/.claude/skills/crit/, keeping any earlier copy as a backup. Open a new Claude Code session (or type /reload-skills), and run /crit on a page.

What it does, step by step

1. Finds your rules. It reads the design rules your project already wrote down: taste.md for judgment, DESIGN.md for rules, principles.md, .claude/rules/design-principles.md. It skips a file that only points somewhere else, and asks you when it finds none.
2. Looks before it asks. It screenshots the page in headless Chrome at phone and desktop width (the first screen, then the whole page screen by screen) and measures what a critic would otherwise guess: fonts, sizes, colours, contrast, buttons above the fold, gradients, shadows, corner radii, alt text, form labels, anything running past the screen edge. It warns you when it lands on a sign-in screen or gets redirected.
3. Grills you. One question at a time, each with its recommended answer drawn from what it saw: the page's one job; who's on it, and when; how finished it is; what you want from this crit, and whether you want its opinions or your rules only; what's already settled. It pushes back on vague answers ("cleaner" for whom, doing what?) and ends by showing you a five-line brief to confirm.
4. Critiques. A fresh critique-partner agent writes the critique: a verdict, a direct answer to your question, the one thing to fix first, then P0, P1 and P2 findings. Each finding names the page text or selector, quotes your rule word for word, says what's wrong and why it matters to the person on the page, and suggests a fix. Then up to three labelled opinions, what works and must survive the fixes, and what it couldn't check.
5. Checks itself against a script. check.mjs fails the critique if a quoted rule isn't word for word in the section it cites (a paraphrase, an invention, or a quote that drops the "never" in front of it), if quoted page text or a selector isn't on the page, or if the verdict contradicts the findings.
6. Gets a second opinion. Another fresh agent tries to prove each serious finding wrong against the screenshots and measurements, checks the severity and the verdict, and looks for anything serious the first one missed.
7. Loops. If the script or the second critic objects, the critic fixes only what was flagged, and both checks run again. Three passes at most.
8. Reports. The verdict, the answer to your question and what to fix first, the serious findings one line each, and anything assumed or unchecked.
9. Keeps going with you. Push back on a finding and the critic re-examines it, changing it on evidence, never on pressure; if you still reject it, it lands in a dismissed list and is never raised again. Fix the page and run /crit again, and round 2 shows what's fixed, still open, new or regressed.

What a finding looks like

### The hero copy sits over a full-bleed image
**Where:** 1280-fold.png, hero: "Spark is the powerful, AI-native workspace" (`section.hero`)
**Rule:** "No full-bleed hero images with text overlays." (taste.md § Density & spacing)
**What's wrong:** The image failed to load, so the white subhead sits on a white page.
A visitor deciding in seconds sees a slogan and two buttons, with nothing to judge the trial by.
**Fix:** Two grid cells: the copy in ink on one side, the image on the other.

Anything your rules don't cover is a judgment call: labelled, kept in its own section, at most three, and it never sets the verdict.

Why it holds up

Language models are confident critics and unreliable ones. In Google's UICrit study, 13% of zero-shot UI critiques held up. Three things keep this one honest:

• The gate is a script, not a vibe. Self-correction without outside feedback makes models worse (Huang et al. 2023). So the loop runs on checks outside the model: the rule files, the captured page, and a deterministic gate with 55 self-test cases.
• A second critic, with fresh eyes. Model judges favour their own output (Zheng et al. 2023). The verifier never sees the first critic's reasoning, only its claims, and has to uphold each one line by line before the loop stops.
• Short and anchored. Longer critiques invent more bugs and nitpicks (CriticGPT), and models can't locate elements from a screenshot (UICrit). So findings are capped at 8, grouped by rule, and every one points at page text or a selector the capture recorded.

In testing on the example page, the loop took all three passes. The second critic caught five factual slips (a button placed on the wrong screenshot, a 56px headline reported as 48px, a black background that didn't exist), and each was fixed before the critique was shown.

This is the beginning of the README. Read the rest at the original. Read the full README ↗