Unifying Tailwind v4 and Element Plus with a Design Token Bridge

theme: fancy

The core idea of the best practice is: Use Design Tokens as a "universal language" so that both Tailwind v4 and Element Plus read from the same set of variables, resolving style conflicts and visual inconsistencies at the source.

Here is the four-step best practice implementation plan:

1. Architecture: Token-Driven Three-Layer System

It is recommended to establish a clear "Primitive Layer → Semantic Layer → Component Layer" Token system and register them in Tailwind v4's @theme by layer.

Primitive Tokens: Pure color values, e.g., --blue-500: oklch(54.6% 0.245 262.881). Tailwind v4 recommends using the oklch() format by default, as colors are more uniform.
Semantic Tokens: Define usage, e.g., --color-primary: var(--blue-500).
Component Tokens: Component-specific variables, e.g., --el-button-bg: var(--color-primary), for consumption by Element Plus.

In Tailwind v4, it is recommended to register these Tokens directly in CSS via @theme, abandoning the JavaScript configuration file approach.

@import "tailwindcss";

@theme {
  /* Primitive Tokens */
  --color-blue-500: oklch(54.6% 0.245 262.881);
  /* Semantic Tokens */
  --color-primary: var(--color-blue-500);
}

2. Bridging: Making Element Plus "Understand" Your Tokens

Element Plus's styles are based on CSS variables, which is the key to visual unification. You can directly override Element Plus's CSS variables with Tailwind's variables like this:

:root {
  /* Directly assign Tailwind v4's CSS variables to Element Plus's internal variables */
  --el-color-primary: var(--color-primary);
  --el-font-family: var(--font-family-sans);
  --el-border-radius-base: var(--radius-lg);
}

The benefit of this approach is that all Element Plus components will automatically follow the Design Tokens you defined via @theme, truly achieving "change one place, update everywhere."

3. Integration: Using Element Plus Variables in Tailwind

If you are accustomed to using Element Plus's theme variables directly in Tailwind utility classes, you can also establish mappings in @theme to generate utility classes like text-el-primary.

@theme {
  --color-el-primary: var(--el-color-primary);
  /* or other color levels, such as --el-color-primary-light-3 */
}

This way, you can directly use class names like text-el-primary, bg-el-primary, etc.

4. Conflicts: Handling Style Override Issues

Since Element Plus components are dynamically rendered, they may conflict with Tailwind's preflight base styles. There are two mainstream solutions:

Option A: Disable Tailwind's Base Styles (Recommended) Turn off preflight in tailwind.config.js or CSS to prevent it from interfering with Element Plus's built-in styles.
```
// tailwind.config.js (v3 configuration method, v4 can refer to similar configuration)
export default {
  corePlugins: {
    preflight: false,
  },
}
```
Option B: Use CSS Prefix (Isolate Risk) If you are concerned about global pollution, you can add a prefix (e.g., tw:) to all Tailwind utility classes to isolate the risk. However, using tw:flex will reduce some development efficiency, which requires a trade-off.

💎 Summary Mnemonic

Token defines the variables, EL references them; Tailwind injects the classes, prefix prevents conflicts; Dark mode needs linkage, dynamically swap the sequence.

Regarding the linkage of dark mode, because the color change mechanism in Element Plus's dark mode is relatively complex, if you need a detailed explanation of this part of the configuration, let me know and I will explain it separately for you.