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. Trigger with 'refactoring', 'ui'.
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. Trigger with 'refactoring', 'ui'.
allowed-tools
Read, Glob, Grep
license
MIT
author
Wondelai <hello@wondelai.com>
version
1.0.1
compatible-with
claude-code, codex, openclaw
tags
["design","scaling","workflow","audit"]
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
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)
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)
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).
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 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
Ethical boundary: Don't use layout tricks to hide or obscure important user choices like opt-outs or data permissions.
"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 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.
Overview
Audit and fix visual hierarchy, spacing, color, and depth in web UIs.
Prerequisites
Access to the audit environment or API
Required CLI tools installed and authenticated
Familiarity with audit concepts and terminology
Instructions
Assess the current state of the audit configuration
Identify the specific requirements and constraints
Apply the recommended patterns from this skill
Validate the changes against expected behavior
Document the configuration for team reference
Output
Configuration files or code changes applied to the project
