# Admin UI 设计规范

更新时间：2026-03-19

## 1. 文档定位

本文基于 [ADMIN_FRONTEND_EXECUTION_PLAN.md](../plans/ADMIN_FRONTEND_EXECUTION_PLAN.md) 继续向下收敛，负责定义 Admin 前端的视觉语言、布局规则、组件行为和交互基线。

生效边界：

- 不扩张页面范围，不新增任何执行方案未纳入的页面。
- 不引入假数据、假图表、假按钮。
- 与真实 API 或执行方案冲突时，以 [API.md](../API.md) 和 [ADMIN_FRONTEND_EXECUTION_PLAN.md](../plans/ADMIN_FRONTEND_EXECUTION_PLAN.md) 为准。

## 2. 设计目标

1. 高密度但不压迫。后台场景需要高信息密度，但必须保证 3 秒内可定位主要操作区。
2. 可扫读。标题、指标、状态、风险项必须一眼分层，避免所有信息同权重堆叠。
3. 可追溯。删除、状态切换、权限分配、导入导出等高风险操作必须有明确确认与反馈。
4. 可落地。所有规范都要能直接映射到 `React 18 + Ant Design 5 + CSS Variables`，不依赖额外设计系统。

## 3. 视觉方向

### 3.1 主题定义

本项目采用 `Mineral Console` 视觉方向：

- 背景使用温暖矿物色，而不是纯白大平板。
- 主色使用稳重的石油蓝，强调“可信、可控、可维护”。
- 点缀色使用铜橙，只用于重点 CTA、提醒或人工介入点。
- 整体气质偏企业运维中控，而不是消费化营销页面。

### 3.2 关键词

- 稳定
- 清晰
- 审计感
- 有层次但不过度装饰

### 3.3 禁止项

- 霓虹、赛博、发光描边。
- 大面积纯黑或纯白极端对比。
- 无数据支撑的趋势图、热力图、地域图。
- 超轻字重、小字号堆叠、低对比浅灰文本。

## 4. 设计 Token

基础 token 草案已同步落在 [admin-ui-tokens.css](./admin-ui-tokens.css)，后续实现时可直接迁移到 `frontend/admin/src/styles/tokens.css`。

### 4.1 色彩系统

| Token | 值 | 用途 |
|------|----|------|
| `--color-canvas` | `#F4F1EA` | 应用整体背景 |
| `--color-layout` | `#E9E3D5` | Sidebar 与大区块分层底色 |
| `--color-surface` | `#FFFFFF` | 卡片、抽屉、表单面板 |
| `--color-surface-muted` | `#F8F5EF` | 表格工具栏、弱容器 |
| `--color-surface-strong` | `#DDD5C6` | 分组标题底、边界强调 |
| `--color-text-strong` | `#17212B` | 主文本 |
| `--color-text-base` | `#314150` | 正文 |
| `--color-text-muted` | `#677380` | 次级说明 |
| `--color-text-inverse` | `#F8FAFC` | 深色背景上的文本 |
| `--color-border-soft` | `#D6D0C3` | 默认边框 |
| `--color-border-strong` | `#BFB6A6` | 高对比边框 |
| `--color-primary` | `#0E5A6A` | 主操作色 |
| `--color-primary-hover` | `#0A4B59` | 主操作 hover |
| `--color-accent` | `#C26D3A` | 重点提示、次主按钮 |
| `--color-success` | `#217A5B` | 成功、已启用、已激活 |
| `--color-warning` | `#B7791F` | 风险、锁定、待确认 |
| `--color-danger` | `#B33A3A` | 删除、禁用、失败 |
| `--color-info` | `#2D6A9F` | 信息提示 |

### 4.2 状态映射

