# GEO 平台 - UI 风格指南

## 概述

本文档定义 GEO 平台的前端 UI 风格规范，确保全平台视觉一致性。所有前端开发人员、UI 设计师和产品经理应遵循本指南进行界面设计和开发。

GEO 平台的 UI 设计遵循以下核心原则：
- **专业可信**：体现企业级 SaaS 平台的专业感和可信度
- **简洁高效**：减少视觉噪音，让用户聚焦于数据和操作
- **层次分明**：通过清晰的信息层级引导用户注意力
- **响应式适配**：适配桌面端、平板和移动端设备

## 风格特征总结

### 设计语言

| 特征 | 描述 | 应用场景 |
|------|------|----------|
| 扁平化设计 | 去除冗余装饰，强调内容和功能 | 全局 |
| 卡片化布局 | 使用卡片容器组织信息模块 | 仪表盘、列表页 |
| 留白呼吸感 | 充足的内边距和外边距 | 全局 |
| 微妙的层次感 | 通过阴影和边框区分层级 | 卡片、弹窗、下拉 |
| 数据可视化 | 丰富的图表和数据展示 | 仪表盘、报告页 |
| 状态色彩编码 | 使用颜色直观表达状态 | 状态标签、进度条 |

### 整体氛围

- **主色调**：深蓝/靛蓝色系，传达专业、科技、可信
- **辅助色**：翠绿色表示成功/正向，琥珀色表示警告，红色表示错误
- **中性色**：丰富的灰度层级用于文字和边框
- **背景**：浅色背景为主，深色模式作为可选项

## Design Tokens

### 颜色体系

#### 主色调（Primary）

| Token | 色值 | 用途 |
|-------|------|------|
| `--color-primary-50` | `#EEF2FF` | 极浅背景、hover 状态 |
| `--color-primary-100` | `#E0E7FF` | 轻色背景、选中状态 |
| `--color-primary-200` | `#C7D2FE` | 边框高亮 |
| `--color-primary-300` | `#A5B4FC` | 禁用状态主色 |
| `--color-primary-400` | `#818CF8` | 次要强调 |
| `--color-primary-500` | `#6366F1` | **主色** - 按钮、链接、图标 |
| `--color-primary-600` | `#4F46E5` | 按钮 hover、深色调 |
| `--color-primary-700` | `#4338CA` | 按钮 active |
| `--color-primary-800` | `#3730A3` | 深色背景文字 |
| `--color-primary-900` | `#312E81` | 标题、深色元素 |

#### 语义色（Semantic）

| Token | 色值 | 用途 |
|-------|------|------|
| `--color-success-50` | `#F0FDF4` | 成功状态轻背景 |
| `--color-success-500` | `#22C55E` | **成功** - 成功提示、正向指标 |
| `--color-success-600` | `#16A34A` | 成功 hover |
| `--color-warning-50` | `#FFFBEB` | 警告状态轻背景 |
| `--color-warning-500` | `#F59E0B` | **警告** - 警告提示、待处理 |
| `--color-warning-600` | `#D97706` | 警告 hover |
| `--color-error-50` | `#FEF2F2` | 错误状态轻背景 |
| `--color-error-500` | `#EF4444` | **错误** - 错误提示、失败状态 |
| `--color-error-600` | `#DC2626` | 错误 hover |
| `--color-info-50` | `#EFF6FF` | 信息状态轻背景 |
| `--color-info-500` | `#3B82F6` | **信息** - 信息提示 |

#### 中性色（Neutral）

| Token | 色值 | 用途 |
|-------|------|------|
| `--color-gray-50` | `#F9FAFB` | 页面背景、hover 背景 |
| `--color-gray-100` | `#F3F4F6` | 卡片背景、分隔背景 |
| `--color-gray-200` | `#E5E7EB` | 边框、分隔线 |
| `--color-gray-300` | `#D1D5DB` | 禁用边框、占位符 |
| `--color-gray-400` | `#9CA3AF` | 次要文字、图标 |
| `--color-gray-500` | `#6B7280` | 辅助文字 |
| `--color-gray-600` | `#4B5563` | 正文文字 |
| `--color-gray-700` | `#374151` | 标题文字 |
| `--color-gray-800` | `#1F2937` | 深色标题 |
| `--color-gray-900` | `#111827` | 主标题、深色文字 |

