Files
persionalBrand/apps/admin/design.md
T
que01 0d9f4a7d6f
CI / Static checks (push) Has been cancelled
CI / Production build (push) Has been cancelled
CI / API integration (push) Has been cancelled
CI / Taro builds (acheng-campus-food) (push) Has been cancelled
CI / Taro builds (atelier-solopreneur) (push) Has been cancelled
CI / Taro builds (linjing-editorial) (push) Has been cancelled
CI / Browser regression (push) Has been cancelled
refactor: 拆分品牌业务类型与页面方案
2026-10-20 17:04:30 +08:00

20 KiB
Raw Blame History

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 卡片,标识 + 说明 + 表单 + 通栏主按钮;错误态展示在字段下方
首次改密 同登录卡片形态,说明文案 + 三个密码字段 + 「保存新密码」
品牌概览 品牌卡 + 三张指标卡(等宽一行)+ 两栏(发布准备度 / 品牌内容检查)
内容与发布 内容发布 / 小程序发布 / 小程序配置三个分区;内容发布含发布状态卡、草稿卡和历史版本表,不承载业务类型或页面方案选择
页面方案 当前业务类型与页面方案 + 升级预览 + 版本选择 + 配置恢复 + 高级示例内容导入
品牌管理 品牌列表与创建入口;创建品牌先选不可变的业务类型,再选兼容页面方案,创建时不导入示例内容
小程序页面 左右两栏:左 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。