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:

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

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

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