| 领域状态 | 颜色 | 呈现方式 |
|----------|------|----------|
| 用户 `已激活` | `success` | 实心状态点 + 浅底 Tag |
| 用户 `未激活` | `info` | 浅蓝灰 Tag |
| 用户 `已锁定` | `warning` | 琥珀色 Tag |
| 用户 `已禁用` | `danger` | 红色 Tag |
| 角色/权限 `启用` | `success` | 绿色开关或 Tag |
| 角色/权限 `禁用` | `danger` | 红色 Tag |
| Webhook `active` | `success` | 绿色 Tag |
| Webhook `inactive` | `warning` | 琥珀色 Tag |
| 登录失败 | `danger` | 红色点标记 |
| 登录成功 | `success` | 绿色点标记 |

### 4.3 字体系统

| 层级 | 字体 | 说明 |
|------|------|------|
| 主字体 | `IBM Plex Sans`, `PingFang SC`, `Microsoft YaHei`, sans-serif | 页面主体、标题、表格 |
| 等宽字体 | `JetBrains Mono`, `Consolas`, monospace | ID、状态码、时间戳、Webhook 事件名 |

字号与字重：

- `32 / 600`: 仪表盘总览数字、登录页主标题
- `24 / 600`: 页面标题
- `20 / 600`: 分区标题
- `16 / 600`: 卡片标题、表单大标签
- `14 / 500`: 正文、表格内容、按钮
- `12 / 500`: 辅助说明、标签、注释

## 5. 栅格与布局

### 5.1 页面壳层

- 左侧导航宽度：`248px`
- 折叠导航宽度：`84px`
- 顶栏高度：`64px`
- 页面内容最大宽度：`1440px`
- 页面容器左右留白：桌面 `32px`，平板 `24px`，移动 `16px`

### 5.2 栅格

| 断点 | 栅格 | 列间距 | 场景 |
|------|------|--------|------|
| `>= 1280px` | 12 列 | 24px | Desktop 主后台 |
| `768px - 1279px` | 8 列 | 20px | Tablet / 小屏笔记本 |
| `< 768px` | 4 列 | 16px | Mobile |

### 5.3 间距与圆角

- 间距刻度：`4 / 8 / 12 / 16 / 24 / 32 / 40 / 48`
- 小型控件圆角：`10px`
- 卡片和抽屉圆角：`16px`
- 大型容器圆角：`20px`

### 5.4 阴影

- 卡片阴影：轻量，强调层次，不强调浮夸漂浮感。
- 抽屉/弹窗阴影：明显高于卡片，但透明度控制在 `12%` 以内。

## 6. 组件规范

### 6.1 App Shell

- Sidebar 采用深一点的矿物底色，与内容区形成结构分层。
- 顶栏左侧放页面标题和面包屑，右侧固定为全局搜索预留位、当前用户信息、退出入口。
- 非管理员登录后，导航仅显示 `Webhooks / Profile / Security` 三组可访问页面。

### 6.2 Page Header

每个页面头部保持四段式结构：

1. 标题
2. 一句范围说明
3. 右侧主操作区
4. 次级状态信息，如“最后刷新时间”

禁止在页面头部堆叠超过两个主按钮。

### 6.3 Filter Bar

根据后端能力分三类：

- `组合筛选条`：只用于 `/users` 和 `/import-export`，可同时提交多个条件。
- `单维筛选条`：用于 `/roles`、`/permissions`、`/logs/*`，一次只激活一个查询维度，避免 UI 表达超出后端查询能力。
- `动作工具条`：用于 `/webhooks`、`/profile`，只保留刷新、创建、编辑等轻操作。

### 6.4 Metric Card

仪表盘指标卡统一规则：

- 左上是指标标题
- 中间是大号数字
- 右上是状态图标或补充标签
- 底部是一行说明文字

禁止使用折线图、面积图冒充趋势。
如需占比，只能用现有字段在前端做简单比率计算。

### 6.5 数据表格

- 头部固定高度，列标题字重 `600`
- 行 hover 使用极浅主色背景
- 表格默认不做斑马纹
- 操作列固定在右侧
- 分页统一放右下角
- 列表为空时必须给出下一步建议，不允许空白页

推荐表格密度：

