agentleFS
jayminwestjayminwest/warren/.claude/skills/ui-design-review/SKILL.md

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

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
  1. Very specific:

    Read-only: Never edit, create, or delete a file in the repo.

    line 19
  2. Distinctive:

    Rubric ids only: Every finding names one criterion id from rubric section 5.

    line 22
  3. Very specific:

    Evidence or nothing: Every finding cites a screenshot file or a path:line in the diff.

    line 25
  4. Very specific:

    If ARTIFACT_DIR or ci-meta.json is missing, do not stop.

    line 45
  5. Very specific:

    Load the contract: Read docs/design/ui-design-review.md sections 3 to 6.

    line 52
  6. Very specific:

    Check the evidence: Read ARTIFACT_DIR/ci-meta.json.

    line 55
  7. Very specific:

    Write and validate: Write the JSON to VERDICT_PATH, then run:

    line 86

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:line in 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.

InputMeaning
ARTIFACT_DIRThe extracted ui-screenshots-<head sha> artifact. It holds screenshots/<page>.<viewport>.<theme>.png and ci-meta.json.
DIFFThe PR diff, as a file path or a git range. [git diff origin/main...HEAD]
PAGES_IN_SCOPEComma list of page ids from scripts/ui-visual/pages.ts. [every page in PAGES]
VERDICT_PATHWhere 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

  1. Load the contract. Read docs/design/ui-design-review.md sections 3 to 6. Read the Typography section of docs/ui-revamp/README.md and the "Responsive contract" section of src/ui/README.md.
  2. Check the evidence. Read ARTIFACT_DIR/ci-meta.json. Note headSha and outcome. List ARTIFACT_DIR/screenshots/. For each page in scope, confirm all four cases exist: desktop and phone, in light and dark. Record each case you open in casesReviewed. A missing case is an evidence-complete blocker for that page. An outcome other than success is a smoke-clean blocker.
  3. Read the diff. List the changed files under src/ui/. If the diff touches src/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.
  4. Review each page in scope. Open the four screenshots. Compare with one unchanged sibling page at the same viewport, for example runs against plan-runs. Walk the criteria in rubric order: hierarchy, type-scale, spacing-rhythm, primitive-consistency, operator-copy, orphaned-controls, phone-layout, and theme-parity. Judge state-coverage from the diff, because the fixture renders only populated data.
  5. Classify each finding. Choose the severity from the rubric text for that criterion. Set origin to diff when this PR introduced or changed the defect. Set it to pre-existing when 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 with git show origin/main:<path>.
  6. Write one line per field. issue says what is wrong, as the operator sees it. fix names 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 with viewport and theme set to both.
  7. Decide. Count only diff findings. PASS needs zero blockers and at most two majors. Set verdict to match.
  8. 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.

  9. Report. Reply with the validator's JSON line and the summary string. 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, or shell for the sidebar, topbar, and bottom nav.
  • viewport: desktop, phone, or both. theme: light, dark, or both.
  • evidence: a screenshot file name or path: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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.