v4 @theme vs. @theme inline #18560

gabrieloureiro · 2025-07-17T11:48:20Z

gabrieloureiro
Jul 17, 2025

Hello everyone. I'm migrating an application from Tailwind v3 to v4. I'm defining my theme this way, but I've encountered the following error:

When I use @theme inline {...}, the themes work correctly, but dark mode doesn't.
When I use @theme {...} without inline, the themes stop working, but dark mode works.

I have a Next application with the same theming logic, which works perfectly, but the one I'm migrating uses Vite.

Any ideas on how to fix this error? I've tried several approaches here, including using @variant dark, :root(&:where...), using outside @layer theme, and nothing has worked.

theme.css

@custom-variant cyan (&:where([data-theme=cyan], [data-theme=cyan] *));
@custom-variant dark (&:where([data-mode=dark], [data-mode=dark] *));

/* @theme */
@theme inline {
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);

  --font-body: 'body', sans-serif;
  --font-display: 'display', sans-serif;

  --text-display-2xl: 4.5rem;
  --text-display-2xl--line-height: 5.625rem;

  --color-text-primary: var(--color-slate-900);
  --color-text-primary-on-brand: var(--color-white);

  --color-text-secondary: var(--color-slate-700);
  --color-text-secondary-on-brand: var(--color-brand-200);

  --color-text-tertiary: var(--color-slate-500);
  --color-text-tertiary-on-brand: var(--color-brand-200);

  --color-text-disabled: var(--color-slate-300);
  --color-text-placeholder: var(--color-slate-400);
  --color-text-white: var(--color-white);

  --color-text-brand-primary: var(--color-brand-900);
  --color-text-brand-secondary: var(--color-brand-700);
  --color-text-brand-tertiary: var(--color-brand-600);

  --color-text-error-primary: var(--color-rose-600);
  --color-text-warning-primary: var(--color-amber-600);
  --color-text-success-primary: var(--color-green-600);

  --color-border-primary: var(--color-slate-300);
  --color-border-secondary: var(--color-slate-200);
  --color-border-tertiary: var(--color-slate-200);

  --color-border-disabled: var(--color-slate-200);
  --color-border-disabled-subtle: var(--color-slate-200);

  --color-border-brand: var(--color-brand-600);
  --color-border-brand-subtle: var(--color-brand-100);

  --color-border-error: var(--color-rose-600);
  --color-border-error-subtle: var(--color-rose-100);

  --color-fg-primary: var(--color-slate-900);
  --color-fg-secondary: var(--color-slate-700);
  --color-fg-tertiary: var(--color-slate-500);

  --color-fg-white: var(--color-white);
  --color-fg-disabled: var(--color-slate-300);
  --color-fg-placeholder: var(--color-slate-400);

  --color-fg-brand-primary: var(--color-brand-600);
  --color-fg-brand-secondary: var(--color-brand-500);

  --color-fg-error-primary: var(--color-rose-600);
  --color-fg-error-secondary: var(--color-rose-500);

  --color-fg-warning-primary: var(--color-amber-600);
  --color-fg-warning-secondary: var(--color-amber-500);

  --color-fg-success-primary: var(--color-green-600);
  --color-fg-success-secondary: var(--color-green-500);

  --color-focus-ring: var(--color-brand-500);
  --color-focus-ring-error: var(--color-rose-500);

  --color-bg-primary: var(--color-slate-50);
  --color-bg-primary-alpha: var(--color-slate-50);
  --color-bg-primary-solid: var(--color-white);

  --color-bg-surface: var(--color-white);

  --color-bg-secondary: var(--color-slate-100);
  --color-bg-secondary-alpha: var(--color-slate-100);
  --color-bg-secondary-solid: var(--color-slate-600);

  --color-bg-tertiary: var(--color-slate-200);
  --color-bg-tertiary-alpha: var(--color-slate-200);

  --color-bg-active: var(--color-slate-50);
  --color-bg-disabled: var(--color-slate-100);
  --color-bg-disabled-subtle: var(--color-slate-50);
  --color-bg-overlay: var(--color-slate-950);

  --color-bg-brand-primary: var(--color-brand-50);
  --color-bg-brand-secondary: var(--color-brand-100);

  --color-bg-brand-solid: var(--color-brand-600);
  --color-bg-brand-alpha: var(--color-brand-600);

  --color-bg-error-primary: var(--color-rose-50);
  --color-bg-error-secondary: var(--color-rose-100);
  --color-bg-error-solid: var(--color-rose-600);
  --color-bg-error-alpha: var(--color-rose-600);

  --color-bg-warning-primary: var(--color-amber-50);
  --color-bg-warning-secondary: var(--color-amber-100);
  --color-bg-warning-solid: var(--color-amber-600);

  --color-bg-success-primary: var(--color-green-50);
  --color-bg-success-secondary: var(--color-green-100);
  --color-bg-success-solid: var(--color-green-600);

  --color-utility-gray-50: var(--color-slate-50);
  --color-utility-gray-100: var(--color-slate-100);
  --color-utility-gray-200: var(--color-slate-200);
  --color-utility-gray-300: var(--color-slate-300);
  --color-utility-gray-400: var(--color-slate-400);
  --color-utility-gray-500: var(--color-slate-500);
  --color-utility-gray-600: var(--color-slate-600);
  --color-utility-gray-700: var(--color-slate-700);
  --color-utility-gray-800: var(--color-slate-800);
  --color-utility-gray-900: var(--color-slate-900);

  --color-utility-brand-50: var(--color-brand-50);
  --color-utility-brand-50-alt: var(--color-brand-50);

  --color-utility-brand-100: var(--color-brand-100);
  --color-utility-brand-100-alt: var(--color-brand-100);

  --color-utility-brand-200: var(--color-brand-200);
  --color-utility-brand-200-alt: var(--color-brand-200);

  --color-utility-brand-300: var(--color-brand-300);
  --color-utility-brand-300-alt: var(--color-brand-300);

  --color-utility-brand-400: var(--color-brand-400);
  --color-utility-brand-400-alt: var(--color-brand-400);

  --color-utility-brand-500: var(--color-brand-500);
  --color-utility-brand-500-alt: var(--color-brand-500);

  --color-utility-brand-600: var(--color-brand-600);
  --color-utility-brand-600-alt: var(--color-brand-600);

  --color-utility-brand-700: var(--color-brand-700);
  --color-utility-brand-700-alt: var(--color-brand-700);

  --color-utility-brand-800: var(--color-brand-800);
  --color-utility-brand-800-alt: var(--color-brand-800);

  --color-utility-brand-900: var(--color-brand-900);
  --color-utility-brand-900-alt: var(--color-brand-900);

  --color-utility-brand-950: var(--color-brand-950);

  --color-button-primary-icon: var(--color-white);
  --color-button-primary-icon-hover: var(--color-brand-50);
  --color-button-destructive-primary-icon: var(--color-red-300);
  --color-button-destructive-primary-icon-hover: var(--color-red-200);

  --color-icon-fg-brand: var(--color-brand-600);
  --color-icon-fg-brand-on-brand: var(--color-brand-200);

  --color-featured-icon-light-fg-brand: var(--color-brand-600);
  --color-featured-icon-light-fg-gray: var(--color-slate-500);
  --color-featured-icon-light-fg-error: var(--color-rose-600);
  --color-featured-icon-light-fg-warning: var(--color-amber-600);
  --color-featured-icon-light-fg-success: var(--color-green-600);

  --color-toggle-button-fg-disabled: var(--color-slate-50);
  --color-toggle-border: var(--color-slate-300);

  --color-tooltip-supporting-text: var(--color-zinc-300);
}

