← Back to Blogs

Invalid Date

title: Beyond the Basics: Leveraging Tailwind CSS Config for a Truly Scalable Design System date: 2026-04-22T07:00:00.573Z description: Blog about Beyond the Basics: Leveraging Tailwind CSS Config for a Truly Scalable Design System

Hey everyone, Prashuk here.

If you’ve been following my work, you know I’m a big fan of getting things done without over-complicating them. I’ve spent a lot of time building with the MERN stack and Next.js, and for a long while, I used Tailwind CSS just like everyone else—throwing utility classes at elements until they looked "okay."

But honestly? That approach falls apart the moment your project grows. I learned this the hard way. Today, I want to talk about how to actually use tailwind.config.js to build a design system that doesn’t make you want to pull your hair out six months down the line.

1. The "Random Hex Code" Trap

In one of my early freelance projects, I was building a dashboard for a client. I kept copying and pasting hex codes like #3b82f6 and #1e293b everywhere. Then, the client decided they wanted a "slightly more vibrant" blue.

I had to search and replace across 40 different components. It was a nightmare.

What worked for me was moving everything into the theme.extend section of the config file. Instead of using arbitrary colors, I started defining semantic names. Now, if the "Primary" color changes, I change it in one line in the config, and the whole app updates.

2. Don’t Just Extend—Standardize Your Spacing

I’ve noticed that UI looks "cheap" when the spacing is inconsistent. If your button has px-5 but your input has px-4, the alignment feels off, even if the user can’t quite put their finger on why.

I ran into this issue when building a SaaS landing page. The sections felt cluttered. I decided to strip back the default Tailwind spacing and define a custom scale. By limiting myself to a few specific values (like xs, sm, md, lg, xl), I forced myself to keep the UI clean. It’s much harder to mess up a layout when you have a pre-defined "rhythm."

3. Leveraging CSS Variables for True Flexibility

This is a game-changer for themes (like Dark Mode). Instead of hardcoding colors in your Tailwind config, use CSS variables.

I started doing this recently, and it’s so much cleaner. You define the variable in your global CSS and then reference it in your tailwind.config.js. This allows you to toggle themes by just changing a class on the <body> tag without writing a bunch of dark:text-white classes everywhere in your HTML.

4. A Practical Code Example

Here’s a look at how I usually structure a scalable config for my projects:

// tailwind.config.js
module.exports = {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        // Using CSS variables for easy theme switching
        brand: {
          primary: 'var(--color-primary)',
          secondary: 'var(--color-secondary)',
          accent: '#f59e0b', // Fixed brand color
        },
        surface: {
          100: 'var(--color-bg-100)',
          200: 'var(--color-bg-200)',
        }
      },
      spacing: {
        'safe-area': '1.25rem',
        'section-gap': '5rem',
      },
      borderRadius: {
        'brand': '12px',
      }
    },
  },
  plugins: [],
}

5. Best Practices from the Trenches

  • Stop using arbitrary values: If you find yourself writing top-[13px] more than twice, go into your config and give it a name.
  • Keep it semantic: Name colors by their function (brand-primary) rather than their appearance (bright-blue).
  • Purge responsibly: Always make sure your content array is accurately pointing to your folders. I once spent an hour wondering why my styles weren't applying, only to realize I forgot to include a new src/features folder.
  • Sync with your Designer: If you're working with a designer using Figma, make sure your Tailwind config matches their "Design Tokens." It makes communication 10x faster.

Conclusion

At the end of the day, Tailwind is more than just a bunch of shorthand classes; it’s a tool to build a framework for your UI. By spending 20 minutes setting up a proper tailwind.config.js, you save yourself dozens of hours of refactoring later.

Clean code isn't just about how it looks to the computer; it's about how easy it is for you (or the next dev) to change things. Use the config, keep it consistent, and focus on building features rather than hunting down hex codes.

Catch you in the next one!

— Prashuk