Colors

Purpose and Scope

Tailwind’s color system gives utility classes a shared vocabulary for text, backgrounds, borders, SVG, shadows, outlines, and other color-bearing CSS properties. The official documentation presents this as a default palette with named families and shade steps, where values such as bg-sky-500, text-gray-950, border-pink-300, and fill-current all draw from the same color naming model. In the source evidence for this page, that model is represented by a compatibility color table and by a shadow-specific color replacement helper that understands how colors appear inside compound CSS values.

Sources: packages/tailwindcss/src/compat/colors.ts, packages/tailwindcss/src/utils/replace-shadow-colors.ts

This page focuses on two practical reader problems. First, it explains how the default color names map to concrete CSS color values so that custom styles, compatibility behavior, and generated utilities can agree on the same palette. Second, it explains why shadows need special handling: a box-shadow-like value can mix offsets, blur radii, keywords, functions, and colors in one declaration, so replacing only the color portion requires parsing rather than simple string substitution.

Relevant Source Files

• packages/tailwindcss/src/compat/colors.ts — Exports the compatibility palette object used to map Tailwind color names and shade keys to CSS color strings such as inherit, currentcolor, transparent, hex values, and OKLCH palette values.
• packages/tailwindcss/src/utils/replace-shadow-colors.ts — Exports replaceShadowColors(input, replacement), a parser-driven helper that identifies and replaces color components inside comma-separated shadow values while preserving offsets and other non-color parts.

Color Palette Model

The compatibility palette is a nested object whose top-level entries include special color keywords and named palettes. The special entries include inherit, current, transparent, black, and white, which map directly to CSS-compatible values such as inherit, currentcolor, transparent, #000, and #fff. Named families such as slate, gray, zinc, neutral, stone, mauve, olive, mist, and taupe are represented as objects keyed by shade numbers. In the supplied source, each family uses the familiar sequence from 50 through 950, with OKLCH values assigned to each shade.

Sources: packages/tailwindcss/src/compat/colors.ts

The official color documentation describes the same reader-facing model: every default palette family has eleven steps, with 50 as the lightest and 950 as the darkest. That matters because Tailwind utility names are compositional. A color token is not tied to one CSS property; instead, the same palette key can be combined with utility prefixes like bg-, text-, border-, stroke-, fill-, and related color utilities. The source object is therefore best understood as a shared compatibility data set, not as a background-color-only table.

OKLCH values are visible throughout the source palette entries. For developers working on Tailwind internals, this means color values are already stored in CSS syntax that can be emitted or referenced without converting from a separate color-space representation at this layer. For developers using Tailwind, the important consequence is consistency: text-slate-700 and bg-slate-700 point at the same named shade, even though the generated CSS property differs by utility family.

Color Utilities in Use

In user-facing CSS, color utilities combine a property prefix with a color token. The official examples show values like bg-white, border-pink-300, bg-pink-100, stroke-pink-700, and text-gray-700. The source palette explains the token side of that naming scheme: white is a top-level entry, while names like gray-700 are formed from a nested family key and a shade key. Internally, code that needs compatibility with the default palette can resolve these names from the exported palette object rather than hard-coding values in each utility family.

Sources: packages/tailwindcss/src/compat/colors.ts

A useful way to read the palette is as a flattened namespace waiting to be consumed by higher-level utility generation. The source file stores nested objects because that mirrors palette organization and keeps shade families readable. Utility classes, documentation tables, and CSS variable names often appear flattened, as in --color-gray-700 or text-gray-700. The flattening concept is the bridge between these two shapes: implementation code can preserve a maintainable nested data structure while presenting a flat class-name vocabulary to users.

Color-related utilities are broader than text and backgrounds. The official docs explicitly call out that the entire palette is available across color-related APIs, including background color, border color, fill, and caret color. The source evidence here does not enumerate every generated utility family, so this page treats those names as documentation-level behavior and uses the palette source to ground the underlying color values. When changing or auditing palette compatibility, start with the shared color data before looking at any individual utility family.

Shadow Color Replacement

Shadows are different from simple color properties because a shadow value is a structured list. A single value can contain inset, numeric lengths, CSS functions, a color, or several comma-separated shadows. The replaceShadowColors helper handles this by segmenting the input on commas, parsing each shadow value into a value AST, walking that AST, and replacing only the node that represents a color. This avoids treating every token as a color and preserves the rest of the shadow declaration.

Sources: packages/tailwindcss/src/utils/replace-shadow-colors.ts

The helper classifies tokens carefully. It skips known keywords such as inset, inherit, initial, revert, and unset. It treats numeric-looking words as lengths and recognizes length functions like calc, clamp, max, min, and --spacing. It treats color functions such as rgb, rgba, hsl, oklch, color-mix, light-dark, and --alpha as color candidates. It also recognizes hex values and named colors through isNamedColor. This classification lets Tailwind update color-bearing shadows without damaging offsets or blur values.

The fallback behavior is important for correctness. If a shadow has fewer than two detected lengths, the helper returns that shadow unchanged because it cannot confidently identify the x and y offsets. If a valid-looking shadow contains no explicit color and no unknown token, it appends the replacement for currentcolor, matching the browser-default color assumption. If there is exactly one unknown token left after lengths and keywords are handled, the helper assumes that token is the color and replaces it. Multiple unknowns are left unchanged to avoid unsafe rewrites.

Compact Reference

Component	Source-level contract	Practical meaning
Default palette export	export default { ... } in packages/tailwindcss/src/compat/colors.ts	Provides named colors and shade maps for compatibility-oriented color resolution.
Special color entries	inherit, current, transparent, black, white	Supports utility tokens that map to CSS keywords or fixed hex values.
Shade families	Nested keys such as slate['50'] through slate['950']	Represents the stepped palette used by classes like text-slate-700 or bg-slate-50.
Shadow replacement API	replaceShadowColors(input: string, replacement: (color: string) => string)	Rewrites color portions of shadow values while preserving non-color structure.
Shadow color detection	Color functions, hex values, and named colors	Handles modern CSS colors including OKLCH, RGB, HSL, color-mix, and related functions.

Sources: packages/tailwindcss/src/compat/colors.ts, packages/tailwindcss/src/utils/replace-shadow-colors.ts

System-to-Code Mapping

For readers tracing behavior from documentation to code, start with the class name vocabulary and then map it backward. A documented class like text-gray-950 expresses a CSS property choice, color, plus a palette token, gray-950. The compatibility palette supplies the token value. A shadow utility, by contrast, may already have a complex CSS value and only need its color component replaced or appended. That is why color data and shadow color replacement live in separate modules: one defines reusable values, while the other performs safe value-level rewriting.

The next useful pages are the typography and effects references if you are applying colors through text-*, shadow, or opacity utilities. If you are extending Tailwind itself, continue with configuration and plugin API material to see how custom utilities and theme data fit around the default palette.