How to migrate CSS to Tailwind

Tailwind promises less CSS and faster iteration, but migrating an existing stylesheet is where most teams stall. Pick the wrong approach and you end up with a mess of utility classes next to dead CSS files for months. This guide covers the migration strategies that work (big bang vs component-by-component vs utilities alongside), the config you need to preserve your design tokens, how to handle nested selectors / pseudo-classes / media queries, dealing with component libraries, common breakages, and tools that speed up the conversion.

Decide the migration shape first

Three viable paths. Picking the wrong one is the main source of pain.

Big bang (rewrite all CSS at once): fastest finish, highest risk. Works only for small codebases (<5k lines CSS) or fresh projects.

Utilities alongside legacy CSS: add Tailwind, start using it on new components, don’t touch existing ones. Low risk, slow finish, potential for drift. Fine if the goal is “stop writing new CSS” not “delete all CSS”.

Component-by-component: pick a component, convert fully (remove its dedicated CSS, replace with utilities), verify, move on. Best balance. This is what most successful migrations use.

Pick one and commit. Mixing strategies without discipline leads to half-done components everywhere.

Set up the config to match your existing design tokens

Don’t use Tailwind defaults blindly. Map your existing colors, spacing scale, font sizes, and breakpoints into tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: { 50: '#f0f9ff', 500: '#3b82f6', 900: '#1e3a8a' },
        // from your existing --color-* tokens
      },
      spacing: {
        18: '4.5rem',  // if you have odd values
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
      screens: {
        'xs': '475px',  // if you have custom breakpoints
      },
    },
  },
};

This single step saves thousands of find-replaces. Your utility classes now reflect your tokens, so bg-brand-500 means exactly what your design system says it means.

Convert nested selectors

Nested CSS like .card > .title { color: blue; } becomes utility classes on the child element directly.

/* Before */
.card { padding: 1rem; border: 1px solid gray; }
.card > .title { font-weight: 600; color: blue; }

/* After */
<div class="p-4 border border-gray-300">
  <h3 class="font-semibold text-blue-600">...</h3>
</div>

Think in terms of elements, not cascades. This is the biggest mindset shift.

Pseudo-classes and states

Tailwind uses variant prefixes:

/* Before */
.button:hover { background: darkblue; }
.button:focus { outline: 2px solid blue; }
.button:disabled { opacity: 0.5; }

/* After */
<button class="bg-blue-500 hover:bg-blue-700 focus:outline-2 focus:outline-blue-500 disabled:opacity-50">

Stack variants freely: md:hover:bg-gray-100 means “on medium+ screens, when hovered”. Order matters only for readability — Tailwind processes them correctly regardless.

Media queries → responsive prefixes

Tailwind’s responsive prefixes are mobile-first. md: = “at 768px and above”, lg: = “1024px and above”.

/* Before */
.layout { display: block; }
@media (min-width: 768px) { .layout { display: flex; } }

/* After */
<div class="block md:flex">

Max-width queries use max-* variants (Tailwind 3.0+). Mostly you won’t need them if you think mobile-first.

Dealing with component libraries

If you use Bootstrap, Material UI, or similar, don’t rip them out on day one. Migrate leaf components (your own buttons, cards, layouts) first. Move to Tailwind-based component libraries (shadcn/ui, Radix + Tailwind, Headless UI) only after your own styles are stable.

Some libraries conflict with Tailwind’s base reset (it zeros out margins, list styles, etc.). Either scope Tailwind’s preflight or add a root selector in the config to limit its reach.

Extracting repeated patterns

When you see class=“flex items-center px-4 py-2 bg-blue-500 text-white rounded” everywhere, extract it. Options:

Component: <Button variant=“primary”> — best for React/Vue/Svelte apps. Utility classes stay local to one file.

@apply directive: in a CSS file, write .btn-primary { @apply flex items-center ...; }. Useful for non-component codebases but somewhat defeats the utility-first point. Use sparingly.

Tailwind plugin: register custom components via addComponents(). Good for design system primitives used everywhere.

Handling dynamic class names

Tailwind compiles classes by scanning source files for class strings. Dynamic composition breaks this:

// Bad — Tailwind can't see 'bg-red-500' in source
<div className={`bg-${color}-500`}>

// Good — complete class names in source
<div className={color === 'red' ? 'bg-red-500' : 'bg-blue-500'}>

// Also good — safelist in config
// tailwind.config.js: safelist: ['bg-red-500', 'bg-blue-500']

This is the #1 source of “why is my class not working” bug reports.

Global styles that remain

Some styles don’t convert cleanly:

Complex animations with many keyframes — keep as CSS, reference via Tailwind’s animate-* extension.

Print styles — Tailwind supports print: variant now, but complex print CSS often stays separate.

Third-party embed styles (markdown content, rich text from CMS) — use @tailwindcss/typography plugin or keep a separate content stylesheet.

Stripping dead CSS after conversion

The payoff: delete the old CSS. Do this per component, not at the end. Steps:

1. Convert component to Tailwind utilities.

2. Remove its class names from the template.

3. Delete the matching CSS rules.

4. Run the app; verify visually.

5. Commit the component + its CSS deletion together.

If you wait until “everything is converted” to delete CSS, you won’t.

Build size and performance

Modern Tailwind (3.0+) uses JIT compilation — generates only classes you use. Production CSS is typically 10-50KB. Old codebases with 500KB of custom CSS often drop to under 30KB after migration.

Check with npx tailwindcss -i in.css -o out.css --minify — compare file sizes before and after.

Common mistakes

Keeping both old CSS and Tailwind on the same element. Specificity wars. Remove old classes as you add new ones, per commit.

Inlining 30 utility classes. At some point, extract to a component. Utility chains longer than ~15 are a smell.

Ignoring Tailwind’s preflight. Its base reset removes default margins/list styles/button styling. Check your layouts after enabling it.

Overriding with !important. Tailwind provides the ! prefix (!bg-red-500). Use extremely sparingly — the real fix is usually source order.

Not configuring the content glob. Tailwind only scans files listed in content: [...]. Missing your .mdx or .svelte files means classes disappear from prod.

Treating migration as 100% utility coverage. Complex animations, print styles, third-party content — leaving some CSS is fine.

Run the numbers

Convert existing CSS rules to Tailwind utility classes with the CSS to Tailwind converter. Pair with the CSS minifier to ship the legacy styles you kept, and the CSS clamp generator for fluid values Tailwind doesn’t cover out of the box.