9.4 KiB
9.4 KiB
前端设计系统
- 功能:一份人可读的设计系统说明,记录 LPT 前端的调性、颜色、间距、圆角、文字角色与组件语法,作为新增 UI 与评审的共同基准。
- 何时用:新增页面/组件前;需要决定字号、间距、圆角、颜色取哪个值的时候;评审 UI 是否偏离现有规范时;与
roles/design-principles.md配套使用。
调性
五个刻度上的取值(依据:个人长期使用的学习工具,中文界面,桌面为主兼顾手机,内容是学习记录):
| 刻度 | 取值 | 依据 |
|---|---|---|
| 能量 | 偏安静 | 每天多次打开的记录工具,不喧闹 |
| 完成度 | 偏精致(公差小) | 长期使用,粗糙边缘会持续被看到 |
| 密度 | 中等偏密 | 复习总览要一次看全任务/残片/待归类 |
| 分量 | 中等 | 字重常规,色块面积克制 |
| 严肃度 | 中性偏稳重 | 学习记录,不玩梗、不用插画语言 |
一句话北极星:「像在看一本自己整理的笔记本」——安静、清楚、字先于装饰。
颜色
颜色字面量只允许出现在 src/assets/main.css,组件里一律用 var(--x)。
| 用途 | 变量 | 值 |
|---|---|---|
| 主色(实底、白字,满足 WCAG AA) | --green-700 |
#237556 |
| 文字/链接用主色 | --green-600 |
#2f8f68 |
| 悬停/描边强调 | --green-500 |
#43a879 |
| 深色标题文字 | --green-900 / --green-800 |
#123d2d / #1a5a42 |
| 浅色底(选中、标签底) | --green-100 |
#eef9f3 |
| 页面底 / 卡片底 | --surface / --surface-strong |
#f7fbf8 / #ffffff |
| 主文字 / 次要文字 | --text-primary / --text-secondary |
#1b2a23 / #4b6156 |
| 占位文字 | --text-placeholder |
#69796f |
| 实底强调色上的文字 | --text-on-accent |
#ffffff |
| 结构边框 | --border-soft |
#d6e6dc |
| 提醒语义 | --accent-warning / --accent-warning-soft / --accent-warning-strong / --accent-warning-text |
#e6a23c / #fff8e1 / #b8860b / #856404 |
| 成功语义 | --accent-success-soft / --accent-success-softer / --accent-success-strong / --accent-success-text |
#e8f5e9 / #f1f8e9 / #2e7d32 / #856404 |
| 阴影 | --shadow-soft / --shadow-strong |
见 main.css |
规则:
- 语义色同时提供浅底 + 深字一对,标签/状态块用它,不用纯色底压深字。
- 浅色底上的正文字号颜色必须过 WCAG AA 4.5:1:提醒块内的文字用
--accent-warning-text(#856404,5.17:1,实测踩过的坑);--accent-warning-strong(3.06:1)只能用于描边等非文字场合。 - Element Plus 的
primary与success同源指向主题绿(src/assets/main.css覆盖),组件不逐个改色。 - 状态不只用颜色表达:配色之外配文字或图标。
- Element Plus 默认灰阶不达标,已在
main.css覆盖:EP 的--el-text-color-secondary(#909399,白底 3.08:1)与--el-text-color-placeholder(#a8abb2,2.30:1)都低于 AA,已分别改为--text-secondary与--text-placeholder。不要在使用处再单独写灰色,也不要把 EP 默认灰放回来。 - 深色模式暂未做;将来做时按「同色系降低饱和度 + 提高明度」派生,而不是把浅色值反相。
间距节奏
以 4px 为基数,只用下面这几档(当前代码里散布的 5px / 7px / 9px / 13px 属于漂移,改动到时收敛):
| 语义 | 值 | 用在哪 |
|---|---|---|
| 紧凑 | 4 / 6 / 8px | 图标与文字之间、标签内边距、行内控件间距 |
| 组内 | 10 / 12px | 卡片内相邻元素、列表条目之间 |
| 组间 | 14 / 16px | 区块内子块之间、卡片之间 |
| 区块间 | 20 / 24px | 页面主要区块之间 |
| 页面留白 | 32px 起 | 首屏与页脚 |
- 组内紧、组间松;同一种关系用同一档。
- 卡片内边距:常规
18px,紧凑列表行12–14px。 - 内容最大宽度:正文/表单页
960px居中(如 TagReview)。
圆角、描边、阴影
- 圆角档位(当前有 3/4/6/8/10/12/18 共 7 种,收敛为 4 档):
4px行内小控件(按钮、输入框、标签行)8px块级容器(列表行、内嵌面板)18px页面卡片(.surface-card)9999px仅用于纯状态胶囊(.map-badge这类)
- 嵌套圆角:内层 ≤ 外层。
- 描边统一
1px solid var(--border-soft);需要更重的分隔时靠间距与底色,不靠加粗边框。 - 阴影只用
--shadow-soft(常态)与--shadow-strong(悬停抬升),不为每个组件各自造值。
文字角色
固定 6 个角色,不新增中间档:
| 角色 | 字号 | 字重 | 颜色 | 用在哪 |
|---|---|---|---|---|
| 页面标题 | clamp(24px, 3vw, 34px) |
600 | --text-primary |
.page-title,每页一个 |
| 页面区块标题 | 17px | 600 | --green-900 |
页面内的模块 h2(如「按任务复习」) |
| 区块内标题 | 15px | 600 | --green-900 或 --text-primary |
卡片/列表行内的 h3 与名称 |
| 正文 | 14px | 400 | --text-primary |
内容、说明 |
| 辅助文字 | 12–13px | 400 | --text-secondary |
提示、meta、时间 |
| 数据 | 13px | 600 | 语义色 | 指标、覆盖率、条数;加 tabular-nums |
- 正文行高 1.6(
body已设);标题行高 1.2–1.35。 - 中英混排时检查基线与字重观感;数字与单位不拆行。
- 不靠加粗表达强调:优先用字号、颜色和位置差。
- 正文对比度是硬门槛:正文与辅助文字都 ≥4.5:1;浅色底上的深字要用登记过的 token(如提醒块用
--accent-warning-text),不要拿只达到 3:1 的强调色去写文字。
组件语法
一套统一语法,跨按钮、输入、标签、状态、空态保持一致:
- 按钮:主操作
type="success"size="large"(40px);次级plain;编辑类type="primary";危险type="danger"。工具栏/页内操作用默认尺寸,列表行内用size="small"(28px,不再调小)。同一功能不混用 success 与 primary。 - 标签/状态胶囊:小字号、浅底 + 深字(
--accent-success-soft+--green-700等),不使用粗边框 + 重阴影。 - 列表行:整行可点(
role="link"+tabindex="0"+@keydown.enter/@keydown.space),行内附加动作@click.stop;操作簇右对齐,不用space-between拉两端。 - 列表超过一页就分页:页大小 20;列表顶部给轻量页码(「‹ 上一页 · 第 X / Y 页 · 下一页 ›」)+ 底部完整
el-pagination,避免「必须先滚到底才能再翻」。分页后滚回 Tab 头(保住「在哪个 Tab」,也让顶部页码留在视野)。 - 列表接口用
pageNum/pageSize并返回PageResult<T>(records/total/size/current/pages);后端排序必须带唯一键兜底(如id desc),否则翻页会重复或漏。 - 汇总数字单独取全量口径(如
GET /review/summary):列表分页后把每页数字相加会得到「本页合计」而不是总数。 - 筛选条件下推到服务端(如按标签筛任务),不在客户端筛当前页。
- 选项类下拉(需要全部而不是一页):用专用轻量接口(如
/tasks/options),不复用带聚合的分页列表接口。 - 需要可见的纤细分隔线与浅底胶囊要放在不透明底上:页面背景是渐变,
--border-soft纤细分隔线与--accent-*-soft浅底直接放上去对比只有 ~1.1:1,屏幕上等于不存在(Tab 条、胶囊都踩过)。 - 容器语法分两级,同一页里同级条目必须用同一套:
- 区块卡(
.surface-card):18px 圆角 + 半透明底 +--shadow-soft,只用于页面级的独立区块(如待归类块),不用于列表条目。 - 列表行:8px 圆角 +
--surface-strong纯白 +1px var(--border-soft)+ 无阴影;hover 只改边框色(可加--shadow-soft),不做位移。同一页里任务行与导图行都走这一套。
- 区块卡(
- 卡片:
.surface-card统一背景/圆角/阴影;hover只做边框变色 +--shadow-soft,不做缩放、位移与发光。 - 模块切换用 Tab:同一页里的两个并列模块(如按任务/按标签复习)用
el-tabs同位置切换,URL 带?tab=可深链;未访问过的 Tab 懒加载(lazy),Tab 标签上用胶囊显示条数并写清单位(45 个/3 张),让用户不进去也知道另一边有多少东西,也不会把「3 张导图」读成「3 条内容」。 - 空状态:
el-empty+ 一句说明 + 一个主操作按钮(size="small"或默认,视位置);页面级空态必须有下一步动作。 - 等待文案:「正在 X…,已等待 N 秒」用
useElapsedSeconds(既有规则),不用固定延时。 - 图标:当前未引入图标库;需要时按方向选一套(一产品只用一套),不混用 emoji 与 SVG。
- 时间显示:统一用
src/utils/format.ts的formatDateTime(Intl),不写replace("T"," ").substring(0,16)。
不要什么
(同 roles/design-principles.md 的禁用清单,这里只列与本设计系统直接冲突的)
- 不新增第 6 档字号、第 5 档圆角、第 3 档阴影——需要时先改本文档,再改变量。
- 不为单个页面另造一套色板;品牌感靠这套语义色与排版一致性,不靠换主色。
- 不在组件里写颜色字面量或
#fff之外的中性色(rgba(255,255,255,.85)这类半透明卡片底除外,且应下沉为变量)。