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

## 修复时间

2025-01-14

## 问题描述

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

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

这导致：

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

## 解决方案

### 1. 清理冗余变量

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

```css
/* 已删除 */
--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` 块中修改：

```css
@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 类名：

```tsx
// 自动使用你自定义的主色
<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` 块中定义：

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

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

然后在组件中使用：

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

### 方法 4：使用轨道颜色

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

```tsx
// 直接使用 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` 类名控制：

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

## 影响范围

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

## 验证

```bash
# 搜索是否有遗漏的旧变量使用
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 文档](https://tailwindcss.com/docs/v4-beta)
- [Tailwind CSS 主题配置](https://tailwindcss.com/docs/theme)