Install to Claude Code
npx -y skills add https://github.com/wondelai/skills --skill refactoring-uiDescription
refactoring ui
SKILL.md
--- name: refactoring-ui description: 'Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.' license: MIT metadata: author: wondelai version: "1.5.0" --- # 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 See [references/theming-dark-mode.md](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](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](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 - Icon sizing: `w-4 h-4` inline, `w-6 h-6` navigation, `w-8 h-8` feature icons - 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](references/data-visualization.md) when laying out charts, tables, or dashboards — chart-type selection, color use in charts, table density, and dashboard composition. ## Common Mistakes | Mistake | Why It Fails | Fix | |---------|-------------|------| | **"Looks amateur"** | Insufficient white space, unconstrained widths | More white space, constrain content widths | | **"Feels flat"** | No depth differentiation | Subtle shadows, border-bottom on sections | | **"Text is hard to read"** | Poor line-height, too wide, low contrast | Increase line-height, constrain width, boost contrast | | **"Everything looks the same"** | No visual hierarchy | Vary size/weight/color between primary and secondary | | **"Feels cluttered"** | Equal spacing everywhere | Group related items, larger gaps between groups | | **"Colors clash"** | Random choices, no system | Reduce saturation, more grays, limit to palette | | **"Buttons don't pop"** | Low contrast with surroundings | Increase contrast, add shadow | | **Arbitrary values** | px values like 13, 17, 23 breed inconsistency | Stick to the spacing and type scales | ## Quick Diagnostic Audit any UI design: | Question | If No | Action | |----------|-------|--------| | Does hierarchy read when squinting (blur test)? | Elements competing | Increase primary/secondary contrast | | Does it work in grayscale? | Color is a crutch | Strengthen size/weight/spacing hierarchy | | Is there enough white space? | Probably not — most designs are too dense | Increase spacing, especially between groups | | Are labels de-emphasized vs. values? | Labels competing with data | Smaller, lighter, or uppercase-small labels | | Does spacing follow a consistent scale? | Arbitrary spacing = visual noise | Use 4/8/16/24/32/48/64 only | | Is text width constrained? | Long lines fatigue readers | Apply `max-w-prose` (~65ch) | | Do colors have sufficient contrast? | Accessibility failure | WCAG-check; use gray-700+ on white | | Are shadows appropriate for elevation? | Elements float at wrong level | Match shadow scale to element purpose | ## Further Reading For the complete system with visual before/after examples: - [*"Refactoring UI"*](https://www.amazon.com/Refactoring-UI-Adam-Wathan/dp/B0BLJ7MC21?tag=wondelai00-20) by Adam Wathan & Steve Schoger (the full book with hundreds of visual examples) - [*"The Design of Everyday Things"*](https://www.amazon.com/Design-Everyday-Things-Revised-Expanded/dp/0465050654?tag=wondelai00-20) by Don Norman (foundational design thinking and usability) - [*"Don't Make Me Think"*](https://www.amazon.com/Dont-Make-Think-Revisited-Usability/dp/0321965515?tag=wondelai00-20) by Steve Krug (web usability principles that complement Refactoring UI) - [Refactoring UI](https://www.refactoringui.com/) — 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.