tailwind-ui-refactor

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 52 rules across 9 categories, prioritized by design impact to guide automated refactoring and code generation. Uses Tailwind CSS v4 syntax (v3 notes provided where syntax differs). Important: Think first, style second. Before applying any visual rule, understand the UI's purpose, identify what matters to the user, and remove unnecessary elements. The Design Intent category (priority 1) must be considered before any styling changes. A simpler component with fewer elements always beats a decorated component with unnecessary markup. 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 Priority Category Impact Prefix 1 Design Intent CRITICAL intent- 2 Visual Hierarchy CRITICAL hier- 3 Layout & Spacing CRITICAL space- 4 Typography HIGH type- 5 Color Systems HIGH color- 6 Depth & Shadows MEDIUM depth- 7 Borders & Separation MEDIUM sep- 8 Images & Content LOW-MEDIUM img- 9 Polish & Details LOW 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 This skill covers layout, hierarchy, spacing, color, and polish based on Refactoring UI principles. It does NOT cover: 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 For these concerns, pair this skill with a design-thinking or frontend-design skill that covers creative direction and aesthetic execution. 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 File Description references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information