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