# 🎨 主题变量快速参考卡

## 常用替换速查表

### 📦 背景色

| 用途 | 旧写法 | ✅ 新写法 | 说明 |
|------|--------|----------|------|
| 信息框/卡片 | `bg-gray-50` | `bg-muted` | 自动适配明暗 |
| 信息框/卡片 | `bg-gray-100` | `bg-muted` | 自动适配明暗 |
| 主背景 | `bg-white dark:bg-gray-900` | `bg-background` | 自动适配 |
| 卡片背景 | `bg-white dark:bg-gray-800` | `bg-card` | 自动适配 |
| 弹窗背景 | `bg-white dark:bg-gray-800` | `bg-popover` | 自动适配 |
| 次要背景 | `bg-gray-100 dark:bg-gray-700` | `bg-secondary` | 自动适配 |
| 强调背景 | `bg-gray-50 dark:bg-gray-700` | `bg-accent` | 自动适配 |

### 🖱️ 交互效果

| 用途 | 旧写法 | ✅ 新写法 | 说明 |
|------|--------|----------|------|
| 悬停高亮 | `hover:bg-gray-50` | `hover:bg-accent` | 轻微高亮 |
| 悬停高亮 | `hover:bg-gray-100` | `hover:bg-accent` | 轻微高亮 |
| 激活状态 | `active:bg-gray-200` | `active:bg-accent` | 按下效果 |

### 📝 文字颜色

| 用途 | 旧写法 | ✅ 新写法 | 说明 |
|------|--------|----------|------|
| 主文字 | `text-gray-900 dark:text-white` | `text-foreground` | 自动适配 |
| 辅助文字 | `text-gray-600 dark:text-gray-400` | `text-muted-foreground` | 自动适配 |
| 卡片文字 | `text-gray-900 dark:text-gray-100` | `text-card-foreground` | 自动适配 |
| 主按钮文字 | `text-white dark:text-gray-900` | `text-primary-foreground` | 自动适配 |

### 🎨 状态色（保持不变）

| 状态 | 类名 | 说明 |
|------|------|------|
| ✅ 成功/激活 | `bg-green-100 text-green-800` | 保持不变 |
| ❌ 错误/危险 | `bg-red-100 text-red-800` | 保持不变 |
| ⚠️ 告警 | `bg-orange-100 text-orange-800` | 保持不变 |
| 💡 警告 | `bg-yellow-100 text-yellow-800` | 保持不变 |
| ℹ️ 信息 | `bg-blue-100 text-blue-800` | 保持不变 |
| ⚪ 离线/禁用 | `bg-gray-100 text-gray-800` | 保持不变 |
| 💜 其他 | `bg-purple-100 text-purple-800` | 保持不变 |

### 🔲 边框

| 用途 | 旧写法 | ✅ 新写法 | 说明 |
|------|--------|----------|------|
| 普通边框 | `border-gray-200 dark:border-gray-700` | `border` | 自动适配 |
| 输入框边框 | `border-gray-300 dark:border-gray-600` | `border-input` | 自动适配 |

### 📝 特殊组件

| 组件 | 旧写法 | ✅ 新写法 | 说明 |
|------|--------|----------|------|
| 代码块 | `bg-gray-100` | `bg-muted` | 自动适配 |
| 字段值 | `field-value bg-gray-50` | `field-value` | 已含bg-muted |
| 输入框 | `bg-gray-50 dark:bg-gray-800` | `bg-input-background` | 自动适配 |

---

## 🚫 禁止使用的写法

```tsx
❌ className="bg-gray-50 dark:bg-gray-800"
❌ className="bg-white dark:bg-gray-900"
❌ className="text-gray-900 dark:text-white"
❌ className="hover:bg-gray-50 dark:hover:bg-gray-700"
❌ className="border-gray-200 dark:border-gray-700"
```

**原因：** 手动定义dark模式维护成本高，且不统一

---

## ✅ 推荐使用的写法

```tsx
✅ className="bg-muted"
✅ className="bg-background"
✅ className="text-foreground"
✅ className="hover:bg-accent"
✅ className="border"
```

**原因：** 自动适配明暗模式，统一主题管理

---

## 📋 常见场景示例

### 场景1：信息展示卡片
```tsx
// ❌ 旧写法
<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700">
  <p className="text-gray-900 dark:text-white">标题</p>
  <p className="text-gray-600 dark:text-gray-400">描述</p>
</div>

// ✅ 新写法
<div className="p-4 bg-muted rounded-lg border">
  <p className="text-foreground">标题</p>
  <p className="text-muted-foreground">描述</p>
</div>
```

