# shadcn UI 配色系统完整指南

## 概述

shadcn UI 使用基于 CSS 变量的分层配色系统，通过语义化的变量名来管理整个应用的色彩方案。系统分为亮色主题（`:root`）和暗色主题（`.dark`）两套配色。

## 🎨 颜色层级分类

### 1. 核心系统颜色 (Core System Colors)

#### 主要交互色 (Primary Colors)
- **`--primary`**: 应用主题色，用于最重要的交互元素
  - 亮色: `hsl(349.5238 100% 87.6471%)` - 粉红色
  - 暗色: `hsl(330 100.0000% 80%)` - 粉红色
- **`--primary-foreground`**: 主要色上的文字/图标颜色
  - 亮色: `hsl(0 0% 0%)` - 黑色
  - 暗色: `hsl(0 0% 0%)` - 黑色

**用途**: 按钮、链接、选中状态、重要高亮等主要交互元素

#### 次要交互色 (Secondary Colors)
- **`--secondary`**: 次要按钮和元素背景色
  - 亮色: `hsl(197.4000 71.4286% 72.5490%)` - 蓝色
  - 暗色: `hsl(120 60.0000% 50%)` - 绿色
- **`--secondary-foreground`**: 次要色上的文字/图标颜色
  - 亮色: `hsl(0 0% 0%)` - 黑色
  - 暗色: `hsl(0 0% 0%)` - 黑色

**用途**: 次要按钮、标签、分页器等辅助交互元素

#### 强调色 (Accent Colors)
- **`--accent`**: 悬停和强调状态
  - 亮色: `hsl(60 100% 50%)` - 黄色
  - 暗色: `hsl(197.4000 71.4286% 72.5490%)` - 蓝色
- **`--accent-foreground`**: 强调色上的文字/图标颜色
  - 亮色: `hsl(0 0% 0%)` - 黑色
  - 暗色: `hsl(0 0% 0%)` - 黑色

**用途**: 悬停状态、选中背景、高亮区域

### 2. 背景和前景色 (Background & Foreground)

#### 基础背景色
- **`--background`**: 应用主背景色
  - 亮色: `hsl(200 23.0769% 97.4510%)` - 浅蓝灰
  - 暗色: `hsl(220.0000 14.7541% 11.9608%)` - 深蓝灰
- **`--foreground`**: 主要文字颜色
  - 亮色: `hsl(0 0% 20%)` - 深灰
  - 暗色: `hsl(0 0% 89.8039%)` - 浅灰

#### 卡片背景色
- **`--card`**: 卡片和弹出层背景
  - 亮色: `hsl(0 0% 100%)` - 纯白
  - 暗色: `hsl(197.1429 6.9307% 19.8039%)` - 深蓝灰
- **`--card-foreground`**: 卡片上的文字颜色
  - 亮色: `hsl(0 0% 20%)` - 深灰
  - 暗色: `hsl(0 0% 89.8039%)` - 浅灰

#### 弹出层背景色
- **`--popover`**: 弹出层、下拉菜单背景
  - 亮色: `hsl(0 0% 100%)` - 纯白
  - 暗色: `hsl(197.1429 6.9307% 19.8039%)` - 深蓝灰
- **`--popover-foreground`**: 弹出层文字颜色
  - 亮色: `hsl(0 0% 20%)` - 深灰
  - 暗色: `hsl(0 0% 89.8039%)` - 浅灰

### 3. 弱化和辅助色 (Muted & Support)

#### 弱化元素
- **`--muted`**: 弱化背景色
  - 亮色: `hsl(50.4000 26.8817% 81.7647%)` - 浅黄灰
  - 暗色: `hsl(0 0% 26.6667%)` - 深灰
- **`--muted-foreground`**: 弱化文字颜色
  - 亮色: `hsl(0 0% 43.1373%)` - 中灰
  - 暗色: `hsl(0 0% 63.9216%)` - 中浅灰

**用途**: 禁用状态、占位符、不重要的信息

### 4. 边框和输入色 (Border & Input)

- **`--border`**: 边框颜色
  - 亮色: `hsl(0 0% 83.1373%)` - 浅灰
  - 暗色: `hsl(0 0% 26.6667%)` - 深灰
- **`--input`**: 输入框边框色
  - 亮色: `hsl(0 0% 83.1373%)` - 浅灰
  - 暗色: `hsl(0 0% 26.6667%)` - 深灰

### 5. 危险和警告色 (Destructive)

- **`--destructive`**: 危险操作色（删除、警告等）
  - 亮色: `hsl(0 84.2365% 60.1961%)` - 红色
  - 暗色: `hsl(0 84.2365% 60.1961%)` - 红色
