ahmedhamadto/software-forge/ui-polish-review

UI Polish Review

Overview

A structured visual design audit methodology based on Refactoring UI by Adam Wathan and Steve Schoger. Guides you through 7 sequential phases to systematically evaluate and improve the visual quality of any web or application interface, transforming rough or inconsistent designs into polished, professional ones.

When to Use

• Before launching a product or feature to production
• When a design "looks off" but you cannot pinpoint why
• During design reviews or code reviews that include UI changes
• When elevating a functional prototype into a polished product
• After implementing a design and wanting to verify visual quality against best practices
• When onboarding a new team and establishing design standards

When NOT to Use

• As a substitute for usability testing (use the ux-usability-review skill for that)
• For branding or marketing strategy decisions
• When the interface is still in wireframe stage and visual design has not started yet
• For accessibility-only audits (though contrast is covered here, a full a11y audit requires more)

Process

Work through each phase sequentially. At each phase:

1. Ask targeted questions about the specific interface being reviewed
2. Read the relevant chapter summary from front-end-design/refactoring-ui/ for detailed guidance
3. Suggest and execute concrete tests (grep patterns in source code, visual inspection checklists, automated checks)
4. Flag findings with severity: CRITICAL / HIGH / MEDIUM / LOW / INFO
5. Summarize findings before moving to the next phase

If the application does not have a relevant surface for a phase (e.g., no user-uploaded images), acknowledge and skip with rationale.

digraph audit_phases {
  rankdir=TB;
  node [shape=box, style=rounded];
 
  p1 [label="Phase 1\nVisual Hierarchy"];
  p2 [label="Phase 2\nLayout & Spacing"];
  p3 [label="Phase 3\nTypography"];
  p4 [label="Phase 4\nColor"];
  p5 [label="Phase 5\nDepth & Shadows"];
  p6 [label="Phase 6\nImages & Icons"];
  p7 [label="Phase 7\nFinishing Touches"];
  report [label="UI Polish\nReport", shape=note];
 
  p1 -> p2 -> p3 -> p4 -> p5 -> p6 -> p7 -> report;
}

Phase 1: Visual Hierarchy

Reference: front-end-design/refactoring-ui/ch02-hierarchy-is-everything.md

Goal: Verify that the interface communicates a clear, intentional visual hierarchy so users instantly know what is most important, secondary, and tertiary.

Questions to ask:

• Is hierarchy communicated through a combination of font weight, color, and size -- not size alone?
• Are labels used only when the data format is not self-explanatory? (Email addresses, phone numbers, dates, and currencies rarely need labels.)
• Are secondary and tertiary actions properly de-emphasized? (Outlined or text-only buttons, muted colors, smaller size.)
• Is document hierarchy (h1, h2, h3) independent from visual hierarchy? (An h2 can be visually smaller than a paragraph if that serves the design.)
• Are destructive actions de-emphasized rather than given prominent red buttons?
• Is the "emphasize by de-emphasizing" technique used -- making surrounding elements quieter rather than making the primary element louder?

Tests to run:

# Find font-size declarations without corresponding weight/color differentiation
# Red flag: many different font-sizes but uniform font-weight and color
grep -rn "font-size" --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx"
 
# Find multiple primary-styled buttons on the same screen (hierarchy violation)
grep -rn "btn-primary\|variant=\"primary\"\|variant='primary'\|type=\"primary\"\|isPrimary\|button.*primary" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue"
 
# Check for destructive actions given excessive visual prominence
grep -rn "btn-danger\|variant=\"destructive\"\|variant=\"danger\"\|bg-red-\|bg-destructive" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue"
 
# Find label-heavy patterns that might be unnecessary
grep -rn "label.*:\|<label\|<Label" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue"

Visual inspection checklist:

• [ ] Can you identify the primary, secondary, and tertiary content on each screen within 2 seconds?
• [ ] Do headings use weight and color in addition to size to establish prominence?
• [ ] Is there only one primary action per screen or section?
• [ ] Are labels removed where the data format is self-explanatory?
• [ ] On colored backgrounds, is de-emphasized text using opacity or a hue-matched lighter color rather than grey?

Finding template:

[SEVERITY] Visual Hierarchy: [description]
  Affected: [component/screen]
  Issue: [what breaks the hierarchy]
  Impact: [how it confuses or overwhelms users]
  Fix: [specific recommendation — e.g., "reduce secondary text to #666, use font-weight 400"]

Phase 2: Layout & Spacing

Reference: front-end-design/refactoring-ui/ch03-layout-and-spacing.md

Goal: Verify the interface uses a consistent, systematic spacing scale and that layout decisions support content readability and visual grouping.

Questions to ask:

• Is there a defined spacing system based on a consistent scale (multiples of 4px or 8px)?
• Is content width constrained for readability (not stretching to fill the full viewport)?
• Is spacing between groups larger than spacing within groups (Law of Proximity)?
• Are there arbitrary pixel values that fall outside the spacing scale? (17px, 13px, 37px are red flags.)
• Is the spacing scale roughly geometric (each step 1.5-2x the previous) with linear steps at the small end?
• Are elements given enough breathing room, or is the design feeling cramped?

Tests to run:

# Search for arbitrary padding/margin values not on a standard 4px or 8px scale
# Red flags: odd numbers, values like 13, 17, 21, 37, 43
grep -rn "padding:\s*[0-9]\+px\|margin:\s*[0-9]\+px\|gap:\s*[0-9]\+px" --include="*.css" --include="*.scss"
grep -rn "p-\[.*px\]\|m-\[.*px\]\|gap-\[.*px\]" --include="*.tsx" --include="*.jsx" --include="*.html"
 
