user-system/docs/design/ADMIN_UI_DESIGN_SPEC.md

Admin UI 设计规范

更新时间：2026-03-19

1. 文档定位

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

生效边界：

• 不扩张页面范围，不新增任何执行方案未纳入的页面。
• 不引入假数据、假图表、假按钮。
• 与真实 API 或执行方案冲突时，以 API.md 和 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，后续实现时可直接迁移到 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
• 不做用户创建页
• 不做批量用户操作
• 不做全局设备管理页
• 不做社交登录回调页
• 不做细粒度按钮权限前端系统
• 不引入图表库实现“看起来更像后台”的伪需求