Files
persionalBrand/apps/admin/design.md
T
que01 896f3240f9 refactor: 拆分模板治理与咨询表单页面
- /admin/workspace 收敛为「咨询表单与字段」,只做咨询入口表单与高级自定义字段
- 行业模板版本升级/回滚迁入「配置与发布 → 内容发布 → 选择表达方式」
- 移除行业模板安装入口、视觉模板历史与模板组合预览等不可达 UI
- 表单下拉的业务选项改用本品牌后台数据,避免公开接口回退默认品牌导致跨品牌串数据
- 侧栏导航与设计文档同步
2026-10-14 13:55:35 +08:00

419 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`。
| 角色 | 字号 | 字重 | 行高 |
| ------------------ | ---- | ---- | ---- |
| 页面标题 | 20px | 600 | 1.4 |
| 区块/卡片标题 | 16px | 600 | 1.45 |
| 卡片内对象主标题 | 18px | 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,居中 |
| 页面头部到主体 | 32px |
| 卡片内边距 | 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` 渲染:页面标题 20px/600 + 可选副标题 13px 次要色 + 右侧操作区。标题与副标题间距 6px,页头到主体 32px(明显大于卡片之间的 16px)。页面内不得再手写标题层级。
- 页面标题必须与侧栏导航用词一致,不额外添加「小程序内容:」这类前缀;页面职责写进副标题。
- 副标题一句话讲清这一页做什么,最长不超过 2 行;能由页面内文案表达的细节不要重复写在这里。
### 卡片
- 标题 16px/600,标题区底部间距 12px,标题右侧放次要操作(文字按钮)。
- 卡片只承载一个主题;一个页面最多两级卡片嵌套,避免再嵌套。
### 按钮
| 类型 | 场景 |
| -------------------- | ---------------------------------------- |
| 主按钮(实心强调色) | 每个页面/卡片最多一个,用于当前主流程 |
| 次按钮(白底细边框) | 并列的次要操作 |
| 文字按钮 | 表格行内操作、列表「去处理」、返回类操作 |
| 危险按钮 | 删除、撤回、卸载等不可逆操作 |
- 高度:默认 32px,主流程按钮 40px。
- 等待态用 `loading`,禁用态用 `disabled`,禁止用文字变形表达状态。
### 表单
- 标签在输入框上方,13px `#475467`,必填星号 `#B42318`。
- 帮助文本 12px `#9AA1AC`,错误文本 12px `#B42318`,都显示在字段下方。
- 输入框聚焦:1.5px `#2563EB` 描边 + `#EFF4FF` 2px 外发光。
- 提交失败必须保留用户输入,错误提示定位到字段或表单顶部,禁止弹窗后清空。
### 数据表格
- 无竖线;表头底色 `#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` 输出(20px / 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`)替换内容区,不使用 antd `Table` 的转圈遮罩;卡片级加载用 `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` 注入,不逐页覆盖。
```ts
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`。