In This Guide
1. Why Migrate to Tailwind?
Benefits
- • Faster development with utility classes
- • Smaller production CSS (unused styles removed)
- • Consistent design system out of the box
- • No context switching between HTML and CSS
- • Easy responsive design with prefixes
- • Dark mode support built-in
Considerations
- • Learning curve for the team
- • HTML can become verbose
- • Migration takes time
- • Different mental model
- • May not suit all projects
Good candidates for migration:
- • Projects with inconsistent styling
- • Sites with large unused CSS bundles
- • Teams wanting a design system
- • New features in existing projects
2. Assessment Phase
Audit Your Current CSS
Before migrating, understand what you're working with:
- • How many CSS files do you have?
- • Total lines of CSS?
- • How much is actually used?
- • Are there existing patterns or components?
- • Any CSS-in-JS or preprocessors?
Identify Components
Group your CSS by component or feature:
/* Group 1: Layout */ .container, .sidebar, .main-content /* Group 2: Navigation */ .nav, .nav-item, .nav-link /* Group 3: Cards */ .card, .card-header, .card-body /* Group 4: Forms */ .form-group, .input, .button
Check for Custom Values
Note any values that don't map to Tailwind defaults:
- • Custom colors (brand colors)
- • Non-standard spacing values
- • Custom fonts
- • Unique breakpoints
3. Migration Strategies
Strategy 1: Incremental (Recommended)
Migrate component by component while keeping old CSS alongside Tailwind.
- • Lower risk - can roll back individual components
- • Team learns gradually
- • Ship continuously
- • Takes longer overall
Strategy 2: New Features Only
Use Tailwind only for new features, leave existing CSS alone.
- • Lowest effort
- • No risk to existing features
- • Results in mixed codebase
- • May need both systems long-term
Strategy 3: Full Rewrite
Replace all CSS with Tailwind at once.
- • Clean result
- • High risk
- • Long development freeze
- • Only for small projects
4. Common CSS to Tailwind Mappings
| CSS Property | Tailwind Class |
|---|---|
display: flex | flex |
display: grid | grid |
justify-content: center | justify-center |
align-items: center | items-center |
margin: 1rem | m-4 |
padding: 0.5rem 1rem | py-2 px-4 |
font-size: 1.25rem | text-xl |
font-weight: 600 | font-semibold |
color: #3b82f6 | text-blue-500 |
background-color: #f3f4f6 | bg-gray-100 |
border-radius: 0.5rem | rounded-lg |
box-shadow: 0 1px 3px... | shadow-sm |
Before & After Example
Traditional CSS:
.card {
display: flex;
flex-direction: column;
padding: 1.5rem;
background: white;
border-radius: 0.5rem;
box-shadow: 0 1px 3px rgba(0,0,0,0.1);
}
.card-title {
font-size: 1.25rem;
font-weight: 600;
color: #1f2937;
margin-bottom: 0.5rem;
}
.card-text {
color: #6b7280;
font-size: 0.875rem;
}Tailwind:
<div class="
flex flex-col
p-6
bg-white
rounded-lg
shadow-sm
">
<h3 class="
text-xl font-semibold
text-gray-800
mb-2
">Title</h3>
<p class="
text-gray-500
text-sm
">Description</p>
</div>5. Component-by-Component Approach
Pick a Low-Risk Component
Start with a simple, isolated component like a button or card.
Identify All Styles
List every CSS property affecting the component, including hover/focus states.
Map to Tailwind Classes
Convert each property. Use arbitrary values [value] for custom values.
Replace and Test
Apply Tailwind classes, remove old CSS, visually compare results.
Extract Repeated Patterns
Use @apply or component abstraction for repeated class combinations.
6. Testing and Validation
Visual Regression Testing
Use tools like Percy, Chromatic, or BackstopJS to catch visual differences automatically.
Manual Checklist
- • Compare screenshots before/after
- • Test all interactive states (hover, focus, active)
- • Check responsive breakpoints
- • Verify dark mode if applicable
- • Test in multiple browsers
CSS Bundle Size Check
Compare CSS file sizes before and after. Production Tailwind with purging should be smaller.
7. Tools That Help
Frontend Hero Tailwind Converter
The fastest way to convert CSS to Tailwind. Click any element on any website to see its CSS automatically converted to Tailwind classes.
- ✓Click any element to get Tailwind classes
- ✓Handles pseudo-classes and media queries
- ✓Shows arbitrary values for non-standard CSS
- ✓Works on your existing site - no setup needed
Online Converters
- • transform.tools/css-to-tailwind
- • tailwind-converter.com
VS Code Extensions
- • Tailwind CSS IntelliSense
- • Headwind (class sorting)
Migration Checklist
- Audit existing CSS and identify components
- Choose migration strategy (incremental recommended)
- Set up Tailwind in your project
- Add custom colors/fonts to tailwind.config.js
- Migrate components one at a time
- Test each component visually
- Remove unused CSS as you go
- Verify production build size is smaller