Which TailwindCSS v4 namespace matches a given TailwindCSS v3's theme keys?

[rozsazoltan]

From TailwindCSS v4 onward, the JS-based configuration is not available by default. However, in the new CSS-first configuration, everything is completely different. The old keys have been removed, and new namespaces have been introduced. There is no concrete mapping showing which old key corresponds to which new namespace. Additionally, the number of documented namespaces is much smaller.

In TailwindCSS v3's JS-based configuration (i.e. in tailwind.config.js), there were many configuration options - for example, I could declare a color exclusively for the text-* utility (by textColor key) or only for the bg-* utility (by backgroundColor key).

• TailwindCSS v3: Customizing your theme with theme.textColor or theme.extend.textColor
• TailwindCSS v3: Customizing your theme with theme.backgroundColor or theme.extend.backgroundColor

But in the CSS-first documentation, colors can only be declared globally.

• TailwindCSS v4: Customizing your theme with --color-* namespace (not only for text-* utility)
• TailwindCSS v4: Customizing your theme with --color-* namespace (not only for bg-* utility)

I've discovered, however, that these settings are still available, though there's no concrete list of them in the official v4 CSS-first configuration docs: You can use --text-color-* and --background-color-* namespaces.

I'm looking for a canonical list that enumerates which namespaces are available by default in TailwindCSS v4's CSS-first configuration.

[rozsazoltan]

Yes, a lot is missing from TailwindCSS v4's new CSS-first documentation. You can find the documented ones listed here (such as --color-*):

• Theme variable namespaces

Many undocumented namespaces - like the --text-color-* or --background-color-* you mentioned - don't yet have a dedicated place, so the following table contains the complete list of what's missing.

Explanation of the table:

• The 1st column contains the old v3 JS-based key, which could be used in theme.{key} or theme.extend.{key}. Based on the v3 key, you can easily find its v4 counterpart.
• The 2nd column contains the corresponding new v4 CSS-first configuration namespace, which can be used within @theme. It may also include documented but renamed keys, in which case the key directly points to the corresponding entry.
• The 3rd column provides an explanation of which specific utility the key/namespace affects.

Source: philipp-spiess/theme-variable-namespaces-table.md - It's important to note that the source has been expanded with records and columns, providing a more complete picture of the changes between v3 and v4.

