# 迷毂智能调度平台 · 设计系统 (MASTER)

> 由 ui-ux-pro-max skill 推导生成 (v1)。本文档是项目的**单一设计真理**。
> 页面级覆盖请放在 `design-system/pages/<page-name>.md`，覆盖优先级高于本 MASTER。

---

## 1. 产品定位 (Product Identity)

| 维度 | 取值 |
|---|---|
| **产品类型** | B2B 工业 SaaS · AGV 智能调度平台 · 实时监控仪表板 |
| **行业** | 智能制造 / 物流自动化 / 仓储机器人 |
| **匹配 reasoning rule** | `Autonomous Drone Fleet` (id=97) 主匹配 / `Logistics-Delivery` (id=25) + `Smart Home/IoT Dashboard` (id=54) + `SaaS Dashboard` (id=19) 辅助 |
| **目标用户** | 现场调度员、运维工程师、车队管理员、平台管理员 |
| **使用环境** | 桌面端为主 (1920×1080 / 2560×1440)、长时间在线、信息密集 |

---

## 2. 设计模式与风格 (Pattern & Style)

| 维度 | 主选 | 辅助 |
|---|---|---|
| **Landing/页面模式** | Real-Time + Feature-Rich | Bento Grid (主体布局) |
| **核心 UI 风格** | Real-Time Monitoring + Data-Dense Dashboard | Glassmorphism (卡片层级) + Dimensional Layering (z-轴层级) |
| **可选风格元素** | HUD/Sci-Fi FUI 微元素 (装饰用,不主导) | — |

### Real-Time Monitoring 必备特征
- 实时状态指示器（脉动 dot / pulsing badge）
- 流式图表（数值平滑过渡而非跳变）
- 告警通知层级（critical → warning → info）
- 连接状态/自动刷新指示
- 数值用 `font-variant-numeric: tabular-nums` 防抖动

### Data-Dense Dashboard 必备特征
- 多 widget 并排（KPI 行 + 主图 + 列表）
- 紧凑 padding（卡片 12-18px、KPI 项 10-12px）
- 高效栅格布局（CSS Grid）
- 表头常驻 hover tooltip
- 列表行 hover 高亮 + 平滑过渡

---

## 3. 颜色系统 (Color System)

### 3.1 状态色（项目级强约束 · 跨主题保持语义）

> **关键原则**：状态色与品牌色解耦。不要把品牌紫色当 "执行中"、把品牌橙色当 "警告"。

| Token | 浅色主题 (light) | 深色主题 (dark) | 语义 |
|---|---|---|---|
| `--mg-status-success` | `#16A34A` | `#22C55E` | 正常 / 成功 / 已完成 |
| `--mg-status-warning` | `#D97706` | `#F59E0B` | 异常 / 警告 / 等待人工 |
| `--mg-status-danger` | `#DC2626` | `#EF4444` | 严重故障 / critical / 阻断 |
| `--mg-status-info` | `#2563EB` | `#3B82F6` | 信息 / 进行中 / 通信 |
| `--mg-status-idle` | `#64748B` | `#94A3B8` | 待执行 / 已暂停 / 静默 |

### 3.2 数据可视化色板 (ECharts / Progress / Chart)

按"冷色→暖色"递进，避免单一色相被多 series 共用：

```
'#3B82F6'   蓝   优先级 1
'#22C55E'   绿   优先级 2
'#A855F7'   紫   优先级 3 (品牌色复用)
'#F59E0B'   琥珀  优先级 4
'#EF4444'   红   优先级 5 (告警语义保留时慎用)
'#06B6D4'   青   优先级 6
'#EC4899'   粉   优先级 7
'#84CC16'   黄绿  优先级 8
```

### 3.3 品牌主色（保留现有 7 套主题）

当前默认 `fame-lavender`（浅紫白主区 + 深紫侧栏）保持不变，所有变量在 `themes.ts` 中维护。
新增的状态色变量在每个主题预设里要补齐。

### 3.4 文字与对比度

| Context | 浅色主题 | 深色主题 |
|---|---|---|
| `text-light` (主文字) | `#0F172A` (slate-900) | `#FFFFFF` |
| `text-muted` (次要) | `#475569` (slate-600 ≥ 4.5:1) | `rgba(255,255,255,0.72)` |
| `text-dim` (装饰) | `#94A3B8` | `rgba(255,255,255,0.50)` |
| `text-faint` (占位) | `#CBD5E1` | `rgba(255,255,255,0.35)` |

> ⚠ 不要用 `slate-400 (#94A3B8)` 做正文 (light mode) ——对比度不够。

---

## 4. 字体 (Typography)

> 选自 `Minimal Swiss` (Inter) + `Developer Mono` (JetBrains Mono) 组合，Dashboard Data 类目最佳实践。

| 用途 | 字体栈 | 备注 |
|---|---|---|
| **UI 主字体** | `'PingFang SC', 'Microsoft YaHei', Inter, -apple-system, 'Segoe UI', sans-serif` | 中文优先,英文 fallback Inter |
| **数据数字** (KPI/坐标/ID) | `'JetBrains Mono', 'Cascadia Mono', Menlo, Consolas, monospace` | 等宽,`font-variant-numeric: tabular-nums` |
| **代码/JSON** | 同数据数字 | — |

