Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท Dark Mode and Theming

Multiple Themes with CSS Variables

Build switchable themes in Tailwind CSS v4: semantic color variables, @theme inline, data-theme attributes, dark mode without dark: prefixes and color-mix tints.

The dark: variant is simple, but it doubles your classes: every color needs a light and a dark twin. For anything bigger than a small site, a better approach is semantic theme variables. You write bg-surface text-ink once, and the meaning of surface and ink changes with the theme. This is the technique behind design systems with light, dark, high-contrast and brand themes, and it needs no extra Tailwind features beyond what you already know.

The idea

  1. Define plain CSS variables for each role (--surface, --ink, --accent) in :root, and override them under a selector such as [data-theme="dark"].
  2. Expose the roles to Tailwind with @theme inline, so --color-surface points at var(--surface).
  3. Use bg-surface, text-ink, border-line, bg-accent in your markup. Switching theme changes the variables and the whole page follows.
flowchart LR
  A["[data-theme]<br/>on html"] --> B["--surface, --ink,<br/>--accent change"]
  B --> C["@theme inline<br/>--color-surface: var(--surface)"]
  C --> D["bg-surface<br/>text-ink"]

The attribute changes variables; utilities read variables.

Why inline matters

Without inline, Tailwind would emit --color-surface: var(--surface) on :root and utilities would use var(--color-surface). That variable is resolved on :root, so a [data-theme] set on a nested element would not change it for that subtree. With @theme inline, utilities contain var(--surface) directly, so each element sees the nearest theme. That makes it possible to have a dark card on a light page.

A complete example

Three themes, one markup

Click the three buttons. The card, text, borders and button recolor, although the markup has no theme-specific class. Adding a fourth theme means adding one more block of variables; no templates change.

Nested and scoped themes

Because the variables are inherited, you can scope a theme to any element:

HTML
<body data-theme="light">
  <main>...</main>
  <footer data-theme="dark" class="bg-surface text-ink">
    The footer is dark on a light page.
  </footer>
</body>

This works because of @theme inline; the footer reads --surface from itself first.

A dark section on a light page

Mixing semantic colors and dark:

You do not have to choose one style. Many projects use semantic variables for the big roles and keep occasional dark: utilities for one-offs. The two combine if dark: follows the same switch as your variables. If your dark theme is [data-theme=dark], define the variant to match:

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

You can also set the variables from the system preference with a media query, then override with an explicit attribute, giving "system by default, user can override":

CSS
:root { --surface: white; --ink: #111; }
@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) { --surface: #111; --ink: white; }
}
[data-theme="dark"] { --surface: #111; --ink: white; }

Tints and states from one variable

With the colors as variables you can derive shades in the template instead of storing them. The opacity modifier already uses color-mix, so bg-accent/10 gives a subtle tint of whatever the accent is in the current theme, and hover:bg-accent/90 slightly softens it.

Derived tints

Practical advice

  • Keep the number of roles small: surface, raised surface, ink, muted ink, line, accent, and status colors cover most interfaces.
  • Name by role, never by appearance. --color-surface survives a redesign; --color-white does not.
  • Test contrast in every theme. A color that passes on a light theme can fail on a dark one.
  • Persist the chosen theme the same way as in Dark Mode: a tiny script in the <head> that sets the attribute before paint.
  • Add color-scheme per theme (color-scheme: dark; inside [data-theme="dark"]) so scrollbars and form controls match.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does @theme inline change for --color-surface: var(--surface)?

    Inline puts the referenced variable into the utility, so it resolves at the element that uses it.
  2. 2. Why name a variable --color-surface rather than --color-white?

    Semantic names describe the job, so a dark theme can keep surface while changing its value.
  3. 3. How do you switch theme at runtime in the example?

    Only the variable values change; the utilities already read them.
  4. 4. What does bg-accent/10 give you with a themed accent?

    The opacity modifier mixes the theme color with transparency, so it follows the theme.

Summary

  • Define roles as plain CSS variables and override them per theme with [data-theme] selectors or classes.
  • Map the roles with @theme inline so utilities like bg-surface read the nearest variable.
  • This avoids repeating dark: and allows nested or scoped themes.
  • Opacity modifiers derive tints from themed colors; set color-scheme per theme.

Next: Reusing Styles with Components