How to Add Brand Colors to Tailwind CSS (v3 & v4)

How do I add brand colors in Tailwind v3?

v3 keeps theme configuration in JavaScript. Register your scale under theme.extend.colors so the defaults survive alongside your additions:

• Open tailwind.config.js.
• Add a brand object under theme.extend.colors with your shade keys: 50 through 950.
• Use the colors as bg-brand-500, text-brand-700, border-brand-200 — every utility picks them up automatically.

How do I add brand colors in Tailwind v4?

v4 moved configuration into CSS. There is no tailwind.config.js by default; instead you declare custom properties inside @theme, and Tailwind generates the matching utilities:

• In your global stylesheet, add @theme { --color-brand-500: #0b63f6; ... }.
• Every --color-* variable becomes a utility: bg-brand-500 works exactly as in v3.
• The rest of the default palette is still available — you are adding to it, not replacing it.

What changed between v3 and v4 — and why should you care?

Two changes matter for brand colors. First, the config format: v4 reads theme values from CSS variables, which means your brand colors are plain CSS — visible in DevTools, overridable per component, and friendly to techniques like color-mix().

Second, the default palette itself was recalculated in OKLCH, a perceptual color space. Named colors kept their identity but shifted slightly: red-500, for example, moved from #ef4444 in v3 to #fb2c36 in v4. The new scale steps more evenly in perceived lightness, which makes opacity and color-mix results more predictable. If you migrate a project, re-check contrast afterwards — your old ratios no longer describe the shipped values.

How do I generate a full 50–950 brand scale?

Registering one hex is easy; inventing ten harmonious neighbors is not. Scales need perceptually even lightness steps, a 500 that actually matches your brand color, and tints that stay on-hue instead of drifting gray.

The fastest route: open the Tailwind color generator on ColorwayKit, paste your hex, and it produces the full ramp with live UI previews and contrast annotations. The code panel outputs a ready-to-paste tailwind.config.js (v3) or @theme block (v4), switchable with one click, so both versions of your team stay unblocked.

Should I write hex or OKLCH values in my config?

Tailwind accepts any valid CSS color. Hex is the safest interchange format — every tool, browser and designer understands it. OKLCH is worth considering when you want perceptually uniform manipulation in CSS itself (lightness tweaks via oklch() without a design tool round-trip) or plan to support wide-gamut displays where P3 colors outperform sRGB.

Pragmatic rule: store hex in your config, and reach for OKLCH when you are deriving new values or fine-tuning lightness. ColorwayKit shows both formats side by side, so you can copy whichever your project prefers.

Common mistakes when registering brand colors

The config syntax is easy; the mistakes around it are predictable. Knowing them in advance saves a refactor:

• Overriding a default family (colors: { red: {...} }) instead of extending — every red utility across the site changes, including errors and badges you never touched.
• Registering only brand-500 and faking hover states with opacity-90 — opacity blends with whatever is behind the element, so the same button looks different on every surface.
• Naming colors after their look (light-blue) instead of their role (brand, surface) — the name stops being true the first time you rebrand.
• Forgetting that v4 needs @theme inside a file that already imports tailwindcss, then concluding that utilities were "removed".

How do I keep light and dark modes consistent?

Register both variants side by side. In v3, use the dark: variant of the same utility (bg-brand-500 dark:bg-brand-400) so the pairing is visible in one line of markup. In v4, prefer semantic variables — define --color-surface differently per mode in plain CSS, and components never branch on theme at all.

Whichever version you use, generate the dark-mode ramp from the same engine run rather than eyeballing it: the tints that feel right on white rarely survive translation to near-black, and contrast failures hide there first. The Tailwind color generator on this site previews both modes before you copy a single line.

Checklist before you ship

A quick pass before your brand colors reach production:

• Your 500 step visually matches the logo color (not just numerically close).
• Body text on your brand surface passes 4.5:1 (WCAG AA) and APCA Lc 75+.
• White text on brand-500 passes contrast — if not, define the pairing with brand-600/700.
• Dark mode re-maps roles rather than inverting; the accent should stay recognizable.
• Focus rings and disabled states use ramp steps, not opacity hacks on text colors.

FAQ