refactoring-ui

What this skill does

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

**The foundation:** Great UI isn't about creativity or talent -- it's about systems. Constrained scales for spacing, type, color, and shadows produce consistently professional results. Start with too much white space, then remove. Details come later -- don't obsess over icons, shadows, or micro-interactions until the layout and hierarchy work.

## Scoring

**Goal: 10/10.** When reviewing or creating UI designs or frontend code, rate it 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and specific improvements needed to reach 10/10.

## The Refactoring UI Framework

Seven principles for building professional interfaces without a designer:

### 1. Visual Hierarchy

**Core concept:** Not everything can be important. Create hierarchy through three levers: size, weight, and color.

**Why it works:** When every element competes for attention, nothing stands out. Deliberate de-emphasis of secondary content makes primary content powerful by contrast.

**Key insights:**

- Combine levers, don't multiply -- primary text = large OR bold OR dark, not all three
- Save "all three" for the single most important element on the page
- Labels are secondary -- form labels, table headers, and metadata labels support the data, not compete with it
- Semantic color does not equal visual weight -- a muted red secondary button often works better than screaming danger for routine actions
- De-emphasize labels by making them smaller, lighter, or uppercase-small

**Product applications:**

| Context | Hierarchy Technique | Example |
|---------|---------------------|---------|
| **Form fields** | De-emphasize labels, emphasize values | Small uppercase label above large value text |
| **Navigation** | Primary nav bold, secondary nav lighter | Active link in dark gray-900, inactive in gray-500 |
| **Cards** | Title large, metadata small and light | Card title 20px bold, date 12px gray-400 |
| **Dashboards** | Key metric large, context small | Revenue "$42,300" large, "vs last month" small |
| **Tables** | De-emphasize headers, emphasize cell data | Headers uppercase small gray, data normal weight |

**Design patterns:**

- Three-level hierarchy table: Size (large/base/small), Weight (bold/medium/normal), Color (dark/medium/light gray)
- Label-value pattern: de-emphasized label above emphasized value
- Button hierarchy: primary (filled), secondary (outlined or muted), tertiary (text only)

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

See: [references/advanced-patterns.md](references/advanced-patterns.md) for interaction states and advanced component patterns.

### 2. Spacing & Sizing

**Core concept:** Use a constrained spacing scale, not arbitrary values. Spacing defines relationships -- elements closer together are more related.

**Why it works:** Arbitrary spacing (padding: 13px) creates inconsistency. A fixed scale forces deliberate decisions and produces harmonious layouts. Generous spacing feels premium; dense spacing feels overwhelming.

**Key insights:**

- Use a linear or near-linear scale: 4, 8, 16, 24, 32, 48, 64px
- Start with too much white space, then remove -- you'll almost never remove enough
- Spacing between groups should be larger than spacing within groups
- Text blocks should be constrained to 45-75 characters (`max-w-prose` or ~65ch)
- Forms should max out at 300-500px width
- Full-width is almost never right for content

**Product applications:**

| Context | Spacing Strategy | Example |
|---------|-----------------|---------|
| **Icon + label** | Tight coupling (4px) | Small gap keeps them visually connected |
| **Form fields** | Related elements (8-16px) | Input and its label tightly coupled |
| **Card sections** | Section separation (24px) | Title block, content block, footer block |
| **Page sections** | Major sections (48-64px) | Hero, features, testimonials, footer |
| **Container width** | Constrain to content | `max-w-prose` for text, `max-w-md` for forms |

**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

**Ethical boundary:** Don't use spacing to bury important UI elements like unsubscribe buttons or privacy controls.

See: [references/advanced-patterns.md](references/advanced-patterns.md) for responsive breakpoint strategies.

### 3. Typography

**Core concept:** Use a modular type scale, constrain line heights by context, and limit to two font families maximum.

**Why it works:** A modular scale (e.g., 1.25 ratio) creates natural visual rhythm. Tight line heights on headings and relaxed line heights on body text improve readability across contexts.

**Key insights:**

- Use a modular scale: 12, 14, 16, 20, 24, 30, 36px (1.25 ratio)
- Headings need tight line height (1.0-1.25); body text needs relaxed (1.5-1.75)
- Wider text needs more line height
- 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 one family with weight variation)

**Product applications:**

| Context | Typography Rule | Example |
|---------|----------------|---------|
| **Hero headline** | 36px, tight line-height (1.1), bold | Large impactful statement |
| **Section title** | 24px, line-height 1.25, semibold | Clear section demarcation |
| **Body text** | 16px, line-height 1.75, normal weight | Comfortable reading |
| **Captions/labels** | 12-14px, line-height 1.5, medium gray | Secondary information |
| **Code/data** | Monospace, 14px, consistent width | Tabular data alignment |

**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)

**Ethical boundary:** Don't use tiny type sizes to hide terms, conditions, or fees from users.

See: [references/advanced-patterns.md](references/advanced-patterns.md) for text truncation and responsive typography.

### 4. Color

**Core concept:** Build a systematic palette with 5-9 shades per color, add subtle saturation to grays, and design in grayscale first.

**Why it works:** Random colors clash. A systematic palette with predefined shades ensures consistency across the entire interface. HSL adjustments create natural-feeling lighter and darker variants.

**Key insights:**

- Each color needs 5-9 shades from near-white to near-black (50 through 900)
- The darkest shade is not black -- use 900-level dark grays (e.g., `#111827`) instead of pure `#000000`
- Pure grays look lifeless -- add subtle saturation (cool UI: blue tint like `#64748b`; warm UI: yellow/brown tint like `#78716c`)
- HSL adjustments: lighter = higher lightness, lower saturation, shift hue toward 60 degrees; darker = lower lightness, higher saturation, shift hue toward 0/240 degrees
- Body text minimum 4.5:1 contrast ratio; large text (18px+) minimum 3:1
- Use `#374151` (gray-700) on white, not lighter grays for readable text

**Product applications:**

| Context | Color Strategy | Example |
|---------|---------------|---------|
| **Primary palette** | 9 shades (50-900) for main brand color | Blue-500 for buttons, Blue-100 for backgrounds |
| **Gray palette** | Saturated grays matching UI temperature | Cool gra