### 圆角（Border Radius）

| Token | 值 | 用途 |
|-------|-----|------|
| `--radius-none` | `0` | 直角（表格、特殊场景） |
| `--radius-sm` | `4px` | 小元素（标签、徽章） |
| `--radius-md` | `6px` | 默认（按钮、输入框） |
| `--radius-lg` | `8px` | 卡片、容器 |
| `--radius-xl` | `12px` | 大卡片、模态框 |
| `--radius-2xl` | `16px` | 页面级容器 |
| `--radius-full` | `9999px` | 圆形（头像、状态点） |

### 阴影（Shadow）

| Token | 值 | 用途 |
|-------|-----|------|
| `--shadow-sm` | `0 1px 2px 0 rgba(0,0,0,0.05)` | 轻微提升（按钮 hover） |
| `--shadow-md` | `0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1)` | 卡片默认 |
| `--shadow-lg` | `0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)` | 下拉菜单、浮层 |
| `--shadow-xl` | `0 20px 25px -5px rgba(0,0,0,0.1), 0 8px 10px -6px rgba(0,0,0,0.1)` | 模态框、抽屉 |
| `--shadow-inner` | `inset 0 2px 4px 0 rgba(0,0,0,0.05)` | 内嵌效果 |

### 字体（Typography）

#### 字体族

| Token | 值 | 用途 |
|-------|-----|------|
| `--font-sans` | `Inter, "PingFang SC", "Microsoft YaHei", sans-serif` | 正文、UI 文字 |
| `--font-mono` | `"JetBrains Mono", "Fira Code", monospace` | 代码、数据值 |

#### 字号层级

| Token | 大小 | 字重 | 行高 | 用途 |
|-------|------|------|------|------|
| `--text-xs` | `12px` | 400 | `16px` | 辅助说明、时间戳 |
| `--text-sm` | `14px` | 400 | `20px` | 次要文字、描述 |
| `--text-base` | `16px` | 400 | `24px` | **正文默认** |
| `--text-lg` | `18px` | 500 | `28px` | 小标题、强调文字 |
| `--text-xl` | `20px` | 600 | `28px` | 卡片标题 |
| `--text-2xl` | `24px` | 600 | `32px` | 页面小标题 |
| `--text-3xl` | `30px` | 700 | `36px` | 页面标题 |
| `--text-4xl` | `36px` | 700 | `40px` | 大标题、数字展示 |

### 间距（Spacing）

| Token | 值 | 用途 |
|-------|-----|------|
| `--space-1` | `4px` | 极小间距 |
| `--space-2` | `8px` | 紧凑间距（图标与文字） |
| `--space-3` | `12px` | 小间距 |
| `--space-4` | `16px` | **默认间距**（内边距基础） |
| `--space-5` | `20px` | 中等间距 |
| `--space-6` | `24px` | 卡片内边距 |
| `--space-8` | `32px` | 区块间距 |
| `--space-10` | `40px` | 大区块间距 |
| `--space-12` | `48px` | 页面级间距 |
| `--space-16` | `64px` | 大页面间距 |

## 组件改造计划

GEO 平台基于 shadcn/ui 组件库进行构建，以下是对核心组件的定制化规范。

### Button 按钮

| 变体 | 背景 | 文字 | 边框 | Hover | 用途 |
|------|------|------|------|-------|------|
| `default` | `primary-500` | white | none | `primary-600` | 主要操作 |
| `secondary` | `gray-100` | `gray-900` | none | `gray-200` | 次要操作 |
| `outline` | transparent | `gray-700` | `gray-200` | `gray-50` | 辅助操作 |
| `ghost` | transparent | `gray-700` | none | `gray-100` | 极简操作 |
| `destructive` | `error-500` | white | none | `error-600` | 危险操作 |
| `link` | transparent | `primary-500` | none | underline | 链接样式 |

**尺寸规范**：
- `sm`：`h-8 px-3 text-sm`
- `md`（默认）：`h-10 px-4 text-base`
- `lg`：`h-12 px-6 text-lg`

### Card 卡片

