CSS

从零搭建 Tailwind CSS 多模式颜色系统：自动生成主题色工具类的实践方案

Posted by Panda on 2025-09-13

从零搭建 Tailwind CSS 多模式颜色系统：自动生成主题色工具类的实践方案

在前端开发中，颜色系统是 UI 一致性的核心，尤其在需要支持「亮色/暗色模式」「品牌色/经典色切换」的场景下，手动维护 CSS 变量和工具类不仅效率低下，还容易出现不一致问题。本文将分享一套基于 Tailwind CSS 插件的解决方案，通过一份配置自动生成多模式颜色变量与工具类，彻底解放重复劳动。

一、方案背景：为什么需要自动化颜色系统？

在传统开发模式中，处理多主题颜色往往面临以下痛点：

  1. 重复编写 CSS：为亮色/暗色模式分别写 .text-primary-light、.text-primary-dark 等类，代码冗余；
  2. 变量管理混乱：手动维护大量 CSS 变量，新增颜色时需同步更新变量、工具类和文档；
  3. 切换逻辑复杂：主题切换时需手动控制多个类名或变量，易漏改；
  4. 一致性难保障：团队协作中，颜色使用规范依赖人工遵守，难以统一。

而本文的方案通过 「一份配置 + 一个插件」，可实现：

  • 自动生成亮色/暗色模式的 CSS 变量；
  • 自动生成 text-xxx/bg-xxx/border-xxx 系列工具类；
  • 支持「品牌色/经典色」双色系切换；
  • 提供固定模式（不随主题变化）的工具类兜底。

二、核心实现：两大核心文件解析

整个方案由「颜色配置文件」和「Tailwind 插件」两部分组成，前者定义颜色规则，后者负责自动化生成。

1. 颜色配置文件：colorTokenConfig.ts

配置文件是整个颜色系统的「数据源」，按「颜色用途」分类（如品牌色、文本色、背景色），每个颜色项包含「亮色值」「暗色值」和「描述」，结构清晰且易于维护。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// colorTokenConfig.ts：定义所有颜色的基础规则
export const colorTokenConfig = {
  // 品牌色：产品主色调，包含默认、悬停、点击等状态
  "Brand": {
    "Normal-1": { "light": "#A7E315", "dark": "#ABE127", "dsc": "品牌色" },
    "Hover-2": { "light": "#BCE752", "dark": "#BCE752", "dsc": "品牌色-悬停" },
    "Click-3": { "light": "#9ACA23", "dark": "#9ACA23", "dsc": "品牌色-点击" },
    "Disable-4": { "light": "#A7E31566", "dark": "#ABE12766", "dsc": "品牌色-禁用" },
    "Container-5": { "light": "#A7E31526", "dark": "#ABE12726", "dsc": "品牌色-容器底" }
  },
  // 文本&图标色：按层级区分（一级/二级/禁用等）
  "Text_Icon": {
    "Primary-1": { "light": "#1B1C23", "dark": "#FAFAFA", "dsc": "一级文字&icon" },
    "Secondary-2": { "light": "#6F727C", "dark": "#A5A6AC", "dsc": "二级文字&icon" },
    "Tertiary-3": { "light": "#9EA0A8", "dark": "#71737A", "dsc": "三级文字&icon" },
    "Disabled-4": { "light": "#C2C3C9", "dark": "#53555A", "dsc": "文字&icon禁用" },
    // ... 其他文本色状态
  },
  // 背景色：按层级区分（整体背景、一级背景、二级背景）
  "Bg": {
    "Whole-1": { "light": "#FFFFFF", "dark": "#101113", "dsc": "整体/交易页面背景" },
    "First-1": { "light": "#F4F5F6", "dark": "#1A1C1E", "dsc": "一级背景（卡片/模块）" },
    "First-2": { "light": "#FFFFFF", "dark": "#1A1C1E", "dsc": "一级背景（弹窗/下拉框）" },
    "Second-3": { "light": "#FFFFFF", "dark": "#26272B", "dsc": "二级背景（子模块）" }
  },
  // 功能色：成功/错误/警告（支持品牌/经典双色系）
  "Success": {
    "Normal-1": {
      "light": { "classic": "#31CAA1", "brand": "#72CC29" }, // 亮色模式：经典色/品牌色
      "dark": { "classic": "#31CAA1", "brand": "#ABE127" },  // 暗色模式：经典色/品牌色
      "dsc": "成功色"
    },
    "Hover-2": {
      "light": { "classic": "#5AD5B4", "brand": "#80D13E" },
      "dark": { "classic": "#5AD5B4", "brand": "#BCE752" },
      "dsc": "成功色-悬停"
    },
    // ... 其他成功色状态
  },
  // ... 其他分类（Fill填充色、Border边框色、Others特殊色、Tab标签色等）
};

