ui-review
Skill2 starsChanged yesterdayMITView on GitHub
Review a user interface that already exists and report what harms its customers, with evidence and severity. Use when asked to audit, review, critique or check a page, screen, dashboard, component or flow, to test a journey such as signup or checkout, to check a screen on a phone, or before claiming a change works. Also use to review what a change did to an interface: a diff, a branch, a pull request or uncommitted work. Also use when the user says a product looks off, looks AI-generated, feels dated or asks whether it is ready to ship. Works against a running application or a Storybook, measures the live render, walks the journey as a customer, checks the result against the project's design principles, and sorts findings by harm. Two modes: review only, which changes no files, and review and fix.
22 other projects use a version of this.
Adopted by
Most recently taken up by
- joshuafosterbdo/Skillstheir own version, first seen Nov 16, 2026
- colasama/MahoShojo-Generatortheir own version, first seen Nov 9, 2026
- WilliamEbong/CourseForgetheir own version, first seen Nov 8, 2026
- buildomator/buildomatortheir own version, first seen Nov 4, 2026
- krzysztofsurdy/code-virtuosotheir own version, first seen Nov 1, 2026
- TucsenRoman/claude-skillstheir own version, first seen Oct 20, 2026
Used with
Projects with it also use accessibility and grill-me.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
ElasticSkillaccessibility
Accessibility guidance for Kibana. Use this skill when working with or reviewing EUI components, resolving a11y-related (@elastic/eui) ESLint issues, and ensuring proper use of ARIA attributes, focus management, keyboard interactions, and accessible naming conventions.
Also in 3 projects that use this
GoogleSkillgrill-me
A relentless interview to sharpen a plan or design.
Also in 3 projects that use this
Other versions22 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 22
- RandallLiuXin/GodotMaker★ 555same name
- arla6ka/skills★ 424same name
- arla6ka/design.how★ 421same name
- colasama/MahoShojo-Generator★ 168same name
- jvm-skills/jvm-skills★ 140same name
- buildomator/buildomator★ 102same name
- nimadorostkar/Claude-Skills-collection★ 37same name
- krzysztofsurdy/code-virtuoso★ 36same name
- applypack/applypack★ 32same name
- ceptln/quota-burner★ 18same name
12 more not listed
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.
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 13 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 18 edited versions we read keep these.
13
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
Read references/changes.md and work through it, then return here for the measuring, the looking and the severity.
- Very specific: line 122
Run it again with the first list of controls replaced by svg, img, [role=img], p, span, li, dt, dd, td to check each text, icon and mark in …
- Distinctive: line 126
Every number the script returns is a candidate, not a finding.
- Distinctive: line 149
Rhythm: Do the spacing and type sizes come from the product's scale, or were they chosen for this screen alone?
- Distinctive: line 151
State: Look at every state step 5 rendered, not only the one the fixtures gave you.
- Distinctive: line 172
Write the journey down before opening the browser, so what you expected is recorded independently of what happened:
- Distinctive: line 197
Every row needs evidence that exists.
- Distinctive: line 227
No permission: what does a customer who may not do this see?
- Distinctive: line 264
When the application cannot be started or reached, stop.
- Distinctive: line 293
Never by how easy the fix is.
- Distinctive: line 323
Taste: Every finding names who it hurts and how.
- Distinctive: line 378
No score out of 100. A number invites arguing about the number instead of fixing the blocker, and the severity list already carries the …
- Distinctive: line 388
Run the project's checks for the area changed, then the broader suite once.
- Distinctive: line 393
Stop every server you started.
“Common” is measured: kept by at least 6 in 10 of the 18 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
UI review
Two modes, and the mode is settled before anything else.
| Mode | Triggered by | What it may do |
| Review only | "review", "audit", "critique", "what is wrong with", "is this ready" | Read, render, measure, walk, report. It changes no files. |
| Review and fix | "review and fix", "find and fix", "improve", or an explicit yes to an offer | Everything above, then the approved fixes, then verification |
State the mode in the first line of the reply. A review-only request never becomes a redesign because the findings were bad. Where fixing is the obvious next step, finish the report and offer it.
Scope: a surface, or a change
Two scopes, which answer different questions.
| Scope | Asked by | Answers |
| A surface | "review this page", "audit the dashboard", "is this ready" | Is this interface good |
| A change | "review my diff", "review this branch", "review pr 482", "did I break anything" | Did this change make it worse |
A change scope is not a surface scope with a filter. It resolves a base commit and expands the changed files to the surfaces they render in. It then reads the lines the change removed, and statuses every finding by what caused it. Read references/changes.md and work through it, then return here for the measuring, the looking and the severity.
Where the request names no scope and the tree is dirty or ahead of its base, ask which the user meant. The two reports are not interchangeable.
1. Find the design principles first
A review with no stated principles is taste, and taste loses arguments. Decide what this interface is being measured against, in this order:
DESIGN.mdat the project root. Its tokens and its Do's and Don'ts are the first standard. Runpnpm dlx @google/design.md lint DESIGN.mdand treat what it reports as findings about the system itself.- The project's own system in code: a token file, a theme, a Tailwind config, a component library. Values off that system are drift.
- gates.md, the floor that holds for any product.
- craft.md, the layer above the floor.
Where the project has none of the first two, say so in the report and review
against 3 and 4 alone. Offer to write a DESIGN.md with ui-design; do not
write one inside a review.
2. Pick the target: running app, Storybook, or both
| Target | Use it for | How |
| The running application | Journeys, real data, real density, anything a customer meets | The project's own dev or start script |
| Storybook | A component's states and variants in isolation, including the ones the app never shows | storybook dev -p 6006, then one story per state |
| A static page | A mock, a landing page, an exported build | Serve the folder; never open it as a file: URL |
Find Storybook before assuming it is absent: look for .storybook/, a
storybook script in package.json, or *.stories.* files. Where both a
Storybook and a running application exist, use both. Storybook alone cannot
close a review. It shows components, never the journey, the real data or the
page they sit on together. Say which target each finding came from.
In Storybook, walk the story index rather than guessing names. Open
/index.json on the running Storybook for every story id. Then visit each as
/iframe.html?id=<story-id>. That URL renders the component alone, with no
surrounding chrome to measure around.
3. Measure the render
Measure at 1440, 1024 and 375. playwright.md has the mechanics.
Pass the whole contents of .claude/skills/ui-design/scripts/measure.js as the
function argument of browser_evaluate, once per width. It returns overflow,
text contrast, target sizes, controls with no accessible name, heading order,
unsized media and text below 12px. It also returns a census of the type sizes,
radii, shadows and font families the page really uses.
It reports five geometry faults by name, each one a rule in craft.md, Spacing and alignment:
| Fault | What the number means |
clipped | A mark sliced by a container that hides overflow. A crop marked data-crop is exempt, and truncation with an ellipsis is not counted |
tightInsets | Ink closer than 8px to the edge of the surface it sits on, where 12px is the rule. Measured from the text, not from its box. A dense table or a chip set tighter than 8px on purpose reports here too |
unevenPadding | A panel of at least 120 by 80 with two or more children whose content is cramped against one edge, or whose left and right gaps differ while the content fills the width. A panel with room below its content is not reported |
nearTangents | Sibling edges 0.5 to 3.5px apart: a gap that neither closes nor clears a step of the scale, or two left, right or top edges that were meant to line up. Bottom edges are not compared, because baseline-aligned text of two sizes misses by a pixel or two when it is right |
wrappedUnits | A figure split from its unit, or a currency sign from its digits, over two lines. It puts a range round each and compares the line they landed on, and it reads through a child span, so 42 <span>GB</span> counts |
Against the skill's own fixtures on 2026-11-12, at 1440 in Chrome 157,
dashboard-after.html returned zero of all five and geometry-faults.html
returned 1 / 1 / 1 / 2 / 2: the faults each panel was built to carry.
docs/testing-report.md has every count. No real application, no 375 width
and no dark surface has been measured yet, so a count on one of those is new
ground. A page with a dozen nearTangents from one cause is one finding with
twelve occurrences.
Then check that nothing covers a control. Each visible control and link must
be the top element at its centre: document.elementFromPoint(x, y) returns it
or a child. Run this with browser_evaluate at each width, after each scroll:
() => [...document.querySelectorAll('a, button, input, select, textarea, summary, [role=button], [role=link], [role=tab]')].filter(e => { const r = e.getBoundingClientRect(), x = r.x + r.width / 2, y = r.y + r.height / 2; if (!r.width || !r.height || y < 0 || y > innerHeight || x < 0 || x > innerWidth) return false; const t = document.elementFromPoint(x, y); for (let n = t; n; n = n.parentElement) if (/sticky|fixed/.test(getComputedStyle(n).position) && n.matches('header, [role=banner]')) return false; return !t || !((e.closest('a, button, label, summary, [role=button], [role=link], [role=tab], [data-node], [role=group]') ?? e).contains(t) || t.contains(e)); }).map(e => e.outerHTML.slice(0, 120))Report each one it returns as fault covered. It skips an element under a
sticky or fixed page header (header, [role=banner]) after a scroll. A fixed
toast, banner or dialog over a control is still a finding. It also skips an
element covered by part of its own control, node or card ([data-node],
[role=group]), such as an icon under its own label. It skips an element its
cover holds, such as an icon that lets clicks through to its parent. If the
page draws a graph, add its node class to that list, such as
.react-flow__node.
Run it again with the first list of controls replaced by
svg, img, [role=img], p, span, li, dt, dd, td to check each text, icon and
mark in a panel, key or legend.
Every number the script returns is a candidate, not a finding. Confirm it on the render, decide whether it harms a customer, and fold one cause into one finding.
4. Look at the screenshots, in this order
The script cannot see hierarchy, rhythm, crowding, visual weight or whether the page is any good. Open every screenshot at every width and walk these eight. Each one is a failure that renders wrong while the source reads fine.
- Placement. Is the main element where it belongs? Centre what should be centred and align the rest to the grid. Is there a large empty region carrying nothing?
- Containment. Does any text, number or label cross or touch the edge of its card, column or button? Right-aligned values and long identifiers fail here first.
- Duplication. Does the screen offer the same action twice? Does a control the customer had before still exist?
- Reachability at 375. Is every control on screen? Is each target at least 24 × 24, and 44 × 44 where a thumb is expected? Does anything need a horizontal scroll?
- Contrast. Can you read every label against its own background, including the pressed, hovered and selected states?
- Rhythm. Do the spacing and type sizes come from the product's scale, or were they chosen for this screen alone?
- State. Look at every state step 5 rendered, not only the one the fixtures gave you. A state that is correct in the DOM and ugly on screen fails here. Step 5 decides which states to render; this check judges them.
- The named geometry faults. Open the screenshot at each place the script
named a
clipped,tightInsets,unevenPadding,nearTangentsorwrappedUnitscandidate and decide whether it harms a reader. File a confirmed one under check 2 where it is containment and check 6 where it is rhythm: a clip is a Warning, and a miss of a pixel or two is Polish. Three of them have an innocent explanation worth checking first: a deliberate crop, a chip whose vertical padding is tight on purpose, and a grid that stretched a panel taller than its content. The rest ofcraft.md, Spacing and alignment is eye work: a dot outside its row, a body starting under an avatar instead of at the name, a title spread from its own subtitle.
Say which of the eight each finding is. Where you could not render, say so rather than judging from the source.
5. Walk it as a customer
A DOM is not an experience. Skip this only for a single static element.
Write the journey down before opening the browser, so what you expected is recorded independently of what happened:
JOURNEY: reassign a late run
ENTRY: /runs, signed in as a dispatcher, 40 open runs seeded
GOAL: the late run is assigned to another operator
STEPS: 1 find the late run 2 open it 3 choose an operator 4 confirm
MISTAKES TO TRY: confirm with nobody chosen; reassign a finished run;
lose the connection mid-saveThen walk it, recording what the customer meets rather than what the code intends:
STEP 2: open the late run
SEES: <what is on screen, from the snapshot or the screenshot>
EXPECTS: <what a customer would assume happens next>
HAPPENS: <what actually happened>
EVIDENCE: <the screenshot file, or the snapshot line>
FRICTION: none | low | high | blocker
WHY: <what caused it: a label, a missing state, a dead control>Every row needs evidence that exists. A row with no screenshot and no snapshot behind it does not go in the report. "The customer would feel confused" is usable only when the row says what confused them.
The states and scenarios a happy path hides. Each axis carries a cue: the property that makes it worth running. Cue matches, run the axis. Cue fails, drop it and name the drop in the report. An unnamed drop reads as coverage you did not have.
| Axis | Cue | What to render |
| Lifecycle | always | Empty at first use, empty because a filter matched nothing, loading, failure, recovery, no permission |
| Quantity | it repeats over items | Zero, one, the realistic count, ten times the realistic count |
| Content length | it renders text it does not author | Empty string, one word, several sentences, one unbreakable string |
| Content shape | the text can come from customers or from locales nobody on the team writes | Emoji alone and inside a sentence, right-to-left, mixed direction, diacritics and tall scripts, figures down a column |
| Container | always | 320px, squeezed by a flex or grid sibling, very wide |
| Environment | the project has the mode | Dark theme, browser zoom, reduced motion |
Lifecycle, in detail. "Not reachable here" is a valid result as long as it is recorded.
- Empty at first use: no rows yet. Does it say what to do next?
- Empty because a filter matched nothing: a different screen from the one above. Does it say which filter emptied it and offer to clear it? Zeros in place of an empty result are a defect, not a state.
- Loading: feedback inside a few hundred milliseconds, and does the layout hold its size?
- Failure: a request that fails, a validation that rejects, a timeout. Is the message specific, next to the thing that failed, and recoverable?
- Recovery: can the customer get back without starting over or reloading?
- No permission: what does a customer who may not do this see?
What each of the others catches, and where it is easy to get wrong:
- Ten times the realistic count finds the missing scroll or pagination, the sticky header that unsticks, and the render that collapses. The densest fixture a project ships is almost never its densest real case.
- One unbreakable string is a long URL or a long identifier with no wrap opportunity. It overflows where several sentences wrap cleanly, so the two are different tests.
- The container widths are fixed boxes on the page, not viewport resizes.
The flex-sibling squeeze is the one that finds a missing
min-width: 0orminmax(0, 1fr), which is gates rule 15, and no viewport resize reproduces it. A component does not choose its container's width. - Toggle the real environment mode. Re-declaring dark tokens under a class observes a different component, not the one that ships. Zoom in the browser and set reduced motion in the system, then look again.
- Focus and hover are yours to try by hand. Tab through the instances rather than simulating a focus state in a harness, which can hold a ring the keyboard would never show.
- Anything that moves is filmed, not inferred. Slow it down and capture every appear, disappear, press and loop seam, then reduced motion. playwright.md, Filming motion, has the mechanics. A hidden element that still takes clicks, an entrance that fires on every keystroke and an element left invisible under reduced motion all read as correct in the source and in a still.
The mistakes. Submit the form empty, and with one field wrong. Press the primary action twice. Go back mid-flow, then forward. Reload halfway through. Open a link in a new tab and carry on in the first. Content length and shape are the axes above, not mistakes to try here.
At 375. Walk the whole journey at a phone width, not only look at it. A journey that works on desktop and dead-ends on a phone is a blocker. Check every control reachable without horizontal scrolling, targets at least 24 × 24 and comfortably 44 × 44, the primary action reachable with a thumb.
When the application cannot be started or reached, stop. Say which it was — no server, no credentials, no data, a failing build — and mark every journey claim unverified. Reading the source is not a substitute.
6. Sort every finding into its kind
The kinds matter because they go to different people and cost different amounts to fix. Give each finding exactly one.
- Product and information architecture. The screen solves the wrong problem. Or it shows the system's internals rather than the customer's task. Or it buries what the job needs behind what the database holds.
- Journey and usability — the customer cannot get from the entry point to the outcome without confusion, a dead end or a detour.
- Design system — values off the system in
DESIGN.mdor the token file: a hard-coded colour, an off-scale spacing, a third radius, a fourth font. - Visual design — hierarchy, rhythm, density, type, colour, distinctiveness. Nothing dominates; twelve equal tiles; a page that could belong to any other product.
- Interaction and state — a missing empty, loading, error or recovery state; feedback that lies; a control with no response.
- Accessibility — contrast, naming, keyboard operability, focus, status carried by colour alone, heading structure, reduced motion.
- Implementation — the code behind one of the above: a hard-coded palette, a fixture that hides the dense case, a layout that cannot hold long content.
7. Severity, by harm to the customer
Never by how easy the fix is.
| Severity | Meaning |
| Blocker | Stops a core task, loses data, misleads: the primary action unreachable, a keyboard trap, a figure that misstates the data, a success message for a failure, a form that prints "Sent" with nothing behind it |
| Critical | Major harm on a common path: body or action text below 4.5:1, horizontal scrolling at 375, a missing empty or error state on a primary flow, a control with no accessible name, a placeholder used as the only label, an invented metric or testimonial |
| Warning | Degrades the experience: off-system spacing, values off a shared scale, weak hierarchy, duplicated actions, words or a mark clipped by their own container, a forgettable public page |
| Polish | Refinement: a widow, nested corners, a few pixels of asymmetry |
Torn between two, take the lower and say why. An inflated review gets ignored.
Order the report by harm, then by how many customers meet it, then by how often, then by business consequence. Where two findings share a cause, the cause is the finding and the occurrences are its evidence.
8. What not to flag
- Deliberate, consistent choices. A dense 32px control row on a pointer-first console, a labelled zoomed axis, an established domain convention. Ask about it; do not score it.
- Anything
DESIGN.mdexplicitly allows. The project's own system outranks the general floor. Where the two disagree, say so once and followDESIGN.md. - Wiring a static page cannot have: a
#link, a form with no endpoint. List those once, unscored, as wiring to confirm. The exception is a result that is false, such as a filter that relabels the view but not the data. - House rules that are not standards. 12px labels and table headers are normal in dense data interfaces. Flag reading copy below 16px on a reading page; do not invent a floor.
- Missing dark mode, unless the product has or promises one.
- Taste. Every finding names who it hurts and how.
- The same cause twice.
9. Finding format
C2. Run status shown by colour alone (.run-row .status, 40 rows)
Kind: accessibility
Found: status is a coloured dot with no word or shape; green and amber
measure 2.9:1 against the row background
Why: a colour-blind dispatcher cannot tell a late run from a running one,
which is the screen's whole job
Fix: add the status word beside the dot and give each status its own shape
Evidence: shots/1440-runs.png, measure-1440.json contrastFailures[3]One line each for polish items. Keep Found and Why to one or two lines.
In a change scope, every finding also carries a Status line of introduced,
regression or pre-existing, set by cause and not by position. Cap
pre-existing at three.
10. The report
# UI review: <surface or change>
Mode: review only | review and fix
Scope: a surface | a change
Measured against: <DESIGN.md | the token file | gates.md and craft.md alone>
Checked: <widths, axes run, journeys walked, target, browser>
Axes dropped: <axis, and the cue that failed>
Stood in for: <fixtures for live data, a seeded account, a local font>
Not checked: <what the environment could not reach>
Top three: <three ids, one line each>
## Blockers / Critical / Warnings / Polish
<findings in the format above, each with its kind>
## States
empty first use <result> · empty by filter <result> · loading <result>
· dense <result> · error <result> · recovery <result>
· permission <result | not reachable> · 10x count <result>
· unbreakable string <result> · 320px <result> · flex squeeze <result>
## What is sound
<the decisions worth keeping, so a later session does not undo them>
## Questions
<at most three, each with the assumption made meanwhile>Record what is sound. A review that lists only faults invites a rewrite of things that were right.
No score out of 100. A number invites arguing about the number instead of fixing the blocker, and the severity list already carries the order.
11. In review-and-fix mode
- Get the fix list agreed, or fix only blockers and critical findings and say that is what you did.
- Identify the journeys that already work, before editing.
- Fix one cause at a time. Re-measure and re-render after each.
- Walk the journey again. A fix nobody re-walked is a claim, not a result.
- Run the project's checks for the area changed, then the broader suite once. regression.md has the rules, including how to tell your failures from the ones already failing.
- Report each finding as fixed, left with a reason, or not verified.
Stop every server you started. Record the port and how to stop it while the review runs.
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.

