design-review

Design review

Target: $ARGUMENTS (if empty, ask which URL and port the dev server is on, or infer it from the project's dev script — Next.js 3000, Vite 5173, CRA 3000).

What this skill is for

Generated UI is rarely broken. It is undifferentiated: correct HTML, plausible Tailwind, and every decision left at its default. This review names the specific defaults that are still in place and replaces them with chosen values.

Two sources, two jobs. The screenshot is the only thing that can tell you whether the page reads as designed — hierarchy, density, rhythm, weight of the accent. The simplifiedDOM is the only thing that can tell you why, because it carries the real ids and utility classes. A finding with no class or element behind it is an opinion; do not ship opinions.

The full catalogue of tells, with the reasoning behind each one, is docs/design/ANTI-SLOP.md. Read it when a finding needs depth. Do not restate it here.

Steps

1. Capture the page with inspect_localhost_ui, fullPage: true, viewport desktop. Add a mobile capture too — density and hierarchy failures are loudest at 390px. Raise delay to 2000–3000 if the DOM comes back nearly empty; you cannot review an unhydrated page.

2. Check summary.domTruncated. If it is true, the tree is partial. Scope every finding to what you actually saw and say which regions you could not reach.

3. Work the nine checks below in this order. The order is deliberate: typography and colour dominate perceived quality, so a page that fails check 1 is not helped by fixing check 7.

   1. Type scale, or one size repeated. Collect every text-* / font-size class in the DOM and count the distinct values. Three or fewer distinct sizes across a full page means there is no scale and no hierarchy — everything is text-sm and text-base with weight doing all the work. Eight or more usually means sizes were picked ad hoc per component. Look at the screenshot: can you identify the single most important element on the page in under a second? If not, the scale is the cause. Hand off to the type-system skill for the fix.
   2. The accent is the framework default. blue-500, blue-600, indigo-500, #3b82f6, #6366f1, shadcn's untouched --primary, Bootstrap #0d6efd. These are the single strongest tell, because they are the colour of not having decided. Also flag the opposite failure: an accent used on every card, badge, border and heading, which destroys its meaning. Hand off to the color-system skill for the fix.
   3. One radius everywhere. Grep the class lists for rounded-*. If a 1200px-wide page section, a 320px card, a 36px button and a 20px badge all carry rounded-lg, nothing reads as nested — radius should scale with the box. If everything is rounded-full or everything is square, that is the same failure in a different direction.
   4. Spacing carries hierarchy, or is uniform. Collect gap-*, p-*, m-*, space-y-*. If one value (usually 4) accounts for most of them, the page has no grouping: related elements sit as far apart as unrelated ones. Related items should be tighter than the space around their group, and section-level rhythm should be several steps larger than component-level rhythm. See docs/design/SPACING-LAYOUT.md.
   5. Optical alignment. Look at the screenshot, not the DOM. Icons centred by box rather than by mass; a button label that sits low because the cap height is not the box centre; a quote mark or bullet flush to the container instead of hanging outside it; numerals in a column aligned left instead of on the decimal; a card grid whose last row is centred when it should be flush-left. Nothing optically adjusted anywhere on a page is itself the finding.
   6. Real empty, loading and error states. Search the DOM and then the source for what renders when a list is empty, a fetch is in flight, or a request fails. A bare null, a centred "No data", or a spinner where the content will be are all the same defect. The tool cannot click, so reach these states by having the user navigate to one, or by temporarily rendering the state in code, capturing it, and reverting.
   7. Visible focus. Look for focus:outline-none with no accompanying focus-visible: ring on anything interactive — that is a removed affordance, not a style. Absent focus styling on custom div-based controls counts too. Focus cannot be captured (the tool cannot tab), so verify it in the DOM and CSS, and say so.
   8. Neutral ramp and surfaces. Pure #000 / #fff backgrounds, bg-white on a dark-mode-capable page, and text at text-gray-* with no hue are the flattest possible choices. Real interfaces tint their neutrals toward the accent and separate surfaces by a step of lightness rather than by a hard border. Flag bg-white + border-gray-200 + text-black as a set, not as three findings.
   9. Copy. "Lorem ipsum", "Card Title", "Your description here", "Get Started" on four different buttons, "Feature One/Two/Three", alt="image". Filler copy makes every other decision look provisional because nothing was sized against real content. Also flag headings that are longer than the element they label and buttons whose label does not say what happens.