refactoring-ui

Original source / Raw SKILL.md

---
name: refactoring-ui
description: Practical UI design system based on Refactoring UI (Wathan & Schoger). Use when creating or improving user interfaces, web components, dashboards, landing pages, or any visual design work. Applies to HTML/CSS, React, Tailwind, or any frontend output. Triggers on requests for UI design, styling, layout, color schemes, typography, visual hierarchy, or making interfaces "look better."
---

# 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 Philosophy

**Design in grayscale first.** Add color last. This forces proper hierarchy through spacing, contrast, and typography before relying on color as a crutch.

**Start with too much white space, then remove.** Dense interfaces feel overwhelming. Generous spacing feels premium.

**Details come later.** Don't obsess over icons, shadows, or micro-interactions until the layout and hierarchy work.

## Visual Hierarchy

Not everything can be important. Create hierarchy through three levers:

| Lever | Primary | Secondary | Tertiary |
|-------|---------|-----------|----------|
| **Size** | Large | Base | Small |
| **Weight** | Bold (600-700) | Medium (500) | Normal (400) |
| **Color** | Dark gray (#111) | Medium gray (#666) | Light gray (#999) |

**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, metadata labels → these support the data, not compete with it. Make labels smaller, lighter, or uppercase-small.

```
❌ Name: John Smith     (label and value same weight)
✅ NAME                  (de-emphasized label)
   John Smith           (emphasized value)
```

### Semantic Color ≠ Visual Weight

Don't make every destructive button bright red. A muted red secondary button often works better than screaming danger for routine actions.

## Spacing System

Use a **constrained spacing scale**, not arbitrary values:

```
4px  → tight coupling (icon + label)
8px  → related elements
16px → standard gap
24px → section separation  
32px → major sections
48px → page sections
64px → hero spacing
```

**Spacing defines relationships.** Elements closer together = more related. Don't use the same spacing everywhere.

### Container Width

- **Text blocks:** 45-75 characters (use `max-w-prose` or ~65ch)
- **Forms:** 300-500px max width
- **Cards:** Size to content, not viewport
- **Full-width is almost never right** for content

## Typography

### Font Size Scale

Use a modular scale. Example (1.25 ratio):

```
12px → fine print, captions
14px → secondary text, labels  
16px → body text (base)
20px → subheadings
24px → section titles
30px → page titles
36px → hero headlines
```

### Line Height Rules

- **Headings:** 1.0 - 1.25 (tight)
- **Body text:** 1.5 - 1.75 (relaxed)
- **Wider text = more line height** needed

### Font Weight Strategy

Avoid font weights below 400 for body text—they become unreadable. Use bold (600-700) for emphasis, not for everything.

Two fonts maximum: one for headings, one for body. Or use one font family with weight variation.

## Color

### Build a Palette, Not Random Colors

Each color needs **5-9 shades** from near-white to near-black:

```
Gray:    50, 100, 200, 300, 400, 500, 600, 700, 800, 900
Primary: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900
```

**The darkest shade isn't black.** Use 900-level dark grays (e.g., `#111827`) instead of pure `#000000`.

### Grays Need Saturation

Pure gray (`#808080`) looks lifeless. Add subtle saturation:
- Cool UI: Slight blue tint (`#64748b`)
- Warm UI: Slight yellow/brown tint (`#78716c`)

### HSL Adjustments

When deriving shades:
- Lighter = higher lightness, lower saturation, shift hue toward 60° (yellow)
- Darker = lower lightness, higher saturation, shift hue toward 0°/240° (red/blue)

### Accessible Contrast

- Body text: minimum 4.5:1 contrast ratio
- Large text (18px+): minimum 3:1
- Use `#374151` (gray-700) on white, not lighter grays

## Depth & Shadows

### Shadow Scale

Small shadows = raised slightly (buttons, cards)
Large shadows = floating (modals, dropdowns)

```css
--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);
```

**Shadows have two parts:** A tight, dark shadow for crispness + a larger, softer shadow for atmosphere.

### Creating Depth Without Shadows

- Lighter top border, darker bottom border
- Subtle gradient backgrounds (lighter at top)
- Overlapping elements with offset

## Layout Patterns

### Don't Center Everything

Left-aligned text is easier to read. Center only:
- Short headlines
- Hero sections
- Single-action CTAs
- Empty states

### Break Out of the Box

Cards don't need to contain everything. Let images bleed to edges, overlap containers, or extend beyond their bounds.

### Alternate Emphasis

In lists/feeds, vary the visual treatment. Not every card needs the same layout—feature some, minimize others.

## Practical Checklist

Before considering UI "done":

- [ ] Squint test: Does hierarchy still read when blurred?
- [ ] Grayscale test: Does it work without color?
- [ ] Is there enough white space? (Probably not)
- [ ] Are labels de-emphasized vs. their values?
- [ ] Does spacing follow a consistent scale?
- [ ] Is text width constrained for readability?
- [ ] Do colors have sufficient contrast?
- [ ] Are shadows appropriate for elevation level?

## Quick Fixes for Common Problems

| Problem | Fix |
|---------|-----|
| "Looks amateur" | Add more white space, constrain widths |
| "Feels flat" | Add subtle shadows, border-bottom on sections |
| "Text is hard to read" | Increase line-height, constrain width, boost contrast |
| "Everything looks the same" | Vary size/weight/color between primary and secondary elements |
| "Feels cluttered" | Group related items, increase spacing between groups |
| "Colors clash" | Reduce saturation, use more grays, limit palette |
| "Buttons don't pop" | Increase contrast with surroundings, add shadow |

## Tailwind Quick Reference

For Tailwind CSS implementations:

```
Spacing:    p-1(4px) p-2(8px) p-4(16px) p-6(24px) p-8(32px)
Text size:  text-xs(12) text-sm(14) text-base(16) text-lg(18) text-xl(20)
Font weight: font-normal(400) font-medium(500) font-semibold(600) font-bold(700)  
Text color: text-gray-900(dark) text-gray-600(medium) text-gray-400(light)
Max width:  max-w-prose(65ch) max-w-md(28rem) max-w-lg(32rem) max-w-xl(36rem)
Shadow:     shadow-sm shadow-md shadow-lg shadow-xl
```

## Advanced Topics

For deeper guidance on specific patterns, see [references/advanced-patterns.md](references/advanced-patterns.md):
- Empty states design
- Form design & input states
- Image treatment & overlays
- Icon sizing & usage
- Interaction states (hover, focus, active)
- Color psychology
- Border radius systems
- Text truncation
- Responsive breakpoints


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/advanced-patterns.md

```markdown
# Advanced Design Patterns

Extended reference for complex scenarios. Load only when deeper guidance needed.

## Table of Contents
1. [Empty States](#empty-states)
2. [Form Design](#form-design)
3. [Image Treatment](#image-treatment)
4. [Icon Usage](#icon-usage)
5. [Interaction States](#interaction-states)
6. [Color Psychology](#color-psychology)
7. [Border Radius System](#border-radius-system)

---

## Empty States

Empty states are opportunities, not afterthoughts.

**Good empty states include:**
- Illustration or icon (not generic)
- Clear explanation of what goes here
- Primary action to remedy emptiness
- Optional secondary actions

```
❌ "No items"
✅ "No projects yet. Create your first project to get started."
   [+ Create Project]
```

**Match the tone.** A todo app empty state can be playful; an enterprise dashboard should be professional.

---

## Form Design

### Input Sizing

Match input width to expected content:
- Email/URL: Full width or ~400px
- Phone: ~200px
- ZIP code: ~100px
- Street address: Full width
- City: ~200px
- State dropdown: ~150px

### Placeholder vs. Label

**Never use placeholder as the only label.** Placeholders disappear on focus. Always have a visible label.

Placeholders work for:
- Format hints: "MM/DD/YYYY"
- Examples: "e.g., [email protected]"
- Optional clarification

### Input States

```
Default:     border-gray-300
Focus:       border-blue-500 ring-2 ring-blue-200
Error:       border-red-500 ring-2 ring-red-200
Disabled:    bg-gray-100 text-gray-400
Success:     border-green-500 (sparingly)
```

### Button Hierarchy

One primary action per view. Everything else is secondary or tertiary.

```
Primary:    Solid color, high contrast (bg-blue-600 text-white)
Secondary:  Outlined or muted (border border-gray-300)
Tertiary:   Text only (text-blue-600 hover:underline)
Danger:     Red but not screaming (bg-red-600 for confirm, text-red-600 for trigger)
```

### Form Layout

- One column for simple forms
- Two columns ONLY when inputs are related (First/Last name, City/State)
- Labels above inputs on mobile, beside on desktop (optional)
- Group related fields with subtle boundaries or spacing

---

## Image Treatment

### Background Images

**Problem:** Text over images is often unreadable.

**Solutions:**
1. Semi-transparent overlay: `bg-black/50`
2. Gradient overlay: `bg-gradient-to-t from-black/80 to-transparent`
3. Text shadow: `text-shadow: 0 2px 4px rgba(0,0,0,0.5)`
4. Solid color box behind text
5. Choose images with natural dark/simple areas for text

### User Avatars

- Always have a fallback (initials, generic icon)
- Consistent size per context (32px list, 48px card, 96px profile)
- Round for people, square with border-radius for companies/products
- Border adds polish: `ring-2 ring-white` for overlapping avatars

### Hero Images

- Don't stretch—use `object-cover`
- Consider `aspect-ratio` for consistency
- Compress appropriately (WebP, quality 80%)

---

## Icon Usage

### Sizing

Icons should feel balanced with adjacent text:
- 12-14px text: 16px icon
- 16px text: 20px icon  
- 18-20px text: 24px icon

### Icon + Text Pairing

Always align icon center with text baseline or center. Add consistent gap (8px typical).

```html
<span class="flex items-center gap-2">
  <IconSettings class="w-5 h-5" />
  <span>Settings</span>
</span>
```

### When to Use Icons

- Navigation items
- Common actions (edit, delete, share)
- Status indicators
- Feature lists (with caution—don't overdo)

### When NOT to Use Icons

- Don't add icons just to fill space
- Skip icons on buttons with clear text ("Submit", "Continue")
- Avoid decorative-only icons that add no meaning

---

## Interaction States

Every interactive element needs visible state changes:

### Hover
- Subtle background change
- Slight shadow increase
- Color shift (darken primary by 10%)

### Active/Pressed
- Darker than hover
- Slight scale down (`scale-95`)
- Reduce shadow

### Focus
- Obvious ring (critical for accessibility)
- Don't rely on color alone
- `focus-visible` for keyboard-only focus

### Loading
- Disable interaction
- Show spinner or skeleton
- Maintain layout size (prevent shift)

```css
/* Example button states */
.btn {
  @apply bg-blue-600 hover:bg-blue-700 active:bg-blue-800;
  @apply focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2;
  @apply disabled:opacity-50 disabled:cursor-not-allowed;
}
```

---

## Color Psychology

Use color purposefully:

| Color | Association | Use for |
|-------|-------------|---------|
| Blue | Trust, calm, professional | Primary actions, links, corporate |
| Green | Success, growth, go | Success states, positive actions |
| Red | Error, danger, urgency | Errors, destructive actions, alerts |
| Yellow/Orange | Warning, attention | Warnings, highlights |
| Purple | Premium, creative | Premium features, creative apps |
| Gray | Neutral, professional | Text, backgrounds, borders |

### Avoid

- Red for non-destructive primary buttons
- Green for errors (colorblind users)
- Low-saturation colors for important actions
- More than 3 accent colors per interface

---

## Border Radius System

Stay consistent. Pick a system:

**Sharp/Modern:**
```
none: 0
sm: 2px
md: 4px
lg: 6px
full: 9999px (pills/circles)
```

**Soft/Friendly:**
```
none: 0
sm: 4px
md: 8px
lg: 12px
xl: 16px
full: 9999px
```

### Rules

- Nested elements: inner radius = outer radius - padding
- Small elements get smaller radius (badges, tags)
- Large elements can have larger radius (cards, modals)
- Images inside cards: match card radius or use `overflow-hidden`

---

## Text Wrapping & Truncation

### When to Truncate

- Navigation items
- Table cells with fixed widths
- Card titles (with hover to reveal)

```css
.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}
```

### When NOT to Truncate

- Body text
- Important information
- Search results
- Error messages

### Multi-line Truncation

```css
.line-clamp-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}
```

---

## Responsive Breakpoints

Standard breakpoints (Tailwind default):

```
sm:  640px  (landscape phones)
md:  768px  (tablets)
lg:  1024px (laptops)
xl:  1280px (desktops)
2xl: 1536px (large screens)
```

### Mobile-First Principles

1. Design for mobile first, add complexity for larger screens
2. Stack on mobile, side-by-side on desktop
3. Full-width inputs on mobile, constrained on desktop
4. Larger touch targets on mobile (44px minimum)
5. Hide secondary navigation in hamburger on mobile

```