Turn a screenshot, URL, or HTML snippet into a scored UX critique with a citation behind every claim - a Claude Code skill built for design teams and the engineers who ship their work.
design-review takes a UI screenshot, a live URL, or an HTML snippet and returns a structured critique: a 0-4 ship-readiness score, up to 6 prioritized issues, and a Before/After/Why line for each one. The rule that keeps it useful is a citation floor - every fix names a Nielsen heuristic, a WCAG 2.2 success criterion, or a named platform guideline, never a bare opinion. Hand it two or more variants and it switches to comparison mode: a score each, a shared-dimension table, and a named winner. With no artifact at all, it switches to advisory mode: one direct recommendation, cited reasoning.
- What it does
- Quick start
- Usage
- Example output
- How it works
- How is this different from just asking the model?
- FAQ
- Related skills
- Who maintains this
- Reviews a screenshot, a live URL, or an HTML snippet and returns a 0-4 ship-readiness score.
- Caps the list at the 6 most impactful issues instead of listing every flaw, and never pads a thin list to reach a count, so the critique stays actionable.
- Writes each issue as Before / After / Why - an observable fact, a fix doable in under an hour, one citation.
- Compares two or more variants on shared dimensions and names a winner, instead of returning two separate critiques and no answer.
- Switches to advisory mode for open decision questions ("modal or a full page for account deletion?") with no artifact attached.
- Answers a decision question that arrives with a screen attached, using the screen as evidence, instead of handing back a critique that never reaches the question.
- Asks for a better screenshot or a working URL when the input is unreadable.
- Still surfaces 2-3 polish items when a review lands on a design that would score 4/4 - never an empty critique. A comparison is the one place the closing fix list can be empty, because there the verdict is the deliverable.
Personal - available in every project:
git clone https://github.com/humbleteam/design-review ~/.claude/skills/design-reviewProject-scoped - checked into one repo:
git clone https://github.com/humbleteam/design-review .claude/skills/design-reviewAny other agent: the skill is plain markdown in the Agent Skills format. Paste SKILL.md into the system prompt of Cursor, Codex, or any other LLM agent.
To verify: restart Claude Code and ask it to list its skills. Skills load from ~/.claude/skills/ (personal) and .claude/skills/ (project) - design-review should appear.
- "Review this screenshot of our onboarding flow." (image attached) - review mode: scores it 0-4, returns up to 6 cited issues.
- "What's wrong with https://example.com/pricing?" - review mode against a live URL instead of a screenshot.
- "Which of these two checkout variants is better?" (two images attached) - comparison mode: a score each, a dimension table, and a named winner.
- "Should I use a modal or a full-page flow for account deletion?" - no artifact, so advisory mode: one recommendation, up to 5 cited bullets.
- "Here's our checkout - should the address form be a modal or a drawer?" (one image attached) - grounded advisory mode: the question gets answered first, with facts read off the screen as the evidence.
Example review of a fictional signup screen - product name and screen are invented for illustration:
## Signup screen - score 2/4
### 1. Primary action competes with a secondary link
- Before: "Create account" and "Log in" share the same font weight.
- After: make "Create account" a filled button; drop "Log in" below it as
plain text, no border.
- Why: Nielsen heuristic #8 - aesthetic and minimalist design - two actions
compete when only one is primary.
### 2. Password field gives no format guidance until after submit
- Before: requirements (8+ characters, one number) only show as an error
after a failed submit.
- After: show them as static helper text under the field before typing.
- Why: WCAG 2.2 SC 3.3.5 (help) - requirements should be visible before an
error occurs, not only after.
### 3. Form fields are unlabeled placeholder text
- Before: "Email" and "Password" exist only as placeholder text and vanish
once the user starts typing.
- After: add persistent labels above each field; keep placeholder as an
example value only.
- Why: Nielsen heuristic #6 - recognition rather than recall - a vanished
placeholder forces recall instead of recognition.
Fix this first: the missing password guidance is the highest-cost fix - most
likely to cause a failed submit, and a one-line copy change.
A comparison of two variants returns the third shape - one table, one winner, and a fix list that only holds what clears the impact bar. Prompt: "Which of these two plan pickers is better?" (two images attached; both screens are invented for illustration):
## Plan picker A vs B - A 3/4, B 2/4
| Dimension | A: three tiers | B: one plan led | Edge |
|---|---|---|---|
| Primary action | One filled "Start trial" per column, three on the screen | One filled "Start trial"; the other two plans are text links | B |
| Scan cost | 11 feature rows repeated in all three columns | 4 rows on the led plan, the full table one tap away | B |
| Price comparison | Three prices sit above the fold together | One price visible, two behind "Compare plans" | A |
| Billing toggle | Sits above the columns; all three prices change with it | Sits inside the led plan's card; the two link prices do not move | A |
Winner: A. The billing toggle decided it: in B the control sits inside one
card while two of the three prices it changes sit outside that card and do
not visibly respond, so the state of the screen after a tap cannot be read
off the screen. Why: Nielsen heuristic #1 - visibility of system status. B
takes both dimensions about reading the screen and A takes both about
comparing it, which is a trade-off either team could defend; the toggle is
the one row where the loss is a defect rather than a bet.
What would change the call: if most visitors arrive on a plan-specific page
and never compare tiers, B's single-plan lead is the right bet and its
toggle is a contained fix.
Worth fixing in the winner: one issue clears the impact bar.
### 1. Three primary buttons compete
- Before: all three columns carry a filled "Start trial" button at the same
weight.
- After: keep the filled button on the recommended tier, make the other two
outlined.
- Why: Nielsen heuristic #8 - aesthetic and minimalist design - three equal
primaries leave the screen with no default.
Ask for a full review of B if you want its own issue list.
A decision question with a screen attached returns the last shape - the answer first, the critique only if it bears on the decision. Prompt: "Here's our checkout. Should the address form be a modal or a drawer?" (screenshot attached):
Recommendation: keep the address form inline on the checkout page; neither a
modal nor a drawer earns its cost here.
- The form is 9 fields deep and the page already carries a sticky order
summary, so an overlay would cover the one element people check while
typing an address. Why: Nielsen heuristic #1 - visibility of system status
- the total is the status people are tracking during checkout.
- A drawer at this height scrolls inside its own container on a 390px-wide
screen, which puts two scroll regions on one screen. Why: Apple Human
Interface Guidelines - sheets - a sheet that scrolls internally competes
with the page behind it.
- General guidance, not visible in this screenshot: if most of your traffic
is returning customers with a saved address, the question changes - the
form becomes a confirm step, and a modal is defensible.
What in the artifact decided it: the sticky order summary sits in the region
a modal or drawer would cover.
Also worth fixing: the "Continue" button is below the fold on the attached
viewport, which hides the exit from the step being discussed.
- Mode detection first, in a fixed order. Two or more artifacts plus a "which one wins" question triggers comparison mode; an artifact plus a decision question triggers grounded advisory mode; one artifact and no decision question triggers review mode; a decision question with no artifact triggers advisory mode.
- The rubric loads before the critique.
references/review-rubric.mdholds the exact 0-4 bands, the tie-break for a screen that fits two of them, and the citation table, so scoring stays consistent run to run. - Score before listing issues. 0 is broken, 4 is ship-ready. Score generously when the design serves the stated project goals; harshly when it ignores them.
- Cap the issue list at 6, ranked by impact - listing every flaw is a failure mode, not thoroughness. The cap is not a quota and there is no minimum: a screen that yields two issues gets two, with one line saying why the list is short, because padding to a count is the same failure reached from the other side. Six is band 1's floor plus one: that band is five or more violations, the largest count the rubric names, and a cap of five would sit on it, so a five-item list could not say whether it was complete or cut off. Past six the count is the finding - the screen is a 1/4 or a 0/4 and the score paragraph says so, rather than a seventh issue vanishing under the cap.
- Before is a fact, never a feeling: "12 elements inside a 320px card with no grouping," not "this feels cluttered."
- After fits inside an hour - concrete enough to hand to a developer with no follow-up question.
- Why is exactly one citation: a Nielsen heuristic, a WCAG 2.2 success criterion, or a named platform guideline - never an uncited opinion.
- The close names the one fix that matters most, not a generic summary.
- Comparison mode judges variants against each other, not one after the other: 3-5 shared dimensions, one row per dimension, an edge called on each, and a named winner with the one fact that would flip it. The fix list that closes it is capped at three and can be empty - the verdict is what a comparison owes you, and an issue added to reach a count is a reason to doubt the verdict rather than a bonus. Three is the top of the 3/4 band, which is defined as one to three polish items left in a screen whose hierarchy and craft are mostly right, so the cap is the length a winner earns rather than a number the template picked; a winner that needs a fourth is a winner below 3/4, and that is said in the verdict paragraph as what the score leaves to do rather than trimmed out of sight. A point that belongs to a losing variant is never printed as a second critique: either it bears on the call, in which case it is already in the argument, or a full review of that variant is offered instead. Three to five variants change nothing but the width of the table - one column each, every score in the header, still one winner, and the columns in the order you presented them rather than sorted by score, because a pre-sorted table reads as a verdict the rows are only decorating - and a dimension two of them are level on says so in the edge column instead of inventing a gap. Five is where the table stops, because a wider one wraps and a wrapped column defeats the reason each variant has one; past five every variant is still scored and the ones outside the table are listed by name with their scores, so none of them drops out of sight.
- Advisory mode compresses the same discipline into one recommendation plus up to 5 cited bullets, asking one clarifying question instead of guessing when a request is too open. Five is a cap, not a quota, the same way six is for the issue list: you get the claims that are actually grounded and no filler under them. Five is band 1's floor, the most cited claims the rubric asks any output to stand behind, and the bar is set by the version of this mode that has a screen attached - adding one does not move either end, so the mode with nothing to read does not get a shorter list for it. It sits on that floor where the issue list sits one above, and the difference is the score: a five-item list printed beside a 1/4 cannot say whether it is complete or cut off, while nothing in an advisory answer is a number these bullets have to substantiate. One is the floor, because the recommendation is a claim too and this skill does not answer without a citation behind the answer - when not one claim holds, you get the clarifying question rather than a confident guess.
- An attached screen raises the evidence bar, it does not change the question. In grounded advisory mode every claim the screen can settle names an observable fact from it, the one fact that carried the call is stated outright, and anything the screen cannot settle is labeled as general guidance rather than dressed up as an observation.
A bare "review this design" prompt returns a wall of adjectives - "the hierarchy feels off," "the spacing could be tighter" - with no way to tell which comment matters most or where it came from. This skill pins the output shape down: a score, a capped issue count, a Before/After/Why line per item, so every run is the same structure and easy to compare. It also pins the citation - a fix traces back to a numbered heuristic, not "best practice" in the abstract. It does not replace judgment about your users or a usability test.
Can AI do a design review? Yes, with limits. This skill scores a screenshot, URL, or HTML snippet against Nielsen's 10 heuristics and WCAG 2.2. It reads pixels and markup, not user behavior, so it catches heuristic and accessibility gaps but cannot replace a usability test.
How do I review a Figma design with Claude? Screenshot the frame and paste it into Claude Code, then ask for a review. A pasted screenshot is treated the same as a live URL: a 0-4 score plus up to 6 cited issues.
What is a good design review checklist?
At minimum, Nielsen's 10 heuristics: system status, real-world match, user control, consistency, error prevention, recognition over recall, flexibility, minimalist design, error recovery, help. references/review-rubric.md has the full table.
How do I score design quality?
This skill uses a 0-4 scale: 0 is broken (basic accessibility, hierarchy, or trust violations), 4 is ship-ready. Bands live in references/review-rubric.md, along with the rule for the common case where two bands fit the same screen: the cost of the fix decides - a rebuild, a restructure, a craft pass, one to three discrete fixes, or nothing material - and a count of violations is evidence rather than a threshold, so five small ones on a sound structure score better than a single one that blocks the task. Score generously when a design serves its stated goals, harshly when it ignores them.
Can this review a live website instead of a screenshot? Yes, give it a URL. If the URL is unreachable - an auth wall or a 404 - it asks for a screenshot instead of guessing.
How do I compare two design variants and pick a winner? Attach both and ask which one wins. That is comparison mode: each variant gets its own 0-4 score, then 3-5 shared dimensions are judged side by side in a table, and one variant is named the winner along with the fact that would change the call. It does not hand back two separate reviews, because two reviews still leave you to make the decision yourself. Anything worth fixing in the winner follows, up to three items and sometimes none - the answer is the deliverable here, so nothing gets added to fill a list. Three is where it stops because three is what the 3/4 band is: hierarchy and craft mostly right, one to three polish items left. A winner that needs a fourth is telling you it is not a 3/4 yet, and you get that in the paragraph that names it rather than as a longer list. Issues that belong only to the variant that lost are not printed either; ask for a review of that one and you get them. The same mode handles a before-and-after pair when you want to know whether a redesign actually improved anything, with the before kept in the first column whatever it scored, because the pair read the other way round answers whether the old screen improved on the new one, and three to five variants work the same way - each gets its own column and its own score, and one of them is still named. Where two of them are genuinely level on a dimension, the edge column says so rather than manufacturing a difference to fill the cell.
How many variants can it compare at once?
Five in the table, and more than five still get an answer. The table gives every artifact its own column so your eye can run down one, and Dimension and Edge take two columns of their own, so six variants make an eight-column table that wraps in a chat pane - at which point the column it was built around is not a column any more. Past five it scores all of them first, which costs nothing because a score needs no column, then runs the table on the contenders and lists the rest by name with their scores and the one observable thing that put each behind. Nothing disappears quietly: an artifact missing from both the table and that list would decide part of your question by not being printed, which is the whole failure the mode exists to avoid. If the cut would fall in the middle of a group that scored the same, the table takes them all and runs one column wide rather than separating them with a tiebreak it does not have.
What if I don't have a design yet, just a decision to make? That's advisory mode: a direct question like "modal or full page for account deletion?" gets one recommendation plus up to 5 cited bullets. Five is the ceiling and nothing pads the list to reach it - two grounded reasons come back as two, because a third one invented to fill the shape is a reason to doubt the other two. The five is the rubric's own largest count, the five-or-more that defines the 1/4 band, so it is the most separately cited claims any output here is asked to carry; the issue list caps one above it because that list is printed under a score and a list resting on its own limit could not tell you which it was, and an advisory answer has no score for its bullets to account for. If the question is open enough that no claim holds up yet, you get one clarifying question with the 2-3 readings that would each have a different answer, instead of a recommendation resting on nothing.
I have a screenshot and a decision to make - which mode is that? Grounded advisory. The question decides the mode and the screen becomes the evidence, so you get the answer first, with the observable facts it rests on, and at most three fixes that bear on that decision. It is deliberately not a review: a critique that never reaches the question you asked is a well-formed way of not answering. Ask for a full review separately and you get the score and the full issue list as well. If the screen does not show the thing you asked about, it says so instead of inferring it from what is around it.
Part of a 10-skill open-source kit for design teams by Humbleteam.
- ascii-wireframes - three distinct layout hypotheses as ASCII wireframes before any hi-fi work.
- html-mockup - census-first HTML mockups that match a reference screenshot: exact palette, item counts, component states.
- extract-design-tokens - pull palette, type, spacing, radii, and shadows from a URL or screenshot into CSS variables and JSON.
- audit-design-tokens - find token drift in a codebase: raw hex values, off-scale spacing, near-duplicate colors.
- design-qa - a pre-ship design QA gate: states, contrast, touch targets, breakpoints, keyboard paths.
- design-handoff - turn a finished mockup into a dev-ready spec: tokens, states, accessibility annotations, open questions.
- accessibility-audit - WCAG 2.2-grounded accessibility review with success-criterion citations and severity levels.
- ux-writing - interface copy that reads human: plain-verb microcopy rules and an AI-tell strip pass.
- design-brief - extract a 5-bullet design brief from messy project inputs, with a gap report for what is missing.
Humbleteam is a digital product design and AI-engineering studio: founded in 2017, working from Prague and Dubai, with 80+ digital awards to the name, including 14 Awwwards wins, a Webby, and a Red Dot. We design digital products for startups and enterprises in fintech, healthtech, sports, and AI, and we build AI infrastructure for design teams - agents, workflows, and skills like this one.
This skill is distilled from the internal playbooks we run on client work: the same checklists behind the case studies at humbleteam.com/work, for clients like Tinder and Acronis.
- The full 10-skill kit: Related skills above, or all repos at github.com/humbleteam
- What we do with AI for design teams: humbleteam.com/ai
- Design and AI writing: humbleteam.com/blog
- LinkedIn: linkedin.com/company/humbleteam
- Talk to us: hi@humbleteam.com
Issues and PRs welcome.
MIT - see LICENSE.