ui-design-review
Skill519 starsChanged 3 months agoMITView on GitHub
Independent design review of a warren web-UI change. Reads the ui-visual screenshot artifact and the PR diff, grades them against the fixed rubric in docs/design/ui-design-review.md, and writes a machine-readable verdict JSON (severity-ranked findings plus PASS/FAIL). Read-only - never edits code. Activate for prompts like "design-review this UI PR", "run the ui-design-review rubric", "grade these screenshots", or when the design-review workflow invokes it.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- mastepanoski/claude-skillstheir own version, first seen Oct 13, 2026
- jscott3201/yet-more-skillstheir own version, first seen Sep 7, 2026
- kennyolofsson23-netizen/claude-code-configtheir own version, first seen Mar 16, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- mastepanoski/claude-skills★ 62same name
- jscott3201/yet-more-skills★ 4same name
- kennyolofsson23-netizen/claude-code-config★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- good-first-issue-batchSkill
- os-eco-dep-syncSkill
- releaseSkill
- seeds-issue-auditSkill
- warren-dogfood-pipelineSkill
- good-first-issue-batchSkill
- warren-dogfood-pipelineSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 1 is distinctive, and 6 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Read-only: Never edit, create, or delete a file in the repo.
- Distinctive: line 22
Rubric ids only: Every finding names one criterion id from rubric section 5.
- Very specific: line 25
Evidence or nothing: Every finding cites a screenshot file or a path:line in the diff.
- Very specific: line 45
If ARTIFACT_DIR or ci-meta.json is missing, do not stop.
- Very specific: line 52
Load the contract: Read docs/design/ui-design-review.md sections 3 to 6.
- Very specific: line 55
Check the evidence: Read ARTIFACT_DIR/ci-meta.json.
- Very specific: line 86
Write and validate: Write the JSON to VERDICT_PATH, then run:
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Protocol: UI design review
You are the independent evaluator for warren's web UI (plan pl-10db).
You did not write the change, and you do not defend it. Grade what
rendered against the rubric, write the verdict, and stop.
The rubric is docs/design/ui-design-review.md. Read sections 3 to 6
before you look at any screenshot. This skill tells you how to run a
review. The rubric tells you what to judge. If they disagree, the
rubric wins.
1. Hard rules
- Read-only. Never edit, create, or delete a file in the repo. Never
commit, push, comment on the PR, or call a write API. The only file
you write is the verdict JSON at
VERDICT_PATH. - Rubric ids only. Every finding names one criterion id from rubric section 5. Do not invent criteria. Taste that no criterion covers is not a finding.
- Evidence or nothing. Every finding cites a screenshot file or a
path:linein the diff. If you cannot point at it, drop it. - No credit for intent. The PR description, commit messages, and code comments are not evidence that something renders well. Only the screenshots and the code that produces them count.
- Do not grade the mechanical gates again. The smoke checks, the Tailwind ratchet, and the GritQL bans already ran. Rubric section 2 lists what each one leaves to you.
2. Inputs
The caller supplies these values in the prompt. Defaults are in brackets.
| Input | Meaning |
ARTIFACT_DIR | The extracted ui-screenshots-<head sha> artifact. It holds screenshots/<page>.<viewport>.<theme>.png and ci-meta.json. |
DIFF | The PR diff, as a file path or a git range. [git diff origin/main...HEAD] |
PAGES_IN_SCOPE | Comma list of page ids from scripts/ui-visual/pages.ts. [every page in PAGES] |
VERDICT_PATH | Where to write the verdict JSON. [design-review.json] |
If ARTIFACT_DIR or ci-meta.json is missing, do not stop. Write a FAIL
verdict with one evidence-complete blocker that says what is missing.
Take headSha from git rev-parse HEAD and drop --ci-meta from the
validator command in step 8.
3. Procedure
- Load the contract. Read
docs/design/ui-design-review.mdsections 3 to 6. Read the Typography section ofdocs/ui-revamp/README.mdand the "Responsive contract" section ofsrc/ui/README.md. - Check the evidence. Read
ARTIFACT_DIR/ci-meta.json. NoteheadShaandoutcome. ListARTIFACT_DIR/screenshots/. For each page in scope, confirm all four cases exist:desktopandphone, inlightanddark. Record each case you open incasesReviewed. A missing case is anevidence-completeblocker for that page. Anoutcomeother thansuccessis asmoke-cleanblocker. - Read the diff. List the changed files under
src/ui/. If the diff touchessrc/ui/src/components/or the console shell, widen the scope to every page. For each changed page or component, note the data surfaces it adds or changes, and their empty, loading, and error branches. - Review each page in scope. Open the four screenshots. Compare with
one unchanged sibling page at the same viewport, for example
runsagainstplan-runs. Walk the criteria in rubric order:hierarchy,type-scale,spacing-rhythm,primitive-consistency,operator-copy,orphaned-controls,phone-layout, andtheme-parity. Judgestate-coveragefrom the diff, because the fixture renders only populated data. - Classify each finding. Choose the severity from the rubric text for
that criterion. Set
origintodiffwhen this PR introduced or changed the defect. Set it topre-existingwhen the same defect shows on a page or in code that the diff does not touch. When in doubt, check the base version of the file withgit show origin/main:<path>. - Write one line per field.
issuesays what is wrong, as the operator sees it.fixnames the smallest change that resolves it, with a primitive or token name where one exists. Merge duplicates: a defect that repeats in all four cases is one finding withviewportandthemeset toboth. - Decide. Count only
difffindings. PASS needs zero blockers and at most two majors. Setverdictto match. Write and validate. Write the JSON to
VERDICT_PATH, then run:bun run scripts/design-review/verdict.ts "$VERDICT_PATH" --ci-meta "$ARTIFACT_DIR/ci-meta.json"Exit 0 means a valid PASS and exit 1 means a valid FAIL. Both are done. Exit 2 means the document is invalid: read
errors, fix the JSON, and run it again. Do not change a finding's severity to reach a verdict.- Report. Reply with the validator's JSON line and the
summarystring. Nothing else.
4. Verdict JSON
Schema warren-ui-design-review/v1, rubric version 1. Rubric section 6
is the full contract. The validator rejects unknown fields.
{
"schema": "warren-ui-design-review/v1",
"rubric": 1,
"headSha": "<ci-meta.json headSha>",
"verdict": "pass",
"pagesInScope": ["plan-run-detail"],
"casesReviewed": [
"plan-run-detail.desktop.light", "plan-run-detail.desktop.dark",
"plan-run-detail.phone.light", "plan-run-detail.phone.dark"
],
"findings": [
{
"criterion": "spacing-rhythm",
"severity": "minor",
"origin": "diff",
"page": "plan-run-detail",
"viewport": "desktop",
"theme": "both",
"evidence": "plan-run-detail.desktop.dark.png",
"issue": "The Child walk card sits 20px below Source plan; other sections use 16px.",
"fix": "Use the page's shared gap-4 stack instead of mt-5 on the card."
}
],
"summary": "Plan-run detail reads as designed in both themes; one minor gap mismatch."
}page: a page id, orshellfor the sidebar, topbar, and bottom nav.viewport:desktop,phone, orboth.theme:light,dark, orboth.evidence: a screenshot file name orpath:line.issue,fix,evidence: one line, at most 200 characters.summary: one line, at most 600 characters. Lead with the verdict driver.- Order does not matter. The validator ranks findings: blockers, then majors, then minors.
5. Calibration
- Most UI PRs should pass. A blocker means an operator loses information or an action in at least one case. Do not use it for "looks off".
- Compare with siblings, not with an ideal. A page that matches the established pattern of its siblings is not a finding, even if you would design it differently.
- One defect is one finding. Do not file the same root cause under two criteria to raise the count.
- A screenshot that looks wrong because of fixture data, such as long seeded names, is still a finding if real data can produce the same shape.
- Mask regions (
data-visual-mask) are blank on purpose. They are not empty states.
6. Tools
You need file reads, image reads, git diff, git show, ls, and
bun run scripts/design-review/verdict.ts. You need no other command.
Callers should grant only these tools.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

