# Forge Color Token Guide

> 本文档定义 Forge 设计系统的颜色使用规范。新代码应遵循此规范；旧代码逐步迁移。

---

## 原则

1. **语义优先**：新代码优先使用语义颜色名（`accent-brand`、`accent-success` 等），而非色相名（`indigo`、`green` 等）。
2. **向后兼容**：现有 `indigo` / `green` / `amber` / `coral` 引用暂时保留，新功能不新增色相名引用。
3. **一组件一色调**：单个组件内不要混用色相名和语义名。

---

## Token 层级

### 1. 表面色（Surface）

| Token | 用途 |
|---|---|
| `bg-page` | 页面底层背景 |
| `bg-surface` / `surface-1` | 一级表面（侧边栏、面板） |
| `bg-elevated` / `surface-2` | 二级表面（卡片、输入框背景） |
| `bg-hover` / `surface-3` | Hover 状态背景 |
| `bg-active` / `surface-4` | Active/选中状态背景 |

### 2. 文字色（Ink）

| Token | 用途 |
|---|---|
| `text-primary` | 主标题、重要文字 |
| `text-secondary` | 正文、次要信息 |
| `text-tertiary` | 辅助文字、图标默认色 |
| `text-muted` | 禁用、placeholder、时间戳 |

### 3. 语义强调色（Semantic Accents）⭐ 新代码优先使用

| Token | 语义 | 对应旧色相 | 使用场景 |
|---|---|---|---|
| `accent-brand` | 品牌主色 | `indigo` | 主按钮、链接、选中态、焦点环 |
| `accent-success` | 成功 | `green` | 成功状态、完成图标、通过 badge |
| `accent-warning` | 警告 | `amber` | 警告状态、需谨慎的操作 |
| `accent-danger` | 危险/错误 | `coral` | 删除按钮、错误提示、失败 badge |

### 4. 品牌按钮状态阶梯（Button States）

| Token | 用途 |
|---|---|
| `brand-primary` | 主按钮背景 |
| `brand-primary-hover` | 主按钮 Hover |
| `brand-primary-active` | 主按钮 Active |
| `brand-primary-subtle` | 主色浅底（badge info、选中背景） |
| `on-primary` | 主按钮上的文字/图标 |

---

## 使用示例

### ✅ 推荐（新代码）

```tsx
// Badge
<Badge tone="success" />   // 内部使用 accent-success
<Badge tone="error" />     // 内部使用 accent-danger

// Button
<Button variant="danger" /> // 内部使用 accent-danger

// 自定义组件
<span className="text-accent-warning">需谨慎</span>
<div className="bg-accent-success/10 text-accent-success">已完成</div>
```

### ⚠️ 兼容（旧代码，逐步迁移）

```tsx
// 以下写法仍可用，但新功能不应新增
<span className="text-green">成功</span>
<span className="text-coral">错误</span>
<span className="text-indigo">链接</span>
```

### ❌ 禁止

```tsx
// 不要为同一个语义创建新的色相名
<span className="text-purple-500">主色</span>

// 不要在同一组件中混用两套命名
<div className="text-accent-success">
  <span className="text-green">子元素</span>  {/* 混用 */}
</div>
```

---

## 迁移路线图

| 阶段 | 范围 | 状态 |
|---|---|---|
| ✅ 建立 token 体系 | `globals.css` + `tailwind.config.ts` | 已完成 |
| ✅ 示范组件迁移 | `button.tsx`（danger）、`badge.tsx`（success/warning/error） | 已完成 |
| ⏳ 核心组件迁移 | `input.tsx`（invalid 状态）、`chat-view.tsx`（状态色） | 待排期 |
| ⏳ 全局搜索替换 | 剩余 250+ 处旧色相名引用 | 待排期，逐步进行 |

---

## 主题切换

所有语义 token 均通过 CSS 变量实现，Light/Dark 主题在 `:root` 和 `[data-theme="light"]` 中分别定义变量值即可自动适配。