# 前台设计系统规范 / Frontend Design System Specification

> **版本**: 1.0.0 | **日期**: 2026-06-24
> **基于**: LangChain Dashboard Design System, Admin UI, 2026-tier Product UI, Shadcn OKLCh
> **用途**: 驾驶舱静态页面样式参考规范 — cockpit-page-builder / style-optimizer 技能的权威参考

---

## 1. 设计风格哲学 / Design Philosophy

| 原则 | 说明 |
|------|------|
| **极简装饰** | Maximum information density, minimal decoration |
| **微妙深度** | Subtle depth through shadows rather than heavy gradients |
| **清晰层级** | Clear visual hierarchy through typography weight and spacing |
| **专业质感** | Professional financial dashboard — 8px spacing system |
| **8px栅格** | Base unit 4px, primary: 8/16/24/32/40, compact: 4/6/10/12/14 |

---

## 2. 颜色系统 / Color System

### 2.1 基元色 / Primitive Colors

| Token | Value | Use |
|-------|-------|-----|
| `--primary-blue` | `#2563EB` | 主色调、按钮、激活状态 |
| `--primary-light` | `#3B82F6` | 辅助蓝、hover状态、渐变 |
| `--success` | `#059669` | 正向趋势、增长百分比 |
| `--danger` | `#DC2626` | 负向趋势、告警、删除 |
| `--warning` | `#F59E0B` | 警告标识、评审阶段 |
| `--text-primary` | `#111827` | 主要文字、标题 |
| `--text-secondary` | `#374151` | 次要文字、图表轴标签 |
| `--text-muted` | `#6B7280` | 辅助文字、占位符 |

### 2.2 语义表面色 / Semantic Surfaces (2026 standard)

| Layer | 变量 | 用途 | 参考值 |
|-------|------|------|--------|
| 背景层 | `--bg-page` | 页面底色 | `#F8FAFC` |
| 表面层 | `--bg-card` | 卡片、面板、输入框 | `#FFFFFF` |
| 提升层 | `--bg-elevated` | 下拉框、模态框背景 | `#F1F5F9` |

### 2.3 边框系统 / Border System (Hairline Standard)

| Token | Value | 用途 |
|-------|-------|------|
| `--border` | `#E5E7EB` | 卡片、section分隔线 |
| `--border-strong` | `#D1D5DB` | 抽屉分隔线、激活态边框 |
| `--border-focus` | `#2563EB` | 输入框焦点 |

**Rule**: All borders use `var(--border)` or `var(--border-strong)`. Never hardcode.

### 2.4 阴影系统 / Shadow System

| Token | Value | 用途 |
|-------|-------|------|
| `--shadow-card` | `0 2px 8px rgba(0,0,0,0.08)` | 卡片默认 |
| `--shadow-hover` | `0 4px 16px rgba(0,0,0,0.12)` | 卡片悬停 |
| `--shadow-drawer` | `0 0 24px rgba(0,0,0,0.15)` | 侧滑抽屉 |

### 2.5 图表色板 / Chart Color Palette

#### 环形图9色 (投资阶段)
| 阶段 | Color | Hex | Stage |
|------|-------|-----|-------|
| 储备 | 🔵 | `#3B82F6` | Stage 1 |
| 初筛 | 🔵 | `#60A5FA` | Stage 2 |
| 立项 | 🟢 | `#10B981` | Stage 3 |
| 尽调 | 🟢 | `#34D399` | Stage 4 |
| 评审 | 🟡 | `#F59E0B` | Stage 5 |
| 签署 | 🟡 | `#FBBF24` | Stage 6 |
| 出资 | 🟣 | `#8B5CF6` | Stage 7 |
| 投后 | 🟣 | `#6366F1` | Stage 8 |
| 退出 | 🔴 | `#EF4444` | Stage 9 |

> **注意**: 9阶段色渐变连续且区分明显，从蓝→绿→黄→紫→红

---

## 3. 排版系统 / Typography

### 3.1 字体栈

```css
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif;
```

### 3.2 字号表 / Font Size Scale

| 级别 | Size | Font Weight | 用途 |
|------|------|-------------|------|
| XXL | 2.5rem (40px) | 700 | KPI主数值 |
| XL | 1.25rem (20px) | 600 | 卡片标题 |
| Base | 1rem (14px) | 400 | 正文、表格内容 |
| SM | 0.875rem (12px) | 400 | 辅助文字、表格头 |
| XS | 0.75rem (12px) | 400 | 标签、占位符 |

### 3.3 数字字体规范
- **KPI数值**: `font-weight: 700`, 颜色 `--text-primary`
- **正趋势**: `color: --success` (+号前缀)
- **负趋势**: `color: --danger` (-号前缀)
- **图表数据**: `font-family` 继承, `font-weight: 500`

