Gotcha: Extending vs. Overriding Default Colors

A common pitfall when defining custom colors is accidentally overriding Tailwind's entire default color palette instead of extending it.

The Gotcha!

If you define your custom colors directly under theme.colors in your tailwind.config.js , you will lose access to all of Tailwind's built-in colors (like bg-blue-500 , text-green-600 , etc.). 

// INCORRECT - This replaces all default colors:
module.exports = {
  theme: {
    colors: { // <--- Problem: Directly under 'colors'
      'brand-primary': '#FF00FF',
    }
  },
  // ...
}

The Correct Way: Using extend

To add your custom colors while keeping the defaults, define them under theme.extend.colors . 

// CORRECT - This adds 'brand-primary' and keeps defaults:
module.exports = {
  theme: {
    extend: { // <--- Correct: Using 'extend'
      colors: {
        'brand-primary': '#FF00FF', // Your custom magenta
        'brand-secondary': '#00FFFF', // Your custom cyan
      },
    },
  },
  // ...
}

Demonstration:

Below, we simulate how this works. Since we are using the CDN, default Tailwind colors will always work. However, the comments explain what would happen with a local Tailwind setup and incorrect configuration.

This uses a default Tailwind color: bg-sky-500 .

If you had incorrectly overridden theme.colors (without extend ), this bg-sky-500 class might not apply the blue background, or it might not work at all, as 'sky' would no longer be a defined color. With theme.extend.colors , it works perfectly alongside your custom colors.

This uses a simulated custom color: bg-[#FF00FF] (e.g., 'brand-primary').

This custom color would be available whether you used theme.colors or theme.extend.colors . The key difference is what happens to the default palette.

Key Takeaway: Always use theme.extend.colors to add your brand colors unless you have a very specific reason to replace the entire default palette. This ensures you retain access to Tailwind's rich set of predefined colors.