Files
lpt-fe/roles/design-system.md
T

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