前端颜色与组件规范

# 前端颜色与组件规范

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-27
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新] [强制执行]

---

## ⚠️ 核心原则

**禁止硬编码，必须使用语义化变量！**

---

## &#127912; 颜色规范

### 全局颜色变量（定义在 `globals.css`）

```css
:root {
  /* 基础颜色 */
  --background: #FFFFFF;
  --foreground: #111827;
  
  /* 卡片颜色 */
  --card: #FFFFFF;
  --card-foreground: #111827;
  
  /* 弹窗颜色 */
  --popover: #FFFFFF;
  --popover-foreground: #111827;
  
  /* 主色调 */
  --primary: #07C160;
  --primary-foreground: #FFFFFF;
  
  /* 次要颜色 */
  --secondary: #F3F4F6;
  --secondary-foreground: #111827;
  
  /* 静默颜色 */
  --muted: #F9FAFB;
  --muted-foreground: #6B7280;
  
  /* 强调颜色 */
  --accent: #F3F4F6;
  --accent-foreground: #111827;
  
  /* 危险颜色 */
  --destructive: #EF4444;
  --destructive-foreground: #FFFFFF;
  
  /* 边框颜色 */
  --border: #E5E5E5;
  --input: #E5E5E5;
  --ring: #07C160;
  
  /* 状态颜色 */
  --success: #10B981;
  --warning: #F59E0B;
  --info: #3B82F6;
}

/* 暗色主题 */
.dark {
  --background: #111827;
  --foreground: #F9FAFB;
  --card: #1F2937;
  --card-foreground: #F9FAFB;
  /* ... */
}
```

### Tailwind 语义化类名映射

| 类名 | 对应变量 | 用途 |
|------|----------|------|
| `bg-background` | `var(--background)` | 页面背景 |
| `text-foreground` | `var(--foreground)` | 主文字 |
| `bg-card` | `var(--card)` | 卡片背景 |
| `text-card-foreground` | `var(--card-foreground)` | 卡片文字 |
| `bg-primary` | `var(--primary)` | 主色调背景 |
| `text-primary` | `var(--primary)` | 主色调文字 |
| `text-primary-foreground` | `var(--primary-foreground)` | 主色调上的文字 |
| `bg-secondary` | `var(--secondary)` | 次要背景 |
| `text-muted-foreground` | `var(--muted-foreground)` | 次要文字 |
| `bg-destructive` | `var(--destructive)` | 危险/删除背景 |
| `text-destructive` | `var(--destructive)` | 危险文字 |
| `border-border` | `var(--border)` | 边框 |

### 透明度修饰符

```tsx
// 背景透明度
<div className="bg-primary/10">主色调 10% 透明度背景</div>
<div className="bg-card/80">卡片 80% 透明度背景</div>

// 文字透明度
<span className="text-foreground/80">80% 不透明度文字</span>
<span className="text-muted-foreground/60">60% 不透明度次要文字</span>

// 边框透明度
<div className="border border-border/50">50% 透明度边框</div>
```

### 状态颜色使用

```tsx
// 成功状态
<Tag color="green">正常</Tag>
<Badge status="success" text="已完成" />

// 警告状态
<Tag color="orange">待处理</Tag>
<Badge status="warning" text="待审核" />

// 错误状态
<Tag color="red">异常</Tag>
<Badge status="error" text="失败" />

// 处理中
<Tag color="blue">处理中</Tag>
<Badge status="processing" text="进行中" />

// 默认/禁用
<Tag>禁用</Tag>
<Badge status="default" text="未开始" />
```

### 禁止使用的颜色方式

```tsx
// ❌ 硬编码 Hex 值
<div style={{ background: '#07C160' }}>错误</div>
<div className="bg-[#07C160]">错误</div>

// ❌ RGB/RGBA
<div style={{ color: 'rgb(7, 193, 96)' }}>错误</div>
<div style={{ background: 'rgba(0, 0, 0, 0.5)' }}>错误</div>

// ❌ Tailwind 原色
<div className="bg-blue-500">错误</div>
<div className="text-gray-600">错误</div>
<div className="border-slate-200">错误</div>

// ❌ AI 味渐变
<div className="bg-gradient-to-r from-purple-500 to-blue-600">错误</div>
<div className="bg-gradient-to-r from-indigo-500 to-pink-500">错误</div>
```

---

## &#129513; 组件库规范

### shadcn/ui 组件（优先使用）

**位置**: `src/components/ui/`

| 组件 | 用途 | 导入路径 |
|------|------|----------|
| Button | 按钮 | `@/components/ui/button` |
| Input | 输入框 | `@/components/ui/input` |
| Label | 标签 | `@/components/ui/label` |
| Card | 卡片 | `@/components/ui/card` |
| Dialog | 弹窗 | `@/components/ui/dialog` |
| Select | 下拉选择 | `@/components/ui/select` |
| Checkbox | 复选框 | `@/components/ui/checkbox` |
| Radio | 单选框 | `@/components/ui/radio-group` |
| Switch | 开关 | `@/components/ui/switch` |
| Tabs | 标签页 | `@/components/ui/tabs` |
| Toast | 提示 | `@/components/ui/toast` |
| Avatar | 头像 | `@/components/ui/avatar` |
| Badge | 徽章 | `@/components/ui/badge` |
| Skeleton | 骨架屏 | `@/components/ui/skeleton` |

