Deep Customization with tailwind.config.js

While the default design token variables in Tailwind CSS cover most projects, you will eventually need to customize the configuration to match a corporate brand guide or custom design sheets.

1. The Configuration File Structure

The tailwind.config.js file is the central control room for your project styling system. It typically looks like this:

module.exports = {
  content: ["./src/**/*.{html,js,ts,jsx,tsx,astro}"],
  theme: {
    // Override the default system settings here
    colors: {
      black: "#000",
      white: "#fff",
    },
    extend: {
      // Add custom styles without losing default styles here
    },
  },
  plugins: [],
}

2. Override vs Extend

A common mistake is placing custom styles directly inside the theme: object. Doing so wipes out all default configurations for that attribute.

Example: Overriding Colors

If you define theme.colors, Tailwind disables gray, red, blue, and all other default color names:

// Overrides color definitions entirely
theme: {
  colors: {
    brand: "#1a73e8",
  }
}

Example: Extending Colors (Recommended)

To append new options while keeping the default Tailwind color scale, place your additions inside the extend: block:

theme: {
  extend: {
    colors: {
      brand: {
        50: "#e8f0fe",
        500: "#1a73e8",
        900: "#174ea6",
      }
    }
  }
}

This registers classes like bg-brand-50 and text-brand-900 alongside existing defaults (such as bg-red-500).

3. Extending Font Families and Spacing

You can customize font files and spacing values in the same way:

theme: {
  extend: {
    fontFamily: {
      sans: ["Inter", "sans-serif"],
      display: ["Oswald", "sans-serif"],
    },
    spacing: {
      // Registers custom margin / padding increments (e.g. h-128)
      "128": "32rem", // 512px
    }
  }
}