Audits and fixes hierarchy, spacing, color, depth and typography with the Refactoring UI principles, with a score and a quick diagnostic.
$ npx skills add https://craftwork.design/skills/refactoring-ui -a claude-code -y
Installs into .claude/skills/refactoring-ui. Add -g for every project.
SKILL.md
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 (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.
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)
Ethical boundary: Don't use hierarchy tricks to hide important information like pricing, terms, or cancellation options.
See 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
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.
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)
bg-blue-50 for subtle backgrounds, bg-blue-500 for primary actions
border-gray-200 for subtle borders, border-gray-300 for stronger
See references/theming-dark-mode.md when building a dark theme — hex shade scales, why darkest is #111827 not black (halation), and conveying elevation via lightness instead of shadow. See references/accessibility-depth.md when contrast, focus rings, keyboard nav, or screen-reader support is in scope — full WCAG 2.1 AA checklist and fixes.
5. Depth & Shadows
Core concept: Use a shadow scale to convey elevation — small shadows for slightly raised elements, large shadows for floating ones.
Why it works: The eye reads shadow size as height above the page; a consistent scale makes elevation legible, so users intuit what's interactive, floating, or background.
Key insights:
Small shadows = raised slightly (buttons, cards); large = floating (modals, dropdowns)
Good shadows have two parts: a tight dark shadow for crispness plus a larger soft one for atmosphere
Depth without shadows: lighter top border + darker bottom border, subtle gradients, overlapping elements
Don't overuse — if everything floats, nothing has depth; shadow color is transparent dark, never opaque gray
Product applications:
Context
Shadow Level
Example
Buttons
shadow-sm (subtle raise)
Slightly elevated above surface
Dropdowns
shadow-lg (floating)
Menu clearly above content
Modals
shadow-xl (highest)
Overlay detached from page
CSS patterns:
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)
See references/animation-microinteractions.md when adding motion to interactive elements — durations, easing curves, loading states, and the prefers-reduced-motion rule.
6. Images & Icons
Core concept: Treat images as design elements, not afterthoughts. Size icons deliberately and use overlays to keep text readable on images.
Why it works: Poorly sized icons look awkward and unstyled images break consistency; deliberate treatment (overlays, object-fit, radius) makes interfaces feel polished.
Key insights:
Size icons relative to context; use sets with consistent stroke width and style
Never stretch or distort — use object-fit: cover with fixed aspect ratios and crop deliberately
Text over images needs an overlay (semi-transparent gradient)
Empty states are an opportunity — use illustrations plus a clear CTA, not just text
Product applications:
Context
Image/Icon Technique
Example
Hero images
Semi-transparent gradient overlay
Text readable over any photo
Avatars
Consistent size, rounded, fallback initials
40px circle, object-fit cover
Empty states
Custom illustration + CTA
Friendly illustration with "Get started"
CSS patterns:
object-fit: cover with fixed aspect-ratio for consistent display
Overlay: bg-gradient-to-t from-black/60 to-transparent for text on images
7. Layout & Composition
Core concept: Don't center everything. Use alignment, overlap, and emphasis variation to create engaging compositions.
Why it works: A consistent left edge gives the eye a fixed return point per line, so it costs less to scan; centered multi-line text moves that edge every line and slows reading.
Key insights:
Left-align by default; center only short headlines, heroes, single-action CTAs, and empty states
Cards don't need to contain everything — let images bleed to edges or overlap containers
Vary visual treatment in lists and feeds — feature some items, minimize others
Use alignment to create relationships between unrelated elements
Product applications:
Context
Layout Strategy
Example
Hero sections
Centered text, generous spacing
Short headline + subtext + single CTA
Blog feeds
Varied card sizes for emphasis
First post large, rest in 2-column grid
Content pages
Constrained width, left-aligned
max-w-prose container with left text
CSS patterns:
text-left by default, text-center only for heroes and short headlines
grid grid-cols-3 gap-6 for feature grids; max-w-4xl mx-auto for page containers
overflow-hidden on cards with object-fit: cover images that bleed to edges
See references/data-visualization.md when laying out charts, tables, or dashboards — chart-type selection, color use in charts, table density, and dashboard composition.
"Don't Make Me Think" by Steve Krug (web usability principles that complement Refactoring UI)
Refactoring UI — Official site with resources and examples
About the Authors
Adam Wathan, creator of Tailwind CSS, and Steve Schoger, the visual designer behind its design language, wrote Refactoring UI to teach developers systematic, repeatable design techniques. Their approach replaces artistic talent with constrained systems — fixed scales for spacing, typography, color, and shadows — that produce professional results.