配置设计思路：

  • 按「用途」分类（Brand/Text_Icon/Bg），避免颜色混用；
  • 每个颜色项带「状态后缀」（Normal/Hover/Click/Disable），覆盖交互全场景；
  • 关键功能色（Success/Error）支持「双色系」（brand/classic），满足不同品牌需求；
  • 每个项带 dsc 描述，便于团队理解和维护。

2. Tailwind 插件：colorPlugin.ts

插件是自动化的「核心引擎」，通过解析 colorTokenConfig，自动生成：

  • 亮色/暗色模式的 CSS 变量；
  • 双色系（品牌/经典）的切换变量；
  • text-xxx/bg-xxx/border-xxx 工具类；
  • 固定模式（不随主题变化）的工具类。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
// colorPlugin.ts：Tailwind 插件，自动生成变量和工具类
import plugin from 'tailwindcss/plugin';
import { CSSRuleObject } from 'tailwindcss/types/config';
import { safeName } from '../utils'; // 辅助函数：处理类名特殊字符（如斜杠、连字符）
import { colorTokenConfig } from "./colorTokenConfig";

// 定义支持的色系（品牌色/经典色）
type ColorVariant = 'brand' | 'classic';
// 定义颜色模式结构（支持单颜色值或双色系）
type ColorMode = Record<ColorVariant, string>;
type ColorItem = Record<string, { light: string | ColorMode; dark: string | ColorMode; dsc: string }>;

// 插件配置项
export interface ColorProps {
  respectPrefix?: boolean; // 是否尊重 Tailwind 前缀（如自定义 prefix: 'tw-' 时生效）
  defaultVariant?: ColorVariant; // 默认色系（默认 brand）
}

