Every project I’ve started with a designer’s brand color has had the same moment: Tailwind wants brand-50 through brand-950, and I have one hex code. The first time, I made the other ten by nudging HSL lightness up and down. The light shades came out chalky, the dark ones muddy, and brand-300 and brand-400 looked almost the same.
This guide explains why that happens and how the Tailwind shade generator avoids it.
Why HSL makes bad scales
HSL’s “lightness” isn’t how light a color looks. Yellow at 50% HSL lightness is blinding, while blue at 50% is quite dark. So if you step HSL lightness evenly, each hue gets a different-looking scale, and neighbouring steps can look nearly identical in one part of the range and far apart in another.
OKLCH fixes this. Its L channel is designed to match perceived lightness, so two colors with the same L look equally light regardless of hue. Tailwind v4 moved its entire default palette to OKLCH for this reason, and its @theme values are written as oklch().
How the generator builds the scale
I measured Tailwind v4’s seventeen chromatic palettes (red through rose) and took the median lightness and chroma at each step. The generator then:
- converts your color to OKLCH and keeps its hue,
- follows that median lightness curve (≈ 0.977 at 50 down to ≈ 0.279 at 950),
- tapers chroma toward both ends (light tints and deep shades are less saturated than the middle, as in Tailwind’s own palettes), and
- gamut-maps every shade into sRGB by reducing chroma only, so lightness and hue are preserved and nothing clips.
Grays follow Tailwind’s neutral curve instead and get no added hue.
Where does your color go?
This is the decision most generators hide. If your brand color is dark, forcing it to be the 500 squeezes the dark half of the scale and stretches the light half. By default the generator puts your color at the step whose lightness it’s closest to.
As a test, I gave it #0d9488 — which happens to be Tailwind v3’s teal-600. It came back as brand-600, exactly where Tailwind has it:
@theme {
--color-brand-50: oklch(97.7% 0.008 184.704);
--color-brand-100: oklch(95.2% 0.016 184.704);
--color-brand-200: oklch(90.4% 0.036 184.704);
--color-brand-300: oklch(83.6% 0.063 184.704);
--color-brand-400: oklch(75.1% 0.09 184.704);
--color-brand-500: oklch(69.1% 0.105 184.704);
--color-brand-600: oklch(60% 0.104 184.704);
--color-brand-700: oklch(52% 0.091 184.704);
--color-brand-800: oklch(45.2% 0.076 184.704);
--color-brand-900: oklch(39.9% 0.06 184.704);
--color-brand-950: oklch(27.9% 0.041 184.704);
}
If your design system says “the brand color is 500, full stop”, choose “As 500”. The scale is then stretched around your color, and the tool returns your exact hex at 500. It will warn you if that makes some neighbouring shades too close to tell apart — which happens with very light or very dark brand colors.
Using it in Tailwind v4
Paste the @theme block into your main CSS file, after the import:
@import "tailwindcss";
@theme {
--color-brand-500: oklch(69.1% 0.105 184.704);
/* …the rest of the scale… */
}
Tailwind generates bg-brand-500, text-brand-700, border-brand-200 and so on from those variables, and the variables are also available at runtime as var(--color-brand-500). If you need hex values (for an email template, or a tool that doesn’t understand oklch()), switch the output to hex.
Using it in Tailwind v3
v3 wants a config object with hex values. With #0d9488 pinned as 500:
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
brand: {
50: '#f2f9f8',
100: '#e1f0ed',
200: '#bfe0da',
300: '#8dc8c0',
400: '#4eaa9f',
500: '#0d9488',
600: '#007d72',
700: '#006960',
800: '#005850',
900: '#0d4a44',
950: '#0c2f2b',
DEFAULT: '#0d9488',
},
},
},
},
};
DEFAULT lets you write plain bg-brand. The generator can also output CSS custom properties, an SCSS map, or JSON for design tokens.
Check the text colors
A nice-looking scale can still fail accessibility. Each swatch in the generator shows its contrast ratio with white and black text. For the teal scale above, white text first reaches 4.5:1 (WCAG AA for body text) at 700 — brand-600 is only 3.74:1 with white, so white body text on a teal-600 button fails AA. That’s worth knowing before a designer’s mockup ships.
For pairs that aren’t white or black, the contrast checker tests any two colors and suggests a fix. And if you need the brand color in another format first, the color converter converts between hex, RGB, HSL and OKLCH.