---
name: refactoring-ui
description: Audit and fix visual hierarchy, spacing, color, and depth in web UIs using Refactoring UI principles
version: 1.0.0
author: wondelai (adapted)
platforms: [claude-code, cursor, windsurf]
license: MIT
source: https://github.com/wondelai/skills
based_on: "Refactoring UI by Adam Wathan & Steve Schoger"
---

# Refactoring UI

Audit and improve web interfaces using evidence-based design principles.

## Scoring System
Rate the UI 0-10 on adherence to principles.
Show: current score → top 3 issues → concrete CSS fixes → expected new score.

## Core Principles

### Visual Hierarchy
- Use **size + weight + color** for hierarchy — never all three simultaneously
- Text sizes: at least 5 distinct sizes (12, 14, 16, 20, 24, 30, 36px)
- Limit font weights to 2-3: regular (400), medium (500), bold (700)
- Reduce contrast for supporting text, don't grey it out completely

### Color
- **Design in grayscale first.** Add color last — it reveals hierarchy issues
- Color temperature matters: cool grays (blue tint) feel professional; warm grays (yellow/red tint) feel friendly
- Avoid pure black (#000000) — use dark grays (#1a1a2e, #1e293b)
- Use color purposefully: blue = interactive, red = destructive, green = success
- Accessible contrast: 4.5:1 for normal text, 3:1 for large text

### Spacing
- Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128px
- **Start with too much space, then reduce** — don't start cramped
- Related elements get less space between them than unrelated elements
- Padding inside components should be proportional (button: 12px 24px, not 5px 10px)

### Typography
- Limit line width to 45-75 characters (max-w-prose or width: 65ch)
- Line height: 1.5 for body, 1.1-1.3 for headings
- Letter-spacing: slightly negative for large headings (-0.02em), slightly positive for small caps (+0.05em)
- Use real content to test — "Lorem ipsum" hides wrapping issues

### Depth
- Shadows: use 2-5 distinct levels (xs, sm, md, lg, xl)
- Offset is more impactful than blur for small shadows
- Colored shadows match the element color (blue button → blue shadow)
- Layering: overlap elements to create depth without shadows

### Layout Patterns
- Don't center everything — left-align most content
- Grid doesn't need equal columns — use different widths intentionally
- Empty state design matters: add illustration + CTA, don't just show "No items"