### 字号分级

| Token | 用途 | 字号 |
|---|---|---|
| `text-xs` | 标签/时间戳 | 11-12px |
| `text-sm` | 次要说明 | 12.5-13px |
| `text-base` | 正文/列表 | 14px |
| `text-md` | 卡片标题 | 15-16px |
| `text-lg` | 模块标题 | 18-20px |
| `text-xl` | 页面标题 | 24-28px |
| `text-2xl` | KPI 数值 | 28-32px |
| `text-hero` | Hero 标题 | 36-44px |

---

## 5. 间距与圆角 (Spacing & Radius)

### 5.1 间距尺度 (8pt 网格)

`4 / 8 / 12 / 16 / 18 / 24 / 32 / 48 / 64`

### 5.2 圆角

| Token | 值 | 用途 |
|---|---|---|
| `--mg-radius-sm` | 8px | 小标签、按钮、tag |
| `--mg-radius` | 14px | 卡片、面板 |
| `--mg-radius-lg` | 20px | Hero 区、对话框 |
| `--mg-radius-xl` | 24px | 全屏覆盖、巨型卡片 |

### 5.3 卡片层级 (Dimensional Layering)

```
z-0  背景 / orb / 网格
z-1  body 主区
z-2  普通卡片        shadow: 0 4px 14px rgba(_, .06)  light / 0 12px 30px rgba(0,0,0,.5) dark
z-3  浮起卡片 (hover) shadow: 0 8px 24px rgba(_, .10) light / 0 18px 40px rgba(0,0,0,.6) dark
z-4  Header / 侧栏  shadow: 0 1px 6px rgba(_, .05)
z-5  Dropdown / Toast
z-6  Modal / Dialog
```

---

## 6. 动画 (Motion)

| 场景 | 时长 | 缓动 |
|---|---|---|
| 颜色/边框变化 | 200ms | `ease-out` |
| 卡片 hover (transform) | 250ms | `cubic-bezier(.25, .8, .25, 1)` |
| 路由切换 | 250ms | 同上 |
| 状态脉动 (live dot) | 1.5-2s | `ease-in-out infinite` |
| Real-time 数值平滑 | 600-800ms | 同卡片 hover |

> ⚠ 严禁 hover 用 `transform: scale()` 引起 layout shift；用 `translateY(-2px)` + `box-shadow` 增强即可。
> ⚠ 必须遵守 `prefers-reduced-motion: reduce` —— 关闭装饰性动画。

---

## 7. 反模式清单 (Anti-Patterns)

来自 ui-reasoning.csv (Autonomous Drone Fleet + SaaS Dashboard) + Common Rules：

| 禁忌 | 原因 |
|---|---|
| ❌ 把品牌紫当作 "执行中" 状态色 | 状态色与品牌色冲突,扫读时干扰 |
| ❌ KPI 数值用变宽字体 | 实时跳动时数字晃动,影响阅读 |
| ❌ 浅色主题用 `slate-400` 做正文 | 对比度 < 4.5:1,违反 WCAG AA |
| ❌ 侧栏 active 用 4+ 重 box-shadow + text-shadow | 视觉噪音,装饰过度 |
| ❌ 硬编码 `#1a0b3d` 等颜色 | 跨主题切换失效 |
| ❌ 用 emoji 做 UI icon (🚀⚙️🎨) | 不统一,在不同 OS 渲染差异大 — 用 Heroicons / Element Plus icons |
| ❌ 实时图表用 hard refresh (闪一下) | 视觉干扰 — 用 `series.universalTransition` 或 `dataset` 平滑过渡 |

---

## 8. 实施清单 (Pre-Delivery Checklist)

每次发版前对照检查：

- [ ] 所有状态色用 `--mg-status-*` token,不直接 hardcode `#22c55e`
- [ ] 所有 KPI / 坐标 / ID 数字用 `font-family: var(--mg-font-mono)` + `font-variant-numeric: tabular-nums`
- [ ] 卡片/表单 hover 不引起 layout shift
- [ ] 浅色主题文字对比度 ≥ 4.5:1 (WCAG AA)
- [ ] 浮动元素 (header / aside) 在两套主题下都可见
- [ ] 响应式断点：375 / 768 / 1024 / 1440 / 1920 都过一遍
- [ ] 主题切换时无硬编码色 (grep `#[0-9a-f]{3,6}` in DashboardView/AppShell)

---

## 9. 引用与扩展

- **设计系统生成依据**：`.cursor/skills/ui-ux-pro-max/data/ui-reasoning.csv` (rows 19, 25, 54, 97), `colors.csv` (rows 26, 51, 53), `styles.csv` (rows 28, 31, 39, 46), `typography.csv` (rows 5, 9, 42)
- **页面级覆盖**：`design-system/pages/<page-name>.md`
- **变量来源**：`src/styles/theme.css` (CSS 变量声明) + `src/styles/themes.ts` (TS 主题预设)
- **Element Plus 适配**：`theme.css` 中 `.mg-content .el-*` 选择器统一管理

---

> **Generated**: ui-ux-pro-max v2.0 推理 + 项目实际代码 cross-check  
> **Last sync**: 2026-05-24