docs: 补充设计原则、设计系统与界面自检规则

This commit is contained in:
2026-10-22 22:00:21 +08:00
parent a69b350829
commit a0f8abd757
7 changed files with 412 additions and 3 deletions
+19 -1
View File
@@ -1,6 +1,6 @@
# 前端代码标准
- **功能**:约束前端交互、按钮、颜色与主题、卡片列表、移动端、代码整洁、请求层与类型、组合式函数的写法,保证全站一致、可维护。
- **功能**:约束前端交互、按钮、颜色与主题、卡片列表、移动端、界面质量与可访问性、代码整洁、请求层与类型、组合式函数的写法,保证全站一致、可维护。
- **何时用**:新增或修改前端组件、样式、请求封装、composable 时;评审前端改动时。
## 规则
@@ -29,6 +29,23 @@
- 实底主色统一用满足 WCAG AA(白字对比度 ≥4.5:1)的 `--green-700`;`--green-600` 仅用于文字/链接。
- 颜色字面量不得出现在 JS/模板表达式里(如 `:color="'#xxx'"` 引 CSS 变量会失效),需要动态色时保留字面量或改用 CSS 类。
### 界面质量与可访问性
交付前逐项过 `roles/ui-review-checklist.md`;本节只列代码层面的写法要求。
- 可聚焦元素必须有 `:focus-visible` 焦点环;不得写 `outline: none` 而不给替代。粘性头部/遮罩不得盖住获得焦点的控件。
- 过渡显式列出属性(`transition: opacity .2s ease, transform .2s ease`),**禁止 `transition: all`**;只动 `transform` / `opacity`。
- 需要动效时给 `@media (prefers-reduced-motion: reduce)` 降级;全站统一的淡入上移不作为入场方案。
- 统计、覆盖率、计时、金额等需要上下比较的数字加 `font-variant-numeric: tabular-nums`。
- 加载/处理中的文案以 `…`(省略号字符)结尾,不用 `...`。
- 长内容容器加 `min-width: 0` 并允许换行或省略,验证 URL、ID 与用户输入的极端情况。
- 空态与错误态分开:空态给下一步动作,错误态给原因 + 重试;不要用同一个 `el-empty` 兜住失败。
- 加载指示延迟约 150–300ms 再显示,并保证最短可见约 300–500ms,避免快响应时闪一下。**统一用 `useDelayedVisible`**,不要自己写定时器。
- 骨架形状要与最终内容一致(清单在 `roles/ui-review-checklist.md`);骨架用 `main.css` 的 `.skeleton-line`,不要在组件里另造一套灰。
- 纯图标按钮必须有 `aria-label`;装饰图标 `aria-hidden="true"`。
> 页面的信息架构与视觉层级取舍见 `roles/design-principles.md`,设计变量的当前取值见 `roles/design-system.md`;出现新页面或大范围 UI 改动时走 `skills/ui-review/`。
### 卡片列表交互
- 卡片列表的卡片整体可点击进入详情:外层加 `role="link" tabindex="0"` 与 `aria-label`,并绑定 `@click` 及 `@keydown.enter/@keydown.space.prevent`。
@@ -63,5 +80,6 @@
### 组合式函数复用
- “已等待 N 秒”类秒表计时统一使用 `useElapsedSeconds`,禁止组件内手写 `setInterval` 秒数递增。
- 骨架/加载指示的「延迟显示 + 最短可见」统一使用 `useDelayedVisible`,禁止组件内手写 setTimeout 开关加载态。
- 页面新增功能域时先抽 composable(参考 `useSessionHistory` / `useSummaryReport` / `useSessionExpectation`),不要继续膨胀 StartTask 等大页面组件。
- 通用解析器、格式化工具放 `src/utils/`,不埋在组件内(如大纲文本转树应放 utils)。
+54
View File
@@ -0,0 +1,54 @@
# 前端设计原则
- **功能**:规定页面的信息架构与视觉层级取舍,并列出「模型默认做法」禁用清单,保证每屏只服务一个主任务、层级靠对齐与留白而不是靠堆容器与装饰。
- **何时用**:新增页面或重构页面结构时;决定某块内容放主区还是收起时;评审 UI 层级时。出现新页面或大范围 UI 改动时,须同时走 `skills/ui-review/`(见下「独立评审」)。
## 规则
### 页面信息架构
- **一屏一个主角。** 动手前先回答「用户来这一屏是看什么、做什么」,让那件事占据最大面积与最强对比;其余信息靠更小的字号、更轻的字重、更低的对比或靠边的位置退到后面。同一屏里不让两种强调同时抢注意力。
- **内容先行,页面不自述。** 内容型页面的首屏就是第一排内容本身或工作区;**不放"这个页面是干什么的"说明段落**。页面标题已说清的事不再补一行副标题;操作提示放控件附近(`.scope-field` 的 label、输入框 placeholder),不放页面顶部当导语。
- **低频操作不进工具栏,主操作只有一个。** 主操作显眼且每屏不超过一个;次级操作视觉从属(`plain` / 默认尺寸);**更低的低频操作收进「更多」下拉或设置入口**,不要一排等权按钮平铺。
- **按用户心智分模块,不按实现分按钮。** 同一件事的多个入口是两个并列的**内容区块**(各自有标题、说明与主入口),不是工具栏上的两个按钮。
- **渐进披露。** 复杂或低频的选项默认收起(折叠区、弹窗、抽屉),用户需要时展开;不要把全部字段、全部说明一次铺满首屏。
- **待办与汇总各成一块。** 需要用户处理的内容(待归类等)独立成块并给出条数;纯指标汇总独立成块,不与待办混排。
### 视觉层级
- **间距表达分组:** 同一种关系用同一种间距;一组之内紧(8–12px),组与组之间松(14–24px)。先用对齐和留白立结构,再考虑容器与分隔线。
- **分隔线只做一件事:** 同一处分隔不叠双线、不「线 + 边框框」重复;留白已经分开的地方不再补线。全页线的粗细一致,粗细差对应层级差。
- **容器只在必要时加:** 需要分组、表示选中、拉开背景对比或划出操作范围时才用 `.surface-card`。不要把页面、区块、条目、条目说明一层层套成卡片。
- **同层级等重:** 同一层级的卡片看起来一样重;嵌套的圆角与外层协调(内层 ≤ 外层)。
- **每屏过一遍减法:** 逐区块删文字与装饰,只把删了会影响理解的放回去。删完主角没有变大变强的,说明删得不对或本来就不该有。
### 模型默认做法禁用清单
以下写法是 agent 生成界面的默认倾向,不是经过判断的选择;除非能说出**来自本产品的理由**,一律不用:
- 层层套卡片、每个层级都画一遍边框线。
- 单侧彩色边条(引文、当前项左侧加一根色条)。
- 每张普通卡片配不同的强调色、粗边框、重阴影。
- 标题上方加全大写小眉标;meta 信息用 `A · B · C` 串起来。
- 无来由的渐变、发光、emoji 当图标。
- 全站统一的「淡入上移」入场动画;每张卡片都有的 hover 位移。
- 空泛文案:「了解更多」「立即开始」「高级」「丝滑」「无缝」。
- 组件库默认样子只改主色(换了主色也认不出是哪个产品)。
- 数字指标配一个大号数字 + 大渐变强调色(默认处理,不是最优处理)。
### 文案即设计
- 按钮说清按下去会发生什么(「保存草稿」而不是「提交」);同一动作在整个流程中同名——按钮写「发布」,成功提示就写「已发布」。
- 用用户能理解的语言命名,不用系统内部叫法;不写设计说明类文字进界面(「示例」「示意图」「仅保存在本机」)。
- 错误说清**原因 + 怎么修**,不道歉、不含糊;空状态给下一步动作,不给情绪。
### 独立评审
- **触发条件:新页面,或大范围 UI 改动**(整页重构、视觉语言变更、新增信息区块),交付前必须走 `skills/ui-review/`:取图 → 派无上下文的独立评审者 → 按清单修 → 下一轮逐条核对。
- 小改动、局部低风险调整不走技能,按 `roles/ui-review-checklist.md` 自检即可。
- 评审结论(轮次、分数或问题处理情况)写进交付说明;没做独立评审的,明确写出来。
### 设计系统锚点
- 调性、色板/间距/文字角色/组件语法的**当前取值**见 `roles/design-system.md`;新增颜色、间距、圆角、字号先在那里登记,再落 `src/assets/main.css` 的变量。
- 组件里禁止写颜色字面量(既有规则,见 `roles/code-standards.md`)。
+123
View File
@@ -0,0 +1,123 @@
# 前端设计系统
- **功能**:一份人可读的设计系统说明,记录 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)` 这类半透明卡片底除外,且应下沉为变量)。
+75
View File
@@ -0,0 +1,75 @@
# 前端界面交付自检清单
- **功能**:交付前端界面前逐项自检的清单,覆盖状态完整性、交互反馈、可访问性、动效、内容承载与表单,避免出现闪加载、无焦点环、空/错态缺失、长内容撑破等问题。
- **何时用**:改完任何有可见界面变化的代码、准备交付前;code review 前端改动时;补 e2e 用例时。
## 规则
### 状态完整性(每处都要有)
- [ ] **五态齐备**:空 / 稀疏 / 密集 / 加载 / 错误。空态给下一步动作(`el-empty` + 主按钮),错误态给可读原因 + 重试按钮,且**错误与空数据分开**(不要用同一个空态兜住失败)。
- [ ] **加载不闪**:进度指示延迟 ~150–300ms 才显示,并保证最短可见 ~300–500ms;快响应不出现「闪一下」的 spinner。
- [ ] **骨架/占位与最终内容形状一致**,不造成内容跳动。
- [ ] **加载失败可恢复**:保留 `loadFailed` 状态,重试前重置该状态,不只靠 `finally` 关 loading 留白屏。
### 交互与反馈
- [ ] 可点元素看得出可点;悬停才出现的入口,触屏与键盘也能到达。
- [ ] 状态变化时点击区域不变大变小,也不挤动旁边布局。
- [ ] 异步按钮:请求期间自身 loading 或禁用;**loading 时保留原文案**,只加 spinner。
- [ ] 提交按钮保持可用直到请求真正开始,不在填表期间预先禁用。
- [ ] 破坏性操作有确认,或提供 Undo 窗口;危险动作视觉上与主操作分离(`type="danger"`)。
- [ ] 提示/toast 3–5 秒自动消失;**toast 不抢焦点**。
- [ ] 表单校验在失焦时给结论(不要在每次按键时就报错);字段多时提交失败后聚焦第一个错误处。
- [ ] 未保存内容在离开前有提示。
### 可访问性(底线,不是加分项)
- [ ] 全流程键盘可达;Tab 顺序与视觉顺序一致。
- [ ] 每个可聚焦元素有 `:focus-visible` 焦点环;粘性头部/底部、遮罩**不得盖住获得焦点的控件**。
- [ ] 弹窗:焦点进入时被约束在弹窗内、Esc 可关、关闭后焦点归还触发元素。
- [ ] 纯图标按钮有可访问名称(`aria-label`);装饰性图标 `aria-hidden="true"`。
- [ ] 图标按钮与行内控件的指针目标 ≥24px(移动端 ≥44px);视觉小于此值时扩大命中区。
- [ ] 语义元素优先(`button` / `a` / `label`),次选 ARIA;标题层级 `h1→h6` 不跳级。
- [ ] 状态不只靠颜色传达(配色 + 文字或图标)。
- [ ] 文字对比 ≥4.5:1;非文字(图标、边框、图表)对比 ≥3:1。
### 动效
- [ ] 显式列出过渡属性(`transition: opacity .2s ease, transform .2s ease`);**禁止 `transition: all`**。
- [ ] 只动 `transform` / `opacity`,不动 `width` / `height` / `top` / `left`。
- [ ] 尊重 `prefers-reduced-motion`(可动效果在 reduce 下停用或大幅减弱)。
- [ ] 动效可被用户操作打断;不阻塞输入。
- [ ] 只动 1–2 处关键元素表达因果,不做全页统一淡入上移。
### 内容承载
- [ ] 长内容不撑破布局:`min-width: 0` + 省略/换行/`overflow-wrap: anywhere`;URL、ID、用户输入按最长情况验证过。
- [ ] 截断时保留看全文的入口,且相近内容截断后仍能区分。
- [ ] 上下比较的数字(统计、金额、计时、覆盖率)用 `font-variant-numeric: tabular-nums`。
- [ ] 日期、时间、数字用本地化格式(`Intl.DateTimeFormat` / `Intl.NumberFormat`),不手拼字符串。
- [ ] 文案用 `…`(省略号字符)而不是 `...`;加载态文案以 `…` 结尾(「加载中…」「生成中…」)。
- [ ] 中文断行受控:数字与单位、「不会」这类不可拆词不换行;行末不留孤字。
### 表单
- [ ] 每个输入有可见 label(不用 placeholder 代替 label)。
- [ ] 用语义 `type`(`email` / `tel` / `number`)与 `inputmode` 触发正确键盘。
- [ ] 错误就近字段显示并与之关联;复杂输入提供常驻帮助文字,不靠 placeholder。
- [ ] 不用 placeholder 承载必要信息;placeholder 用示例值。
- [ ] 不阻止输入(包括粘贴)、不预先禁用提交;校验放在输入之后。
- [ ] 禁用态与只读态在视觉与语义上可区分。
### 移动端与布局
- [ ] 375px 宽与横屏下可读、可操作;无横向滚动。
- [ ] 固定头/底栏给内容留出内边距,列表不被遮挡。
- [ ] 移动端输入框字号 ≥16px(避免 iOS 聚焦缩放)。
- [ ] 弹窗宽度 `calc(100% - 24px)`,footer 按钮全宽纵向堆叠(全局规则已在 `main.css`,新增弹窗无需重写)。
- [ ] 断点遵循既有口径:按钮/弹窗 768px,卡片与汇总布局 900px。
### 交付前
- [ ] `npm run type-check`、`npm run lint`(0 error)、`npm run test` 全绿。
- [ ] 关键路径有交互式集成测试(`src/__tests__/integration/`),只断言应用自身行为。
- [ ] 改动涉及新页面或大范围 UI:已走 `skills/ui-review/` 并记录评审结论。