export default plugin.withOptions(
  function (options: ColorProps = {
    respectPrefix: false,
    defaultVariant: 'brand',
  }) {
    return function ({ addBase, addUtilities }) {
      // 1. 初始化变量存储容器
      const lightVars: Record<string, string> = {}; // 亮色模式变量
      const darkVars: Record<string, string> = {};  // 暗色模式变量
      const reverseVariantVars: Record<string, string> = {}; // 反向色系（如默认brand时，reverse为classic）变量
      const reverseVariantDarkVars: Record<string, string> = {}; // 反向色系-暗色模式变量
      const utilities: CSSRuleObject = {}; // 工具类存储

      const colors = colorTokenConfig as unknown as Record<string, ColorItem>;
      const reverseVariant: ColorVariant = options.defaultVariant === 'brand' ? 'classic' : 'brand';

      // 2. 遍历配置，生成变量和工具类
      Object.entries(colors).forEach(([category, colorGroup]) => {
        Object.entries(colorGroup).forEach(([name, colorItem]) => {
          // 生成类名和变量名（如 Brand/Normal-1 → brand-normal-1）
          const className = `${category}/${name}`;
          const varName = `--${safeName(className, true)}`; // 变量名：--brand-normal-1

          // 2.1 处理颜色值（区分单颜色值和双色系）
          // 亮色模式颜色值
          const lightColor = typeof colorItem.light === 'string' 
            ? colorItem.light 
            : colorItem.light[options.defaultVariant];
          // 暗色模式颜色值
          const darkColor = typeof colorItem.dark === 'string' 
            ? colorItem.dark 
            : colorItem.dark[options.defaultVariant];

          // 2.2 存储基础变量（随主题切换）
          lightVars[varName] = `${lightColor} /* ${colorItem.dsc} */`;
          darkVars[varName] = `${darkColor} /* ${colorItem.dsc} */`;

          // 2.3 生成基础工具类（text-xxx/bg-xxx/border-xxx）
          utilities[`.text-${safeName(className)}`] = { color: `var(${varName})` };
          utilities[`.bg-${safeName(className)}`] = { backgroundColor: `var(${varName})` };
          utilities[`.border-${safeName(className)}`] = { borderColor: `var(${varName})` };

          // 2.4 处理双色系：生成反向色系变量（如品牌色→经典色）
          if (typeof colorItem.light !== 'string') {
            reverseVariantVars[varName] = `${colorItem.light[reverseVariant]} /* ${reverseVariant}模式: ${colorItem.dsc} */`;
          }
          if (typeof colorItem.dark !== 'string') {
            reverseVariantDarkVars[varName] = `${colorItem.dark[reverseVariant]} /* ${reverseVariant}模式: ${colorItem.dsc} */`;
          }

          // 2.5 生成固定模式工具类（不随主题切换，如 .text-light-brand-normal-1）
          ['light', 'dark'].forEach((mode) => {
            const fixedColor = colorItem[mode as keyof typeof colorItem];
            const fixedClassName = `.text-${mode}-${safeName(className)}`;
            const fixedBgClassName = `.bg-${mode}-${safeName(className)}`;
            const fixedBorderClassName = `.border-${mode}-${safeName(className)}`;

            // 固定模式颜色值（区分单颜色值和双色系）
            const fixedColorValue = typeof fixedColor === 'string' 
              ? fixedColor 
              : fixedColor[options.defaultVariant];

            // 存储固定模式工具类
            utilities[fixedClassName] = { color: fixedColorValue };
            utilities[fixedBgClassName] = { backgroundColor: fixedColorValue };
            utilities[fixedBorderClassName] = { borderColor: fixedColorValue };

            // 存储固定模式变量（如 --light-brand-normal-1）
            const staticVarName = `--${mode}-${safeName(className, true)}`;
            lightVars[staticVarName] = `${fixedColorValue} /* ${mode}模式固定颜色：${colorItem.dsc} */`;

            // 双色系场景：生成反向色系的固定变量
            if (typeof fixedColor !== 'string') {
              reverseVariantVars[staticVarName] = `${fixedColor[reverseVariant]} /* ${mode}模式-${reverseVariant}色系：${colorItem.dsc} */`;
            }
          });
        });
      });

      // 3. 注入变量到全局（addBase：添加基础样式，如 :root、[data-theme=dark]）
      addBase({
        ':root': lightVars, // 亮色模式（默认）
        '[data-theme=dark]': darkVars, // 暗色模式（通过 data-theme="dark" 激活）
        [`[data-variant=${reverseVariant}]`]: reverseVariantVars, // 反向色系（默认品牌色时，激活经典色）
        [`[data-variant=${reverseVariant}][data-theme=dark]`]: reverseVariantDarkVars, // 反向色系+暗色模式
      });

      // 4. 注入工具类到 Tailwind（addUtilities：添加自定义工具类）
      addUtilities(utilities, {
        respectPrefix: options.respectPrefix, // 尊重 Tailwind 前缀配置
      });
    };
  }
);

插件核心逻辑：

  1. 变量生成：遍历配置，为每个颜色项生成 --xxx 格式的 CSS 变量，区分亮色/暗色/反向色系；
  2. 工具类生成：基于变量生成 text-xxx/bg-xxx/border-xxx 工具类，直接映射变量值；
  3. 固定模式处理：生成 text-light-xxx/bg-dark-xxx 等固定模式工具类，避免主题切换影响；
  4. 双色系支持：通过 data-variant 属性切换反向色系，无需修改工具类。

三、实际使用：3 步上手多模式颜色系统

配置和插件开发完成后，前端项目中只需 3 步即可使用多模式颜色系统。

1. 注册插件到 Tailwind 配置

在 tailwind.config.ts 中引入插件，完成注册：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// tailwind.config.ts
import type { Config } from 'tailwindcss';
import colorPlugin from './plugins/colorPlugin'; // 引入自定义颜色插件

