Refactoring UI Tailwind CSS Best Practices

Comprehensive UI refactoring guide based on Refactoring UI by Adam Wathan & Steve Schoger, implemented with Tailwind CSS utility classes. Contains 44 rules across 8 categories, prioritized by visual impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Refactoring existing Tailwind CSS components
• Writing new UI with Tailwind utility classes
• Reviewing code for visual hierarchy and spacing issues
• Improving design quality without a designer
• Fixing accessibility contrast problems

Rule Categories by Priority

Quick Reference

1. Visual Hierarchy (CRITICAL)

• hier-size-weight-color – Use size, weight, and color for hierarchy — not just size
• hier-deemphasize-secondary – De-emphasize secondary content instead of emphasizing primary
• hier-button-hierarchy – Style buttons by visual hierarchy, not semantic importance
• hier-label-value-pairs – Combine labels and values into natural language
• hier-semantic-vs-visual – Separate visual hierarchy from document hierarchy
• hier-icon-sizing – Size icons relative to adjacent text, not to fill space
• hier-color-hierarchy-on-dark – Use opacity or muted colors for hierarchy on colored backgrounds

2. Layout & Spacing (CRITICAL)

• space-start-generous – Start with too much whitespace, then remove
• space-systematic-scale – Use a constrained spacing scale, not arbitrary values
• space-relationship-proximity – Use spacing to show relationships between elements
• space-dont-fill-screen – Don’t fill the whole screen — constrain content width
• space-grids-not-required – Don’t force everything into a grid — use fixed widths
• space-relative-sizing-fails – Avoid viewport-relative units for element sizing
• space-mobile-first – Design mobile-first at ~400px, then expand

3. Typography (HIGH)

• type-line-length – Keep line length between 45-75 characters
• type-line-height-inverse – Line height and font size are inversely proportional
• type-font-weight-variety – Choose fonts with at least 5 weight variations
• type-no-center-long-text – Don’t center long-form text — left-align body content
• type-letter-spacing – Tighten letter spacing for headlines, loosen for uppercase
• type-align-numbers-right – Right-align numbers in tables for easy comparison

4. Color Systems (HIGH)

• color-define-palette-upfront – Define a complete color palette upfront — don’t pick colors ad-hoc
• color-grayscale-first – Design in grayscale first, add color last
• color-accessible-contrast – Ensure 4.5:1 contrast ratio for body text
• color-dark-gray-not-black – Use dark gray instead of pure black for text
• color-saturated-grays – Add subtle saturation to grays for warmth or coolness
• color-light-backgrounds-dark-text – Use light-colored backgrounds with dark text for badges

5. Depth & Shadows (MEDIUM)

• depth-shadow-scale – Define a fixed shadow scale — small to extra large
• depth-shadow-vertical-offset – Use vertical offset for natural-looking shadows
• depth-interactive-elevation – Use shadow changes to communicate interactivity
• depth-light-closer-dark-recedes – Lighter colors feel closer, darker colors recede
• depth-overlap-layers – Overlap elements to create visual layers

6. Borders & Separation (MEDIUM)

• sep-fewer-borders – Use fewer borders — replace with spacing, shadows, or background color
• sep-background-color-separation – Use background color differences to separate sections
• sep-table-spacing-not-lines – Use spacing instead of lines in simple tables
• sep-card-radio-buttons – Convert radio buttons and checkboxes to selectable cards

7. Images & Content (LOW-MEDIUM)

• img-control-user-content – Control user-uploaded image size and aspect ratio
• img-text-overlay – Add overlays or reduce contrast for text over images
• img-dont-scale-up-icons – Don’t scale up icons designed for small sizes
• img-empty-states – Design meaningful empty states with clear CTAs

8. Polish & Details (LOW)

• polish-accent-borders – Add accent borders to highlight important elements
• polish-custom-bullets – Replace default bullets with icons or checkmarks
• polish-border-radius-personality – Match border radius to brand personality
• polish-gradient-close-hues – Use gradients with hues within 30 degrees of each other
• polish-inner-shadow-images – Add inner shadow to prevent image background bleed

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Reference Files