refactoring-ui

---
name: refactoring-ui
description: Use when auditing or fixing visual hierarchy, spacing, color, or depth in a web UI, or when a design "looks amateur" and needs a systematic polish pass.
category: Design
version: 1.0.0
tools: []
---

# Refactoring UI Design System

A practical, opinionated approach to UI design. Apply these principles when generating frontend code, reviewing designs, or advising on visual improvements.

## Core Principle

**Design in grayscale first. Add color last.** This forces proper hierarchy through spacing, contrast, and typography before relying on color as a crutch. Great UI isn't about talent — it's about systems. Constrained scales for spacing, type, color, and shadows produce consistently professional results. Start with too much white space and remove; leave details (icons, shadows, micro-interactions) until layout and hierarchy work.

## Scoring

**Goal: 10/10.** Score by counting satisfied rows in the Quick Diagnostic (8 yes/no checks): `score = round(satisfied / 8 × 10)`. Bands: **10** = all 8 pass (hierarchy reads blurred and in grayscale, every value on a scale); **9** = exactly 1 gap (usually weak hierarchy or thin white space); **6-8** = 2-3 gaps; **≤5** = 4+ gaps (arbitrary spacing, color doing the work hierarchy should, or failing contrast). State the current score and the specific rows to fix.

## The Refactoring UI Framework

### 1. Visual Hierarchy

Not everything can be important. Create hierarchy through three levers: **size, weight, color**. Combine levers, don't multiply — primary text = large OR bold OR dark, not all three; save "all three" for the single most important element. Labels are secondary: form labels, table headers, and metadata support the data, not compete with it — make them smaller, lighter, or uppercase-small. Semantic color ≠ visual weight — a muted secondary button often beats screaming red for routine destructive actions.

**Design patterns:** three-level hierarchy (Size: large/base/small; Weight: bold/medium/normal; Color: dark/medium/light gray); button hierarchy (primary filled, secondary outlined/muted, tertiary text-only).

**Ethical boundary:** don't use hierarchy tricks to hide important information like pricing, terms, or cancellation options.

### 2. Spacing & Sizing

Use a constrained spacing scale, not arbitrary values: **4, 8, 16, 24, 32, 48, 64px**. Spacing defines relationships — closer elements read as more related. Start with too much white space, then remove — you'll almost never remove enough. Spacing between groups must exceed spacing within groups. Constrain widths: text to 45-75 characters (`max-w-prose`), forms to 300-500px; full-width is almost never right.

**CSS patterns:** `p-1`(4px) `p-2`(8px) `p-4`(16px) `p-6`(24px) `p-8`(32px) `p-12`(48px) `p-16`(64px); `max-w-prose`(65ch) `max-w-md`(28rem) `max-w-lg`(32rem) `max-w-xl`(36rem); `gap-2` for related items, `gap-6` for section separation.

### 3. Typography

Use a modular type scale (~1.2× steps, hand-tuned): **12, 14, 16, 18, 20, 24, 30, 36px**. This creates natural visual rhythm. Headings: tight line height (1.0-1.25); body: relaxed (1.5-1.75) — wider text needs more line height. Avoid weights below 400 for body text; use bold (600-700) for emphasis, not everything. Two fonts max: one for headings, one for body (or one family with weight variation).

**CSS patterns:** `text-xs`(12px) `text-sm`(14px) `text-base`(16px) `text-lg`(18px) `text-xl`(20px); `font-normal`(400) `font-medium`(500) `font-semibold`(600) `font-bold`(700); `leading-tight`(1.25) `leading-normal`(1.5) `leading-relaxed`(1.75).

### 4. Color

Build a systematic palette with **5-9 shades per color**, add subtle saturation to grays, and design in grayscale first. Each color needs shades from near-white to near-black (50-900); darkest is not pure black — use `#111827`, not `#000000`. Pure grays look lifeless — tint them (cool UI: blue like `#64748b`; warm UI: yellow/brown like `#78716c`). HSL: lighter = raise lightness, lower saturation, hue toward 60°; darker = the reverse, hue toward 0°/240°. Contrast minimums: 4.5:1 body text, 3:1 large text (18px+); use `#374151` (gray-700) on white, not lighter grays.

