Sign In

Sign in with your preferred provider:

← Back to Articles

Migrating to Tailwind CSS

Created:
Updated:
Written by: AI
#Technology #CSS #Tailwind #Development

AI-generated content. Yes, a lazy human reviewed it, but the AI did the research and writing.

After building a custom utility class system inspired by Tailwind CSS, I recently made the decision to migrate to the actual Tailwind CSS framework. This article documents the migration process, the reasoning behind the decision, and provides recommendations for future development.

The Starting Point

Before the migration, vikan.cloud used a custom utility class system with:

  • 400+ custom utility classes in src/styles/utilities.css
  • CSS variables for theming and spacing
  • Custom spacing scale: xs, sm, md, lg, xl
  • Custom color system using CSS variables for light/dark mode
  • ~900 lines of CSS across global.css and utilities.css

The system was working well, but I identified several benefits of migrating to Tailwind CSS:

  1. Ecosystem and tooling: Better IDE support, extensive documentation, and community resources
  2. Build-time optimization: Automatic purging of unused classes
  3. Consistency: Standardized design tokens and predictable spacing scales
  4. Maintainability: Less custom code to maintain, easier for new developers

The Migration Process

Step 1: Installation and Configuration

Installed Tailwind CSS v3.4.19 with the Astro integration:

npm install -D tailwindcss@3.4.19 @astrojs/tailwind@6.0.2
npm install -D @tailwindcss/typography@0.5.15 @tailwindcss/forms@0.5.9

Note: Initially installed Tailwind v4, but had to downgrade to v3.4.19 for compatibility with the Astro plugin and existing plugins.

Step 2: Tailwind Configuration

Created tailwind.config.mjs with custom theme extensions:

export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {
      colors: {
        accent: {
          DEFAULT: '#6366f1',
          hover: '#4f46e5',
          light: '#818cf8',
          dark: '#4338ca',
        },
        // ... custom colors
      },
      spacing: {
        xs: '0.5rem',
        sm: '1rem',
        md: '1.5rem',
        lg: '2rem',
        xl: '3rem',
      },
      // ... custom spacing, borderRadius, boxShadow
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
  darkMode: ['selector', '[data-theme="dark"]'],
}

Key decisions:

  • Preserved custom spacing scale (xs, sm, md, lg, xl) for consistency
  • Maintained CSS variables for theming (light/dark mode)
  • Used selector-based dark mode to match existing [data-theme="dark"] approach
  • Set applyBaseStyles: false in Astro config to preserve existing base styles

Step 3: Global CSS Migration

Updated src/styles/global.css to include Tailwind directives while preserving CSS variables:

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer utilities {
  /* Custom color utilities using CSS variables */
  .bg-primary {
    background-color: var(--bg-primary);
  }
  .bg-secondary {
    background-color: var(--bg-secondary);
  }
  .text-gray-dark {
    color: rgb(var(--gray-dark));
  }
  /* ... more custom utilities */
}

:root {
  /* Preserved all existing CSS variables */
  --accent: #6366f1;
  --spacing-xs: 0.5rem;
  /* ... */
}

Why preserve CSS variables?

  • Maintains existing theme system
  • Allows runtime theme switching (light/dark mode)
  • Keeps custom component styles working

Step 4: Plugin Integration

Installed and configured three key plugins:

  1. @tailwindcss/typography: Enhanced prose styling for articles and book reviews
  2. @tailwindcss/forms: Better form input styling (search, network tools)
  3. Aspect ratio: Built into Tailwind v3.3+, no plugin needed

Step 5: Class Compatibility

The existing utility classes were largely compatible with Tailwind because:

  • Custom spacing (xs, sm, md, lg, xl) was defined in Tailwind config
  • Standard Tailwind classes (flex, items-center, justify-between) worked out of the box
  • Custom color utilities were added via @layer utilities to reference CSS variables

No major refactoring required - the migration was mostly configuration!

Migration Results

What Changed

✅ Build process: Now includes Tailwind’s PostCSS processing
✅ Bundle size: Tailwind automatically purges unused classes
✅ IDE support: Better autocomplete and IntelliSense
✅ Documentation: Access to official Tailwind docs and examples

What Stayed the Same

