visual-hierarchy-refactoring

What this skill does

# Visual Hierarchy & Refactoring UI

## Overview

Visual hierarchy is the principle that **design is a function of size, weight, and contrast**—not color. When done right, users instantly understand what's important and where to look next. This skill teaches you to establish clear hierarchy through systematic visual decisions.

## Core Principle: The Rule of Excessive Whitespace

The most common mistake in interface design is **density**. When interfaces feel cluttered, the instinct is to shrink text. This is wrong.

**The Solution: Start with too much space.**

When you have breathing room, users can scan the interface and identify signals amongst the noise. Generous whitespace signals confidence—it implies that the content presented is important enough to stand on its own, without competing for attention.

### Application

If a standard margin is 16px, try 32px or 48px. If you feel it's too much space, you're probably on the right track. Reduce from there, but never back to density.

```css
/* Generous whitespace creates confidence */
.card {
  padding: 48px;  /* Not 16px */
  margin-bottom: 32px;  /* Not 8px */
}

.section {
  margin-top: 64px;  /* Breathing room between sections */
  margin-bottom: 64px;
}
```

## Visual Hierarchy Through Size, Weight, and Contrast

### 1. Size Hierarchy

Size is the most powerful tool for establishing hierarchy. Larger elements draw attention first.

**Guidelines:**
- Primary information should be 1.5-2x larger than secondary
- Each level should be clearly distinguishable
- Use modular scales (Major Second, Major Third, Perfect Fifth)

```css
/* Size hierarchy */
h1 {
  font-size: 48px;  /* Primary */
}

h2 {
  font-size: 32px;  /* Secondary */
}

h3 {
  font-size: 24px;  /* Tertiary */
}

body {
  font-size: 16px;  /* Base */
}

small {
  font-size: 12px;  /* Tertiary text */
}
```

### 2. Weight Hierarchy

Font weight creates visual emphasis without changing size.

**Guidelines:**
- Use 2-3 weights maximum (e.g., 400, 600, 700)
- Bold for emphasis, not for everything
- Lighter weight for secondary information

```css
/* Weight hierarchy */
h1 {
  font-weight: 700;  /* Bold for primary */
  font-size: 48px;
}

h2 {
  font-weight: 600;  /* Semi-bold for secondary */
  font-size: 32px;
}

body {
  font-weight: 400;  /* Regular for body */
  font-size: 16px;
}

.secondary-text {
  font-weight: 400;  /* Regular, not bold */
  color: var(--text-secondary);
}
```

### 3. Contrast Hierarchy

Contrast creates visual separation and guides attention.

**Guidelines:**
- High contrast for primary information
- Medium contrast for secondary
- Low contrast for tertiary/disabled

```css
/* Contrast hierarchy */
.primary-text {
  color: var(--text-primary);  /* High contrast */
}

.secondary-text {
  color: var(--text-secondary);  /* Medium contrast */
}

.tertiary-text {
  color: var(--text-tertiary);  /* Low contrast */
}

.disabled-text {
  color: var(--text-disabled);  /* Very low contrast */
  opacity: 0.5;
}
```

## The Color Weight System

### Tinted Greys, Not True Greys

