Refactoring UI Tailwind CSS Best Practices

When to Apply

• 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

intent-

hier-

space-

type-

color-

depth-

sep-

img-

polish-

Quick Reference

1. Design Intent (CRITICAL)

• intent-audit-before-styling

  - Audit what each element communicates before changing any CSS

• intent-remove-before-decorating

  - Remove unnecessary elements before styling what remains

• intent-reduce-cognitive-load

  - Reduce choices per screen — fewer options beat prettier options

• intent-progressive-disclosure

  - Hide secondary information behind interactions

• intent-content-drives-layout

  - Let real content determine layout — not the other way around

• intent-simplify-over-decorate

  - Prefer removing a wrapper over adding 5 utility classes to it

• intent-match-context-fidelity

  - Match design polish to context — admin vs consumer vs product

• intent-match-existing-patterns

  - Audit sibling component patterns before restyling

2. 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

3. 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

  - Constrain content width — avoid filling the whole screen

• space-grids-not-required

  - Use fixed widths when grids are not needed

• space-relative-sizing-fails

  - Avoid raw viewport units without clamping

• space-mobile-first

  - Design mobile-first at ~400px, then expand

4. 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

  - Left-align body content — avoid centering long-form text

• type-letter-spacing

  - Tighten letter spacing for headlines, loosen for uppercase

• type-align-numbers-right

  - Align numbers right in tables for easy comparison

5. 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

6. 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

7. 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

  - Upgrade radio buttons to selectable cards for key choices

8. 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

  - Avoid scaling up icons designed for small sizes

• img-empty-states

  - Design meaningful empty states with clear CTAs

9. 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

Scope & Limitations

• Font selection & pairing — choosing distinctive typefaces, avoiding generic AI defaults (Inter, Arial, system-ui), or pairing display + body fonts
• Animation & motion — meaningful transitions, micro-interactions, page load sequences, or scroll-triggered reveals
• Creative direction — establishing an aesthetic vision, choosing a tone (minimal, maximalist, brutalist, etc.), or differentiating from generic "AI slop" aesthetics
• Spatial composition — asymmetric layouts, grid-breaking elements, or unconventional visual flow

How to Use

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

Reference Files