生产管理系统前端 - openapi - fetch生成器开发

2025-10-27 21:53:18 +08:00
parent 5055e40de6
commit 42a4a9f566
29 changed files with 4264 additions and 1463 deletions
--- a/配色系统完整指南.md
+++ b/配色系统完整指南.md
@@ -0,0 +1,242 @@
+# 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 项目。*