Color & Design·4 min read

Extending Tailwind Colors: Custom Scales Done Right

Rebrands rarely fail at the logo stage. They fail three weeks later, when the new brand color needs to become bg-brand-500 across four hundred components and nobody planned the scale around it. Adding a brand color to Tailwind properly means arriving with a full ramp, sensible step names, and contrast already verified, instead of pasting one hex and improvising the other ten shades during code review. This is the config half of a rebrand, and it's very doable in an afternoon if you sequence it right.

Open the free Tailwind Color Palette All insights

The rebrand your Tailwind setup wasn't ready for

One hex is not a design system.

Picture the standard sequence: the founders approve a new violet, marketing ships the announcement, and engineering opens the Tailwind config to find the old palette hard-coded in eleven places. The brand team delivered exactly one hex code. Tailwind, meanwhile, thinks in scales of eleven, and every existing component references steps like 100 for washes, 500 for fills, and 700 for hover.

The gap between one hex and eleven steps is where rebrand delays actually live. Close it before touching the config: generate the full ramp from the approved color first, then the config change becomes a five-minute paste instead of a week of threads about whether the new hover looks right.

Extending Tailwind colors without losing the defaults

Extend, don't replace.

In Tailwind v3 you have two places to put a custom scale: theme.colors, which replaces the entire default palette, and theme.extend.colors, which adds yours alongside it. For a rebrand, extend is almost always correct. Your gray text, red error states, and green success badges probably still use stock hues, and replacing the palette wholesale breaks all of them at once. In Tailwind v4 the same idea lives in CSS: you add --color-brand-500 and friends inside an @theme block, and the defaults stay unless you clear them.

Step names deserve one deliberate decision: keep the numeric convention. A scale named brand with steps 50 through 950 behaves exactly like the built-ins, so bg-brand-500 and hover:bg-brand-600 read as native Tailwind to anyone who joins the team. Semantic names like brand-light and brand-dark feel friendly for a week, then fail the first time you need a step between them.

A worked Tailwind scale for the new brand

Real values, drop-in shape.

Suppose the approved brand color is #6366F1. Tailwind's own indigo scale is anchored on that exact hex, which makes it an honest worked example. The extend block looks like this: brand: { 50: "#EEF2FF", 100: "#E0E7FF", 300: "#A5B4FC", 500: "#6366F1", 600: "#4F46E5", 700: "#4338CA", 900: "#312E81" }, and components immediately gain bg-brand-50 card washes, bg-brand-500 buttons, and hover:bg-brand-600 states.

Notice the shape of that scale: 50 is a near-white wash, the jump from 500 to 600 is big enough to register as a hover but small enough to stay on-brand, and 900 is dark enough for text on the 50. When your brand color isn't a stock Tailwind hue, the generator at the top of the Tailwind Color Palette page builds the same 50 to 950 shape from your hex, following the lightness curve of the default palette in OKLCH, and exports it as a v3 config object or a v4 @theme block.

Before generating anything, paste your brand hex into the Tailwind Color Palette's finder. It lists the three closest default colors with a Delta E score each. If the nearest one is very close, using the stock scale may be simpler than maintaining a custom one. The hex values shown are Tailwind v3's; v4 defines its default palette in OKLCH, so v4 colors can look slightly different.

Tailwind config mistakes that surface months later

Cheap now, expensive later.

These four show up in almost every inherited config.

Defining brand as a single value instead of a scale. The first developer who needs a hover state will hand-pick a darker hex inline, and drift begins.
Skipping steps you don't need yet. A scale with only 500 and 700 forces the eventual 100 and 300 to be invented under deadline, by whoever is around.
Overwriting a default hue with brand values. Redefining blue to be your violet means every tutorial snippet and copied component renders wrong.
Never checking which steps carry white text. White on indigo-500, #6366F1, measures 4.47:1, just under the 4.5:1 AA line for body text, while 600 clears it comfortably. If your brand-500 fails the same way, every primary button fails with it.

Habits that keep a Tailwind config maintainable

Two rules from teams that rebrand cleanly.

Add a one-line comment above the scale recording where the values came from: the source hex, the tool, and the date. Six months on, when someone asks whether brand-400 can be nudged, that comment answers whether the scale was generated systematically or eyeballed, which decides whether one step can change or the whole ramp must be rebuilt.

Keep the old scale in the config, renamed to something like legacy, for one release cycle. A rebrand always misses a marketing page or an email template, and grepping for bg-legacy-500 finds stragglers far faster than visually diffing screenshots ever will.

Tailwind Color Palette alongside the other palette tools

The reference, the generator, the gate.

The Tailwind Color Palette covers the reference layer and the generation layer on one page: all 22 default colors with shades 50 to 950, copyable as hex, class name, RGB or OKLCH, the nearest-color finder, and a generator that turns the single approved brand hex into the full ramp your config needs. The Color Shades Generator is the alternative when you want an even LAB ramp with your color fixed at 500.

Before any step ships, the Color Contrast Checker is the gate, confirming which positions can carry white or black text. And if your product also maintains an Android presence, the Material Design Color Palette holds the parallel palette world your mobile team is probably matching against.