docs/v1.0/client/rfcs/103-fix-css-variables.md

CSS 变量清理与主题自定义方案

修复时间

2025-01-14

问题描述

globals.css 中存在两套颜色系统：

1. Tailwind v4 主题变量（@theme 块中的 --color-*）- 被项目广泛使用
2. 自定义 CSS 变量（:root 中的 --primary-*, --accent-*, --text-*, --bg-*）- 未被使用

这导致：

• 代码冗余，维护困难
• 变量命名不够语义化
• 两套系统并存容易混淆

解决方案

1. 清理冗余变量

删除的变量（未在项目中使用）：

/* 已删除 */
--primary-100: #2563eb;
--primary-200: #598ef3;
--primary-300: #d3e6fe;
--accent-100: #d946ef;
--accent-200: #fae8ff;
--text-100: #cbd5e1;
--text-200: #94a3b8;
--bg-100: #1e293b;
--bg-200: #334155;
--bg-300: #475569;

2. 统一到 Tailwind v4 主题系统

迁移的变量：

• 功能色（success/warning/error/info）→ 移入 @theme 块
• 轨道颜色（track-*）→ 移入 @theme 块
• 布局尺寸 → 保留在 :root（非颜色变量）

3. 优化注释和结构

为每个变量添加清晰的注释，方便自定义。

如何自定义主题色

方法 1：修改主色调（推荐）

在 globals.css 的 @theme 块中修改：

@theme {
  /* 深色主题 */
  --color-primary: #2563eb; /* 改为你的品牌色，如 #ff6b6b */
  --color-primary-foreground: #ffffff; /* 主色上的文字颜色 */

  --color-accent: var(--color-primary); /* 强调色默认使用主色 */
  /* 或单独设置：--color-accent: #d946ef; */
}

.light {
  /* 亮色主题 */
  --color-primary: #2563eb; /* 亮色主题的主色 */
  --color-accent: #d946ef; /* 亮色主题的强调色 */
}

方法 2：使用 Tailwind 类名

修改主题变量后，直接使用 Tailwind 类名：

// 自动使用你自定义的主色
<button className="bg-primary text-primary-foreground">
  按钮
</button>

// 使用强调色
<div className="bg-accent text-accent-foreground">
  高亮内容
</div>

// 使用功能色
<span className="text-success">成功</span>
<span className="text-warning">警告</span>
<span className="text-error">错误</span>

方法 3：添加自定义颜色

如需添加新的颜色变量，在 @theme 块中定义：

@theme {
  /* 自定义品牌色 */
  --color-brand: #ff6b6b;
  --color-brand-foreground: #ffffff;

  /* 自定义渐变色 */
  --color-gradient-start: #667eea;
  --color-gradient-end: #764ba2;
}

然后在组件中使用：

<div className="bg-brand text-brand-foreground">品牌色按钮</div>

方法 4：使用轨道颜色

时间轴编辑器的轨道颜色已内置：

// 直接使用 CSS 变量
<div style={{ backgroundColor: 'var(--color-track-video)' }}>
  视频轨道
</div>

// 或在 Tailwind 中使用
<div className="bg-[var(--color-track-storyboard)]">
  分镜轨道
</div>

可用的颜色变量

语义化颜色（推荐使用）

变量名	Tailwind 类名	用途
--color-primary	bg-primary text-primary	主色/品牌色
--color-secondary	bg-secondary text-secondary	次要元素
--color-accent	bg-accent text-accent	强调/高亮
--color-muted	bg-muted text-muted-foreground	低对比度元素
--color-destructive	bg-destructive text-destructive	危险操作
--color-background	bg-background	主背景
--color-foreground	text-foreground	主文字
--color-card	bg-card	卡片背景
--color-border	border-border	边框

功能色

变量名	Tailwind 类名	用途
--color-success	text-success	成功状态
--color-warning	text-warning	警告状态
--color-error	text-error	错误状态
--color-info	text-info	信息提示

轨道颜色

变量名	用途
--color-track-storyboard	分镜轨道
--color-track-resource	资源轨道
--color-track-video	视频轨道
--color-track-sound	音效轨道
--color-track-subtitle	字幕轨道
--color-track-voice	配音轨道

主题切换

项目支持深色/亮色主题切换，通过 .light 类名控制：

// 在根元素添加/移除 .light 类
document.documentElement.classList.toggle("light");

影响范围

• ✅ 删除了 10 个未使用的变量
• ✅ 将功能色和轨道色迁移到 Tailwind 主题系统
• ✅ 优化了注释，提升可维护性
• ✅ 无破坏性变更（删除的都是未使用的变量）

验证

# 搜索是否有遗漏的旧变量使用
cd client
grep -r "var(--primary-[0-9]" src/
grep -r "var(--accent-[0-9]" src/
grep -r "var(--text-[0-9]" src/
grep -r "var(--bg-[0-9]" src/

预期结果：无匹配项

相关文件

• client/src/styles/globals.css - 主题配置文件
• client/vite.config.ts - Tailwind v4 配置
• client/package.json - 依赖版本

参考资料

• Tailwind CSS v4 文档
• Tailwind CSS 主题配置