v4's @theme layer and WordPress' theme.json

[sntran]

Hi,

If you work with WordPress' Full Site Editing and integrate Tailwind v4 with it, welcome!

I'd like to discuss a challenge I'm facing and to see some ideas come out of this.

As we all know, with Tailwind, we define our theme in @theme { ... }, with --color-*, --spacing-* CSS custom variables. These variables are then used for utility classes like text-*, bg-*, border-*, my-*, etc...

For WordPress with its new Full Site Editing, a theme.json with settings for colors, spacing, ... is used:

{
  "settings": {
    "color": {
      "palette": [
        {
          "color": "#FFFFFF",
          "name": "Base",
          "slug": "base"
        }
      ]
    },
    "spacing": {
      "spacingSizes": [
        {
          "name": "Auto",
          "size": "auto",
          "slug": "auto"
        }
      ]
    }
  }
}

For each of those settings, WordPress generates a CSS variable, i.e. --wp--preset--color--base: #FFFFFF, --wp--preset--spacing--auto: auto, ...

The challenge I have is to figure out where I should actually define my theme. Should the colors be in "theme.json" or "theme.css"?

If I define the colors in @theme, then I would need to set settings.color.palette[0].color = "var(--color-base)". Otherwise, I would need to define --color-base: var(--wp--preset--color--base); in @theme.

Another challenge is that while Tailwind uses text-base, bg-base for setting colors, WordPress generates has-base-color and has-base-background-color.

Is there a way to unify them?

[victormoni]

Hi @sntran

When integrating Tailwind CSS v4 with WordPress Full Site Editing (FSE), the main challenge is that both systems define and use CSS variables differently:

• Tailwind v4: Uses variables like --color-base, --spacing-auto, applied via utility classes (text-base, bg-base, etc.).
• WordPress FSE: Generates variables from theme.json like --wp--preset--color--base or --wp--preset--spacing--auto, and also uses class names such as .has-base-color or .has-base-background-color.

Unifying Tailwind and WordPress

To unify them, you can map WordPress variables to Tailwind variables inside your @theme layer in CSS:

@theme {
  --color-base: var(--wp--preset--color--base);
  --spacing-auto: var(--wp--preset--spacing--auto);
}

This way:

• WordPress still manages the values in theme.json.
• Tailwind utilities (text-base, bg-base, etc.) work seamlessly using the mapped variables.

Best Practice

• Define colors and spacing in theme.json so WordPress FSE features and block editor previews stay accurate.
• Bridge them in theme.css so Tailwind utilities reference the same values without duplication.

By doing this, you avoid conflicts, keep WordPress's editor in sync with the frontend, and leverage Tailwind's utilities without redefining values twice.

References:

• Tailwind CSS v4 Theme Variables
• WordPress theme.json Reference
• WordPress Global Styles & Presets