```
默认样式：
- 背景：white
- 圆角：`radius-lg` (8px)
- 阴影：`shadow-md`
- 内边距：`space-6` (24px)
- 边框：`1px solid gray-200`

Hover 状态：
- 阴影提升：`shadow-lg`
- 过渡：`transition-shadow duration-200`
```

**卡片变体**：
| 变体 | 说明 |
|------|------|
| `default` | 标准卡片，用于信息展示 |
| `stats` | 统计卡片，大号数字 + 描述 |
| `interactive` | 可交互卡片，hover 有明显反馈 |
| `flat` | 扁平卡片，无阴影，用于列表项 |

### Input 输入框

```
默认样式：
- 高度：`h-10`
- 圆角：`radius-md` (6px)
- 边框：`1px solid gray-300`
- 内边距：`px-3`
- 字体：`text-base`
- 背景：white

Focus 状态：
- 边框：`primary-500`
- 阴影：`0 0 0 2px primary-100`
- 过渡：`transition-all duration-200`

错误状态：
- 边框：`error-500`
- 阴影：`0 0 0 2px error-50`
```

### Badge 标签

| 变体 | 背景 | 文字 | 用途 |
|------|------|------|------|
| `default` | `primary-100` | `primary-700` | 默认标签 |
| `secondary` | `gray-100` | `gray-700` | 次要标签 |
| `success` | `success-50` | `success-600` | 成功状态 |
| `warning` | `warning-50` | `warning-600` | 警告状态 |
| `error` | `error-50` | `error-600` | 错误状态 |
| `info` | `info-50` | `info-600` | 信息状态 |

### Table 表格

```
默认样式：
- 表头背景：`gray-50`
- 表头文字：`gray-700` font-medium text-sm
- 行高：`h-12`
- 行边框：`border-b border-gray-200`
- 行 hover：`bg-gray-50`
- 单元格内边距：`px-4 py-3`
- 空状态：居中显示插图 + 提示文字
```

**特殊行样式**：
| 状态 | 样式 |
|------|------|
| 选中行 | `bg-primary-50` |
| 禁用行 | `opacity-50` |
| 高亮行 | `bg-warning-50` |

### Modal / Dialog 模态框

```
默认样式：
- 遮罩：`bg-black/50`
- 容器背景：white
- 圆角：`radius-xl` (12px)
- 阴影：`shadow-xl`
- 最大宽度：`max-w-lg` (512px)
- 内边距：`p-6`
- 动画：fade-in + scale-in

头部：
- 标题：`text-lg font-semibold`
- 关闭按钮：右上角 ghost 按钮

底部操作区：
- 居右排列
- 主按钮在右，次按钮在左
- 间距：`gap-3`
```

### Toast 通知

| 类型 | 图标 | 背景 | 边框 |
|------|------|------|------|
| `success` | CheckCircle | white | `success-200` |
| `warning` | AlertTriangle | white | `warning-200` |
| `error` | XCircle | white | `error-200` |
| `info` | Info | white | `info-200` |

```
默认样式：
- 位置：右上角固定
- 最大宽度：`400px`
- 圆角：`radius-lg`
- 阴影：`shadow-lg`
- 内边距：`p-4`
- 自动关闭：`5秒`
- 动画：slide-in-right + fade-out
```

### Navigation 导航

**侧边栏导航**：
```
默认样式：
- 宽度：`w-64` (256px)
- 背景：`gray-900`
- 文字：`gray-300`

选中状态：
- 背景：`primary-600`
- 文字：white
- 左侧边框指示：`3px solid primary-400`

Hover 状态：
- 背景：`gray-800`
- 文字：white
```

**顶部导航**：
```
默认样式：
- 高度：`h-16`
- 背景：white
- 边框：`border-b border-gray-200`
- 阴影：`shadow-sm`
```

## 交互规范

### 过渡动画

| 场景 | 时长 | 缓动函数 | 属性 |
|------|------|----------|------|
| 按钮 hover | `150ms` | `ease-in-out` | `background-color, border-color, box-shadow` |
| 卡片 hover | `200ms` | `ease-out` | `box-shadow, transform` |
| 模态框出现 | `200ms` | `cubic-bezier(0.16, 1, 0.3, 1)` | `opacity, transform` |
| 下拉菜单 | `150ms` | `ease-out` | `opacity, transform` |
| Toast 出现/消失 | `300ms` | `ease-in-out` | `opacity, transform` |
| 页面切换 | `200ms` | `ease-in-out` | `opacity` |
| 数据加载骨架屏 | `pulse 2s infinite` | - | `opacity` |

