Adding Custom Colors to Tailwind CSS

By swatches.net team • November 2025 • 4 min read

Tailwind's default color palette is excellent, but every brand needs custom colors. Whether you're matching a brand guide or creating a unique aesthetic, extending Tailwind's colors is essential for professional projects.

Using Tailwind v4? Since v4 (January 2025) colors are defined in CSS with @theme { --color-brand-500: #3b82f6; } instead of tailwind.config.js. The JavaScript config examples in this article apply to Tailwind v3. See our Tailwind color config guide for v4 syntax.

Understanding Tailwind's Color System

Tailwind uses a numeric scale from 50 (lightest) to 950 (darkest) for each color. This creates predictable, accessible color ramps that work across your entire design.

Default Scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950

Extending the Default Palette

The cleanest approach is extending (not replacing) Tailwind's colors:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        // Add your brand color
        brand: {
          50: '#eff6ff',
          100: '#dbeafe',
          200: '#bfdbfe',
          300: '#93c5fd',
          400: '#60a5fa',
          500: '#3b82f6',  // Base brand color
          600: '#2563eb',
          700: '#1d4ed8',
          800: '#1e40af',
          900: '#1e3a8a',
          950: '#172554',
        },
      },
    },
  },
}

Now you can use classes like bg-brand-500, text-brand-700, etc.

Creating Shade Scales

Generating a complete 11-shade scale manually is tedious. Here are better approaches:

Method 1: Online Generators

UI Colors: uicolors.app/create - Paste your hex, get Tailwind scale
Tailwind Shades: tailwindshades.com - Auto-generate from single color
Coolors: coolors.co - Create scales, export for Tailwind

Method 2: Using theme()

Reference existing Tailwind colors in your config:

// tailwind.config.js
const colors = require('tailwindcss/colors');

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: colors.blue,      // Use Tailwind's blue scale
        secondary: colors.gray,
        accent: colors.rose,
      },
    },
  },
}

Method 3: Single Color (Simplified)

If you only need one shade:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',  // Single color, no scale
      },
    },
  },
}

Use with: bg-brand, text-brand, etc.

Complete Brand Color System

A professional setup with semantic naming:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        // Brand colors
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          900: '#1e3a8a',
        },
        
        // Semantic colors
        success: {
          light: '#d1fae5',
          DEFAULT: '#10b981',
          dark: '#065f46',
        },
        
        error: {
          light: '#fee2e2',
          DEFAULT: '#ef4444',
          dark: '#991b1b',
        },
        
        warning: {
          light: '#fef3c7',
          DEFAULT: '#f59e0b',
          dark: '#92400e',
        },
      },
    },
  },
}

Using with theme()

Access your custom colors in CSS or other config values:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
      },
      // Use in other theme values
      borderColor: theme => ({
        DEFAULT: theme('colors.primary'),
      }),
    },
  },
}

Or in CSS with @apply:

/* In your CSS */
.custom-button {
  @apply bg-primary hover:bg-primary/90 text-white;
}

Configuration Best Practices

1. Use Semantic Names

Name colors by purpose, not appearance:

Good: primary, secondary, accent
Bad: blue, lightBlue, darkBlue

2. Keep DEFAULT Shade

Always define a DEFAULT shade for simple class names:

colors: {
  brand: {
    DEFAULT: '#3b82f6',  // Allows bg-brand instead of bg-brand-500
    light: '#dbeafe',
    dark: '#1e40af',
  },
}

3. Document Your System

Add comments explaining color usage:

colors: {
  primary: '#3b82f6',    // Primary CTAs, links
  secondary: '#6b7280',  // Secondary buttons, muted text
  accent: '#f59e0b',     // Highlights, notifications
}

Opacity Modifiers

Tailwind v3+ supports opacity modifiers out of the box:

50% opacity
75% opacity
25% opacity

Dark Mode Colors

Define different colors for dark mode:

Text that adapts

Or configure globally:

// tailwind.config.js
module.exports = {
  darkMode: 'class', // or 'media'
  theme: {
    extend: {
      colors: {
        background: {
          light: '#ffffff',
          dark: '#0f0f0f',
        },
      },
    },
  },
}

Plugin Recommendations

1. @tailwindcss/forms

Better form styling that respects custom colors:

npm install @tailwindcss/forms

// tailwind.config.js
plugins: [
  require('@tailwindcss/forms'),
]

2. tailwindcss-animate

Smooth animations using your custom colors:

npm install tailwindcss-animate

// tailwind.config.js
plugins: [
  require('tailwindcss-animate'),
]

Exporting for Design Tools

Share your Tailwind colors with designers:

For Figma

Use Tailwind CSS Figma Plugin
Several community plugins can turn a Tailwind color config into Figma color styles or variables
Check that the plugin you choose supports your Tailwind version

For Adobe tools

Adobe XD is in maintenance mode. For Illustrator, Photoshop or InDesign, export your palette as an .ASE swatch file (every palette on our palette pages has an .ASE button) and load it into the Swatches panel.

Real Project Example

Here's a complete, production-ready configuration:

// tailwind.config.js
const colors = require('tailwindcss/colors');

module.exports = {
  darkMode: 'class',
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {
      colors: {
        // Brand identity
        brand: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
        
        // Semantic UI colors
        primary: colors.blue,
        secondary: colors.slate,
        success: colors.emerald,
        warning: colors.amber,
        danger: colors.red,
        
        // Backgrounds
        background: {
          DEFAULT: '#ffffff',
          secondary: '#f9fafb',
          dark: {
            DEFAULT: '#0f0f0f',
            secondary: '#1a1a1a',
          },
        },
        
        // Text
        foreground: {
          DEFAULT: '#1a1a1a',
          secondary: '#6b7280',
          dark: {
            DEFAULT: '#ffffff',
            secondary: '#a1a1aa',
          },
        },
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('tailwindcss-animate'),
  ],
}

Testing Your Colors

Contrast Check: Test all text/background combinations for WCAG compliance
Dark Mode: Verify colors work in both light and dark themes
Color Blind: Use simulators to test accessibility
Print Styles: Ensure colors translate to @media print

Common Mistakes

1. Replacing Instead of Extending

Don't do this (loses all default colors):

// ❌ BAD - Overwrites all colors
module.exports = {
  theme: {
    colors: {
      brand: '#3b82f6',  // Now bg-white doesn't work!
    },
  },
}

Do this instead:

// ✅ GOOD - Keeps defaults, adds yours
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
}

2. Incomplete Scales

Utilities are only generated for the shades you define, so a missing shade simply has no class (bg-brand-300 won't exist). Define a full 50-950 scale if your team expects every step to be available.

3. Poor Naming

Avoid names tied to specific colors—they become confusing when you rebrand.

Conclusion

Custom colors in Tailwind are straightforward once you understand the config structure. Use extending (not replacing), maintain complete shade scales, choose semantic names, and document your system. With these practices, your Tailwind colors will be maintainable, scalable, and designer-friendly.