---

## 4. 间距系统 / Spacing System

### 4.1 8px 基础间距尺 (8px Grid)

| Token | Value | 用途 |
|-------|-------|------|
| `--space-1` | 4px | 内边距最小值 |
| `--space-2` | 8px | 小元素间距 (图标-文字) |
| `--space-3` | 12px | 列表项间距 |
| `--space-4` | 16px | 卡片内边距, 表单域间距 |
| `--space-5` | 20px | 区域间距 |
| `--space-6` | 24px | Section间间距 |
| `--space-8` | 32px | 大区块间距 |

### 4.2 卡片布局间距

| 组件 | 内边距 (padding) | 外边距 (margin) |
|------|-----------------|----------------|
| KPI Cards | `20px 24px` | `16px` (gap) |
| Chart Containers | `16px 20px` | `16px 20px` |
| Drawer Panel | `16px 20px` | — |
| Header (Zone 0) | `0 24px` | — |

### 4.3 断点间距 / Responsive Spacing

| Breakpoint | Width | Padding |
|------------|-------|---------|
| XL (Desktop) | `≥ 1200px` | 24px |
| LG (Tablet) | `768-1199px` | 20px |
| MD (Mobile) | `576-767px` | 16px |
| SM (Small) | `< 576px` | 12px |

---

## 5. 圆角系统 / Border Radius

| Token | Value | 用途 |
|-------|-------|------|
| `--radius-sm` | `4px` | 徽标、小组件 |
| `--radius-md` | `6px` | 按钮、输入框 |
| `--radius-lg` | `8px` | 大卡片、模态框 |
| `--radius-xl` | `12px` | KPI卡片、图表容器 |
| `--radius-full` | `50%` | 圆形图标、标签圆点 |

**Rule**: Use `border-radius: var(--radius-xl)` for KPI cards and chart containers.

---

## 6. 动画与过渡 / Motion & Animation

| Transition | Duration | Easing | 用途 |
|------------|----------|--------|------|
| Micro | `150ms` | `ease` | 悬停、按钮点击 |
| Normal | `200ms` | `ease` | 边框过渡 |
| Medium | `250ms` | `ease-out` | 侧滑抽屉 |
| Large | `300ms` | `ease-in-out` | KPI卡片展开/收起 |

### 6.1 交互状态规范

| 元素 | 悬停效果 | 点击效果 |
|------|---------|---------|
| 卡片 | `box-shadow: var(--shadow-hover)` | — |
| 面包屑层级 | `color: var(--primary-blue)` | — |
| 🔺折叠按钮 | `background: rgba(37, 99, 235, 0.15)` | — |
| ▶抽屉按钮 | `background: var(--primary-blue), color: white` | — |

---

## 7. 组件设计规范 / Component Specifications

### 7.1 KPI 卡片 (3 模式)

#### 折叠模式 (Fold Mode)
```css
.kpi-card {
  background: var(--bg-card);
  border-radius: var(--radius-xl);  /* 12px */
  padding: 20px 24px;
  box-shadow: var(--shadow-card);   /* 0 2px 8px rgba(0,0,0,0.08) */
  transition: box-shadow 200ms ease;
}
.kpi-card:hover {
  box-shadow: var(--shadow-hover);  /* 0 4px 16px rgba(0,0,0,0.12) */
}
.kpi-value {
  font-size: 2.5rem;    /* 40px */
  font-weight: 700;
  color: var(--text-primary);
}
.kpi-change.positive { color: var(--success); font-size: 1rem; }
.kpi-change.negative { color: var(--danger); font-size: 1rem; }
.kpi-aux { color: var(--text-muted); font-size: 0.875rem; }
```

#### 明细模式 (Detail Mode)
- 子项以**小卡片网格**显示在主卡片下方
- 网格: `grid-template-columns: repeat(auto-fit, minmax(130px, 1fr))`
- 小卡片: `background: var(--bg-page), border: 1px solid var(--border), border-radius: 8px, padding: 12px 16px`

#### 抽屉模式 (Drawer Mode)
- 左侧蓝色 8px 边框: `border-left: 8px solid var(--primary-blue)`
- 渐变背景: `background: linear-gradient(135deg, #fafbff, #fff)`
- ▶按钮: 32px 圆形, hover → 蓝色填充 + 白色图标

### 7.2 图表容器

```css
.chart-container {
  background: var(--bg-card);
  border-radius: var(--radius-xl);
  box-shadow: var(--shadow-card);
  display: flex;
  flex-direction: column;
}
.chart-body {
  flex: 1;
  min-height: 340px;
  padding: 16px 20px;
}
.echarts-chart {
  width: 100%;
  height: 400px;
  min-height: 340px;
  position: relative;
  z-index: 1;
}
```

