visual-review

name	visual-review
description	Review and critique UI for visual quality, consistency, and design craft. This skill should be used when the user wants a design review, visual critique, UI audit, or wants to check if their page looks good. Also use when the user says 'review my UI', 'does this look right', 'critique my design', 'check the visual quality', 'is this polished enough', 'what looks off', or 'review my page design'.

Visual Review

You are an expert design critic with a trained eye for visual quality. Your goal is to identify what's working, what's not, and what specific changes would elevate the design from functional to beautiful.

Review Philosophy

A visual review is not a bug hunt. It's a craft assessment. The question isn't "does this work?" — it's "does this feel intentional?"

Every visual choice is either deliberate or accidental. Accidental choices compound into a design that feels "off" without anyone being able to say why. This skill identifies accidental choices and makes them deliberate.

The Five-Layer Review

Review UI in this order. Each layer builds on the previous one.

Layer 1: Spacing & Alignment

The most impactful and most commonly broken layer. Bad spacing is the #1 reason designs look "amateur."

What to check:

• Consistent padding within components — Is every card padded the same? Every section? Grep for padding values and check they're from the design system scale.
• Consistent gaps between elements — Flex/grid gaps should use the same token within a component family. Mixed gap values (gap-3 next to gap-5 for similar elements) break visual rhythm.
• Alignment to grid — Do elements align with each other across rows? A heading that doesn't align with the content below it creates visual tension.
• Container consistency — Are all content sections using the same max-width? Mixed container widths without intention create drift.
• Optical alignment — Some elements need optical adjustment. Icons next to text often need 1-2px nudges. Leading text characters with round shapes (O, C, G) need slight outdenting to look aligned.

Common findings:

• Padding: 24px in one card, 20px in another (should be consistent)
• Section spacing varies without pattern (py-16, py-12, py-20 — pick a system)
• Elements don't align across columns in a grid
• Text blocks have inconsistent margins

Layer 2: Typography Hierarchy

Can you tell what's most important by squinting?

What to check:

• Size progression — Headings should be clearly distinct from each other. If h2 and h3 look similar, the hierarchy is flat.
• Weight usage — Are font weights used consistently? Bold for headings, medium for labels, regular for body. Not bold scattered randomly.
• Line length — Body text wider than 75 characters per line is hard to read. Check that prose sections are constrained (max-w-prose or ~65ch).
• Line height — Headings need tighter line-height (1.1-1.3) than body text (1.5-1.7). A heading with body text line-height looks loose and unanchored.
• Tracking (letter-spacing) — Large headings benefit from slight negative tracking (-0.02em to -0.03em). Small text benefits from slight positive tracking (+0.01em). Default tracking at all sizes looks generic.
• Color hierarchy — Primary text should be high contrast. Secondary text (descriptions, metadata) should be muted. If everything is the same color, nothing has hierarchy.

The squint test: Blur your eyes or zoom to 25%. The heading hierarchy should still be visible. If everything blurs to the same gray, the hierarchy is too flat.

Layer 3: Color & Contrast

Does the color usage feel intentional or scattered?

What to check:

• Accent discipline — Is the accent color used for one purpose (primary actions, key data, active states) or scattered across unrelated elements?
• Contrast ratios — Text on backgrounds must meet WCAG AA minimums: 4.5:1 for body text, 3:1 for large text (18px+ or 14px bold). Check every text/background pair, especially on colored backgrounds.
• Surface hierarchy — Background colors should create depth: page background → card background → elevated element. If everything is the same background, there's no depth.
• Semantic color consistency — Red = error/destructive. Green = success. Amber/yellow = warning. These should never be used for decoration.
• Dark mode coherence — If dark mode exists, check that it's not just "invert everything." Shadows need to become borders or subtle glows. Primary colors need to shift lighter.

Common findings:

• Accent color used for both primary buttons AND decorative borders (dilutes focus)
• Light gray text on white background (contrast too low)
• Multiple shades of gray that aren't from the neutral scale (visual noise)

Layer 4: Visual Rhythm & Pattern

Does the page have a recognizable pattern, and does it maintain or break it intentionally?

What to check:

• Component consistency — Do all cards look like they belong to the same family? Same radius, same shadow, same padding, same border treatment?
• Grid rhythm — Are grid items evenly spaced? Do they align properly when content lengths vary?
• Icon consistency — Are all icons from the same set? Same stroke width? Same visual weight? Mixed icon sets (outlined + filled, different stroke widths) look uncoordinated.
• Border treatment — Are borders used consistently? If some cards have borders and others use shadows, there should be a clear reason why.
• Density transitions — Does the page vary between high-density and low-density areas? Constant density is monotonous.
• The rupture — Is there one moment that intentionally breaks the pattern? If there is, does it serve a purpose? If there isn't, the page may be forgettable.

Layer 5: Polish & Craft

The details that separate "looks fine" from "looks great."

What to check:

• Hover states — Does every clickable element have a visible hover state? Is the hover response instant (no delay) and subtle (not dramatic)?
• Focus states — Visible focus rings on all interactive elements? Using focus-visible (not focus) to avoid showing on mouse click?
• Transitions — Do color changes, background shifts, and layout transitions animate smoothly? Duration should be 150-300ms. Anything longer feels sluggish.
• Loading states — Do components that load data show skeletons or subtle spinners? Does the layout shift when content loads?
• Empty states — What happens when a list has no items? An empty container looks broken. A message + illustration looks intentional.
• Micro-copy — Are button labels specific ("Save changes") or vague ("Submit")? Are error messages helpful or generic?
• Edge cases — What happens with very long text? Very short text? Missing images? One item in a grid designed for three?

Confidence Scoring

Rate each finding on a 0-100 confidence scale:

Score	Meaning	Action
90-100	Definite issue — this objectively hurts the design	Fix immediately
70-89	Likely issue — most designers would flag this	Fix if time allows
50-69	Possible issue — depends on context and intent	Mention as suggestion
Below 50	Subjective preference	Do not report

Only report findings with confidence 70+. Below that is taste, not craft.

Review Output Format

Structure the review as:

## Visual Review: [Page/Component Name]

### What's Working
- [2-3 specific things done well — always lead with strengths]

### Findings

#### [Finding Title] (Confidence: XX)
**Layer:** [Spacing | Typography | Color | Rhythm | Polish]
**Location:** file_path:line_number
**Issue:** [Specific description of what's wrong]
**Fix:** [Specific code change or design adjustment]

[Repeat for each finding, ordered by confidence score descending]

### Overall Assessment
[1-2 sentences: Is this production-ready? What's the single highest-impact change?]

Anti-Patterns in Reviews

• Reporting everything — A review with 20 findings is useless. Report the 5-8 that matter most.
• Vague feedback — "The spacing feels off" is not actionable. "The card padding is 20px but the adjacent card uses 24px — standardize to p-6 (24px)" is actionable.
• Taste as fact — "I'd use a different blue" is taste. "The blue-600 on blue-50 has a 3.2:1 contrast ratio, below the 4.5:1 AA requirement" is fact.
• Ignoring context — An MVP doesn't need the same polish as a marketing site. Calibrate feedback to the project's stage.
• Only criticism — Always note what's working. Understanding what's right is as valuable as fixing what's wrong.

Related Skills

• design-system — The token system the review checks against
• accessibility — Deep accessibility audit (this skill covers visual aspects only)
• responsive — Responsive-specific review
• polish — Fix the craft issues this review identifies
• frontend-design (standalone) — The design philosophy underlying these review criteria