@layer theme {
  :root {
    --color-brand-50: #ECFDF5;
    --color-brand-100: #D1FAE5;
    --color-brand-200: #A7F3D0;
    --color-brand-300: #6EE7B7;
    --color-brand-400: #34D399;
    --color-brand-500: #10B981;
    --color-brand-600: #059669;
    --color-brand-700: #047857;
    --color-brand-800: #065F46;
    --color-brand-900: #064E3B;
    --color-brand-950: #022C22;
  }

  [data-theme="cyan"] {
    --color-brand-50: oklch(0.984 0.019 200.873);
    --color-brand-100: oklch(0.956 0.045 203.388);
    --color-brand-200: oklch(0.917 0.08 205.041);
    --color-brand-300: oklch(0.865 0.127 207.078);
    --color-brand-400: oklch(0.789 0.154 211.53);
    --color-brand-500: oklch(0.715 0.143 215.221);
    --color-brand-600: oklch(0.609 0.126 221.723);
    --color-brand-700: oklch(0.52 0.105 223.128);
    --color-brand-800: oklch(0.45 0.085 224.283);
    --color-brand-900: oklch(0.398 0.07 227.392);
    --color-brand-950: oklch(0.302 0.056 229.695);
  }

  [data-mode="dark"] {
    --color-text-primary: var(--color-white);
    --color-text-primary-on-brand: var(--color-zinc-50);

    --color-text-secondary: var(--color-zinc-200);
    --color-text-secondary-on-brand: var(--color-zinc-300);

    --color-text-tertiary: var(--color-zinc-400);
    --color-text-tertiary-on-brand: var(--color-zinc-400);

    --color-text-disabled: var(--color-zinc-700);
    --color-text-placeholder: var(--color-zinc-500);
    --color-text-white: var(--color-white);

    --color-text-brand-primary: var(--color-brand-100);
    --color-text-brand-secondary: var(--color-brand-300);
    --color-text-brand-tertiary: var(--color-brand-400);

    --color-text-error-primary: var(--color-rose-400);
    --color-text-warning-primary: var(--color-amber-400);
    --color-text-success-primary: var(--color-green-400);

    --color-border-primary: var(--color-zinc-700);
    --color-border-secondary: var(--color-zinc-800);
    --color-border-tertiary: var(--color-zinc-900);

    --color-border-disabled: var(--color-zinc-700);
    --color-border-disabled-subtle: var(--color-zinc-800);

    --color-border-brand: var(--color-brand-800);
    --color-border-brand-subtle: rgba(6, 95, 70, 0.6);

    --color-border-error: var(--color-rose-800);
    --color-border-error-subtle: var(--color-rose-600);

    --color-fg-primary: var(--color-white);
    --color-fg-secondary: var(--color-zinc-200);
    --color-fg-tertiary: var(--color-zinc-400);

    --color-fg-white: var(--color-white);
    --color-fg-disabled: var(--color-zinc-700);
    --color-fg-placeholder: var(--color-zinc-500);

    --color-fg-brand-primary: var(--color-brand-300);
    --color-fg-brand-secondary: var(--color-brand-600);

    --color-fg-error-primary: var(--color-rose-500);
    --color-fg-error-secondary: var(--color-rose-400);

    --color-fg-warning-primary: var(--color-amber-500);
    --color-fg-warning-secondary: var(--color-amber-400);

    --color-fg-success-primary: var(--color-green-500);
    --color-fg-success-secondary: var(--color-green-400);

    --color-bg-primary: var(--color-zinc-950);
    --color-bg-primary-alpha: rgba(255, 255, 255, 0.04);
    --color-bg-primary-solid: var(--color-zinc-950);

    --color-bg-surface: rgba(255, 255, 255, 0.04);

    --color-bg-secondary: var(--color-zinc-900);
    --color-bg-secondary-alpha: rgba(255, 255, 255, 0.04);
    --color-bg-secondary-solid: var(--color-zinc-500);

    --color-bg-tertiary: var(--color-zinc-800);
    --color-bg-tertiary-alpha: rgba(0, 0, 0, 0.4);

    --color-bg-active: var(--color-zinc-800);
    --color-bg-disabled: var(--color-zinc-800);
    --color-bg-disabled-subtle: var(--color-zinc-900);
    --color-bg-overlay: var(--color-zinc-800);

    --color-bg-brand-primary: rgba(2, 44, 34, 0.60);
    --color-bg-brand-secondary: var(--color-brand-700);
    --color-bg-brand-solid: var(--color-brand-600);
    --color-bg-brand-alpha: rgba(4, 120, 87, 0.3);

    --color-bg-error-primary: var(--color-rose-950);
    --color-bg-error-secondary: var(--color-rose-600);
    --color-bg-error-solid: var(--color-rose-600);
    --color-bg-error-alpha: rgba(225, 29, 72, 0.3);

    --color-bg-warning-primary: var(--color-amber-950);
    --color-bg-warning-secondary: var(--color-amber-600);
    --color-bg-warning-solid: var(--color-amber-600);

    --color-bg-success-primary: var(--color-green-950);
    --color-bg-success-secondary: var(--color-green-600);
    --color-bg-success-solid: var(--color-green-600);

    --color-utility-gray-50: var(--color-zinc-900);
    --color-utility-gray-100: var(--color-zinc-800);
    --color-utility-gray-200: var(--color-zinc-700);
    --color-utility-gray-300: var(--color-zinc-700);
    --color-utility-gray-400: var(--color-zinc-600);
    --color-utility-gray-500: var(--color-zinc-500);
    --color-utility-gray-600: var(--color-zinc-400);
    --color-utility-gray-700: var(--color-zinc-50);
    --color-utility-gray-800: var(--color-zinc-200);
    --color-utility-gray-900: var(--color-zinc-100);

    --color-utility-brand-50: var(--color-brand-950);
    --color-utility-brand-50-alt: var(--color-brand-50);

    --color-utility-brand-100: var(--color-brand-900);
    --color-utility-brand-100-alt: var(--color-utility-gray-100);

    --color-utility-brand-200: var(--color-brand-800);
    --color-utility-brand-200-alt: var(--color-utility-gray-200);

    --color-utility-brand-300: var(--color-brand-700);
    --color-utility-brand-300-alt: var(--color-utility-gray-300);

    --color-utility-brand-400: var(--color-brand-600);
    --color-utility-brand-400-alt: var(--color-utility-gray-400);

    --color-utility-brand-500: var(--color-brand-500);
    --color-utility-brand-500-alt: var(--color-utility-gray-500);

    --color-utility-brand-600: var(--color-brand-400);
    --color-utility-brand-600-alt: var(--color-utility-gray-600);

    --color-utility-brand-700: var(--color-brand-50);
    --color-utility-brand-700-alt: var(--color-utility-gray-700);

    --color-utility-brand-800: var(--color-brand-200);
    --color-utility-brand-800-alt: var(--color-brand-800);

    --color-utility-brand-900: var(--color-brand-100);
    --color-utility-brand-900-alt: var(--color-brand-950);

    --color-utility-brand-950: var(--color-brand-100);

    --color-button-primary-icon-hover: var(--color-utility-brand-50-alt);

    --color-icon-fg-brand: var(--color-zinc-400);
    --color-icon-fg-brand-on-brand: var(--color-zinc-400);

    --color-featured-icon-light-fg-brand: var(--color-brand-200);
    --color-featured-icon-light-fg-gray: var(--color-slate-200);
    --color-featured-icon-light-fg-error: var(--color-rose-200);
    --color-featured-icon-light-fg-warning: var(--color-amber-200);
    --color-featured-icon-light-fg-success: var(--color-green-200);

    --color-toggle-button-fg-disabled: var(--color-zinc-600);
    --color-toggle-border: var(--color-alpha-black-10);
  }
}