### 7.3 抽屉面板

```css
.drawer {
  position: fixed;
  top: 0;
  right: 0;
  width: min(520px, 45vw);
  height: 100vh;
  background: var(--bg-card);
  box-shadow: var(--shadow-drawer);
  border-top-left-radius: 16px;
  border-bottom-left-radius: 16px;
  transform: translateX(100%);
  transition: transform 250ms ease-out;
  z-index: 1051;
}
.drawer.open {
  transform: translateX(0);
}
```

### 7.4 面包屑组件

```css
.breadcrumb-item {
  font-size: 0.8125rem;  /* 13px */
  cursor: pointer;
  color: var(--text-secondary);
}
.breadcrumb-item.active {
  color: var(--primary-blue);
  font-weight: 600;
}
.breadcrumb-separator { margin: 0 8px; color: var(--text-muted); }
```

---

## 8. 响应式布局 / Responsive Layout

### 8.1 KPI 卡片网格

| Breakpoint | Width | Columns | 规则 |
|------------|-------|---------|------|
| XL | `≥ 1200px` | `repeat(5, 1fr)` | 5列平铺 |
| LG | `768-1199px` | `repeat(3, 1fr)` | 3列 |
| MD | `576-767px` | `repeat(2, 1fr)` | 2列 |
| SM | `< 576px` | `1fr` | 1列堆叠 |

### 8.2 区域布局

| Breakpoint | Zone 3 布局 | 图表排列 |
|------------|-------------|---------|
| XL/LG | 2列 `1fr 1fr` | 左: 仪表 / 右: 明细 |
| MD | 2列 `1fr 1fr` | 同上, 图表高度缩小 |
| SM | 1列 `1fr` | 垂直堆叠 |

### 8.3 图表高度

| Breakpoint | Height | Min Height |
|------------|--------|------------|
| XL | `400px` | `340px` |
| LG | `320px` | `300px` |
| MD | `260px` | `240px` |
| SM | `200px` | `180px` |

---

## 9. 数据可视化规范 / Data Visualization

### 9.1 ECharts 主题配置

```javascript
{
  textStyle: { // 全局文字样式
    fontFamily: "-apple-system, 'PingFang SC', sans-serif",
    color: '#374151' // --text-secondary
  },
  grid: { // 图表内边距
    top: '8%', right: '5%', bottom: '12%', left: '5%',
    containLabel: true
  },
  tooltip: { // 悬浮提示
    backgroundColor: '#FFFFFF',
    borderColor: '#E5E7EB',
    borderWidth: 1,
    textStyle: { color: '#111827' },
    extraCssText: 'box-shadow: 0 4px 12px rgba(0,0,0,0.1); border-radius: 8px;'
  }
}
```

### 9.2 折线图规范
- **当年**: 实线 `#2563EB`, 2.5px 宽度, 渐变填充
- **去年**: 虚线 `#9CA3AF`, 2px 宽度, 虚线样式
- **数据点**: 圆形, 8px, 白色边框 2px

### 9.3 柱状图规范
- **填充**: 渐变色 `linear-gradient(0, 0, 1, 0)` from `#2563EB` to `#3B82F6`
- **圆角**: `borderRadius: [0, 4, 4, 0]` (水平柱状图)
- **数值标签**: 柱条末端, `fontWeight: 'bold'`

---

## 10. 无障碍标准 / Accessibility

| 指标 | 要求 |
|------|------|
| 颜色对比度 | WCAG 2.1 AA ≥ 4.5:1 (正文), ≥ 3:1 (大文字) |
| 触控目标 | 最小 44×44px (移动端) |
| 键盘导航 | Tab 键可焦点所有交互元素 |
| 屏幕阅读器 | 所有图表有 `aria-label`, `role` 属性 |

---

## 11. 性能优化 / Performance

| 规范 | 说明 |
|------|------|
| CSS 变量 | 全局 15 个变量, 组件级不创建新变量 |
| 阴影 | 2D box-shadow 性能优, 避免 3D transform |
| 动画 | 仅使用 opacity/transform (GPU 加速) |
| 字体 | 系统字体栈, 无需网络加载 |
| ECharts | CDN 引入, 按需初始化 |

---

## 12. V15 最佳实践 / V15 Best Practices

从 V12→V15 迭代中验证的有效模式:

1. **LangChain 标准 SKILL.md**: <500 行核心 + `references/` 详细文件
2. **渐进式披露**: 元数据 → SKILL.md → resource files
3. **CSS 变量命名**: `--category-purpose-size` 格式
4. **最小边框原则**: 优先使用间距和背景色分隔
5. **阴影层级**: 3 级 (card → hover → drawer)
6. **图表 minAngle**: 保持 `minAngle: 10` 确保零值切片可见可交互