cavin/smart-crop-ui
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5b93b6ff7d5d50adb6a27a3efcca2925edaf6d58
smart-crop-ui/shadcn-color-guide.md

7.0 KiB
Raw Blame History

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) - 最低优先级

  • 禁用状态
  • 占位符文本
  • 辅助信息
  • 背景装饰

🎯 实际应用示例

按钮组件

// 主要按钮
<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>

卡片组件

<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>

输入框组件

<input className="bg-background text-foreground border border-input focus:ring-2 focus:ring-ring"
       placeholder="占位符文本" />

🌓 主题切换原理

系统通过 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. 一致性原则

  • 保持相同类型的组件使用相同的颜色变量
  • 避免在组件中硬编码颜色值

🔧 维护工具

检查颜色使用

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

主题切换测试

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

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