smart-crop-ui/src/THEME_REFACTOR_GUIDE.md

主题重构指南

修改原则

本次重构将固定的 Tailwind 颜色类替换为 shadcn 主题变量，以支持主题切换。

CSS变量替换规则

1. 背景色替换

信息展示框、输入框禁用状态

// 旧写法
className="bg-gray-50 dark:bg-gray-800"
className="bg-gray-50"

// 新写法  
className="bg-muted"

卡片次要背景

// 旧写法
className="bg-gray-100"

// 新写法（非状态色场景）
className="bg-accent"

交互悬停效果

// 旧写法
className="hover:bg-gray-50"
className="hover:bg-gray-100"

// 新写法
className="hover:bg-accent"

2. 状态色（保留不变）

以下场景使用固定颜色类表示状态，不需要替换：

成功/激活状态（绿色）

className="bg-green-100 text-green-800"
className="bg-green-50"

错误/危险状态（红色）

className="bg-red-100 text-red-800"
className="bg-red-50"

警告状态（黄色）

className="bg-yellow-100 text-yellow-800"
className="bg-yellow-50"

提示/信息状态（蓝色）

className="bg-blue-100 text-blue-800"
className="bg-blue-50"

中性/禁用状态（灰色）

// 用于表示"离线"、"已忽略"、"禁用"、"建议"等状态
className="bg-gray-100 text-gray-800"
className="bg-gray-100 text-gray-700"

3. 文本颜色替换

次要文本

// 旧写法
className="text-gray-700"
className="text-gray-600"

// 新写法
className="text-muted-foreground"

主要文本

// 旧写法
className="text-gray-900 dark:text-gray-100"

// 新写法
className="text-foreground"

4. 边框颜色

// 旧写法（非状态色）
className="border-gray-200"
className="border-gray-300"

// 新写法
className="border-border"
或
className="border" // 默认使用border颜色

代码替换示例

示例1：信息展示卡片

// 修改前
<div className="p-3 bg-gray-50 rounded">
  <div className="text-xs text-gray-600">标签</div>
  <div className="font-medium">值</div>
</div>

// 修改后
<div className="p-3 bg-muted rounded">
  <div className="text-xs text-muted-foreground">标签</div>
  <div className="font-medium">值</div>
</div>

示例2：列表项悬停

// 修改前
<div className="p-4 hover:bg-gray-50 cursor-pointer">
  内容
</div>

// 修改后
<div className="p-4 hover:bg-accent cursor-pointer">
  内容
</div>

示例3：状态徽章（不修改）

// 保持不变 - 这是状态色
<Badge className="bg-gray-100 text-gray-800">离线</Badge>
<Badge className="bg-green-100 text-green-800">在线</Badge>

示例4：禁用输入框

// 修改前
<Input disabled className="bg-gray-50 dark:bg-gray-800" />

// 修改后
<Input disabled className="bg-muted" />

globals.css 重构

移除的内容

• .dark .bg-gray-50 等非状态色的暗色模式定义
• .dark .text-gray-* 等非状态色的文本颜色定义
• .dark .border-gray-* 等非状态色的边框颜色定义

保留的内容

• 所有状态色的暗色模式定义（green, red, yellow, orange, blue, purple, pink等）
• 状态色的边框定义

field-value组件更新

/* 修改前 */
.field-value {
  @apply bg-gray-50 dark:bg-gray-800;
}

/* 修改后 */
.field-value {
  @apply bg-muted;
}

主题变量说明

背景色

• background - 页面主背景
• card - 卡片背景
• muted - 弱化背景（用于信息框、禁用输入等）
• accent - 强调背景（用于悬停、次要按钮等）
• popover - 弹出层背景

前景色

• foreground - 主文本颜色
• muted-foreground - 次要文本颜色
• card-foreground - 卡片文本颜色
• accent-foreground - 强调文本颜色

其他

• border - 边框颜色
• input - 输入框边框
• ring - 聚焦环颜色

修改优先级

1. 高优先级 - 影响主题切换的固定颜色

   • 信息展示框的 bg-gray-50
   • 禁用输入的 bg-gray-50 dark:bg-gray-800
   • 悬停效果的 hover:bg-gray-50

2. 中优先级 - 视觉一致性

   • 次要文本的 text-gray-600/700
   • 非状态边框的 border-gray-200

3. 低优先级 - 不影响功能但建议修改

   • 装饰性元素的灰色

不需要修改的场景

1. 状态指示器 - 使用固定颜色表示特定状态
2. 代码块 - code标签中的背景色可保留
3. 图表 - 图表颜色方案可保持独立配置
4. 品牌色 - 绿色农业主题的品牌色保持不变

测试检查点

修改后需要测试：

• ✅ 亮色/暗色主题切换
• ✅ 所有状态色正常显示
• ✅ 悬停效果正常
• ✅ 禁用状态样式正确
• ✅ 卡片和信息框背景适配主题
• ✅ 文本可读性良好