✅ CSS variables: All theme variables preserved
✅ Dark mode: Existing [data-theme="dark"] system works
✅ Custom components: Card, tag, and other component styles unchanged
✅ Spacing scale: Custom xs, sm, md, lg, xl spacing maintained
✅ Visual appearance: No visual changes to the site

Build Performance

  • Build time: Slightly increased (~100-200ms) due to PostCSS processing
  • Bundle size: Optimized through automatic purging
  • Development: Faster with better IDE support

Recommendations for Future Development

1. Use Tailwind’s Standard Spacing Scale

Current state: Using custom spacing (xs, sm, md, lg, xl)

Recommendation: Gradually migrate to Tailwind’s standard spacing scale (1, 2, 3, 4, 6, 8, 12, 16, 24, 32, etc.) for better consistency with the ecosystem.

Migration path:

  • Map custom spacing to Tailwind equivalents:
    • xs (0.5rem) → 2 (0.5rem)
    • sm (1rem) → 4 (1rem)
    • md (1.5rem) → 6 (1.5rem)
    • lg (2rem) → 8 (2rem)
    • xl (3rem) → 12 (3rem)
  • Update classes incrementally across pages
  • Remove custom spacing from config once migration complete

2. Leverage Tailwind’s Color System

Current state: Using CSS variables for colors with custom utilities

Recommendation: Consider migrating to Tailwind’s color system while maintaining CSS variables for theme switching.

Approach:

  • Keep CSS variables for runtime theme switching
  • Use Tailwind’s color utilities where possible (bg-accent, text-gray-500)
  • Create custom utilities only when CSS variables are necessary

3. Implement Planned Enhancements

Created GitHub Issue #317 for future enhancements:

High Priority:

  • Enhanced form styling: Better focus states, disabled states, error states
  • Animation utilities: Fade, slide, pulse animations for smoother interactions

Medium Priority:

  • Backdrop blur: Modern glassmorphism effects for overlays
  • Gradient text: Enhanced gradient utilities
  • Transform utilities: More transform options for animations

Low Priority:

  • Container queries: Responsive design based on container size (requires browser support consideration)

4. Use Tailwind’s Typography Plugin More Extensively

Current state: Basic prose styling

Recommendation: Leverage @tailwindcss/typography more extensively:

  • Use prose classes for article content
  • Customize prose styles via Tailwind config
  • Remove custom .prose styles from global.css

Example:

<article class="prose prose-lg max-w-none">
  <!-- Article content -->
</article>

5. Adopt Tailwind’s Responsive Breakpoints

Current state: Custom mobile: prefix for responsive utilities

Recommendation: Use Tailwind’s standard responsive prefixes:

  • sm: (640px+) instead of custom mobile breakpoints
  • md: (768px+)
  • lg: (1024px+)
  • xl: (1280px+)

Migration: Replace mobile:hidden with sm:hidden, etc.

6. Consider Tailwind CSS v4 (When Stable)

Current state: Using Tailwind v3.4.19

Recommendation: Monitor Tailwind CSS v4 development and consider upgrading when:

  • Stable release is available
  • Astro plugin supports v4
  • All required plugins are compatible
  • Migration path is clear

Benefits of v4:

  • Improved performance
  • Better CSS variable support
  • New features and utilities

7. Document Custom Utilities

Recommendation: Create a reference document for custom utilities that extend Tailwind:

  • Document all @layer utilities additions
  • Explain when to use custom utilities vs. Tailwind defaults
  • Keep the list minimal - prefer Tailwind defaults when possible

8. Regular Dependency Updates

Recommendation: Keep Tailwind and plugins updated:

  • Monitor for security updates
  • Test updates in development before production
  • Review changelogs for breaking changes
  • Update incrementally (don’t jump multiple major versions)

Lessons Learned

What Went Well

  1. Smooth migration: Existing utility classes were compatible, minimal refactoring needed

    • The custom utility system was well-designed and followed Tailwind-like patterns
    • Most classes mapped directly to Tailwind equivalents
    • No visual regressions or breaking changes

  2. Preserved functionality: CSS variables and theme system continued working

    • Dark mode switching remained functional
    • Custom theming system intact
    • Component styles unchanged

  3. Better tooling: Improved IDE support and autocomplete

    • IntelliSense for Tailwind classes
    • Better error detection
    • Faster development workflow

  4. Community resources: Access to extensive Tailwind documentation and examples

    • Official documentation is comprehensive
    • Large community with solutions to common problems
    • Plugin ecosystem provides ready-made solutions

  5. Build optimization: Automatic purging of unused classes

    • Smaller CSS bundle size
    • Only includes classes actually used
    • Better performance

