Tailwind Custom Colors: v3 and v4 Guide
2026-09-14 · zhoujingkang · Founder
Tailwind v3 and v4 expose different configuration paths, but the design-system goal is the same: register stable semantic color roles and keep their values accessible to components.
Tailwind v3
Use `theme.extend.colors` in tailwind.config.js so your additions sit beside the default palette. A generated 50–950 scale gives hover, border and surface states more control than opacity hacks.
Tailwind v4
Use CSS variables inside an `@theme` block. This keeps the theme close to CSS and makes the values visible in DevTools. The Tailwind theme documentation is the source of truth for the current syntax.
Keep the roles semantic
Prefer `bg-surface`, `text-muted` and `bg-primary` over names like `bg-light-blue`. Then a light/dark switch changes values, not component class names. Generate and preview both modes with the Tailwind color generator.
Continue with a tool
References
FAQ
Should I use Tailwind v3 or v4 configuration?
Use the format matching your project. v3 uses theme.extend.colors; v4 uses CSS variables in @theme.
Why generate a full scale?
A scale supplies deliberate values for hover, active, border and surface states instead of relying on unpredictable opacity blending.
Try it on your own brand color
Paste one hex into the Brand Theme Engine and get a full light & dark web theme — semantic tokens, contrast-checked, export-ready.
Open the Brand Theme Engine →