- **`--destructive-foreground`**: 危险色上的文字颜色
  - 亮色: `hsl(0 0% 100%)` - 白色
  - 暗色: `hsl(0 0% 100%)` - 白色

**用途**: 删除按钮、错误提示、警告信息

### 6. 焦点和环色 (Ring)

- **`--ring`**: 焦点环颜色
  - 亮色: `hsl(349.5238 100% 87.6471%)` - 粉红色
  - 暗色: `hsl(330 100.0000% 80%)` - 粉红色

**用途**: 键盘焦点环、表单验证高亮

### 7. 图表色 (Chart Colors)

- **`--chart-1`**: 图表主色 (粉色系)
- **`--chart-2`**: 图表次要色 (蓝色/绿色系)
- **`--chart-3`**: 图表第三色 (黄色/蓝色系)
- **`--chart-4`**: 图表第四色 (黄色系)
- **`--chart-5`**: 图表第五色 (黄绿色系)

### 8. 侧边栏色 (Sidebar Colors)

- **`--sidebar`**: 侧边栏背景色
- **`--sidebar-foreground`**: 侧边栏文字色
- **`--sidebar-primary`**: 侧边栏主要交互色
- **`--sidebar-primary-foreground`**: 侧边栏主要文字色
- **`--sidebar-accent`**: 侧边栏强调色
- **`--sidebar-accent-foreground`**: 侧边栏强调文字色
- **`--sidebar-border`**: 侧边栏边框色
- **`--sidebar-ring`**: 侧边栏焦点环色

## 🏗️ 使用优先级和层级

### 1. 主要色 (Primary) - 最高优先级
- 主按钮
- 重要链接
- 选中状态
- 进度指示器
- 主要数据展示

### 2. 次要色 (Secondary) - 中等优先级
- 次要按钮
- 标签和徽章
- 分页组件
- 辅助交互元素

### 3. 强调色 (Accent) - 低优先级
- 悬停状态
- 选中背景
- 高亮区域
- 过渡效果

### 4. 弱化色 (Muted) - 最低优先级
- 禁用状态
- 占位符文本
- 辅助信息
- 背景装饰

## 🎯 实际应用示例

### 按钮组件
```jsx
// 主要按钮
<button className="bg-primary text-primary-foreground hover:bg-primary/90">
  主要操作
</button>

// 次要按钮
<button className="bg-secondary text-secondary-foreground hover:bg-secondary/80">
  次要操作
</button>

// 危险按钮
<button className="bg-destructive text-destructive-foreground hover:bg-destructive/90">
  删除
</button>
```

### 卡片组件
```jsx
<div className="bg-card text-card-foreground border border-border rounded-lg p-4">
  <h2 className="text-foreground">卡片标题</h2>
  <p className="text-muted-foreground">辅助信息</p>
</div>
```

### 输入框组件
```jsx
<input className="bg-background text-foreground border border-input focus:ring-2 focus:ring-ring"
       placeholder="占位符文本" />
```

## 🌓 主题切换原理

系统通过 CSS 变量实现主题切换：

```css
/* 亮色主题 */
:root {
  --background: hsl(200 23.0769% 97.4510%);
  --foreground: hsl(0 0% 20%);
  /* ... */
}

/* 暗色主题 */
.dark {
  --background: hsl(220.0000 14.7541% 11.9608%);
  --foreground: hsl(0 0% 89.8039%);
  /* ... */
}
```

当 HTML 元素添加 `.dark` 类时，所有使用这些变量的组件都会自动切换颜色。

## 🎨 定制建议

### 1. 保持语义化
- 保持变量名的语义含义，不要为了视觉效果而改变变量用途
- `primary` 始终用于主要交互，`destructive` 始终用于危险操作

### 2. 确保对比度
- 确保 `*-foreground` 颜色与对应的背景色有足够的对比度
- 在两个主题下都要测试可读性

### 3. 渐进增强
- 先定义好核心颜色，再扩展其他颜色
- 使用 HSL 色彩空间便于调整饱和度和亮度

### 4. 一致性原则
- 保持相同类型的组件使用相同的颜色变量
- 避免在组件中硬编码颜色值

## 🔧 维护工具

### 检查颜色使用
```bash
# 查找所有使用 primary 变量的地方
grep -r "bg-primary\|text-primary\|border-primary" src/
```

### 主题切换测试
1. 在浏览器开发者工具中切换 HTML 元素的 class
2. 检查所有组件的颜色是否正确切换
3. 验证对比度和可读性

---

*本文档基于 shadcn UI 标准配色系统编写，适用于 React + Tailwind CSS 项目。*