Challenges Encountered

  1. Version compatibility: Had to downgrade from v4 to v3.4.19 for plugin compatibility

    • Tailwind v4 requires different setup (PostCSS plugin)
    • Astro plugin and other plugins not yet compatible with v4
    • Solution: Use stable v3.4.19 until ecosystem catches up

  2. CSS variable integration: Needed custom utilities to bridge CSS variables with Tailwind classes

    • Tailwind doesn’t natively support CSS variables in all contexts
    • Created custom utilities using @layer utilities to bridge the gap
    • This approach works but adds some maintenance overhead

  3. Learning curve: Understanding Tailwind’s configuration and plugin system

    • Configuration syntax and structure
    • Plugin installation and setup
    • Understanding when to use plugins vs. custom utilities

  4. Documentation overhead: Need to document custom utilities and deviations

    • Custom spacing scale requires documentation
    • CSS variable utilities need explanation
    • Team members need to understand what’s custom vs. standard

What I’d Do Differently

  1. Start with Tailwind from day one: If starting a new project, use Tailwind CSS from the beginning

    • Avoid building custom utility systems
    • Benefit from ecosystem immediately
    • Standard patterns from the start
    • Recommendation for all new projects: Start with Tailwind CSS

  2. Use standard spacing scale: Would use Tailwind’s standard spacing scale instead of custom

    • Better ecosystem compatibility
    • Easier for new developers
    • More predictable and documented

  3. Earlier migration: Would have migrated sooner to benefit from ecosystem earlier

    • Could have avoided building some custom utilities
    • Would have had better tooling support earlier
    • Community resources available from the start

  4. Plan for CSS variables: If using CSS variables, plan the integration strategy upfront

    • Consider Tailwind’s color system vs. CSS variables
    • Design theme system with Tailwind in mind
    • Document the approach early

Key Insights

  1. Custom utilities can be a stepping stone: Building a custom utility system helped understand Tailwind’s value, but starting with Tailwind would have been more efficient.

  2. Migration is easier than expected: If your custom utilities follow Tailwind-like patterns, migration can be relatively smooth.

  3. Ecosystem matters: The Tailwind ecosystem (plugins, tools, community) provides significant value beyond just the CSS framework.

  4. Configuration is powerful: Tailwind’s configuration system allows extensive customization while maintaining consistency.

  5. Documentation is crucial: When deviating from Tailwind standards, clear documentation helps team members understand the approach.

Recommendation for New Projects

If you’re starting a new project, use Tailwind CSS from the beginning.

Here’s why:

  1. No migration needed: Start with the right tool from day one
  2. Full ecosystem access: Benefit from plugins, tools, and community immediately
  3. Standard patterns: Use industry-standard patterns that new team members will recognize
  4. Better tooling: IDE support and autocomplete from the start
  5. Less custom code: Avoid building and maintaining custom utility systems
  6. Proven solution: Tailwind is battle-tested with millions of developers

When NOT to start with Tailwind:

  • Very small projects where CSS-in-JS might be simpler
  • Projects with strict design systems that don’t align with utility-first approach
  • Teams with strong preferences for other CSS approaches

For most projects, especially:

  • Web applications
  • Marketing websites
  • Blogs and content sites
  • Design systems
  • Component libraries

Tailwind CSS is the recommended starting point.

Conclusion

The migration to Tailwind CSS was successful and relatively painless. The existing custom utility system was well-designed and compatible with Tailwind, making the transition smooth. The main benefits are improved tooling, better ecosystem support, and automatic optimization.

Key takeaways:

  • Custom utility systems can be a stepping stone to Tailwind
  • Preserving CSS variables allows maintaining existing theme systems
  • Tailwind’s plugin ecosystem provides powerful extensions
  • Gradual migration is possible without breaking changes

Next steps:

  • Implement enhancements from GitHub Issue #317
  • Gradually migrate to standard Tailwind spacing
  • Leverage typography plugin more extensively
  • Monitor Tailwind v4 development

The migration has positioned vikan.cloud to benefit from Tailwind’s ecosystem while maintaining the custom theming and design system that makes the site unique.

← Back to Articles