### 场景2：列表项悬停
```tsx
// ❌ 旧写法
<div className="p-3 hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
  内容
</div>

// ✅ 新写法
<div className="p-3 hover:bg-accent transition-colors">
  内容
</div>
```

### 场景3：代码块
```tsx
// ❌ 旧写法
<code className="bg-gray-100 dark:bg-gray-800 px-2 py-1 rounded text-sm">
  CODE-001
</code>

// ✅ 新写法
<code className="bg-muted px-2 py-1 rounded text-sm">
  CODE-001
</code>
```

### 场景4：表单字段
```tsx
// ❌ 旧写法
<div className="mt-2 bg-gray-50 dark:bg-gray-800 px-3 py-2 rounded">
  {value}
</div>

// ✅ 新写法（使用预定义类）
<div className="field-value">
  {value}
</div>
```

### 场景5：状态Badge（保持不变）
```tsx
// ✅ 正确写法（状态色不变）
<Badge className="bg-green-100 text-green-800">成功</Badge>
<Badge className="bg-red-100 text-red-800">失败</Badge>
<Badge className="bg-orange-100 text-orange-800">告警</Badge>
<Badge className="bg-gray-100 text-gray-800">离线</Badge>
```

---

## 🎯 主题变量完整列表

### CSS变量（仅供参考）
```css
/* 明亮模式 */
--background: #ffffff;
--foreground: oklch(0.145 0 0);
--card: #ffffff;
--muted: #ececf0;
--muted-foreground: #717182;
--accent: #e9ebef;
--border: rgba(0, 0, 0, 0.1);

/* 暗黑模式 */
--background: #0f1419;
--foreground: #e7e9ea;
--card: #1a1f26;
--muted: #374151;
--muted-foreground: #9ca3af;
--accent: #1f2937;
--border: rgba(255, 255, 255, 0.1);
```

### Tailwind类名映射
```
bg-background → var(--background)
bg-muted → var(--muted)
bg-accent → var(--accent)
bg-card → var(--card)
text-foreground → var(--foreground)
text-muted-foreground → var(--muted-foreground)
border → var(--border)
```

---

## 💡 开发建议

### 1. 新组件开发
```tsx
// 推荐模板
export function MyComponent() {
  return (
    <Card className="p-4">
      <h3 className="text-foreground">标题</h3>
      <div className="mt-3 p-3 bg-muted rounded">
        <p className="text-muted-foreground">描述文字</p>
      </div>
      <Button className="mt-4">操作</Button>
    </Card>
  );
}
```

### 2. 列表组件
```tsx
// 推荐模式
{items.map(item => (
  <div 
    key={item.id}
    className="p-3 hover:bg-accent transition-colors rounded cursor-pointer"
  >
    <div className="flex items-center justify-between">
      <span className="text-foreground">{item.name}</span>
      <Badge className="bg-green-100 text-green-800">{item.status}</Badge>
    </div>
  </div>
))}
```

### 3. 表单展示
```tsx
// 推荐模式
<div className="space-y-4">
  <div>
    <Label>用户名</Label>
    <div className="field-value">{user.name}</div>
  </div>
  <div>
    <Label>邮箱</Label>
    <div className="field-value">{user.email}</div>
  </div>
</div>
```

---

## 🔍 快速检查工具

### VSCode正则搜索
```regex
# 查找需要替换的bg-gray-50（排除状态色）
bg-gray-50(?!\/50)

# 查找需要替换的bg-gray-100（排除状态色）
bg-gray-100(?!\s+text-gray-)

# 查找手动定义的dark模式
dark:bg-gray-\d+
```

### 命令行搜索
```bash
# 搜索所有bg-gray-50
grep -r "bg-gray-50" components/

# 搜索dark:bg-
grep -r "dark:bg-" components/

# 统计使用次数
grep -r "bg-muted" components/ | wc -l
```

---

## 📚 相关文档

- **QUICK_REFACTOR_PATTERNS.md** - 详细重构模式
- **THEME_REFACTOR_GUIDE.md** - 完整重构指南
- **THEME_REFACTOR_COMPLETE.md** - 完成总结
- **THEME_REFACTOR_VERIFICATION.md** - 验证清单
- **globals.css** - 主题变量定义

---

**更新时间：** 2024年（本次会话）  
**版本：** 1.0  
**适用范围：** 智慧农业生产管理系统全系统