# 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,不使用表格线。 落地:``,字号与间距由 `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`。