Adding Custom Colors
Define brand colors as CSS variables or hex values in the config, extend the palette with custom shades, and use them with any color utility.
Adding Custom Colors is a free Tailwind CSS Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Tailwind CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Custom Colors Matter
Every real-world project has a brand identity with specific colors that do not exist in Tailwind's default palette. Adding your brand colors to Tailwind's config unlocks the full utility class API for those colors — you can use them with bg-*, text-*, border-*, ring-*, shadow-*, and every other color utility. Your custom colors also work with opacity modifiers and dark mode variants automatically.
Adding a Simple Custom Color
The simplest way to add a custom color is to provide a single hex value with a key name in theme.extend.colors. Tailwind generates a utility class for that exact color. The key becomes part of the class name: a key of brand creates bg-brand, text-brand, border-brand, etc. Single-value colors do not support shade suffixes like brand-500.
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
brand: '#6366f1',
accent: '#f59e0b',
danger: '#ef4444',
},
},
},
};
<!-- Usage -->
<div class="bg-brand text-white">Brand background</div>
<span class="text-accent font-semibold">Accent text</span>Adding a Full Shade Scale
For colors that need variation — lighter and darker versions for hover states, backgrounds, and text — define a full shade scale as a nested object. Use the standard Tailwind shade numbers (50, 100, 200, ... 900, 950). This unlocks utilities like bg-brand-100 for subtle backgrounds, bg-brand-500 for the main color, and bg-brand-900 for dark accents.
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
brand: {
50: '#eef2ff',
100: '#e0e7ff',
200: '#c7d2fe',
300: '#a5b4fc',
400: '#818cf8',
500: '#6366f1',
600: '#4f46e5',
700: '#4338ca',
800: '#3730a3',
900: '#312e81',
950: '#1e1b4b',
},
},
},
},
};Generating Color Shades Automatically
Manually writing ten hex values for every brand color is tedious. Tools like uicolors.app, palettte.app, or the Tailwind team's online color shades generator take a single base color and produce a full 50-950 scale with perceptually even gradations. Many design tools like Figma also have plugins that export color palettes directly in Tailwind config format.
// Generated from uicolors.app or similar tool
// Base color: #6366f1 (indigo brand)
colors: {
brand: {
'50': '#eef2ff',
'100': '#e0e7ff',
'200': '#c7d2fe',
'300': '#a5b4fc',
'400': '#818cf8',
'500': '#6366f1',
'600': '#4f46e5',
'700': '#4338ca',
'800': '#3730a3',
'900': '#312e81',
'950': '#1e1b4b'
}
}The DEFAULT Key
Inside a color scale object, you can add a DEFAULT key to set the bare utility class (without a shade number) to a specific shade. For example, setting DEFAULT: '#6366f1' means bg-brand renders as the 500 shade. This is useful when your design uses a specific primary shade most often and you want a short class name for it without giving up the full scale.
// tailwind.config.js
colors: {
brand: {
DEFAULT: '#6366f1', // bg-brand = #6366f1 (same as brand-500)
light: '#818cf8', // bg-brand-light
dark: '#4338ca', // bg-brand-dark
50: '#eef2ff', // bg-brand-50
500: '#6366f1', // bg-brand-500 (same as DEFAULT)
900: '#312e81', // bg-brand-900
},
}Using CSS Variables for Colors
For colors that change at runtime — like theme colors toggled by user preference — define them as CSS custom properties and reference those variables in your Tailwind config. Use the <alpha-value> placeholder to enable opacity modifier support (bg-brand/50). This pattern is the foundation of multi-theme design systems built on Tailwind.
/* In your CSS */
:root {
--color-brand: 99 102 241; /* RGB values for opacity support */
}
/* tailwind.config.js */
module.exports = {
theme: {
extend: {
colors: {
brand: 'rgb(var(--color-brand) / <alpha-value>)',
},
},
},
};
<!-- Now bg-brand/50 works correctly -->
<div class="bg-brand/50">50% opacity brand background</div>Referencing Tailwind's Default Colors
Sometimes you want to rename or alias existing Tailwind colors — for example, using primary as an alias for indigo so your components stay brand-agnostic. Import Tailwind's color object and use it in your config to reference any built-in color by name. This keeps your palette DRY: change the alias once to update all component classes that use primary.
const colors = require('tailwindcss/colors');
module.exports = {
theme: {
extend: {
colors: {
primary: colors.indigo, // bg-primary-500 = bg-indigo-500
secondary: colors.violet, // bg-secondary-500 = bg-violet-500
neutral: colors.slate, // text-neutral-700 = text-slate-700
},
},
},
};Semantic Color Naming
Instead of naming colors by their hue (indigo, violet), name them by their semantic role in your design (primary, secondary, success, warning, error). Semantic naming makes your components resilient to rebrand: if the brand color changes from indigo to teal, you update one config entry and all components automatically reflect the change.
// Semantic color system
module.exports = {
theme: {
extend: {
colors: {
primary: { 50: '#eef2ff', 500: '#6366f1', 900: '#312e81' },
secondary: { 50: '#f5f3ff', 500: '#8b5cf6', 900: '#2e1065' },
success: { 50: '#f0fdf4', 500: '#22c55e', 900: '#052e16' },
warning: { 50: '#fffbeb', 500: '#f59e0b', 900: '#451a03' },
error: { 50: '#fef2f2', 500: '#ef4444', 900: '#450a0a' },
},
},
},
};Using Custom Colors in Dark Mode
Custom colors work with dark mode variants the same way as built-in colors. Pair light-shade custom colors for light mode with dark-shade variants for dark mode. If you are using CSS variables for your colors, you can change the variable value in the .dark selector and all utilities that reference the variable update automatically — no extra dark: classes needed.
<!-- Custom color with dark mode -->
<div class="bg-brand-50 dark:bg-brand-950 text-brand-900 dark:text-brand-100 p-6 rounded-xl">
<h2 class="text-brand-700 dark:text-brand-300 font-bold">Brand Card</h2>
<p class="text-brand-600 dark:text-brand-400">Content that adapts to dark mode</p>
</div>Opacity Modifier with Custom Colors
Custom colors defined as hex values also support Tailwind's opacity modifier syntax (bg-brand-500/75) when Tailwind can convert the hex to an RGB representation. Colors defined as CSS variables with the <alpha-value> placeholder work even better, giving you precise control over opacity at every use site without needing separate utility classes.
<!-- Opacity modifier with custom hex colors -->
<div class="bg-brand-500/20 border border-brand-500/30 text-brand-700">
Subtle brand-tinted background
</div>
<div class="shadow-brand-500/50 shadow-xl">
Brand-colored shadow
</div>
<button class="bg-brand-600 hover:bg-brand-600/90 text-white px-4 py-2 rounded-lg">
Slightly transparent on hover
</button>Testing Custom Colors in HTML
After adding custom colors to your config, verify they work by running Tailwind's build and using the classes in your HTML. Check both the generated CSS file (your classes should appear) and the visual output in the browser. Also test dark mode variants, opacity modifiers, and hover states to ensure the full suite of derivative utilities works correctly with your custom colors.
<!-- Test all derivative utilities work -->
<div class="p-4 space-y-2">
<div class="bg-brand-100 text-brand-900 p-2 rounded">bg-brand-100</div>
<div class="bg-brand-500 text-white p-2 rounded">bg-brand-500</div>
<div class="bg-brand-900 text-brand-100 p-2 rounded">bg-brand-900</div>
<div class="bg-brand-500/50 text-brand-900 p-2 rounded">bg-brand-500/50 (opacity)</div>
<div class="border-2 border-brand-500 text-brand-700 p-2 rounded">border-brand-500</div>
</div>Quick Check
Test your understanding of adding custom colors to Tailwind CSS.
Lesson Recap
In this lesson you learned: add custom colors in theme.extend.colors as single hex values or full shade scales, use semantic names like primary and error instead of hue names for resilient design, and define colors as CSS variables with <alpha-value> for opacity modifier support. Next up we add custom font families from Google Fonts and local sources.
Frequently asked questions
Is the “Adding Custom Colors” lesson free?
Yes — the full text of “Adding Custom Colors” is free to read here on the web, and the Tailwind CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Tailwind CSS Academy course, upgrade to CoddyKit PRO.
What will I learn in “Adding Custom Colors”?
Define brand colors as CSS variables or hex values in the config, extend the palette with custom shades, and use them with any color utility. You practise Tailwind CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Tailwind CSS Academy?
No prior experience is required. Tailwind CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Adding Custom Colors” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Tailwind CSS Academy lesson?
Yes. Every Tailwind CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Adding Custom Colors
- Custom Font Families
- Custom Spacing Values
- Using CSS Variables in Tailwind