How to Use Hex Colors in Tailwind CSS

You can use hex colors in Tailwind by adding them to your tailwind.config.js file under the theme.extend.colors object. This lets you reference colors by name, like bg-brand-500, instead of hardcoding hex values in your HTML classes.

Why Hardcoding Hex Codes Fails

Writing bg-[#4F46E5] directly in your markup works for a quick prototype, but it creates maintenance debt. If you need to adjust the shade slightly for better readability or brand consistency, you must find and replace every instance across your codebase. This approach also bypasses Tailwind’s utility-first philosophy, which relies on consistent, named tokens to keep design systems coherent.

While Tailwind v3+ supports opacity modifiers with arbitrary values (e.g., bg-[#ff0000]/50), relying on them everywhere makes your HTML noisy and hard to scan. Named tokens keep your markup clean. Furthermore, while you can use the dark: variant with arbitrary values (e.g., dark:text-[#000]), managing multiple arbitrary hex codes for light and dark modes quickly becomes unmanageable without a centralized config.

Generating a Brand-Safe Palette

Start with your primary brand color, such as #4F46E5. Instead of manually guessing lighter and darker shades, generate a scale that maintains perceptual consistency. You need a range of values from 50 to 900 to cover backgrounds, borders, and text.

When generating these variations, ensure the hue remains stable while lightness and saturation adjust. If you simply multiply or divide the RGB values, the color may drift toward yellow or blue as it gets lighter or darker. A proper scale keeps the "indigo" character intact across all steps.

For our worked example, we will create a 5-step scale (50, 100, 500, 700, 900) derived from #4F46E5. The base color #4F46E5 becomes the 500 step. The 50 and 100 steps are significantly lighter for backgrounds, while 700 and 900 are darker for hover states and text.

Verifying WCAG Contrast Before Coding

Before committing these hex codes to your config, check their accessibility. You need to ensure that text using these colors meets WCAG AA standards when placed on a white (#FFFFFF) or black (#111827) background.

For our indigo scale, we test the 500 and 700 steps against white. The 500 step (#4F46E5) has a contrast ratio of approximately 6.3:1 against white, which passes WCAG AA for both normal text (4.5:1) and large text (3:1). The 700 step (#3730A3) is darker and provides even higher contrast for normal text.

In our example, let’s assume the generated scale yields these values:

• 500: #4F46E5 (Passes AA for normal and large text on white)
• 700: #3730A3 (Passes AAA for normal text on white)

If you were using a lighter brand color that failed AA for normal text, you would use the darker 700 step for body text and keep the 500 step for buttons or large headings.

Exporting to Tailwind Config

Once you have verified your hex values, add them to your tailwind.config.js. You should nest them under a custom key, such as brand, to avoid overwriting Tailwind’s default colors.

Here is the exact config object for our worked example. Note the structure: theme.extend.colors.brand contains the scale.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{html,js}"],
  theme: {
    extend: {
      colors: {
        brand: {
          50: "#EEF2FF",
          100: "#E0E7FF",
          500: "#4F46E5",
          700: "#3730A3",
          900: "#1E1B4B",
        },
      },
    },
  },
  plugins: [],
}

You can generate harmonized palettes and copy a ready-to-paste Tailwind config using ColorWell. It checks contrast within the generated palette and outputs the config block, saving you from manual calculation and verification.

Using Named Tokens in Your Components

With the config updated, you can now use semantic class names. Instead of bg-[#4F46E5], you use bg-brand-500. This makes your HTML readable and maintainable.

Consider a button component. You want the background to be the brand primary, with white text. On hover, it should darken to the 700 step.

<button class="bg-brand-500 text-white hover:bg-brand-700 px-4 py-2 rounded-md">
  Click Me
</button>

You can also apply opacity modifiers. If you need a subtle background for a card, use the 50 step with transparency:

<div class="bg-brand-50/50 border border-brand-100 p-4">
  <h3 class="text-brand-900">Card Title</h3>
  <p class="text-brand-700">This text is accessible on the light background.</p>
</div>

This approach ensures that if you ever need to shift the entire brand palette, you only update the hex values in tailwind.config.js. Every component using bg-brand-500 will automatically reflect the change.

Common Pitfalls with Custom Colors

One frequent mistake is placing custom colors outside the extend object. If you put colors directly under theme, you overwrite Tailwind’s default palette, losing access to standard grays, blues, and reds. Always use theme.extend.colors.

Another issue is naming collisions. Avoid using names like primary or secondary if you plan to have multiple themes. Instead, use descriptive names like brand, accent, or surface. This clarity helps when you introduce dark mode variants later.

Finally, remember that Tailwind does not automatically generate shades for custom colors. You must define every step you intend to use. If you only define 500 and 700, using bg-brand-100 will result in no background color being applied. Define the full range you need, even if you don’t use every step immediately.