export default {
  content: ["./src/**/*.{html,js,jsx,ts,tsx}"], // 扫描文件范围
  theme: {
    extend: {},
  },
  plugins: [
    colorPlugin({ // 注册插件，可配置默认参数
      respectPrefix: false,
      defaultVariant: 'brand', // 默认使用品牌色
    }),
  ],
  darkMode: 'class', // 启用 class 模式的暗色支持（与 data-theme 配合）
} satisfies Config;

2. 切换主题模式

通过给根元素（如 <html> 或 <body>）添加 data-theme 和 data-variant 属性，即可切换主题：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!-- 1. 默认模式：亮色 + 品牌色 -->
<html>
  <div class="text-Brand/Normal-1 bg-Bg/Whole-1">默认样式</div>
</html>

<!-- 2. 暗色模式：暗色 + 品牌色 -->
<html data-theme="dark">
  <div class="text-Brand/Normal-1 bg-Bg/Whole-1">暗色样式</div>
</html>

<!-- 3. 经典色模式：亮色 + 经典色 -->
<html data-variant="classic">
  <div class="text-Success/Normal-1">经典色-成功文本</div>
</html>

<!-- 4. 暗色+经典色模式 -->
<html data-theme="dark" data-variant="classic">
  <div class="text-Success/Normal-1 bg-Bg/Whole-1">暗色+经典色样式</div>
</html>

切换逻辑建议：

  • 在 React/Vue 等框架中，可通过状态管理（如 useState、Pinia）控制根元素属性；
  • 示例（React）：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    import { useEffect, useState } from 'react';

    function App() {
      const [isDark, setIsDark] = useState(false);
      const [isClassic, setIsClassic] = useState(false);

      // 监听状态变化，更新根元素属性
      useEffect(() => {
        const html = document.documentElement;
        if (isDark) html.setAttribute('data-theme', 'dark');
        else html.removeAttribute('data-theme');

        if (isClassic) html.setAttribute('data-variant', 'classic');
        else html.removeAttribute('data-variant');
      }, [isDark, isClassic]);

      return (
        <div>
          <button onClick={() => setIsDark(!isDark)}>切换明暗</button>
          <button onClick={() => setIsClassic(!isClassic)}>切换色系</button>
          <div class="text-Brand/Normal-1 bg-Bg/Whole-1 p-4">内容区域</div>
        </div>
      );
    }

3. 使用工具类编写样式

直接在 HTML/JSX 中使用插件生成的工具类，无需手写 CSS：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// 示例：一个带交互的按钮组件
function Button() {
  return (
    <button className="
      text-Text_Icon/Button_Normal-8 
      bg-Brand/Normal-1 
      hover:bg-Brand/Hover-2 
      active:bg-Brand/Click-3 
      disabled:bg-Brand/Disable-4 
      disabled:text-Text_Icon/Button_Disabled-9
      border-none 
      px-4
      py-2 
      rounded-md
    ">
      确认按钮
    </button>
  );
}

// 示例：带状态提示的卡片
function StatusCard({ isSuccess }) {
  return (
    <div className="
      bg-Bg/First-1 
      border border-Border/Normal-1 
      rounded-lg 
      p-4
    ">
      <div className={`
        text-Text_Icon/Primary-1 
        mb-2
      `}>
        操作结果
      </div>
      <div className={`
        text-${isSuccess ? 'Success/Normal-1' : 'Error/Normal-1'}
      `}>
        {isSuccess ? '操作成功' : '操作失败，请重试'}
      </div>
    </div>
  );
}

工具类使用规则：

  • 基础格式：text-【分类名】/【颜色名】、bg-【分类名】/【颜色名】、border-【分类名】/【颜色名】（如 text-Brand/Normal-1）；
  • 固定模式：在分类名前加 light- 或 dark-，强制使用对应模式颜色（如 text-light-Text_Icon/Primary-1，即使切换到暗色模式仍保持亮色文本）；
  • 交互状态：结合 Tailwind 原生 hover:/active:/disabled: 前缀，实现状态切换（如 hover:bg-Brand/Hover-2）。

四、方案优势：为什么值得用？

相比传统手动维护颜色的方式，这套自动化方案有 4 个核心优势：

