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 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 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 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 grays with blue tint for tech products |
| Semantic colors |
Success, warning, error each with shade range |
Green-500 for success, Red-500 for errors |
| Text colors |
Three levels: dark, medium, light |
text-gray-900, text-gray-600, text-gray-400 |
| Accessible contrast |
Test all text/background combos |
#374151 on white = 10.5:1 ratio |
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 actionsborder-gray-200 for subtle borders, border-gray-300 for stronger
Ethical boundary: Don't use color alone to convey information -- always pair with text or icons for accessibility.
See: references/theming-dark-mode.md for dark palette creation and theme implementation.
5. Depth & Shadows
Core concept: Use a shadow scale to convey elevation. Small shadows for slightly raised elements, large shadows for floating elements.
Why it works: Shadows create a sense of physical depth that helps users understand which elements are interactive, which are floating above the surface, and which are part of the background.
Key insights:
- Small shadows = raised slightly (buttons, cards); large shadows = floating (modals, dropdowns)
- Shadows have two parts: a tight, dark shadow for crispness plus a larger, softer shadow for atmosphere
- Depth without shadows: lighter top border + darker bottom border, subtle gradient backgrounds, overlapping elements with offset
- Don't overuse shadows -- if everything floats, nothing has depth
- Shadow color should be transparent dark, not opaque gray
Product applications:
| Context |
Shadow Level |
Example |
| Buttons |
shadow-sm (subtle raise) |
Slightly elevated above page surface |
| Cards |
shadow-md (clear separation) |
Content grouped and lifted from background |
| Dropdowns |
shadow-lg (floating) |
Menu clearly floating above content |
| Modals |
shadow-xl (highest elevation) |
Overlay clearly detached from page |
| Flat alternatives |
Border + background shift |
Lighter top border, darker bottom border |
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)
Ethical boundary: Don't use excessive shadows or visual emphasis to draw attention to deceptive UI elements (dark patterns).
See: references/advanced-patterns.md for interaction states and elevation hierarchy.
6. Images & Icons
Core concept: Treat images as design elements, not afterthoughts. Size icons deliberately and use overlays to ensure text readability on images.
Why it works: Poorly sized icons look awkward. Unstyled images break visual consistency. Deliberate image treatment (overlays, object-fit, border radius) makes interfaces feel polished.
Key insights:
- Icons should be sized relative to their context -- don't use the same size everywhere
- Use icon sets with consistent stroke width and style
- Images need treatment: object-fit cover, consistent aspect ratios, overlays for text
- Don't stretch or distort images -- use
object-fit: cover and crop deliberately
- Empty states are an opportunity -- use illustrations, not just text
Product applications:
| Context |
Image/Icon Technique |
Example |
| Hero images |
Overlay with semi-transparent gradient |
Text readable over any photo |
| Avatars |
Consistent size, rounded, fallback initials |
40px circle with object-fit cover |
| Feature icons |
Consistent size, weight, and color |
24px stroke icons in gray-500 |
| Empty states |
Custom illustration + clear CTA |
Friendly illustration with "Get started" button |
| Thumbnails |
Fixed aspect ratio with object-fit cover |
16:9 cards with no distortion |
CSS patterns:
object-fit: cover with fixed aspect-ratio for consistent image display- Icon sizing:
w-4 h-4 inline, w-6 h-6 in navigation, w-8 h-8 for feature icons
- Image overlay:
bg-gradient-to-t from-black/60 to-transparent for text on images
Ethical boundary: Don't use misleading images or icons that misrepresent functionality or product capabilities.
See: references/advanced-patterns.md for image treatment, icon usage, and empty states.
7. Layout & Composition
Core concept: Don't center everything. Use alignment, overlap, and emphasis variation to create engaging compositions.
Why it works: Left-aligned text is easier to read. Varied layouts keep users engaged. Breaking out of rigid boxes makes designs feel dynamic and intentional.
Key insights:
- Left-align text by default; center only short headlines, hero sections, single-action CTAs, and empty states
- Cards don't need to contain everything -- let images bleed to edges, overlap containers, or extend beyond bounds
- In lists and feeds, vary the visual treatment -- feature some items, minimize others
- Use alignment to create visual relationships between unrelated elements
- Alternate emphasis: not every card in a list needs the same layout
Product applications:
| Context |
Layout Strategy |
Example |
| Hero sections |
Centered text, generous spacing |
Short headline + subtext + single CTA |
| Feature grids |
Left-aligned text, consistent card sizes |
3-column grid with icon + title + description |
| Blog feeds |
Varied card sizes for emphasis |
First post large, next posts in 2-column grid |
| Sidebars |
Narrower than main content, lighter background |
Navigation or filters at 240-320px width |
| Content pages |
Constrained width, left-aligned |
max-w-prose centered container with left text |
CSS patterns:
text-left by default, text-center only for heroes and short headlinesgrid grid-cols-3 gap-6 for feature gridsmax-w-4xl mx-auto for page containersoverflow-hidden on cards with object-fit: cover images that bleed to edges
Ethical boundary: Don't use layout tricks to hide or obscure important user choices like opt-outs or data permissions.
See: references/advanced-patterns.md for responsive breakpoints and complex layout patterns.
Common Mistakes
| Mistake |
Why It Fails |
Fix |
| "Looks amateur" |
Insufficient white space, unconstrained widths |
Add more white space, constrain content widths |
| "Feels flat" |
No depth differentiation between elements |
Add 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 between elements |
Vary size/weight/color between primary and secondary |
| "Feels cluttered" |
Equal spacing everywhere, no grouping |
Group related items, increase spacing between groups |
| "Colors clash" |
Random color choices without a system |
Reduce saturation, use more grays, limit palette to system |
| "Buttons don't pop" |
Low contrast with surrounding elements |
Increase contrast with surroundings, add shadow |
| Using arbitrary values |
px values like 13, 17, 23 create 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 for attention |
Increase contrast between primary and secondary |
| Does it work in grayscale? |
Relying on color for hierarchy |
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. their values? |
Labels competing with data |
Make labels smaller, lighter, or uppercase-small |
| Does spacing follow a consistent scale? |
Arbitrary spacing creates visual noise |
Use 4/8/16/24/32/48/64 scale only |
| Is text width constrained for readability? |
Long lines cause reader fatigue |
Apply max-w-prose (~65ch) to text blocks |
| Do colors have sufficient contrast? |
Accessibility failure, hard to read |
Test with WCAG contrast checker, use gray-700+ on white |
| Are shadows appropriate for elevation? |
Elements floating at wrong visual level |
Match shadow scale to element purpose |
Reference Files
- advanced-patterns.md: Empty states, form design, image treatment, icon sizing, interaction states, color psychology, border radius systems, text truncation, responsive breakpoints
- animation-microinteractions.md: When to animate, easing functions, durations, loading states, animation performance
- accessibility-depth.md: WCAG 2.1 AA checklist, focus management, screen reader support, keyboard navigation
- data-visualization.md: Chart selection, color in charts, table design, dashboard layouts
- theming-dark-mode.md: Dark palette creation, elevation in dark mode, theme implementation strategies
Further Reading
This skill is based on Adam Wathan and Steve Schoger's practical design guide. For the complete system with visual examples:
About the Authors
Adam Wathan is a full-stack developer and the creator of Tailwind CSS, one of the most popular utility-first CSS frameworks. Steve Schoger is a visual designer known for his practical design tips and illustrations. Together they created Refactoring UI to teach developers how to design better interfaces using systematic, repeatable techniques rather than relying on innate artistic talent. Their approach emphasizes constrained design systems -- fixed scales for spacing, typography, color, and shadows -- that produce professional results without requiring a design background.
1---2name: refactoring-ui3description: Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off", "fix the design", "Tailwind styling", "color palette", or "visual hierarchy". Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.4license: MIT5---6
7# Refactoring UI Design System
8
9A practical, opinionated approach to UI design. Apply these principles when generating frontend code, reviewing designs, or advising on visual improvements.
10
11## Core Principle
12
13**Design in grayscale first. Add color last.** This forces proper hierarchy through spacing, contrast, and typography before relying on color as a crutch.
14
15**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.
16
17## Scoring
18
19**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.
20
21## The Refactoring UI Framework
22
23Seven principles for building professional interfaces without a designer:
24
25### 1. Visual Hierarchy
26
27**Core concept:** Not everything can be important. Create hierarchy through three levers: size, weight, and color.
28
29**Why it works:** When every element competes for attention, nothing stands out. Deliberate de-emphasis of secondary content makes primary content powerful by contrast.
30
31**Key insights:**
32- Combine levers, don't multiply -- primary text = large OR bold OR dark, not all three
33- Save "all three" for the single most important element on the page
34- Labels are secondary -- form labels, table headers, and metadata labels support the data, not compete with it
35- Semantic color does not equal visual weight -- a muted red secondary button often works better than screaming danger for routine actions
36- De-emphasize labels by making them smaller, lighter, or uppercase-small
37
38**Product applications:**
39
40| Context | Hierarchy Technique | Example |
41|---------|---------------------|---------|
42| **Form fields** | De-emphasize labels, emphasize values | Small uppercase label above large value text |
43| **Navigation** | Primary nav bold, secondary nav lighter | Active link in dark gray-900, inactive in gray-500 |
44| **Cards** | Title large, metadata small and light | Card title 20px bold, date 12px gray-400 |
45| **Dashboards** | Key metric large, context small | Revenue "$42,300" large, "vs last month" small |
46| **Tables** | De-emphasize headers, emphasize cell data | Headers uppercase small gray, data normal weight |
47
48**Design patterns:**
49- Three-level hierarchy table: Size (large/base/small), Weight (bold/medium/normal), Color (dark/medium/light gray)
50- Label-value pattern: de-emphasized label above emphasized value
51- Button hierarchy: primary (filled), secondary (outlined or muted), tertiary (text only)
52
53**Ethical boundary:** Don't use hierarchy tricks to hide important information like pricing, terms, or cancellation options.
54
55See: [references/advanced-patterns.md](references/advanced-patterns.md) for interaction states and advanced component patterns.
56
57### 2. Spacing & Sizing
58
59**Core concept:** Use a constrained spacing scale, not arbitrary values. Spacing defines relationships -- elements closer together are more related.
60
61**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.
62
63**Key insights:**
64- Use a linear or near-linear scale: 4, 8, 16, 24, 32, 48, 64px
65- Start with too much white space, then remove -- you'll almost never remove enough
66- Spacing between groups should be larger than spacing within groups
67- Text blocks should be constrained to 45-75 characters (`max-w-prose` or ~65ch)
68- Forms should max out at 300-500px width
69- Full-width is almost never right for content
70
71**Product applications:**
72
73| Context | Spacing Strategy | Example |
74|---------|-----------------|---------|
75| **Icon + label** | Tight coupling (4px) | Small gap keeps them visually connected |
76| **Form fields** | Related elements (8-16px) | Input and its label tightly coupled |
77| **Card sections** | Section separation (24px) | Title block, content block, footer block |
78| **Page sections** | Major sections (48-64px) | Hero, features, testimonials, footer |
79| **Container width** | Constrain to content | `max-w-prose` for text, `max-w-md` for forms |
80
81**CSS patterns:**
82- `p-1`(4px) `p-2`(8px) `p-4`(16px) `p-6`(24px) `p-8`(32px) `p-12`(48px) `p-16`(64px)
83- `max-w-prose`(65ch) `max-w-md`(28rem) `max-w-lg`(32rem) `max-w-xl`(36rem)
84- `gap-2` for related items, `gap-6` for section separation
85
86**Ethical boundary:** Don't use spacing to bury important UI elements like unsubscribe buttons or privacy controls.
87
88See: [references/advanced-patterns.md](references/advanced-patterns.md) for responsive breakpoint strategies.
89
90### 3. Typography
91
92**Core concept:** Use a modular type scale, constrain line heights by context, and limit to two font families maximum.
93
94**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.
95
96**Key insights:**
97- Use a modular scale: 12, 14, 16, 20, 24, 30, 36px (1.25 ratio)
98- Headings need tight line height (1.0-1.25); body text needs relaxed (1.5-1.75)
99- Wider text needs more line height
100- Avoid font weights below 400 for body text -- they become unreadable
101- Use bold (600-700) for emphasis, not for everything
102- Two fonts maximum: one for headings, one for body (or one family with weight variation)
103
104**Product applications:**
105
106| Context | Typography Rule | Example |
107|---------|----------------|---------|
108| **Hero headline** | 36px, tight line-height (1.1), bold | Large impactful statement |
109| **Section title** | 24px, line-height 1.25, semibold | Clear section demarcation |
110| **Body text** | 16px, line-height 1.75, normal weight | Comfortable reading |
111| **Captions/labels** | 12-14px, line-height 1.5, medium gray | Secondary information |
112| **Code/data** | Monospace, 14px, consistent width | Tabular data alignment |
113
114**CSS patterns:**
115- `text-xs`(12px) `text-sm`(14px) `text-base`(16px) `text-lg`(18px) `text-xl`(20px)
116- `font-normal`(400) `font-medium`(500) `font-semibold`(600) `font-bold`(700)
117- `leading-tight`(1.25) `leading-normal`(1.5) `leading-relaxed`(1.75)
118
119**Ethical boundary:** Don't use tiny type sizes to hide terms, conditions, or fees from users.
120
121See: [references/advanced-patterns.md](references/advanced-patterns.md) for text truncation and responsive typography.
122
123### 4. Color
124
125**Core concept:** Build a systematic palette with 5-9 shades per color, add subtle saturation to grays, and design in grayscale first.
126
127**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.
128
129**Key insights:**
130- Each color needs 5-9 shades from near-white to near-black (50 through 900)
131- The darkest shade is not black -- use 900-level dark grays (e.g., `#111827`) instead of pure `#000000`
132- Pure grays look lifeless -- add subtle saturation (cool UI: blue tint like `#64748b`; warm UI: yellow/brown tint like `#78716c`)
133- HSL adjustments: lighter = higher lightness, lower saturation, shift hue toward 60 degrees; darker = lower lightness, higher saturation, shift hue toward 0/240 degrees
134- Body text minimum 4.5:1 contrast ratio; large text (18px+) minimum 3:1
135- Use `#374151` (gray-700) on white, not lighter grays for readable text
136
137**Product applications:**
138
139| Context | Color Strategy | Example |
140|---------|---------------|---------|
141| **Primary palette** | 9 shades (50-900) for main brand color | Blue-500 for buttons, Blue-100 for backgrounds |
142| **Gray palette** | Saturated grays matching UI temperature | Cool grays with blue tint for tech products |
143| **Semantic colors** | Success, warning, error each with shade range | Green-500 for success, Red-500 for errors |
144| **Text colors** | Three levels: dark, medium, light | `text-gray-900`, `text-gray-600`, `text-gray-400` |
145| **Accessible contrast** | Test all text/background combos | `#374151` on white = 10.5:1 ratio |
146
147**CSS patterns:**
148- `text-gray-900`(dark) `text-gray-600`(medium) `text-gray-400`(light)
149- `bg-blue-50` for subtle backgrounds, `bg-blue-500` for primary actions
150- `border-gray-200` for subtle borders, `border-gray-300` for stronger
151
152**Ethical boundary:** Don't use color alone to convey information -- always pair with text or icons for accessibility.
153
154See: [references/theming-dark-mode.md](references/theming-dark-mode.md) for dark palette creation and theme implementation.
155
156### 5. Depth & Shadows
157
158**Core concept:** Use a shadow scale to convey elevation. Small shadows for slightly raised elements, large shadows for floating elements.
159
160**Why it works:** Shadows create a sense of physical depth that helps users understand which elements are interactive, which are floating above the surface, and which are part of the background.
161
162**Key insights:**
163- Small shadows = raised slightly (buttons, cards); large shadows = floating (modals, dropdowns)
164- Shadows have two parts: a tight, dark shadow for crispness plus a larger, softer shadow for atmosphere
165- Depth without shadows: lighter top border + darker bottom border, subtle gradient backgrounds, overlapping elements with offset
166- Don't overuse shadows -- if everything floats, nothing has depth
167- Shadow color should be transparent dark, not opaque gray
168
169**Product applications:**
170
171| Context | Shadow Level | Example |
172|---------|-------------|---------|
173| **Buttons** | `shadow-sm` (subtle raise) | Slightly elevated above page surface |
174| **Cards** | `shadow-md` (clear separation) | Content grouped and lifted from background |
175| **Dropdowns** | `shadow-lg` (floating) | Menu clearly floating above content |
176| **Modals** | `shadow-xl` (highest elevation) | Overlay clearly detached from page |
177| **Flat alternatives** | Border + background shift | Lighter top border, darker bottom border |
178
179**CSS patterns:**
180- `shadow-sm`: `0 1px 2px rgba(0,0,0,0.05)`
181- `shadow-md`: `0 4px 6px rgba(0,0,0,0.1)`
182- `shadow-lg`: `0 10px 15px rgba(0,0,0,0.1)`
183- `shadow-xl`: `0 20px 25px rgba(0,0,0,0.15)`
184
185**Ethical boundary:** Don't use excessive shadows or visual emphasis to draw attention to deceptive UI elements (dark patterns).
186
187See: [references/advanced-patterns.md](references/advanced-patterns.md) for interaction states and elevation hierarchy.
188
189### 6. Images & Icons
190
191**Core concept:** Treat images as design elements, not afterthoughts. Size icons deliberately and use overlays to ensure text readability on images.
192
193**Why it works:** Poorly sized icons look awkward. Unstyled images break visual consistency. Deliberate image treatment (overlays, object-fit, border radius) makes interfaces feel polished.
194
195**Key insights:**
196- Icons should be sized relative to their context -- don't use the same size everywhere
197- Use icon sets with consistent stroke width and style
198- Images need treatment: object-fit cover, consistent aspect ratios, overlays for text
199- Don't stretch or distort images -- use `object-fit: cover` and crop deliberately
200- Empty states are an opportunity -- use illustrations, not just text
201
202**Product applications:**
203
204| Context | Image/Icon Technique | Example |
205|---------|---------------------|---------|
206| **Hero images** | Overlay with semi-transparent gradient | Text readable over any photo |
207| **Avatars** | Consistent size, rounded, fallback initials | 40px circle with object-fit cover |
208| **Feature icons** | Consistent size, weight, and color | 24px stroke icons in gray-500 |
209| **Empty states** | Custom illustration + clear CTA | Friendly illustration with "Get started" button |
210| **Thumbnails** | Fixed aspect ratio with object-fit cover | 16:9 cards with no distortion |
211
212**CSS patterns:**
213- `object-fit: cover` with fixed `aspect-ratio` for consistent image display
214- Icon sizing: `w-4 h-4` inline, `w-6 h-6` in navigation, `w-8 h-8` for feature icons
215- Image overlay: `bg-gradient-to-t from-black/60 to-transparent` for text on images
216
217**Ethical boundary:** Don't use misleading images or icons that misrepresent functionality or product capabilities.
218
219See: [references/advanced-patterns.md](references/advanced-patterns.md) for image treatment, icon usage, and empty states.
220
221### 7. Layout & Composition
222
223**Core concept:** Don't center everything. Use alignment, overlap, and emphasis variation to create engaging compositions.
224
225**Why it works:** Left-aligned text is easier to read. Varied layouts keep users engaged. Breaking out of rigid boxes makes designs feel dynamic and intentional.
226
227**Key insights:**
228- Left-align text by default; center only short headlines, hero sections, single-action CTAs, and empty states
229- Cards don't need to contain everything -- let images bleed to edges, overlap containers, or extend beyond bounds
230- In lists and feeds, vary the visual treatment -- feature some items, minimize others
231- Use alignment to create visual relationships between unrelated elements
232- Alternate emphasis: not every card in a list needs the same layout
233
234**Product applications:**
235
236| Context | Layout Strategy | Example |
237|---------|----------------|---------|
238| **Hero sections** | Centered text, generous spacing | Short headline + subtext + single CTA |
239| **Feature grids** | Left-aligned text, consistent card sizes | 3-column grid with icon + title + description |
240| **Blog feeds** | Varied card sizes for emphasis | First post large, next posts in 2-column grid |
241| **Sidebars** | Narrower than main content, lighter background | Navigation or filters at 240-320px width |
242| **Content pages** | Constrained width, left-aligned | `max-w-prose` centered container with left text |
243
244**CSS patterns:**
245- `text-left` by default, `text-center` only for heroes and short headlines
246- `grid grid-cols-3 gap-6` for feature grids
247- `max-w-4xl mx-auto` for page containers
248- `overflow-hidden` on cards with `object-fit: cover` images that bleed to edges
249
250**Ethical boundary:** Don't use layout tricks to hide or obscure important user choices like opt-outs or data permissions.
251
252See: [references/advanced-patterns.md](references/advanced-patterns.md) for responsive breakpoints and complex layout patterns.
253
254## Common Mistakes
255
256| Mistake | Why It Fails | Fix |
257|---------|-------------|------|
258| **"Looks amateur"** | Insufficient white space, unconstrained widths | Add more white space, constrain content widths |
259| **"Feels flat"** | No depth differentiation between elements | Add subtle shadows, border-bottom on sections |
260| **"Text is hard to read"** | Poor line-height, too wide, low contrast | Increase line-height, constrain width, boost contrast |
261| **"Everything looks the same"** | No visual hierarchy between elements | Vary size/weight/color between primary and secondary |
262| **"Feels cluttered"** | Equal spacing everywhere, no grouping | Group related items, increase spacing between groups |
263| **"Colors clash"** | Random color choices without a system | Reduce saturation, use more grays, limit palette to system |
264| **"Buttons don't pop"** | Low contrast with surrounding elements | Increase contrast with surroundings, add shadow |
265| **Using arbitrary values** | px values like 13, 17, 23 create inconsistency | Stick to the spacing and type scales |
266
267## Quick Diagnostic
268
269Audit any UI design:
270
271| Question | If No | Action |
272|----------|-------|--------|
273| Does hierarchy read when squinting (blur test)? | Elements competing for attention | Increase contrast between primary and secondary |
274| Does it work in grayscale? | Relying on color for hierarchy | Strengthen size/weight/spacing hierarchy |
275| Is there enough white space? | Probably not -- most designs are too dense | Increase spacing, especially between groups |
276| Are labels de-emphasized vs. their values? | Labels competing with data | Make labels smaller, lighter, or uppercase-small |
277| Does spacing follow a consistent scale? | Arbitrary spacing creates visual noise | Use 4/8/16/24/32/48/64 scale only |
278| Is text width constrained for readability? | Long lines cause reader fatigue | Apply `max-w-prose` (~65ch) to text blocks |
279| Do colors have sufficient contrast? | Accessibility failure, hard to read | Test with WCAG contrast checker, use gray-700+ on white |
280| Are shadows appropriate for elevation? | Elements floating at wrong visual level | Match shadow scale to element purpose |
281
282## Reference Files
283
284- [advanced-patterns.md](references/advanced-patterns.md): Empty states, form design, image treatment, icon sizing, interaction states, color psychology, border radius systems, text truncation, responsive breakpoints
285- [animation-microinteractions.md](references/animation-microinteractions.md): When to animate, easing functions, durations, loading states, animation performance
286- [accessibility-depth.md](references/accessibility-depth.md): WCAG 2.1 AA checklist, focus management, screen reader support, keyboard navigation
287- [data-visualization.md](references/data-visualization.md): Chart selection, color in charts, table design, dashboard layouts
288- [theming-dark-mode.md](references/theming-dark-mode.md): Dark palette creation, elevation in dark mode, theme implementation strategies
289
290## Further Reading
291
292This skill is based on Adam Wathan and Steve Schoger's practical design guide. For the complete system with visual examples:
293
294- [*"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 before/after examples)
295- [*"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)
296- [*"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)
297- [Refactoring UI](https://www.refactoringui.com/) -- Official site with resources and examples
298
299## About the Authors
300
301**Adam Wathan** is a full-stack developer and the creator of Tailwind CSS, one of the most popular utility-first CSS frameworks. **Steve Schoger** is a visual designer known for his practical design tips and illustrations. Together they created *Refactoring UI* to teach developers how to design better interfaces using systematic, repeatable techniques rather than relying on innate artistic talent. Their approach emphasizes constrained design systems -- fixed scales for spacing, typography, color, and shadows -- that produce professional results without requiring a design background.
gabrielmoreira