global.css

@import 'tailwindcss';

@import './fonts.css';
@import './themes.css';

@plugin "@tailwindcss/typography";
@plugin "tailwindcss-animate";

@custom-variant focus-input-within (&:has(input:focus));

@utility scrollbar-hide {
    /* For Webkit-based browsers (Chrome, Safari and Opera) */
    &::-webkit-scrollbar {
        display: none;
        -webkit-appearance: none;
    }

    /* For IE, Edge and Firefox */
    -ms-overflow-style: none; /* IE and Edge */
    scrollbar-width: none; /* Firefox */
}

@utility transition-inherit-all {
    transition-property: inherit;
    transition-duration: inherit;
    transition-timing-function: inherit;
}

html,
body {
    font-family: "body", sans-serif;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    -webkit-font-variant-ligatures: contextual;
    font-variant-ligatures: contextual;
    -webkit-font-kerning: normal;
    font-kerning: normal;
}

ThemeProvider.tsx:

 <ThemeContext.Provider
      value={{
        state,
        dispatch,
      }}
    >
      <div
        id="mode"
        data-mode={state.mode}
      >
        <div
          id="theme"
          data-theme={state.theme?.colors}
        >
          {children}
        </div>
      </div>
    </ThemeContext.Provider>

vite.config.ts

