124 lines
9.4 KiB
Markdown
124 lines
9.4 KiB
Markdown
# 前端设计系统
|
||
|
||
- **功能**:一份人可读的设计系统说明,记录 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)` 这类半透明卡片底除外,且应下沉为变量)。
|