Tailwind Config Customization Without Losing Defaults

The Tailwind docs show a colors config object and developers assume that means 'replace the palette.' It does not. If you write theme.colors, you wipe out slate, red, green, every default. The right key is theme.extend.colors, and the difference matters.

The Mistake

// tailwind.config.js - WRONG
module.exports = {
  theme: {
    colors: {
      brand: '#3b82f6',
    },
  },
}
// Now bg-red-500, text-slate-700, border-gray-200 all fail

Every default color class breaks. The fix is one word.

The Fix

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
}
// bg-brand works. bg-red-500 still works. Everyone wins.

The extend key merges your additions into the defaults. Without extend, your keys replace the defaults. This applies to every theme property: spacing, fontSize, breakpoints, animations.

The Broader Pattern

Tailwind is a decision framework, not just a CSS library. The config is the design system. If I want five brand colors with shades, I define them once in config and use them everywhere as brand-50 through brand-900. The tool enforces the system because it only ships what you configured.

Arbitrary Values As Escape Hatch

Sometimes you need a value that is not in the system. Tailwind's arbitrary value syntax (bg-[#ff5733]) is the escape hatch. Use it rarely. If you find yourself using it often, that value belongs in the config.

See the Tailwind theme configuration docs. Treat the config as the source of truth for your design decisions. Your CSS will be smaller and your designs more consistent.