import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import path from "path";
import { defineConfig } from "vite";


// https://vitejs.dev/config/
export default defineConfig(({ command }) => {
  const isDevelopment = command === "serve";

  return {
    base: isDevelopment ? "/" : "/gl-ui/",
    server: {
      port: 7778,
    },
    resolve: {
      alias: {
        "@": path.resolve(__dirname, "./src"),
        "~relative": path.resolve(__dirname, ".."),
      },
    },
    plugins: [react(), tailwindcss()],
    assetsInclude: ["**/*.md"],
  };
});

index.html

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/src/global.css" rel="stylesheet" />
  <title>GL Design System</title>
</head>

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
</body>

</html>

With inline:

Without inline:

Answered by rozsazoltan

Jul 17, 2025

TL;DR: With @theme inline, you are responsible for providing the variable override, since the variable does not exist globally.
In contrast, with @theme, the value is embedded into a global variable, which means its value can be overridden later.

How to override theme variables in TailwindCSS v4 - @theme vs @layer theme vs :root

So, @theme and @theme inline can be used together - and in fact, you can declare them in multiple places.

Additionally, I would declare styles for different variants using @variant, either inside *, :root, or :host. You can read more about which one to use in this question:

When should I use * and when should I use :root, :host as the parent selector?

I…

View full answer