A definitive marker of amateur design is using "True Grey" (#808080) or "True Black" (#000000) on colored backgrounds.

**The Principle:** Always use tinted greys. If your brand is blue, your "grey" should be a deeply desaturated blue. If your brand is warm/orange, your grey should be warm.

```css
/* Bad - True Grey */
.text-on-blue {
  color: #808080;  /* True grey - looks wrong */
}

/* Good - Tinted Grey */
.text-on-blue {
  color: #4B5563;  /* Deeply desaturated blue - feels right */
}

/* Bad - True Black */
.text {
  color: #000000;  /* True black - harsh */
}

/* Good - Tinted Black */
.text {
  color: #030712;  /* Deeply desaturated blue-black - softer */
}
```

### Building a Color Weight System

Create 8-10 shades per hue before writing any code. This prevents "hex code drift" where a codebase accumulates 50 slightly different versions of the same color.

```css
/* Color weight system - 10 shades per hue */
:root {
  /* Primary Blue */
  --blue-50:   #F0F9FF;
  --blue-100:  #E0F2FE;
  --blue-200:  #BAE6FD;
  --blue-300:  #7DD3FC;
  --blue-400:  #38BDF8;
  --blue-500:  #0EA5E9;
  --blue-600:  #0284C7;
  --blue-700:  #0369A1;
  --blue-800:  #075985;
  --blue-900:  #0C3D66;

  /* Tinted Greys (desaturated blue) */
  --gray-50:   #F8FAFC;
  --gray-100:  #F1F5F9;
  --gray-200:  #E2E8F0;
  --gray-300:  #CBD5E1;
  --gray-400:  #94A3B8;
  --gray-500:  #64748B;
  --gray-600:  #475569;
  --gray-700:  #334155;
  --gray-800:  #1E293B;
  --gray-900:  #0F172A;
}
```

### Contrast Hierarchy with Color Weight

Use color sparingly. Text hierarchy should be handled first by lightness (size/weight), then by color.

```css
/* Contrast hierarchy - color reserved for interactive elements */
.heading {
  color: var(--gray-900);  /* Darkest - highest contrast */
  font-weight: 700;
  font-size: 32px;
}

.body-text {
  color: var(--gray-700);  /* Dark - good contrast */
  font-weight: 400;
  font-size: 16px;
}

.secondary-text {
  color: var(--gray-500);  /* Medium - reduced contrast */
  font-weight: 400;
  font-size: 14px;
}

.button-primary {
  background-color: var(--blue-600);  /* Color for interactive elements */
  color: white;
}

.button-secondary {
  background-color: var(--gray-100);  /* Subtle background */
  color: var(--gray-900);
}
```

## Gestalt Principles: How Humans Perceive Visual Groups

Gestalt principles explain how humans naturally group visual elements. Use these to create clear hierarchy and organization.

### 1. Proximity

Elements that are close together are perceived as related.

**Application:**
- Group related items together
- Increase space between unrelated groups
- Use spacing to show relationships

```css
/* Proximity - group related items */
.form-group {
  margin-bottom: 24px;  /* Space between groups */
}

.form-group label {
  display: block;
  margin-bottom: 8px;  /* Close to input */
}

.form-group input {
  width: 100%;
}
```

### 2. Similarity

Elements that look similar are perceived as related.

**Application:**
- Use consistent styling for related items
- Vary styling to show differences
- Buttons of the same type should look identical

```css
/* Similarity - consistent styling for related items */
.button-primary {
  background: var(--blue-600);
  color: white;
  padding: 12px 24px;
  border-radius: 8px;
}

.button-primary:hover {
  background: var(--blue-700);
}

/* All primary buttons look the same */
.button-primary.small {
  padding: 8px 16px;
  font-size: 14px;
}
```

### 3. Figure/Ground

Humans naturally distinguish foreground from background.

**Application:**
- Use contrast to separate foreground from background
- Active states should stand out from inactive
- Modals should have clear distinction from background

```css
/* Figure/Ground - clear foreground/background separation */
.modal-overlay {
  background: rgba(0, 0, 0, 0.5);  /* Darkened background */
}

.modal {
  background: white;  /* Clear foreground */
  box-shadow: 0 20px 25px rgba(0, 0, 0, 0.1);
}

.button.active {
  background: var(--blue-600);  /* Foreground */
  color: white;
}

.button.inactive {
  background: var(--gray-100);  /* Background */
  color: var(--gray-600);
}
```

### 4. Closure

Humans complete incomplete shapes. Minimalist designs work because of this principle.

**Application:**
- Use negative space to imply forms
- Incomplete shapes are still perceived as complete
- Reduces visual clutter while maintaining clarity

```css
/* Closure - incomplete shapes are still perceived */
.icon-incomplete {
  width: 24px;
  height: 24px;
  border: 2px solid currentColor;
  border-right: none;
  border-bottom: none;
  /* Brain completes the square */
}
```

### 5. Symmetry & Order

Balanced layouts feel stable. Asymmetry draws attention.

**Application:**
- Use grids for stable, organized layouts
- Intentional asymmetry draws attention to important elements
- Symmetry creates trust and predictability

```css
/* Symmetry - stable, organized