1. 一致性：从源头统一颜色规范

  • 所有颜色都来自 colorTokenConfig 单一数据源，避免团队成员随意使用色值；
  • 工具类命名遵循「分类+用途」规则（如 text-Text_Icon/Primary-1 明确是「文本图标类-一级文本」），新人也能快速理解颜色用途，减少「凭感觉选色」的问题。

2. 效率：减少 80% 重复工作

  • 新增颜色时，只需在 colorTokenConfig 中添加一条配置，插件自动生成变量和工具类，无需手动写 CSS；
  • 切换主题/色系时，只需修改根元素的 data-theme/data-variant 属性，全局样式自动同步，无需逐个组件调整。

3. 灵活性：支持多场景定制

  • 双色系切换：通过 data-variant 轻松实现「品牌色」与「经典色」的切换，满足不同业务场景（如白标产品、活动专题）；
  • 固定模式兜底：提供 light-/dark- 前缀工具类，应对「局部不随主题变化」的特殊需求（如 Logo 文本、品牌标识）。

4. 可维护性：降低后期迭代成本

  • 文档自解释：colorTokenConfig 中每个颜色项都有 dsc 描述，相当于内置了颜色文档，无需额外维护独立文档；
  • 修改成本低：若需调整某个颜色（如品牌色从 #A7E315 改为 #A0D911），只需修改 colorTokenConfig 中 Brand/Normal-1 的值，全局所有使用该颜色的地方自动更新，避免漏改。

五、扩展场景：让颜色系统更强大

这套方案还能根据业务需求扩展，满足更复杂的场景：

1. 支持更多色系（如「活动色」）

若需要临时添加「活动专题色系」，只需两步：

  1. 在 colorTokenConfig 中新增支持多色系的颜色项（参考 Success 分类）：

    1
    2
    3
    4
    5
    6
    7
    "Promotion": {
      "Normal-1": {
        "light": { "brand": "#A7E315", "promo": "#FF4500" },
        "dark": { "brand": "#ABE127", "promo": "#FF6347" },
        "dsc": "活动色"
      }
    }

  2. 在插件配置中扩展 ColorVariant 类型：

    1
    type ColorVariant = 'brand' | 'classic' | 'promo';

  3. 切换时添加 data-variant="promo" 即可激活活动色系。

2. 生成渐变色工具类

若需要支持渐变色，可在插件中扩展逻辑，解析配置中的渐变色规则并生成工具类：

1
2
3
4
5
6
7
8
9
10
11
// 1. 在 colorTokenConfig 中添加渐变色配置
"Gradient": {
  "Brand-1": {
    "light": "linear-gradient(90deg, #A7E315, #ABE127)",
    "dark": "linear-gradient(90deg, #ABE127, #BCE752)",
    "dsc": "品牌渐变色"
  }
}

// 2. 在插件中添加渐变色工具类生成逻辑
utilities[`.bg-gradient-${safeName(className)}`] = { backgroundImage: `var(${varName})` };

使用时直接调用：bg-gradient-Gradient/Brand-1。

3. 结合设计 tokens 工具

若团队使用 Figma 等设计工具，可通过「设计 tokens 同步工具」（如 Style Dictionary）将 Figma 中的颜色 tokens 自动同步到 colorTokenConfig.ts，实现「设计-开发」颜色无缝衔接，彻底避免「设计稿与代码色值不一致」的问题。

六、总结：从 0 到 1 搭建颜色系统的关键

搭建一套可靠的多模式颜色系统，核心不是写复杂的代码，而是遵循「单一数据源 + 自动化生成 + 场景化设计」的思路：

  1. 单一数据源：用 colorTokenConfig 统一管理所有颜色，避免分散维护；
  2. 自动化生成：用 Tailwind 插件将配置转化为可直接使用的工具类，减少重复劳动；
  3. 场景化设计：按「用途+状态+模式」设计配置结构，满足交互、主题切换等实际需求。

这套方案不仅能解决当前多主题颜色维护的痛点，还能随着业务增长灵活扩展，是前端工程化中「样式统一」的重要实践。如果你的项目需要支持亮色/暗色模式、多品牌色系，不妨试试这套方案！




FEATURED TAGS
CSS
FRIENDS