refactoring-ui

Files (6)

• SKILL.md
• accessibility-depth.md · references/
• advanced-patterns.md · references/
• animation-microinteractions.md · references/
• data-visualization.md · references/
• theming-dark-mode.md · references/

SKILL.md (first lines)

# 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 talent — it's about systems. Constrained scales for spacing, type, color, and shadows produce consistently professional results. Start with too much white space and remove; leave details (icons, shadows, micro-interactions) until layout and hierarchy work.

## Scoring

**Goal: 10/10.** Score by counting satisfied rows in the [Quick Diagnostic](#quick-diagnostic) (8 yes/no checks): `score = round(satisfied / 8 × 10)`. Bands follow directly: **10** = all 8 pass (hierarchy reads blurred and in grayscale, every value on a scale); **9** = exactly 1 gap (usually weak hierarchy or thin white space); **6-8** = 2-3 gaps; **<=5** = 4+ gaps (arbitrary spacing, color doing the work hierarchy should, or failing contrast). Always state the current score and the specific diagnostic rows to fix 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; deliberately de-emphasizing 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
- Labels are secondary — form labels, table headers, and metadata support the data, not compete with it; make them smaller, lighter, or uppercase-small
- Semantic color ≠ visual weight — a muted secondary button often beats screaming red for routine destructive actions

**Product applications:**

| Context | Hierarchy Technique | Example |
|---------|---------------------|---------|
| **Form fields** | De-emphasize labels, emphasize values | Small uppercase label above large value |
| **Dashboards** | Key metric large, context small | "$42,300" large, "vs last month" small |
| **Tables** | De-emphasize headers, emphasize data | Headers uppercase small gray, data normal |

**Design patterns:**
- Three-level hierarchy: Size (large/base/small), Weight (bold/medium/normal), Color (dark/medium/light gray)
- 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) when designing components beyond static layout — interaction/hover/focus states, form design, empty states, border-radius systems, text truncation, and responsive breakpoints.

### 2. Spacing & Sizing

**Core concept:** Use a constrained spacing scale, not arbitrary values. Spacing defines relationships — closer elements read as more related.

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

**Key insights:**
- Use the 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 must exceed spacing within groups
- Constrain widths: text to 45-75 characters (`max-w-prose`), forms to 300-500px; full-width is almost never right

**Product applications:**

| Context | Spacing Strategy | Example |
|---------|-----------------|---------|
| **Icon + label** | Tight coupling (4px) | Small gap keeps them connected |
| **Card sections** | Section separation (24px) | Title, content, footer blocks |
| **Page sections** | Major sections (48-64px) | Hero, features, testimonials |

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

### 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 (steps growing ~1.2× each) creates natural visual rhythm; tight line heights on headings and relaxed on body text improve readability in each context.

**Key insights:**
- Scale: 12, 14, 16, 18, 20, 24, 30, 36px (~1.2 modular, hand-tuned)
- Headings: tight line height (1.0-1.25); body: relaxed (1.5-1.75); wider text needs more line height
- Avoid weights below 400 for body text; use bold (600-700) for emphasis, not everything
- Two fonts max: one for headings, one for body (or one family with weight variation)

**Product applications:**

| Context | Typography Rule | Example |
|---------|----------------|---------|
| **Hero headline** | 36px, line-height 1.1, bold | Large impactful statement |
| **Body text** | 16px, line-height 1.75, normal | Comfortable reading |
| **Captions/labels** | 12-14px, line-height 1.5, medium gray | Secondary information |

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

### 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 predefined shade system ensures consistency, and HSL adjustments create natural-feeling lighter and darker variants.

**Key insights:**
- Each color needs 5-9 shades from near-white to near-black (50-900); darkest is not pure black — use `#111827`, not `#000000`
- Pure grays look lifeless — tint them (cool UI: blue like `#64748b`; warm UI: yellow/brown like `#78716c`)
- HSL: lighter = raise lightness, lower saturation, hue toward 60°; darker = the reverse, hue toward 0°/240°
- Contrast minimums: 4.5:1 body text, 3:1 large text (18px+); use `#374151` (gray-700) on white, not lighter grays

**Product applications:**

| Context | Color Strategy | Example |
|---------|---------------|---------|
| **Primary palette** | 9 shades (50-900) of brand color | Blue-500 buttons, Blue-100 backgrounds |
| **Semantic colors** | Success/warning/error with shade ranges | Green-500 success, Red-500 errors |
| **Text colors** | Three levels: dark, medium, light | `text-gray-900`, `text-gray-600`, `text-gray-400` |

**CSS patterns:**
- `text-gray-900`(dark) `text-gray-600`(medium) `text-gray-400`(light)
- `bg-blue-50` for subtle backgrounds, `bg-blue-500` for primary actions
- `border-gray-200` for subtle borders, `border-gray-300` for stronger

From wondelai/skills, MIT.

More from wondelai/skills