- 列表按模板声明的类型顺序排列,与必填清单顺序一致 - 类型标签并入说明行,去掉与类型重复的标签;展示位置改为可读页面名 - 类型未识别时页面名补充中文映射(service/inquiry) - 无配图时按类型显示线性图标,替换统一的文件图标 - 摘要长文本按前 3 个字段截断,避免单行超长 - 记录行改为顶部对齐,操作按钮垂直居中,行内段落间距交给 gap - Modal destroyOnClose 迁移到 destroyOnHidden,消除 antd 弃用告警 - 发布必填清单显示同类已配置条数,已配置区块显示总数
19 KiB
Admin Design Language
本文件是 @personal-brand/admin 管理后台的视觉与交互规范,是后台 UI 的唯一设计来源。
设计目标:简洁、干净。留白充足、层级靠排版建立、装饰最少。信息架构与业务语义不在本文件范围内,如需变更请走产品文档。
适用范围:apps/admin/src 下所有页面、组件与样式。新增 UI 前先读本文件,冲突以本文件为准。
- 本文件同时作为 AI 设计工具的规范输入:在 MasterGo「AI 快搭」中直接上传本文件即可,无需重复描述视觉规则。生成提示词见
docs/design/admin-mastergo-guide.md。 - 技术约束:antd 6 + React 19 + React Router 7 + TanStack Query 5。不引入新的 UI 库、状态管理、校验或路由方案。
- 主题令牌统一在根节点通过
ConfigProvider注入,页面与组件内不得写零散色值。 - 共享视觉元素放
apps/admin/src/components/,页面专属组件留在各自的features/目录。 - 中文界面。桌面优先,最小可用宽度 1024px;窄屏允许侧栏折叠,不提供移动端专用布局。
1. 颜色
中性灰打底,只保留一个强调色。禁止渐变、彩色大面积色块、玻璃拟态。
基础色
| 用途 | 令牌 | 值 |
|---|---|---|
| 页面底色 | colorBgLayout |
#F7F8FA |
| 卡片/容器底色 | colorBgContainer |
#FFFFFF |
| 次级填充(表头、悬停) | colorFillQuaternary |
#FAFAFB |
| 悬停底色 | colorFillTertiary |
#F7F8FA |
| 容器边框 | colorBorderSecondary |
#E7E9EC |
| 行分隔线 | colorSplit |
#F0F1F3 |
| 控件边框 | colorBorder |
#D8DBE0 |
文字色
| 用途 | 令牌 | 值 |
|---|---|---|
| 主文字 | colorText |
#1C1F23 |
| 次要文字 | colorTextSecondary |
#6B7280 |
| 辅助/占位文字 | colorTextTertiary |
#9AA1AC |
| 禁用文字 | colorTextQuaternary |
#C3C7CF |
强调色
| 用途 | 令牌 | 值 |
|---|---|---|
| 主色 | colorPrimary |
#2563EB |
| 主色悬停 | colorPrimaryHover |
#1D4ED8 |
| 主色按下 | colorPrimaryActive |
#1E40AF |
| 选中底色 | colorPrimaryBg |
#EFF4FF |
| 选中/链接文字 | colorLink |
#2563EB |
强调色只用于:主按钮、选中态、链接、关键数字、聚焦描边。不得用于大面积背景。
例外:小程序预览区(iframe / 模拟器内)显示的是模板自身的品牌色(例如餐饮模板的砖红 #B54A2C),与后台无关,不视为违规,也不要「修正」成后台强调色。
状态色
状态一律用「浅底 + 深字」,不使用 antd 的实心鲜艳 Tag。
| 语义 | 底色 | 边框 | 文字色 |
|---|---|---|---|
| 成功 / 已发布 | #ECFDF3 |
#ABEFC6 |
#067647 |
| 警告 / 进行中 | #FFFAEB |
#FEDF89 |
#B54708 |
| 错误 / 失败 | #FEF3F2 |
#FBD5D1 |
#B42318 |
| 中性 / 草稿 | #F2F4F7 |
#E7E9EC |
#475467 |
| 信息 / 系统态 | #EFF4FF |
#B2CCFF |
#2563EB |
- 底色 + 边框 + 深色文字三件套同时用于
StatusTag、Alert、错误条与空状态,不得混用其他色阶。 - 需要中间调的场合(图标、进度条完成态)使用中间色:成功
#12B76A、警告#F79009、错误#F04438、信息#2563EB。
2. 排版
系统无衬线字体栈:Inter、PingFang SC、Noto Sans SC、sans-serif。
| 角色 | 字号 | 字重 | 行高 |
|---|---|---|---|
| 页面标题 | 24px | 600 | 1.35 |
| 区块/卡片标题 | 16px | 600 | 1.45 |
| 强调正文、品牌名 | 15px | 600 | 1.5 |
| 正文 | 14px | 400 | 1.5 |
| 表单标签、次要正文 | 13px | 400 | 1.5 |
| 辅助说明、时间戳 | 12px | 400 | 1.5 |
| 指标数值 | 28px | 600 | 1.2 |
- 层级靠字号与字重建立,不靠颜色、下划线、边框。
- 中文不使用斜体;英文与数字不加字距。
- 一段说明文字最长不超过 2 行,超出应改写或省略。
- 中英文与数字之间保留一个空格。
3. 间距与布局
8pt 网格。间距只使用 4 / 8 / 12 / 16 / 24 / 32。
| 场景 | 值 |
|---|---|
| 页面内容区内边距 | 24px |
| 内容最大宽度 | 1200px,居中 |
| 页面头部到主体 | 24px |
| 卡片内边距 | 20px |
| 卡片之间 | 16px |
| 表单字段之间 | 16px |
| 标签与输入框之间 | 6px |
| 行内元素之间 | 8px |
| 小节标题到内容 | 12px |
外壳尺寸:
- 侧栏宽 232px,折叠宽 0(
breakpoint="lg")。 - 顶栏高 56px,与侧栏品牌区对齐。
4. 形状与层次
| 元素 | 圆角 | 说明 |
|---|---|---|
| 卡片 | 10px | 默认 1px #E7E9EC 边框,无阴影 |
| 弹窗 | 12px | 极轻阴影 |
| 按钮、输入框、下拉 | 6px | 统一 |
| 状态标签 | 6px | 高 24px,内边距 2px 8px |
| 图片/头像缩略图 | 8px | 头像用圆形 |
| 进度条 | 3px | 高 6px |
- 层次手段优先级:留白 > 字号字重 > 1px 浅边框 > 阴影。
- 阴影仅用于浮层:
0 1px 2px rgba(16, 24, 40, 0.04),弹窗可加0 8px 24px rgba(16, 24, 40, 0.08)。 - 卡片不使用阴影,不叠加边框与阴影。
5. 组件规范
侧栏导航
- 白底,右侧 1px
#E7E9EC分隔线。不使用深色主题(现有theme="dark"需移除)。 - 顶部品牌区:24x24 圆角 6px 标识 + 品牌名,高 56px。
- 分组标题:12px
#9AA1AC,上下留白 8px,不加图标、不做大写英文。 - 菜单项:高 36px,圆角 6px,左侧 16px 线性图标(描边 1.5px),文字 14px。
- 三态:默认深灰文字无底色;悬停
#F7F8FA;选中#EFF4FF底 +#2563EB文字与图标 + 字重 500。
顶栏
- 高 56px,白底,底部 1px 分隔线,左右内边距 24px。
- 左侧:品牌名 14px/600 + 灰色 13px「品牌工作区」+ 角色标签。
- 角色标签:负责人
#EFF4FF/#2563EB,内容编辑#F2F4F7/#475467。 - 右侧:品牌切换下拉(尺寸
small、白底细边框)+ 「退出登录」文字按钮。 - 顶栏不随机滚动,内容区独立滚动。
页面头部
统一通过 AdminPageHeader 渲染:页面标题 24px/600 + 可选副标题 14px 次要色 + 右侧操作区。底部间距 24px。页面内不得再手写标题层级。
卡片
- 标题 16px/600,标题区底部间距 12px,标题右侧放次要操作(文字按钮)。
- 卡片只承载一个主题;一个页面最多两级卡片嵌套,避免再嵌套。
按钮
| 类型 | 场景 |
|---|---|
| 主按钮(实心强调色) | 每个页面/卡片最多一个,用于当前主流程 |
| 次按钮(白底细边框) | 并列的次要操作 |
| 文字按钮 | 表格行内操作、列表「去处理」、返回类操作 |
| 危险按钮 | 删除、撤回、卸载等不可逆操作 |
- 高度:默认 32px,主流程按钮 40px。
- 等待态用
loading,禁用态用disabled,禁止用文字变形表达状态。
表单
- 标签在输入框上方,13px
#475467,必填星号#B42318。 - 帮助文本 12px
#9AA1AC,错误文本 12px#B42318,都显示在字段下方。 - 输入框聚焦:1.5px
#2563EB描边 +#EFF4FF2px 外发光。 - 提交失败必须保留用户输入,错误提示定位到字段或表单顶部,禁止弹窗后清空。
数据表格
- 无竖线;表头底色
#FAFAFB,13px#6B7280。 - 行高 52px(含头像/双行内容时 60px)。
- 行分隔线
#F0F1F3;悬停行底色#FAFAFB。 - 操作列统一放最右,使用文字按钮,最多 2 个直接操作,更多收进「更多」下拉。
- 空数据不显示空表头,改用空状态组件。
状态标签
- 统一组件,按语义取色,默认
尺寸 = 24px 高 / 12px 字。 - 发布状态机映射:
building信息、uploaded中性、under_review警告、approved成功、rejected错误、published成功、failed错误、superseded中性。 - 同一列表内标签宽度尽量对齐,避免视觉跳动。
弹窗
- 宽 480px(简单表单)或 560px(多字段),圆角 12px。
- 标题 16px/600,底部操作右对齐:次按钮在左、主按钮在右。
- 提交中禁用关闭与重复提交。
描述列表(键值展示)
用于咨询详情、版本信息等只读信息:字段名 13px #6B7280,值 14px #1C1F23,行间距 12px,不使用表格线。
落地:<Descriptions className="admin-descriptions" column={1} size="small">,字号与间距由 admin.css 与 Descriptions 令牌统一,不逐处传 bordered。
Tabs
- 顶部 1px 分隔线,选中项底部 2px 强调色下划线 + 深色文字,未选中 14px
#6B7280。 - 不超过 5 个 Tab,超出改用左侧分段导航。
切换控件选型
同一层级切换控件只允许两种,按范围选择,不得混用:
| 场景 | 控件 | 现状 |
|---|---|---|
| 页面级分区(内容结构不同、各自独立成段) | Tabs |
配置与发布 |
| 区块内视图切换(同一份数据换视角) | Segmented |
小程序页面、业务提供项编辑弹窗 |
Segmented 用作「取值选择」(如能力状态降级/启用/停用)时按表单控件处理,不受本表约束。
标题层级
页面内标题只用三档,禁止再用 Typography.Title level 直接指定字号:
| 用途 | 类名 | 字号 |
|---|---|---|
| 区块标题 | admin-section-title |
16px / 600 |
| 面板内小标题、表单分组 | admin-subhead |
15px / 600 |
| 列表行、条目名称 | admin-row-title |
14px / 600 |
页面级标题只由 AdminPageHeader 输出(24px / 600),一个页面只出现一次。
进度
- 高 6px,圆角 3px,轨道
#F0F1F3,进度条强调色;完成态用成功色。 - 进度条上方 14px 文案说明当前含义,不允许只有一根进度条。
6. 状态设计
每个远程数据页面必须显式实现四种状态,不得出现无反馈的白屏。
| 状态 | 规范 |
|---|---|
| 加载中 | 骨架屏,形状与最终内容一致;不用居中转圈 |
| 空数据 | 居中:极简线性图形 + 15px/600 标题 + 13px 灰色说明 + 主操作按钮 |
| 请求失败 | 卡片内错误条:#FEF3F2 底 + 1px 浅红边框 + 圆角 8px + 文案 14px + 「重试」文字按钮 |
| 成功反馈 | 右上角轻量 toast,白底圆角 8px,280–320px 宽 |
- 行内操作使用按钮
loading表达进行中,不用全局遮罩。 - 提交成功后:关闭弹窗、重置表单、刷新受影响列表;提交失败保持原状。
- 幂等写操作要防止重复点击(提交中禁用)。
落地约定:
- 空状态统一用
EmptyState(components/EmptyState.tsx);表格内用compact变体,整块区域用默认变体。禁止再使用 antd 默认Empty插画。 - 列表 / 表格加载统一用
TableSkeleton、ListSkeleton(components/TableSkeleton.tsx)替换内容区,不使用 antdTable的转圈遮罩;卡片级加载用LoadingStack。 - 卡片内的写操作只在「有未保存修改」时使用主按钮,其余状态用次要按钮并禁用,同时用
StatusTag标明修改状态。
7. 页面结构
以下为各页面的视觉结构约定,业务逻辑不变。
| 页面 | 结构要点 |
|---|---|
| 登录 | 居中 400px 卡片,标识 + 说明 + 表单 + 通栏主按钮;错误态展示在字段下方 |
| 首次改密 | 同登录卡片形态,说明文案 + 三个密码字段 + 「保存新密码」 |
| 品牌概览 | 品牌卡 + 三张指标卡(等宽一行)+ 两栏(发布准备度 / 品牌内容检查) |
| 配置与发布 | 三 Tab(内容发布 / 小程序发布 / 小程序配置);发布状态卡 + 草稿卡 + 历史版本表 |
| 小程序页面 | 左右两栏:左 380px 编辑面板,右预览画布;预览内选中区域虚线高亮 + 区域名气泡 |
| 信任内容 | 列表行(类型图标或配图 + 标题 + 发布状态标签 + 类型/展示位置说明 + 两行摘要 + 行内操作),按模板类型顺序排列,不用表格 |
| 业务提供项 | 表格(名称 / 价格 / 状态开关 / 排序 / 操作)+ 新增弹窗 |
| 咨询记录 | 顶部三指标 + 左 380px 列表 + 右详情的主从布局 |
| 模板与表单设置 | 行业模板网格(三列)+ 咨询表单字段编辑器 + 底部危险操作区 |
| 能力插件 | 插件卡片列表(图标 + 名称 + 说明 + 开关),停用态降低对比度 |
| 团队成员 | 表格(成员 / 角色 / 状态 / 最近登录 / 操作)+ 邀请弹窗 |
两栏页面在小屏下折叠为单列,编辑/预览改为上下排列。
8. 无障碍与细节
- 正文与背景对比度不低于 4.5:1;标签文字与标签底色不低于 4.5:1。
- 可点击元素最小热区 32x32px;纯图标按钮必须带
aria-label。 - 焦点可见:所有可交互元素保留 1.5px 强调色聚焦描边。
- 状态不能只靠颜色区分,需同时有文字。
- 数字使用等宽数字排版(
font-variant-numeric: tabular-nums),避免指标和价格跳动。
9. 禁止项
- 渐变、玻璃拟态、拟物纹理、装饰性插画铺满界面。
- 深色侧栏、彩色大面积色块、实心鲜艳 Tag。
- 重阴影、多重边框、卡片再套卡片超过两级。
- emoji 作为图标;图标与文字混排时不对齐基线。
- 页面内写死色值、圆角、间距魔法数字。
- 一个页面出现多个主按钮竞争视觉焦点。
10. antd 令牌映射
落地时在 Admin 根节点用 ConfigProvider 注入,不逐页覆盖。
const theme = {
token: {
colorPrimary: "#2563EB",
colorLink: "#2563EB",
colorText: "#1C1F23",
colorTextSecondary: "#6B7280",
colorTextTertiary: "#9AA1AC",
colorTextQuaternary: "#C3C7CF",
colorBgLayout: "#F7F8FA",
colorBgContainer: "#FFFFFF",
colorBorder: "#D8DBE0",
colorBorderSecondary: "#E7E9EC",
colorSplit: "#F0F1F3",
colorFillTertiary: "#F7F8FA",
colorFillQuaternary: "#FAFAFB",
colorSuccess: "#12B76A",
colorSuccessBg: "#ECFDF3",
colorSuccessBorder: "#ABEFC6",
colorSuccessText: "#067647",
colorWarning: "#F79009",
colorWarningBg: "#FFFAEB",
colorWarningBorder: "#FEDF89",
colorWarningText: "#B54708",
colorError: "#F04438",
colorErrorBg: "#FEF3F2",
colorErrorBorder: "#FBD5D1",
colorErrorText: "#B42318",
colorInfo: "#2563EB",
colorInfoBg: "#EFF4FF",
colorInfoBorder: "#B2CCFF",
colorInfoText: "#2563EB",
borderRadius: 6,
borderRadiusLG: 10,
borderRadiusSM: 4,
fontSize: 14,
fontFamily:
"Inter, 'PingFang SC', 'Noto Sans SC', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
controlHeight: 32,
controlHeightLG: 40,
boxShadow: "0 1px 2px rgba(16, 24, 40, 0.04)",
boxShadowSecondary: "0 8px 24px rgba(16, 24, 40, 0.08)",
wireframe: false,
},
components: {
Layout: {
headerHeight: 56,
headerBg: "#FFFFFF",
headerPadding: "0 24px",
siderBg: "#FFFFFF",
bodyBg: "#F7F8FA",
triggerBg: "#FFFFFF",
triggerColor: "#475467",
triggerHeight: 40,
},
Menu: {
itemHeight: 36,
itemBorderRadius: 6,
itemBg: "transparent",
itemColor: "#475467",
itemHoverBg: "#F7F8FA",
itemHoverColor: "#1C1F23",
itemSelectedBg: "#EFF4FF",
itemSelectedColor: "#2563EB",
itemMarginInline: 8,
itemMarginBlock: 2,
groupTitleColor: "#9AA1AC",
groupTitleFontSize: 12,
collapsedWidth: 0,
subMenuItemBg: "transparent",
},
Card: { paddingLG: 20, headerFontSize: 16, headerHeight: 52, headerHeightSM: 44 },
Table: {
headerBg: "#FAFAFB",
headerColor: "#6B7280",
rowHoverBg: "#FAFAFB",
headerSplitColor: "transparent",
borderColor: "#F0F1F3",
cellPaddingBlock: 16,
headerBorderRadius: 8,
},
Button: { fontWeight: 500, primaryShadow: "none", defaultShadow: "none" },
Progress: { defaultColor: "#2563EB", remainingColor: "#F0F1F3", lineBorderRadius: 3 },
Tag: { defaultBg: "#F2F4F7", defaultColor: "#475467", borderRadiusSM: 6 },
Tabs: { inkBarColor: "#2563EB", itemSelectedColor: "#1C1F23", itemColor: "#6B7280" },
Form: { labelColor: "#475467", labelFontSize: 13, verticalLabelPadding: "0 0 6px" },
Modal: { borderRadiusLG: 12 },
Statistic: { titleFontSize: 12, contentFontSize: 28 },
Alert: { borderRadius: 8 },
Descriptions: {
labelBg: "#FAFAFB",
labelColor: "#6B7280",
contentColor: "#1C1F23",
itemPaddingBottom: 12,
},
},
};
可执行来源是 apps/admin/src/lib/theme.ts,本块为同值快照;改令牌时两处一起改。
- 新增页面优先使用令牌与共享组件;禁止在 JSX 内写内联色值、字号、圆角(唯一的例外是通过 CSS 变量透传的数据色,例如视觉模板色板的
--swatch-color)。 - 共享视觉组件清单:
AdminPageHeader、AdminSection、StatusTag、EmptyState、TableSkeleton/ListSkeleton、MetricCard、QueryState。