Refactoring UI by Adam Wathan and Steve Schoger is the most practical design resource I have found for developers. Instead of teaching abstract design theory, it gives you concrete rules and systems you can apply immediately. Here are the lessons that changed how I approach UI work.

Start With Too Much Design

Most developers start a project by opening their code editor and building components. The result is usually a page that works but looks generic and unpolished.

The book's advice: do not start with code. Start by figuring out what the interface needs to communicate. Sketch the layout on paper or in a low-fidelity tool before writing any HTML. Decide what information is most important and give it the most visual prominence.

More importantly, design in detail rather than designing the whole page at a low level. Pick one section, make it look great, then move to the next. Trying to lay out an entire page at once leads to mediocre results everywhere.

Choosing Colors

Color is where most developer-designed UIs fall apart. The common mistake is picking colors one at a time as needed, leading to an inconsistent palette with no cohesion.

Build a color palette upfront

Define your colors before you start building. A good palette needs:

  • Grays - 8-10 shades from near-white to near-black. You will use these constantly for text, backgrounds, borders, and shadows.
  • A primary color - 5-10 shades from light to dark. The mid-range shade is your button color, links, and active states. Lighter shades work for backgrounds, darker for hover states.
  • Accent colors - for success (green), warning (yellow), error (red), and informational (blue) states. Each needs 5-10 shades.
/* Example: defining gray scale */
--gray-50:  #f9fafb;
--gray-100: #f3f4f6;
--gray-200: #e5e7eb;
--gray-300: #d1d5db;
--gray-400: #9ca3af;
--gray-500: #6b7280;
--gray-600: #4b5563;
--gray-700: #374151;
--gray-800: #1f2937;
--gray-900: #111827;

Do not use gray text on colored backgrounds

When you need muted text on a colored background, do not just use gray. It looks washed out. Instead, use a lighter or more transparent version of the background color for the text. This keeps the text feeling connected to its context.

Spacing Systems

Inconsistent spacing is one of the most common reasons developer-built UIs look "off." The fix is simple: use a spacing scale and only pick values from it.

/* A spacing scale based on a 4px grid */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;

The key rules:

  • Never use arbitrary spacing values. Always pick from your scale. If 16px feels too small and 24px feels too big, resist the urge to use 20px unless it is in your scale.
  • Bigger elements need more space around them. A heading needs more margin than a paragraph. A card needs more padding than a badge.
  • Use space to create relationships. Elements that are related should be closer together. A label should be closer to its input than to the previous field group.

Typography Hierarchy

Good typography hierarchy means the user can scan a page and understand its structure without reading every word. You achieve this through a combination of size, weight, and color.

Define a type scale

Like spacing, font sizes should come from a predefined scale:

--text-xs: 0.75rem;    /* 12px */
--text-sm: 0.875rem;   /* 14px */
--text-base: 1rem;     /* 16px */
--text-lg: 1.125rem;   /* 18px */
--text-xl: 1.25rem;    /* 20px */
--text-2xl: 1.5rem;    /* 24px */
--text-3xl: 1.875rem;  /* 30px */
--text-4xl: 2.25rem;   /* 36px */

Use weight and color, not just size

A common mistake is using only font size to create hierarchy. This leads to huge headings and tiny body text with nothing in between. Instead, combine three tools:

  • Size - for the biggest distinctions (page title vs body text)
  • Weight - bold for emphasis, normal for body, light for secondary text
  • Color - dark for primary content, medium gray for secondary, light gray for tertiary

With these three dimensions, you can create clear hierarchy even when two elements are the same font size. A bold, dark gray label and a normal weight, medium gray value read at different levels of importance despite being the same size.

Limit Your Choices

The most practical advice in the entire book: systematize everything in advance. Define your colors, spacing, font sizes, shadows, and border radii before you start building. When you are in the middle of coding a component, you should be picking from predefined options, not inventing new values.

This constraint actually speeds you up. Decision fatigue is real. When you have 10 predefined spacing values, you pick one quickly. When you have infinite choices, you waste time debating between 14px and 15px padding.

Final Thought

Refactoring UI's biggest insight is that good design is not about artistic talent. It is about systems and constraints. A developer who follows a well-defined design system will produce better-looking interfaces than a talented designer making ad-hoc decisions. The system does the heavy lifting.