- 默认使用 AntD `middle`
- 日志表、权限表允许切到 `small`

### 6.6 抽屉与弹窗

- `详情`、`编辑` 优先使用右侧抽屉，便于保留列表上下文
- `删除确认`、`状态切换确认` 使用居中弹窗
- `分配角色`、`分配权限` 使用大号弹窗，内部可包含树或双栏选择器

### 6.7 表单

- 表单标签左对齐
- 必填标识保持统一红点或星号
- 单列表单最大宽度 `560px`
- 双列表单仅用于用户资料类页面，不用于权限配置
- 长文本输入区默认展示字符限制提示

### 6.8 反馈组件

- 加载：优先骨架屏，局部操作可用按钮 loading
- 成功：轻量 toast，不阻断流程
- 失败：错误提示 + 可恢复动作
- 危险动作：必须二次确认

## 7. 交互规范

### 7.1 删除与危险操作

- 删除用户、角色、权限、Webhook 时必须展示资源名称。
- 二次确认按钮使用危险色，不使用“主要按钮”配色。
- 删除成功后停留在当前页面，刷新当前列表，不跳转空白页。

### 7.2 状态切换

- 启用/禁用、锁定/解锁类操作使用显式文本，不只依赖颜色。
- 切换成功后局部刷新当前行，不整页闪烁。

### 7.3 上传与下载

- 导入、头像上传显示明确的文件限制和格式。
- 导出使用显式格式选择，下载开始后按钮进入短时 loading。
- 上传失败必须保留错误明细区，尤其是批量导入。

### 7.4 日志与审计

- 时间统一使用 `YYYY-MM-DD HH:mm:ss`
- `IP`、`Request Path`、`Event Type`、`ID` 使用等宽字体
- 长 JSON 或请求参数通过抽屉展开，不在表格中完整摊开

## 8. 响应式规则

- `< 1280px` 时，Dashboard 卡片从四列降为两列。
- `< 1024px` 时，Sidebar 默认折叠。
- `< 768px` 时，列表页顶部操作条改为纵向堆叠。
- `< 768px` 时，抽屉改全屏。
- Mobile 只保留最高优先级列，其余字段进入“展开详情”。

## 9. 无障碍与可用性

- 文本与背景对比度不低于 `4.5:1`
- 所有图标按钮必须提供文字 tooltip
- 表单错误必须靠近字段显示
- 键盘焦点可见，焦点边框使用主色高亮
- 状态不能只靠颜色区分，必须同时有文字

## 10. Ant Design 落地映射

| 需求 | 落地建议 |
|------|----------|
| 全局主题 | 通过 `ConfigProvider` 覆盖 `colorPrimary`、`borderRadius`、`fontFamily` |
| 页面容器 | 使用 `Layout` + 自定义 CSS Modules |
| 指标卡 | `Card` + 自定义头尾结构 |
| 列表页 | `Table` + `Form` + `Space` |
| 状态标签 | `Tag` + 统一状态映射函数 |
| 抽屉编辑 | `Drawer` + `Form` |
| 二次确认 | `Modal.confirm` 或包装组件 |
| 空态/错误态 | 基于 `Result`、`Empty` 二次封装 |

## 11. 页面级设计基线

- `/login` 使用双栏欢迎布局，但不展示社交登录按钮。
- `/dashboard` 只展示真实统计卡片和简表区块。
- `/users` 只做列表、筛选、详情、编辑、状态切换、删除、角色分配。
- `/roles`、`/permissions` 保持“列表 + 编辑弹窗 + 分配弹窗”结构。
- `/logs/*` 优先突出筛选与详情展开，不做复杂可视化。
- `/profile/security` 使用分段卡片，而不是堆满一个超长大表单。

## 12. 不可突破的限制

- 不做 `/settings`
- 不做用户创建页
- 不做批量用户操作
- 不做全局设备管理页
- 不做社交登录回调页
- 不做细粒度按钮权限前端系统
- 不引入图表库实现“看起来更像后台”的伪需求