smart-crop-ui/src/THEME_QUICK_REFERENCE.md

🎨 主题变量快速参考卡

常用替换速查表

📦 背景色

用途	旧写法	✅ 新写法	说明
信息框/卡片	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	自动适配

---

🚫 禁止使用的写法

❌ 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模式维护成本高，且不统一

---

✅ 推荐使用的写法

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

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

---

📋 常见场景示例

场景1：信息展示卡片

// ❌ 旧写法
<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：列表项悬停

// ❌ 旧写法
<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：代码块

// ❌ 旧写法
<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：表单字段

// ❌ 旧写法
<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（保持不变）

// ✅ 正确写法（状态色不变）
<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变量（仅供参考）

/* 明亮模式 */
--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. 新组件开发

// 推荐模板
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. 列表组件

// 推荐模式
{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. 表单展示

// 推荐模式
<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正则搜索

# 查找需要替换的bg-gray-50（排除状态色）
bg-gray-50(?!\/50)

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

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

命令行搜索

# 搜索所有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
适用范围： 智慧农业生产管理系统全系统