Old Key (v3)	New Namespace (v4)	Utility classes	Documented
accentColor	--accent-color-*	Accent color utilities like accent-blue-600	--color-*
animation	--animate-*	Animation utilities like animate-spin	✅
aspectRatio	--aspect-*	Aspect ratio utilities like aspect-video	✅
backdropBlur	--backdrop-blur-*	Backdrop blur utilities like backdrop-blur-md	--blur-*
backdropBrightness	--backdrop-brightness-*	Backdrop brightness utilities like backdrop-brightness-125	Arbitrary or variable
backdropContrast	--backdrop-contrast-*	Backdrop contrast utilities like backdrop-contrast-125
backdropGrayscale	--backdrop-grayscale-*	Backdrop grayscale utilities like backdrop-grayscale
backdropHueRotate	--backdrop-hue-rotate-*	Backdrop hue rotate utilities like backdrop-hue-rotate-60
backdropInvert	--backdrop-invert-*	Backdrop invert utilities like backdrop-invert
backdropOpacity	--backdrop-opacity-*	Backdrop opacity utilities like backdrop-opacity-50
backdropSaturate	--backdrop-saturate-*	Backdrop saturate utilities like backdrop-saturate-150
backdropSepia	--backdrop-sepia-*	Backdrop sepia utilities like backdrop-sepia
backgroundColor	--background-color-*	Background color utilities like bg-zinc-800	--color-*
backgroundOpacity	Removed	Any opacity can be applied as a modifier like bg-zinc-800/30
backgroundImage	--background-image-*	Background image/gradient utilities like bg-[url('/img.png')] and bg-gradient-to-r
backgroundPosition	Not available	Can use bg-position-[value] utility
backgroundSize	Not available	Can use bg-size-[value] utility
blur	--blur-*	Blur filter utilities like blur-md
borderColor	--border-color-*	Border color utilities like border-slate-300	--color-*
borderOpacity	Removed	Any opacity can be applied as a modifier like border-slate-300/30
borderRadius	--radius-* (not recommended)	Border radius utilities like rounded-sm
borderRadius	--rounded-*	Border radius utilities like rounded-sm	✅
borderSpacing	--border-spacing-*	Table border-spacing utilities like border-spacing-4 and border-spacing-x-8
borderWidth	--border-width-*	Border width utilities like border, border-2, border-x
boxShadow	--shadow-*	Box shadow utilities like shadow-md and shadow-lg	✅
boxShadowColor	--box-shadow-color-*	Shadow color utilities like shadow-red-500	--color-*
screens	--breakpoint-*	Responsive breakpoint variants like sm:*	✅
brightness	--brightness-*	Brightness filter utilities like brightness-110
caretColor	--caret-color-*	Caret color utilities like caret-rose-500	--color-*
colors	--color-*	Color utilities like bg-red-500, text-sky-300, and many more	✅
columns	--columns-*	CSS multi‑column utilities like columns-3 and columns-auto
container	Not available	Can be declared as @utility container { ... }	✅
Not available	--container-* (new)	Container query variants like @sm:* and size utilities like max-w-md	✅
content	Not available	Can use content-[value] utility	✅
contrast	--contrast-*	Contrast filter utilities like contrast-125
cursor	--cursor-*	Cursor utilities like cursor-pointer and cursor-not-allowed
data	Deprecated	Can declare custom-named selectors by @custom-variant	✅
supports	Deprecated	Can declare custom-named selectors by @custom-variant	✅
divideColor	--divide-color-*	Divider color utilities like divide-gray-200	--color-* --border-color
divideOpacity	Removed	Any opacity can be applied as a modifier like divide-gray-200/30
divideWidth	--divide-width-*	Divider width utilities like divide-x-2 and divide-y
dropShadow	--drop-shadow-*	Drop shadow filter utilities like drop-shadow-md
Not available	--drop-shadow-color-*	Drop shadow color utilities like drop-shadow-red-500	--color-*
transitionTimingFunction	--ease-*	Transition timing function utilities like ease-out
fill	--fill-*	SVG fill color utilities like fill-blue-500
flexBasis	--flex-basis-*	Flex basis utilities like basis-1/2 and basis-40	--container-* --spacing-*
flexGrow	Not available (Removed)	Can use grow-[value] utility
flexShrink	Not available (Removed)	Can use shrink-[value] utility
fontFamily	--font-*	Font family utilities like font-sans	✅
Not available	--font-feature-settings-*	Advanced font feature utilities via text-[font-feature-settings:'ss01']	✅
Not available	--font-variation-settings-*	Variable font axis utilities via text-[font-variation-settings:'wght'_600]	✅
fontSize	--text-*	Font size utilities like text-3xl	✅
fontWeight	--font-weight-*	Font weight utilities like font-bold	✅
gap	--gap-*	Gap utilities like gap-4, gap-x-2, and gap-y-8
gradientColorStops	Not available	Can use global --color-* namespace	--color-*
gradientColorStopPositions	--gradient-color-stop-positions-*	Gradient stop position utilities like from-10%, via-[35%], and to-90%
grayscale	--grayscale-*	Grayscale filter utilities like grayscale and grayscale-0
gridAutoColumns	--grid-auto-columns-*	Auto columns utilities like auto-cols-fr and auto-cols-min
gridAutoRows	--grid-auto-rows-*	Auto rows utilities like auto-rows-min and auto-rows-fr
gridColumn	--grid-column-*	Grid column shorthand utilities like col-auto or col-[2/4]
gridColumnEnd	--grid-column-end-*	Column end utilities like col-end-7
gridColumnStart	--grid-column-start-*	Column start utilities like col-start-3
gridRow	--grid-row-*	Grid row shorthand utilities like row-auto or row-[2/5]
gridRowEnd	--grid-row-end-*	Row end utilities like row-end-4
gridRowStart	--grid-row-start-*	Row start utilities like row-start-2
gridTemplateColumns	--grid-template-columns-*	Grid template columns utilities like grid-cols-12
gridTemplateRows	--grid-template-rows-*	Grid template rows utilities like grid-rows-6
height	--height-*	Height utilities like h-64 and h-screen	--spacing-*
hueRotate	--hue-rotate-*	Hue rotate filter utilities like hue-rotate-60
inset	--inset-shadow-*	Inset box shadow utilities like inset-shadow-xs
invert	--invert-*	Invert filter utilities like invert and invert-0
keyframes	Not available	Can use @keyframes CSS at-rule
listStyleType	--list-style-type-*	Marker style of a list utilities like list-decimal
listStyleImage	--list-style-image-*	Marker images for list items utilities like list-image-[url(/img/checkmark.png)]
letterSpacing	--tracking-*	Letter spacing utilities like tracking-wide	✅
lineClamp	--line-clamp-*	Line clamping utilities like line-clamp-3 and line-clamp-none
lineHeight	--leading-*	Line height utilities like leading-tight	--spacing-*
margin	--margin-*	Margin utilities like mt-6, mx-auto, and -mb-2	--spacing-*
maxHeight	--max-height-*	Max-height utilities like max-h-96 and max-h-none	--spacing-*
maxWidth	--max-width-*	Max-width utilities like max-w-md and max-w-none	--spacing-*
minHeight	--min-height-*	Min-height utilities like min-h-0 and min-h-screen	--spacing-*
minWidth	--min-width-*	Min-width utilities like min-w-0 and min-w-full	--spacing-*
objectPosition	--object-position-*	Object position utilities like object-center and object-top-left
opacity	--opacity-*	Opacity utilities like opacity-60
order	--order-*	Flex/grid order utilities like order-3, order-first, and order-last
outlineColor	--outline-color-*	Outline color utilities like outline-sky-500	--color-*
outlineOffset	--outline-offset-*	Outline offset utilities like outline-offset-4
outlineWidth	--outline-width-*	Outline width utilities like outline-2
padding	--padding-*	Padding utilities like px-4, pt-2, and p-6	--spacing-*
placeholderColor	Not available	Can use placeholder: variant like placeholder:text-gray-500
placeholderOpacity	Removed	Can use placeholder: variant like placeholder:text-gray-500/30
Not available	--perspective-*	Perspective utilities like perspective-near
Not available	--perspective-origin-*	Perspective origin utilities like perspective-origin-top-left
ringColor	--ring-color-*	Ring color utilities like ring-indigo-500	--color-*
ringOpacity	Removed	Any opacity can be applied as a modifier like ring-indigo-500/30
ringOffsetColor	--ring-offset-color-*	Ring offset color utilities like ring-offset-white	--color-*
ringOffsetWidth	--ring-offset-width-*	Ring offset width utilities like ring-offset-2
ringWidth	--ring-width-*	Ring width utilities like ring and ring-2
rotate	--rotate-*	Rotate utilities like rotate-45 and -rotate-12
saturate	--saturate-*	Saturate filter utilities like saturate-150
scale	--scale-*	Scale utilities like scale-95 and scale-x-110
scrollMargin	--scroll-margin-*	Scroll margin utilities like scroll-mt-16 and scroll-my-8	--spacing-*
scrollPadding	--scroll-padding-*	Scroll padding utilities like scroll-px-4 and scroll-py-8	--spacing-*
sepia	--sepia-*	Sepia filter utilities like sepia and sepia-0
size	--size-*	Square sizing utilities like size-12 (sets width & height)	--spacing-*
skew	--skew-*	Skew utilities like skew-x-6 and skew-y-3
space	--space-*	Space-between utilities like space-x-2 and space-y-4
spacing	--spacing-*	Spacing and sizing utilities like px-4, max-h-16, and many more
stroke	--stroke-*	SVG stroke color utilities like stroke-red-500
strokeWidth	--stroke-width-*	SVG stroke width utilities like stroke-2
Not available	--tab-size-*	Tab size utilities like tab-size-4
textColor	--text-color-*	Text color utilities like text-emerald-500	--color-*
textOpacity	Removed	Any opacity can be applied as a modifier like text-emerald-500/30
textDecorationColor	--text-decoration-color-*	Decoration color utilities like decoration-pink-500	--color-*
textDecorationThickness	--text-decoration-thickness-*	Decoration thickness utilities like decoration-2 and decoration-from-font
textIndent	--text-indent-*	Text indent utilities like indent-4
Not available	--text-shadow-*	Text shadow utilities like text-shadow-md	✅
Not available	--text-shadow-color-*	Text shadow color utilities like text-shadow-red-500	--color-*
textUnderlineOffset	--text-underline-offset-*	Underline offset utilities like underline-offset-4 and underline-offset-auto
transformOrigin	--transform-origin-*	Transform origin utilities like origin-top-left
transitionDelay	--transition-delay-*	Transition delay utilities like delay-150
transitionDuration	--transition-duration-*	Transition duration utilities like duration-300
transitionProperty	--transition-property-*	Transition property utilities like transition, transition-colors, and transition-[...]
translate	--translate-*	Translate utilities like translate-x-1/2 and -translate-y-4
width	--width-*	Width utilities like w-1/2 and w-64	--spacing-*
zIndex	--z-index-*	Z-index utilities like z-50 and z-auto

Note: The list does not include the namespaces found in the previous docs-reference, only those missing from it.

The motivation behind Philipp Spiess's research:

I was looking into this today and prepared an exhaustive list but the full list ends up being extremely long and not really useful so for now we're not going to make changes to the website (editor's note: v4 documentation). I did, however, use my research and upload it to a GitHub Gist so here's the definitive version as of Tailwind CSS v4.1. (source)

So you can use the namespaces within @theme directive, as demonstrated in the documentation.

• How to use @theme directive