Theming best practices in v4

[spacecat]

In my Next.js 15/TailwindCSS v3 app i have 11 themes. 5 dark ones and 6 light ones. I'm planning on upgrading to TailwindCSS v4.

The structure looks likes this:

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --color-app-background: 210 20% 98%;
  }

  .dark {
    --color-app-background: 216 13% 15%;
  }

 .sky_light {
    --color-app-background: 210 20% 98%;
  }

.sky_dark {
    --color-app-background: 216 13% 15%;
 }

/* other themes */
}

How would this look in v4?

Something like this?

@import "tailwindcss";

@theme {
    --color-app-background: oklch(0.7011 0.1882 2.55);;
}

@layer theme {
  :root {
    --color-app-background: oklch(0.7011 0.1882 2.55);;
  }

  .dark {
    --color-app-background: oklch(some value);
  }

 .sky_light {
    --color-app-background: oklch(some value);
  }

.sky_dark {
    --color-app-background: oklch(some value);
 }

/* other themes */
}

Should I use @layer theme or @layer base to put :root, .dark, .sky_light, .sky_dark, etc ?

Is nesting variables in properties in @layer theme legal?

[rozsazoltan]

Related:

• How to override theme variables in TailwindCSS v4 - @theme vs @layer theme vs :root
• From v4 the reset style cannot be overridden by TailwindCSS classes

Based on the linked documentation, I would structure your code like this in v4:

@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));
@custom-variant sky-light (&:where(.sky-light, .sky-light *));
@custom-variant sky-dark (&:where(.sky-dark, .sky-dark *));

@theme {
  --color-app-background: hsl(210 20% 98%);
}

@layer theme {
  :root, :host {
    @variant dark {
      --color-app-background: hsl(216 13% 15%);
    }

    @variant sky-light {
      --color-app-background: hsl(210 20% 98%);
    }

    @variant sky-dark {
      --color-app-background: hsl(216 13% 15%);
    }
  }
}

• https://play.tailwindcss.com/HPjJK5kY1Y?file=css

Of course, you can use OKLCH colors instead of HSL colors - I just didn't feel like converting them.

Themes:

• How to use custom color themes in TailwindCSS v4
• How to define custom colors and use them in dark, light mode without using :dark?

I don't want to repeat myself too much since there are already plenty of write-ups about this on GitHub and Stack Overflow. In v4, the JS config was removed, so to switch the dark variant from the default prefers-color-scheme to a class-based approach, you need to use @custom-variant. Similarly, you can also define your own custom variants this way. I've already set these up for you.

• https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually
• https://tailwindcss.com/docs/functions-and-directives#custom-variant-directive
• https://tailwindcss.com/docs/adding-custom-styles#adding-custom-variants

[spacecat]

From the docs:

This lets you write utilities theme-midnight:bg-black and theme-midnight:text-white.

This is not what I want; I don't think creating custom variants for all my themes is the way to go.

In my className i need ONE custom utility class, E.g. bg-app-bg, and when I change the theme in my theme selector, a different bg color should be applied.

The theme selector sets the selector class in the html element's class attribute.

[rozsazoltan]

You can skip the variant declaration as far as I'm concerned. I was just showing a much more functional solution.

@import "tailwindcss";

@theme {
  --color-app-background: hsl(210 20% 98%);
}

@layer theme {
  :root, :host {
    &:where(.dark, .dark *) {
      --color-app-background: hsl(216 13% 15%);
    }

    &:where(.sky-light, .sky-light *) {
      --color-app-background: hsl(210 20% 98%);
    }

    &:where(.sky-dark, .sky-dark *) {
      --color-app-background: hsl(216 13% 15%);
    }
  }
}

[rozsazoltan]

And if you want it to work in nested contexts as well, I recommend understanding the difference between * and :root.

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

@import "tailwindcss";

@theme {
  --color-app-background: hsl(210 20% 98%);
}

@layer theme {
  * {
    &:where(.dark, .dark *) {
      --color-app-background: hsl(216 13% 15%);
    }

    &:where(.sky-light, .sky-light *) {
      --color-app-background: hsl(210 20% 98%);
    }

    &:where(.sky-dark, .sky-dark *) {
      --color-app-background: hsl(216 13% 15%);
    }
  }
}

or

@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));
@custom-variant sky-light (&:where(.sky-light, .sky-light *));
@custom-variant sky-dark (&:where(.sky-dark, .sky-dark *));

@theme {
  --color-app-background: hsl(210 20% 98%);
}

@layer theme {
  * {
    @variant dark {
      --color-app-background: hsl(216 13% 15%);
    }

    @variant sky-light {
      --color-app-background: hsl(210 20% 98%);
    }

    @variant sky-dark {
      --color-app-background: hsl(216 13% 15%);
    }
  }
}

[rozsazoltan]

I believe the misunderstanding came from the fact that you didn't actually test my CSS code locally - you just glanced at it in the playground and dismissed it because I included a variant declaration while also answering your question at the same time.

In the playground, I don't have access to the :root element, and I can't inject a JS script to demonstrate theme switching. I can only showcase nested themes using *.

[rozsazoltan]

If you take a look, I used firstly @custom-variant in the CSS so that I could refer to the declaration with @variant without having to repeat those ugly :where(...) expressions.

[spacecat]

Your suggestion does not show how it addresses the following:

In my className i need ONE custom utility class, E.g. bg-app-bg, and when I change the theme in my theme selector, a different bg color should be applied.

The theme selector sets the selector class in the html element's class attribute.

How would that work with what you suggested?