### 加载状态

| 场景 | 样式 |
|------|------|
| 页面加载 | 全屏骨架屏 + Logo |
| 数据加载 | 卡片/表格骨架屏 |
| 按钮加载 | 按钮内 Spinner，禁用点击 |
| 无限滚动 | 底部 Spinner |
| 文件上传 | 进度条 + 百分比 |

### 空状态

```
统一空状态样式：
- 居中布局
- 插图/图标：`primary-200` 色调
- 标题：`text-lg font-medium text-gray-700`
- 描述：`text-sm text-gray-500`
- 操作按钮（可选）：`primary` 按钮
```

### 错误状态

```
统一错误状态样式：
- 错误图标：`error-500` 色的 AlertTriangle
- 标题：`text-lg font-medium text-gray-900`
- 描述：`text-sm text-gray-600`
- 重试按钮：`outline` 按钮
- 错误详情（可选）：可展开的折叠面板
```

### 表单校验

```
校验提示样式：
- 错误信息：`text-xs text-error-500 mt-1`
- 错误图标：输入框右侧 `error-500` 图标
- 成功图标：输入框右侧 `success-500` Check 图标
- 实时校验：输入后 `300ms` 延迟触发
```

## 布局规范

### 页面结构

```
┌─────────────────────────────────────────────┐
│  顶部导航栏 (h-16, fixed)                    │
├──────────┬──────────────────────────────────┤
│          │  页面标题区                        │
│  侧边栏   │  ┌────────────────────────────┐  │
│ (w-64)   │  │  内容区                       │  │
│  fixed   │  │  ┌──────┐ ┌──────┐ ┌──────┐ │  │
│          │  │  │ 卡片  │ │ 卡片  │ │ 卡片  │ │  │
│          │  │  └──────┘ └──────┘ └──────┘ │  │
│          │  │  ┌────────────────────────┐  │  │
│          │  │  │ 表格/列表               │  │  │
│          │  │  └────────────────────────┘  │  │
│          │  └────────────────────────────┘  │
└──────────┴──────────────────────────────────┘
```

### 响应式断点

| 断点 | 宽度 | 布局调整 |
|------|------|----------|
| `sm` | `640px` | 移动端基础适配 |
| `md` | `768px` | 侧边栏可折叠 |
| `lg` | `1024px` | 完整桌面布局 |
| `xl` | `1280px` | 宽屏扩展 |
| `2xl` | `1536px` | 超宽屏 |

### 网格系统

- 采用 CSS Grid + Flexbox 混合布局
- 仪表盘卡片网格：`grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4`
- 卡片间距：`gap-6`
- 页面最大宽度：`max-w-7xl` (1280px)，居中显示

## 图表规范

GEO 平台大量使用数据可视化图表，基于 Recharts 实现。

### 配色方案

```
图表主色系：
- 系列 1：`#6366F1` (primary-500)
- 系列 2：`#22C55E` (success-500)
- 系列 3：`#F59E0B` (warning-500)
- 系列 4：`#EF4444` (error-500)
- 系列 5：`#8B5CF6` (violet-500)
- 系列 6：`#06B6D4` (cyan-500)
```

### 图表样式

```
通用样式：
- 背景：透明
- 网格线：`gray-200`，虚线
- 坐标轴文字：`gray-500`，text-xs
- 图例：底部居中
- Tooltip：白色背景，圆角，阴影

柱状图：
- 圆角：`radius-sm` 顶部
- 间距：`barGap=4`

折线图：
- 线条宽度：`2px`
- 数据点：`r=4`，hover `r=6`
- 填充区域：`fillOpacity=0.1`

饼图/环形图：
- 内半径：`60%`
- 标签：外部引导线 + 百分比
```

---

*本文档定义 GEO 平台的 UI 风格规范，所有前端实现应严格遵循以上 Design Tokens 和组件规范。*