rozsazoltan · 2025-07-17T12:29:36Z

rozsazoltan
Jul 17, 2025

TL;DR: With @theme inline, you are responsible for providing the variable override, since the variable does not exist globally.
In contrast, with @theme, the value is embedded into a global variable, which means its value can be overridden later.

How to override theme variables in TailwindCSS v4 - @theme vs @layer theme vs :root

So, @theme and @theme inline can be used together - and in fact, you can declare them in multiple places.

Additionally, I would declare styles for different variants using @variant, either inside *, :root, or :host. You can read more about which one to use in this question:

When should I use * and when should I use :root, :host as the parent selector?

I created a much smaller example than yours:

https://play.tailwindcss.com/ZQuBVd8YxH?file=css

Here you can see that both cyan and the nested dark version of cyan work correctly. That's because brand was declared inside @theme, which allows us to override it later. With @theme, we get a global variable for the color.

Note: You can also declare color values only for text or only for bg using an undocumented namespace. I renamed some of the colors in the example to demonstrate this. More details here:

@theme inline {
  --text-color-primary: var(--color-slate-900);
  --background-color-secondary: var(--color-slate-200);
}

/* Warning: Just an example - code does not work in practice! */
@layer theme {
  * {
    @variant dark {
      --text-color-primary: var(--color-white);
      --background-color-secondary: var(--color-zinc-700);
    }
  }
}

The * > @variant dark part doesn't work - and rightfully so.
That's because values declared inside @theme inline don't get global variables, so there's nothing to override.

In that case, the system leaves the override up to you - so in this example, you'd have to manually override: --color-slate-900 and --color-slate-200.

Theme	Utilities

I'm guessing that's not what you want. To have TailwindCSS generate global variables for --color-slate-900 and --color-slate-200, you can move everything into @theme.

https://play.tailwindcss.com/uGZkvD7xCJ?file=css

/* Without inline */
@theme {
  --text-color-primary: var(--color-slate-900);
  --background-color-secondary: var(--color-slate-200);
}

@layer theme {
  * {
    @variant dark {
       /* a variable declared in @theme (without inline)
           has a corresponding global variable, which can be overridden */
       --text-color-primary: var(--color-white);
       --background-color-secondary: var(--color-zinc-700);
    }
  }
}

Theme	Utilities

Or, in the case of inline, you need to override your local colors manually in dark mode:

https://play.tailwindcss.com/Rm8kbO1tun?file=css

@theme inline {
  --text-color-primary: var(--color-slate-900);
  --background-color-secondary: var(--color-slate-200);
}

@layer theme {
  * {
    @variant dark {
        /* a color declared in @theme inline does not have a global variable,
            so you need to override the assigned variable directly */
        --color-slate-900: var(--color-white);
        --color-slate-200: var(--color-zinc-700);
    }
  }
}

Theme	Utilities

1 reply

gabrieloureiro Jul 17, 2025
Author

Thanks a lot, man! I separated @theme and @theme inline, and followed the variants approach within the theme layer. It worked perfectly.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

v4 @theme vs. @theme inline #18560

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

v4 @theme vs. @theme inline #18560

Uh oh!

Uh oh!

gabrieloureiro Jul 17, 2025

theme.css

global.css

ThemeProvider.tsx:

vite.config.ts

index.html

With inline:

Without inline:

Replies: 1 comment · 1 reply

Uh oh!

Uh oh!

rozsazoltan Jul 17, 2025

Uh oh!

gabrieloureiro Jul 17, 2025 Author

gabrieloureiro
Jul 17, 2025

Replies: 1 comment 1 reply

rozsazoltan
Jul 17, 2025

gabrieloureiro Jul 17, 2025
Author