### Ant Design 组件（复杂业务场景）

**使用场景**:
- 复杂表格（排序、筛选、分页）
- 日期选择器
- 表单（复杂验证）
- 消息提示
- 确认弹窗

```tsx
// 表格
import { Table } from 'antd';
import type { TableColumnsType } from 'antd';

// 日期选择
import { DatePicker, RangePicker } from 'antd';

// 表单
import { Form, FormItem } from 'antd';

// 消息提示
import { App } from 'antd';
const { message, modal } = App.useApp();

// 确认弹窗
import { Modal, Popconfirm } from 'antd';
```

### 组件选择指南

| 场景 | 推荐组件 | 原因 |
|------|----------|------|
| 简单按钮 | shadcn/ui Button | 轻量、风格统一 |
| 带图标的按钮 | Ant Design Button | 图标支持更好 |
| 简单输入框 | shadcn/ui Input | 轻量 |
| 带验证的表单 | Ant Design Form | 验证功能完善 |
| 数据表格 | Ant Design Table | 功能完整 |
| 简单列表 | shadcn/ui 组件 | 轻量 |
| 日期选择 | Ant Design DatePicker | 功能完整 |
| 简单弹窗 | shadcn/ui Dialog | 轻量 |
| 确认对话框 | Ant Design Modal/Popconfirm | 使用方便 |

---

## &#128292; 字体规范

### 字体变量

```css
--font-sans: 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', ui-sans-serif, system-ui, ...;
--font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, ...;
--font-serif: 'Noto Serif SC', 'Songti SC', 'SimSun', ui-serif, Georgia, ...;
```

### 使用方式

```tsx
// ✅ 正确
<p className="font-sans">无衬线字体</p>
<code className="font-mono">等宽字体</code>
<span className="font-serif">衬线字体</span>

// ❌ 错误
<p style={{ fontFamily: 'Inter' }}>错误</p>
<p className="font-['Inter']">错误</p>
```

---

## &#128208; 圆角规范

### 圆角变量

```css
--radius-sm: 0.375rem;  /* 6px */
--radius-md: 0.5rem;    /* 8px */
--radius-lg: 0.625rem;  /* 10px */
--radius-xl: 0.75rem;   /* 12px */
--radius-2xl: 1rem;     /* 16px */
--radius-full: 9999px;  /* 完全圆角 */
```

### Tailwind 类名映射

| 类名 | 对应值 | 用途 |
|------|--------|------|
| `rounded-sm` | 6px | 小圆角 |
| `rounded-md` | 8px | 中等圆角 |
| `rounded-lg` | 10px | 大圆角 |
| `rounded-xl` | 12px | 更大圆角 |
| `rounded-2xl` | 16px | 超大圆角 |
| `rounded-full` | 9999px | 完全圆角（头像、徽章） |

### 使用示例

```tsx
// ✅ 正确
<div className="rounded-md">中等圆角卡片</div>
<Button className="rounded-lg">大圆角按钮</Button>
<Avatar className="rounded-full">完全圆角头像</Avatar>

// ❌ 错误
<div className="rounded-[8px]">错误：硬编码圆角</div>
<div style={{ borderRadius: '10px' }}>错误：内联样式</div>
```

---

## &#127763; 暗色主题规范

### 开发完成后必须测试

1. **切换主题测试**
   - 打开页面，切换到暗色主题
   - 检查所有元素是否显示正常
   - 检查文字是否可读

2. **检查常见问题**
   - 白色背景是否变成深色
   - 黑色文字是否变成浅色
   - 边框是否可见
   - 图标颜色是否正确

### 容易出问题的地方

```tsx
// ❌ 错误：硬编码白色背景
<div style={{ background: 'white' }}>
  错误：暗色主题下仍然白色
</div>

// ❌ 错误：硬编码黑色文字
<p style={{ color: 'black' }}>
  错误：暗色主题下仍然黑色
</p>

// ❌ 错误：硬编码边框
<div style={{ border: '1px solid #E5E5E5' }}>
  错误：暗色主题下边框太亮
</div>

// ✅ 正确：使用语义化变量
<div className="bg-card text-card-foreground border-border">
  正确：自动适配主题
</div>
```

### Ant Design 组件暗色主题

```tsx
// Ant Design 组件会自动适配暗色主题
// 但需要确保 ThemeProvider 正确配置

import { ConfigProvider, theme } from 'antd';
import { useTheme } from '@/contexts/ThemeContext';

function App() {
  const { theme: currentTheme } = useTheme();
  
  return (
    <ConfigProvider
      theme={{
        algorithm: currentTheme === 'dark' ? theme.darkAlgorithm : theme.defaultAlgorithm,
      }}
    >
      {/* 组件 */}
    </ConfigProvider>
  );
}
```

---

## &#128218; 相关文档

- [前端布局规范](./前端布局规范.md) - 布局结构、导航配置
- [前端页面模板](./前端页面模板.md) - 代码模板
- [开发安全规范](../开发安全规范.md) - 防破坏性开发规则
- [项目摘要](../../压缩摘要.md) - 核心红线规则（含全局检查清单）