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
+6 -2
View File
@@ -6,10 +6,14 @@
- 通用规则(跨仓库):meta 仓库 `.agents/roles/`;本仓库的 Git 提交规范已统一到其中的 `commit-convention.md`。
- 本仓库专属规则:`roles/`
- `roles/code-standards.md` — 前端代码标准(交互防抖与加载、按钮规范、颜色与主题、卡片列表交互、移动端适配、代码整洁、请求层与类型规范、组合式函数复用)
- `roles/code-standards.md` — 前端代码标准(交互防抖与加载、按钮规范、颜色与主题、界面质量与可访问性、卡片列表交互、移动端适配、代码整洁、请求层与类型规范、组合式函数复用)
- `roles/design-principles.md` — 前端设计原则(页面信息架构、视觉层级、模型默认做法禁用清单、文案即设计、独立评审触发条件)
- `roles/design-system.md` — 前端设计系统(调性、色板、间距节奏、圆角/描边/阴影、文字角色、组件语法)
- `roles/ui-review-checklist.md` — 前端界面交付自检清单(状态完整性、交互反馈、可访问性、动效、内容承载、表单、移动端)
- `roles/testing.md` — 前端测试规范(分层策略、交互式集成测试、逻辑单测、覆盖率、提交前检查)
- `roles/style-conventions.md` — 样式与交互约定
- 本仓库专属技能:本仓库暂无专属技能目录
- 本仓库专属技能:`skills/`
- `skills/ui-review/` — 新页面或大范围 UI 改动的独立视觉评审(取证 → 派无上下文的评审者 → 修正 → 复核)
## 技术栈
+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/` 并记录评审结论。
+122
View File
@@ -0,0 +1,122 @@
---
name: ui-review
description: 对 lpt-fe 的新页面或大范围 UI 改动做独立视觉评审:起本地服务、按关键状态截图取证、派无上下文的评审者按固定评分锚点打分并输出「问题 / 提升 / 保留」,主 agent 按清单修完再核对一轮。当用户新增页面、重构页面结构、改版视觉语言、或说“页面难看/重新设计一下/评审下这个界面”时使用。触发词:评审界面、UI 评审、页面难看、重新设计、视觉评审、设计走查、新页面、改版。
metadata:
short-description: 前端新页面与大改动的独立视觉评审
---
# 前端界面独立评审
针对 `lpt-fe` 的**新页面**或**大范围 UI 改动**(整页重构、视觉语言变更、新增信息区块)走一遍:取证 → 独立评审 → 修正 → 复核。
小改动、局部低风险调整不走本技能,按 `roles/ui-review-checklist.md` 自检即可。
本技能只在 `lpt-fe` 仓库内使用,规则依据为 `roles/design-principles.md` 与 `roles/design-system.md`——评审时把后者作为「现状规范」交给评审者,不让它凭空想象理想风格。
## 工作区约定
| 用途 | 路径 |
|------|------|
| 本技能 | `lpt-fe/skills/ui-review/` |
| 设计原则(禁用清单) | `lpt-fe/roles/design-principles.md` |
| 设计系统(现状规范) | `lpt-fe/roles/design-system.md` |
| 交付自检清单 | `lpt-fe/roles/ui-review-checklist.md` |
| 证据存放 | 本次任务的工作目录(截图不进仓库) |
## Step 1 确认范围
| 项 | 说明 |
|---|---|
| 改动类型 | 全新页面 / 整页重构 / 视觉语言变更 / 局部新增区块 |
| 涉及页面与路由 | 具体路径(如 `/review`),以及它的当前状态 |
| 不可动的东西 | 品牌色、字体、Element Plus 组件库、既有导航结构 |
| 用户最常做的事 | 决定「一屏一个主角」是谁 |
| 验收重点 | 这次最想让用户看到什么变化 |
缺一项就问,不要猜。存量页面润色时,**不探索新风格**,只对齐 `roles/design-system.md` 的现状规范。
## Step 2 取证
1. 起服务:`npm run dev`(端口 5158,代理到 lpt-be:5157)。
2. 覆盖关键状态截图,不要只截默认态:
- 默认/有数据的常态
- 空状态
- 加载中
- 错误态
- 窄屏(375px)
3. 用 `agent_browser` 截图并落盘到本次任务目录;确认 `artifactVerification` 全部 verified 再用于评审。
4. 后端不可用或需要登录才能到达的页面:把不可达的页面显式标为「未验证」,不要用静态推断代替画面。
5. 缩一张 480px 宽的缩略图,自己先做一次三秒测试(见 Step 4 第 0 条),明显不合格的先改再送评审。
## Step 3 派独立评审者
- 用 `subagent` 派一个**没有历史上下文**的子代理;一次只派一个,不要多个评审者。
- 交给它的材料只有:**截图 + 任务与约束 + `roles/design-system.md` 的现状规范 + 下面的提示词模板**。
- **不给**代码、不给制作过程、不给你的实现说明——评审只看画面,避免被实现细节带偏。
- 没有可派子代理的环境时,按同一模板自查,并在交付说明里写明「未独立评审」。
### 评审提示词模板
```text
你是这次界面改动的独立视觉评审者,没有参与制作。只根据我给的截图、任务描述和现状设计规范评审。
任务:[这次改动要解决什么、给谁用、主任务是什么]
约束:[不可动的品牌色/字体/组件库/导航结构;目标视口]
现状规范:[roles/design-system.md 的全文]
截图:[文件路径与每个文件对应的状态、视口]
评审要求(按顺序做,看不清就写明"未验证",不要猜):
0. 三秒测试:把首屏缩到 480px 宽看三秒,写出两句:它像哪一类产品;第一眼看到的是什么,这个东西换到别的产品上是否同样成立。
1. 品类与标杆:指出这属于什么品类,该品类的优秀产品首屏怎么做;现有画面哪里违背了品类共识,是有意为之还是套了默认模板。
2. 默认做法检查:逐条对照 design-principles.md 的禁用清单,指出画面上仍在的项。
3. 状态检查:空 / 稀疏 / 密集 / 加载 / 错误五态是否都有合理呈现;错误态能否恢复。
4. 层级与减法:哪块在抢注意力、哪块该更安静;点名可直接删掉的文字、面板与装饰。
5. 可访问性与可读性:对比度、焦点可见性、触达尺寸、长内容与数字排版;在 100% 与 200% 缩放下看关键区域。
输出格式(先问题,后提升):
- 问题:只写会阻断任务、读不清、或明显是默认模板的,按影响从大到小,最多 5 条。每条写「位置 + 观察到的现象 + 影响 + 修完应该达到什么结果」。
- 提升:精致度 / 设计感 / 动效三项都要表态,最多 5 条,某项确实没有差距就写"没有"和依据。
- 保留:一两处修改时不能磨掉的做法。
- 打分:[新页面或改版才打分,存量润色不打分,只列客观修正建议]
打分锚点(拿不准取低一档):
10 挑不出可观察缺陷,至少一处是品类里没见过的好做法
9 主流程、异常状态、细节都成立,提升只剩小处
8 方向鲜明、主流程走得通、没有阻断或数据丢失;若干中等问题
7 方向成立,但有一处会让用户丢数据/走错/卡住,或首屏仍是明显默认模板
5-6 能看出方向,但骨架是默认模板,或主流程多处卡住
1-4 主任务走不通,或画面有重叠、裁切、看不清这类基本错误
不要修改任何文件,不要替我定构图,只给诊断与目标。
```
## Step 4 按结果修正
- 问题按评审给出的顺序修,从影响最大的开始。
- 首条是「重做:……」时(分数落在 6 分及以下、骨架仍是默认模板),**回到 `roles/design-principles.md` 的「页面信息架构」重排结构**,不要在被否定的骨架上做局部修补。
- 只做减法与结构修正,不靠加功能、加数据量来换真实感;要求新增任何元素时,同一条里写明为它腾位置删掉什么。
- 修完按 `roles/ui-review-checklist.md` 自检一遍。
## Step 5 复核
- 重新截图(与 Step 2 相同的状态与视口),再派一次评审者,**逐条核对上一轮清单**:修掉了几条、有没有引入新问题。
- 最多两轮。第二轮仍有 6 分及以下的问题,停下来找用户确认方向,不要继续自己改。
- 风格开始漂移、意见反复时,保留最合适的版本并说明取舍。
## Step 6 交付说明
回复里必须包含:
1. 什么改动、为什么这么改(对应哪条设计原则);
2. 做了哪些动效;
3. 评审轮次与结果:打分制写每轮分数,不打分制写问题如何处理;未独立评审要写明;
4. 删掉了哪些文字与装饰;
5. 未完成与非界面问题(环境、接口)各一行,不排查。
## 禁止事项
- 跳过取证(不截图)就派评审,或拿静态推断当画面证据。
- 把代码给评审者,或让评审者看制作过程。
- 把截图、评审记录提交进仓库。
- 存量页面润色时另起一套风格、更换品牌色或字体。
- 在被判定「重做」的骨架上继续做局部修饰。
+13
View File
@@ -9,6 +9,8 @@
--surface-strong: #ffffff;
--text-primary: #1b2a23;
--text-secondary: #4b6156;
/* 占位文字:比次要文字再轻一档,但仍要过 AA(白底 4.6:1) */
--text-placeholder: #69796f;
--border-soft: #d6e6dc;
--shadow-soft: 0 14px 30px rgba(19, 61, 45, 0.09);
--shadow-strong: 0 20px 45px rgba(19, 61, 45, 0.16);
@@ -17,11 +19,16 @@
--accent-warning: #e6a23c;
--accent-warning-soft: #fff8e1;
--accent-warning-strong: #b8860b;
/* 浅黄底上的正文色:#b8860b 仅 3.06:1,达不到 WCAG AA;
提醒块内的文字统一用这个(5.17:1),strong 只用于描边等非文字场合 */
--accent-warning-text: #856404;
/* 成功/命中语义的浅底与深字(统计卡片、标签共用) */
--accent-success-soft: #e8f5e9;
--accent-success-softer: #f1f8e9;
--accent-success-strong: #2e7d32;
--accent-success-text: #856404;
/* 实底强调色上的文字:不要在各组件里写 #fff 字面量 */
--text-on-accent: #ffffff;
}
*,
@@ -78,6 +85,12 @@ body {
--el-color-success-light-8: #bcd9cc;
--el-color-success-light-9: #eef9f3;
--el-color-success-dark-2: var(--green-800);
/* EP 默认的次要文字 #909399(白底 3.08:1)与占位文字 #a8abb2(白底 2.30:1)
都达不到 WCAG AA。空态说明、表单 placeholder 这些会承载必要信息的文字
统一改成我们登记的辅助色与占位色。 */
--el-text-color-secondary: var(--text-secondary);
--el-text-color-placeholder: var(--text-placeholder);
}
#app {