Chapter 12: Colors

Core Idea

Tailwind ships a large default color palette (over 20 color scales × 11 shades each, defined in OKLCH) that's available across every color-related utility (bg-*, text-*, border-*, fill-*, ring-*, etc.); colors are customized, extended, or replaced entirely the same way as any other theme value, via @theme.

Key Concepts

• Shade scale: each color scale has 11 steps, 50 (lightest) → 950 (darkest), e.g. bg-sky-50 … bg-sky-950.
• Utilities that consume the palette: bg-* (background), text-* (text color), decoration-* (text-decoration color), border-*, outline-*, shadow-*/inset-shadow-* (shadow color), ring-*/inset-ring-* (ring color), accent-*, caret-*, scrollbar-thumb-*/scrollbar-track-*, fill-*/stroke-* (SVG) — the same color token works across all of them.
• Opacity modifier: bg-black/75 sets alpha to 75% via a trailing /<value>; supports arbitrary precision (bg-pink-500/[71.37%]) and a CSS-variable alpha (bg-cyan-400/(--my-alpha-value)).
• Dark mode: colors follow the normal dark: variant, e.g. dark:bg-gray-800 (see Dark Mode chapter).
• Referencing colors in CSS: every color is a --color-* CSS variable (var(--color-blue-500)); the --alpha() function adjusts a referenced color's opacity in hand-written CSS (--alpha(var(--color-gray-950) / 10%)), and colors work inside arbitrary values too (bg-[light-dark(var(--color-white),var(--color-gray-950))]).
• Adding custom colors: define new --color-* tokens in @theme (--color-midnight: #121063;) — this immediately makes bg-midnight, text-midnight, fill-midnight, etc. available.
• Overriding a default color: redefine the same --color-<name>-<shade> variables in @theme — the new values replace the built-in ones project-wide.
• Disabling specific colors: --color-lime-*: initial; removes just that scale (and its generated CSS variables/utilities) — useful for trimming unused output.
• Fully custom palette: --color-*: initial; wipes every default color, then define your own tokens from scratch under @theme.
• Colors that reference other variables: use @theme inline (not plain @theme) when a color's value is itself var(...) pointing at another custom property (e.g. a [data-theme="dark"]-swapped brand variable) — this ensures Tailwind resolves it correctly instead of the reference becoming stale.
• Default palette structure: ~22 color families (red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, plus neutrals slate/gray/zinc/neutral/stone and a few newer neutrals like mauve/olive/mist/taupe) × 11 shades each, all defined in OKLCH for perceptually-even lightness steps, plus flat --color-black/--color-white. Redefining a neutral scale to reuse another's values (e.g. making --color-gray-* equal to --color-slate-*) is a supported pattern.

Code Examples

@theme {
  --color-midnight: #121063;   /* new custom color → bg-midnight, text-midnight, ... */
  --color-lime-*: initial;      /* drop one default scale */
}

:root { --acme-canvas-color: oklch(0.967 0.003 264.542); }
[data-theme="dark"] { --acme-canvas-color: oklch(0.21 0.034 264.665); }

@theme inline {
  --color-canvas: var(--acme-canvas-color); /* must be `inline` because it references another variable */
}

• What it demonstrates: adding a one-off custom color, dropping a default scale, and the @theme inline requirement when a color's value is itself a variable reference.

Key Takeaways

1. Any --color-* token defined in @theme automatically becomes usable across every color utility (bg/text/border/fill/ring/...) — colors aren't registered per-utility.
2. Use @theme inline specifically when a color value points at another CSS variable, not for ordinary literal color values.
3. --color-<scale>-*: initial removes one scale; --color-*: initial removes all of them — both are the mechanism for trimming or fully replacing the default palette, not a config array.
4. Full default palette values live in the source theme.css/colors.mdx reference — don't hand-copy the OKLCH table into project code; reference the generated --color-* variables or the utility classes instead.

Connects To

• Theme: colors are one namespace (--color-*) among the full theme variable system documented there (fonts, spacing, breakpoints, etc.) — the same @theme/initial/inline mechanics apply everywhere.
• Dark Mode: dark: variant usage with color utilities.
• Adding Custom Styles: --alpha() and arbitrary-value color syntax in depth.