**CSS patterns:** `text-gray-900`(dark) `text-gray-600`(medium) `text-gray-400`(light); `bg-blue-50` for subtle backgrounds, `bg-blue-500` for primary actions; `border-gray-200` for subtle borders, `border-gray-300` for stronger.

### 5. Depth & Shadows

Use a shadow scale to convey elevation — small shadows for slightly raised elements (buttons, cards), large shadows for floating ones (modals, dropdowns). The eye reads shadow size as height above the page. Good shadows have two parts: a tight dark shadow for crispness plus a larger soft one for atmosphere. Depth without shadows: lighter top border + darker bottom border, subtle gradients, overlapping elements. Don't overuse — if everything floats, nothing has depth; shadow color is transparent dark, never opaque gray.

**CSS patterns:** `shadow-sm`: `0 1px 2px rgba(0,0,0,0.05)`; `shadow-md`: `0 4px 6px rgba(0,0,0,0.1)`; `shadow-lg`: `0 10px 15px rgba(0,0,0,0.1)`; `shadow-xl`: `0 20px 25px rgba(0,0,0,0.15)`.

### 6. Images & Icons

Treat images as design elements, not afterthoughts. Size icons deliberately and use overlays to keep text readable on images — poorly sized icons look unstyled and break consistency. Never stretch or distort — use `object-fit: cover` with fixed aspect ratios and crop deliberately. Text over images needs a semi-transparent overlay. Empty states are an opportunity — use illustrations plus a clear CTA, not just text.

**CSS patterns:** `object-fit: cover` with fixed `aspect-ratio`; icon sizing `w-4 h-4` inline, `w-6 h-6` navigation, `w-8 h-8` feature icons; overlay `bg-gradient-to-t from-black/60 to-transparent` for text on images.

### 7. Layout & Composition

Don't center everything. Use alignment, overlap, and emphasis variation to create engaging compositions. A consistent left edge gives the eye a fixed return point per line, so it costs less to scan; centered multi-line text moves that edge every line and slows reading. Left-align by default; center only short headlines, heroes, single-action CTAs, and empty states. Cards don't need to contain everything — let images bleed to edges or overlap containers. Vary visual treatment in lists and feeds — feature some items, minimize others.

**CSS patterns:** `text-left` by default, `text-center` only for heroes and short headlines; `grid grid-cols-3 gap-6` for feature grids, `max-w-4xl mx-auto` for page containers; `overflow-hidden` on cards with `object-fit: cover` images that bleed to edges.

## Common Mistakes

| Mistake | Why It Fails | Fix |
|---------|-------------|------|
| **"Looks amateur"** | Insufficient white space, unconstrained widths | More white space, constrain content widths |
| **"Feels flat"** | No depth differentiation | Subtle shadows, border-bottom on sections |
| **"Text is hard to read"** | Poor line-height, too wide, low contrast | Increase line-height, constrain width, boost contrast |
| **"Everything looks the same"** | No visual hierarchy | Vary size/weight/color between primary and secondary |
| **"Feels cluttered"** | Equal spacing everywhere | Group related items, larger gaps between groups |
| **"Colors clash"** | Random choices, no system | Reduce saturation, more grays, limit to palette |
| **Arbitrary values** | px values like 13, 17, 23 breed inconsistency | Stick to the spacing and type scales |

## Quick Diagnostic

| Question | If No | Action |
|----------|-------|--------|
| Does hierarchy read when squinting (blur test)? | Elements competing | Increase primary/secondary contrast |
| Does it work in grayscale? | Color is a crutch | Strengthen size/weight/spacing hierarchy |
| Is there enough white space? | Probably not — most designs are too dense | Increase spacing, especially between groups |
| Are labels de-emphasized vs. values? | Labels competing with data | Smaller, lighter, or uppercase-small labels |
| Does spacing follow a consistent scale? | Arbitrary spacing = visual noise | Use 4/8/16/24/32/48/64 only |
| Is text width constrained? | Long lines fatigue readers | Apply `max-w-prose` (~65ch) |
| Do colors have sufficient contrast? | Accessibility failure | WCAG-check; use gray-700+ on white |
| Are shadows appropriate for elevation? | Elements float at wrong level | Match shadow scale to element purpose |

Based on *Refactoring UI* by Adam Wathan & Steve Schoger.