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)。