# Check for max-width constraints on text containers (readability)
grep -rn "max-width\|max-w-\|prose\|container" --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx"
 
# Find hardcoded spacing values that might be arbitrary
grep -rn "13px\|17px\|21px\|37px\|43px\|51px\|67px\|73px\|81px" --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx"
 
# Check for consistent use of spacing utilities (Tailwind)
grep -rn "p-[0-9]\|m-[0-9]\|gap-[0-9]\|space-[xy]-[0-9]" --include="*.tsx" --include="*.jsx" --include="*.html"

Visual inspection checklist:

• [ ] Does the spacing feel rhythmic and consistent across the entire interface?
• [ ] Is content width constrained so text lines do not exceed ~75 characters?
• [ ] Is there clear visual grouping through proximity (related items close, unrelated items far)?
• [ ] Are there any areas that feel either too cramped or too empty?
• [ ] Do cards, modals, and containers use consistent internal padding?

Finding template:

[SEVERITY] Layout & Spacing: [description]
  Affected: [component/screen]
  Issue: [arbitrary value, inconsistent spacing, unconstrained width]
  Current: [what it is now — e.g., "padding: 13px"]
  Fix: [nearest scale value — e.g., "use padding: 12px (3 on 4px scale) or 16px (4 on 4px scale)"]

Phase 3: Typography

Reference: front-end-design/refactoring-ui/ch04-designing-text.md

Goal: Verify the interface uses a disciplined, limited type system with proper line height, line length, and font weight management.

Questions to ask:

• Is there a defined type scale with a limited set of font sizes (8-12 sizes maximum)?
• Is line height proportional to font size? (Tighter for large headings ~1.1-1.2, looser for small body text ~1.5-1.7.)
• Is line length constrained to 45-75 characters for readability?
• Are font weights limited to 2-3 across the interface? (Regular, medium/semi-bold, bold is enough.)
• Is long-form text left-aligned, not center-aligned or justified?
• Is letter-spacing adjusted for uppercase text and very large/small sizes?

Tests to run:

# Count distinct font-size values in use (too many = no type scale)
grep -rn "font-size:" --include="*.css" --include="*.scss" | grep -oP "\d+px" | sort -u
 
# Check for Tailwind text size classes
grep -rn "text-\(xs\|sm\|base\|lg\|xl\|2xl\|3xl\|4xl\|5xl\|6xl\|7xl\|8xl\|9xl\)" --include="*.tsx" --include="*.jsx" --include="*.html"
 
# Find line-height values — check for consistency and proportionality
grep -rn "line-height:" --include="*.css" --include="*.scss" | grep -oP "[\d.]+" | sort -u
 
# Find center-aligned text on potentially long content (readability issue)
grep -rn "text-align:\s*center\|text-center" --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx"
 
# Count distinct font-weight values (too many = inconsistent)
grep -rn "font-weight:" --include="*.css" --include="*.scss" | grep -oP "\d+" | sort -u
 
# Check for font-weight Tailwind classes
grep -rn "font-\(thin\|extralight\|light\|normal\|medium\|semibold\|bold\|extrabold\|black\)" --include="*.tsx" --include="*.jsx" --include="*.html"
 
# Find arbitrary font sizes that suggest no type scale
grep -rn "font-size:\s*\(13\|15\|17\|19\|21\|22\|23\|25\|26\|27\|28\|29\|31\|32\|33\|34\|35\)px" --include="*.css" --include="*.scss"

Visual inspection checklist:

• [ ] Are there more than 10 distinct font sizes? (If yes, the type scale is not constrained enough.)
• [ ] Do headings have tighter line height than body text?
• [ ] Does body text wrap within 45-75 characters per line?
• [ ] Is any long-form text center-aligned? (It should be left-aligned.)
• [ ] Are font weights limited to 2-3 values (not 5+ different weights scattered throughout)?
• [ ] Does the type scale create a clear visual rhythm between headings, subheadings, and body text?

Finding template:

[SEVERITY] Typography: [description]
  Affected: [component/screen]
  Issue: [e.g., "23 distinct font sizes in use — no type scale"]
  Impact: [inconsistency, poor readability, lack of rhythm]
  Fix: [e.g., "consolidate to a 10-step type scale: 12, 14, 16, 18, 20, 24, 30, 36, 48, 60"]

Phase 4: Color

Reference: front-end-design/refactoring-ui/ch05-working-with-color.md

Goal: Verify the interface uses a defined, systematic color palette with proper contrast, tinted greys, and consistent application.

Questions to ask:

• Is there a defined color palette with 8-10 shades per hue (not ad-hoc hex values)?
• Are greys warm-tinted or cool-tinted rather than pure grey (#333, #666, #999)?
• Is contrast ratio sufficient for text readability (WCAG AA: 4.5:1 for normal text, 3:1 for large text)?
• Is the same color used consistently for the same purpose (all primary actions use the same blue, all success states use the same green)?
• Are there too many colors competing, or is the palette focused?
• Is color used to communicate meaning (success = green, error = red, warning = amber) consistently?

Tests to run:

# Count unique color values to find ad-hoc colors
grep -rn "#[0-9a-fA-F]\{3,8\}" --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" | grep -oP "#[0-9a-fA-F]{3,8}" | sort -u
 
# Search for pure greys (should be warm/cool tinted instead)
grep -rn "#333\b\|#444\b\|#555\b\|#666\b\|#777\b\|#888\b\|#999\b\|#aaa\b\|#bbb\b\|#ccc\b\|#ddd\b\|#eee\b" --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx"
grep -rn "#333333\|#444444\|#555555\|#666666\|#777777\|#888888\|#999999\|#aaaaaa\|#bbbbbb\|#cccccc\|#dddddd\|#eeeeee" --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx"