# UI Review

- 审查目标：`src/prototypes/contract-template-management`
- 使用设计依据：`src/themes/linear/DESIGN.md`（实现侧通过 `vehicle-management/style.css` 声明为 Linear **light / inverse** 模式，主色覆写为 ONE-OS 翡翠绿 `--ln-primary: #32a06e`；与 Linear 原文档薰衣草色 `#5e6ad2` 存在有意的品牌偏移）
- 生成时间：2026-06-29

## 总体点评

合同模板管理在整体视觉上与车辆管理等 ONE-OS 中后台模块保持一致：浅灰画布（`--ln-canvas-parchment`）、白卡片、8px 圆角控件、Inter 字体与翡翠绿主色，表格/筛选区复用 `.vm-filter-card`、`.vm-table-card` 模式，信息密度适合法务日常维护任务。编辑页双栏（Word 编辑 + A4 预览）、章节 Tab、预览工具栏的 `aria-label` / `role` 标注较完整，禁用态操作按钮与 `focus-visible` 内描边也体现了一定的可访问性意识。

主要风险集中在**列表操作区触控尺寸**、**宽表横向滚动**以及**多操作并列带来的扫描成本**。Impeccable detector 另提示条件说明卡片的紫色左边框（`#7c3aed`）与全站绿色主色体系不一致，属于品牌表达层面的杂音。整体未达到 Linear 营销站那种极简留白，但作为 dense admin 工具界面，层次与组件复用是成立且可继续打磨的。

## P0-P3 优先级问题

### P1 - 列表行内操作按钮触控高度不足 44px

- 证据：`.ct-action-btn.ant-btn-link` 使用 `min-height: var(--vm-btn-height)`（36px，`vehicle-management/style.css`）；对比同模块预览翻页按钮已设 `min-width/min-height: 44px`（`contract-template.css` 约 1563 行）。列表操作列含「启用/停用」「版本日志」「编辑」「删除」等链接按钮。
- 影响：在触控屏或高精度鼠标场景下，误触率上升；不符合常见 WCAG 2.5.5 目标尺寸建议，与 DESIGN 中间距/控件可点性预期不符。
- 修复方向：将行内操作 `min-height` 提升至 44px，或改为「更多」下拉 + 主操作外露；保持 `cursor-pointer` 与禁用态对比度（当前禁用灰 `#94A3B8` 已处理）。

### P1 - 主表固定最小宽度导致中小屏强依赖横向滚动

- 证据：`.ct-data-table--nested` 设 `--ct-list-table-width: 1232px` 且 `min-width` 强制（`contract-template.css` 72–77 行）；`LIST_TABLE_SCROLL_X` 合计约 1332px（含操作列 300px，`ContractTemplate.jsx`）。右侧还有 `@axhub/annotation` 工具栏占用宽度。
- 影响：13 寸笔记本或分屏预览时，用户需频繁横向拖动才能看到「操作」列；筛选结果核对与批量处理效率下降。
- 修复方向：≥1280px 保持全列；`<1200px` 将「启用状态」与次要时间列折叠为 expandable 摘要，或操作列收进「更多」菜单；与 Linear inverse 表格「密度可伸缩」原则对齐。

### P2 - 操作列 4～5 个并列链接，视觉密度与扫读成本高

- 证据：已发布行同时展示「停用/启用」「版本日志」「编辑」「删除」（`getListColumns` 操作列宽 300px）；多行换行时（`Space wrap`）行高不齐。
- 影响：法务需逐行扫描多个同色链接，难以快速区分主操作与危险操作；与 DESIGN 中 button-primary / button-secondary 层级未充分映射到表格场景。
- 修复方向：主操作保留 1～2 个（如「编辑」）；其余收入「更多」`Dropdown`；危险操作「删除」保持 `danger` 但与次要操作拉开间距或使用图标+文字。

### P2 - 条件条款说明卡使用紫色左边框，偏离主色体系

- 证据：detector 命中 `border-left: 3px solid #7c3aed`（`ContractTemplate.jsx` 内联样式与 `contract-template.css` 约 1390 行）；全站主色为 `--ln-primary #32a06e`，Linear DESIGN 强调单一 chromatic accent。
- 影响：编辑页唯一紫色强调与表格/按钮绿色系统冲突，削弱品牌一致性，易被识别为「拼贴式」装饰。
- 修复方向：改为 `border-left-color: var(--ln-primary)` 或 `var(--ln-primary-soft)` 背景 + 无侧栏；与 `.ct-main-clause-tip` 信息层级一致即可。

### P3 - 字号阶梯偏平，表头与正文层次不够清晰

- 证据：Impeccable detector 报告 11–20px 多档字号、比例约 1.8:1（`flat-type-hierarchy`）；表头 `0.75rem`（12px）/`--ln-muted`，正文 `0.8125rem`（13px）/`--ln-body`，差距仅 1px。
- 影响：长列表扫读时列标题与单元格内容对比偏弱；不影响完成任务，但略损专业感。
- 修复方向：收敛为 3 档：表头 12px medium + `--ln-muted-80`、正文 14px、辅助 12px；确保表头对比度 ≥4.5:1。

## 核心元件

### 筛选区（`ct-list-filter`）

- **符合**：四字段栅格（合同名称可搜索 Select、状态、创建人、启用状态）+ 查询/重置，与 `vm-filter-card` 模式一致；字段带 `aria-label`。
- **调整**：筛选项增至 4 个后，窄屏下建议 `@media (max-width: 992px)` 改为两列栅格（当前 filter grid 响应式依赖 vehicle-management 全局样式，需确认 4 字段是否换行整齐）。

### 列表表格（`ct-list-table`）

- **符合**：表头浅灰底、hairline 分隔、hover 行背景、展开行嵌套章节子表；状态/启用 Tag 使用 Ant Design semantic 色。
- **调整**：操作列与总宽度过宽（见 P1/P2）；禁用编辑/删除的 link 按钮样式已灰化，但缺少 `title` 提示「请先停用」可帮助理解禁用原因。

### 编辑页顶栏与章节 Tab（`ct-editor-topbar` / `ct-section-tabs`）

- **符合**：返回 + 保存/保存并发布 CTA 层级清晰；`ct-btn-cta` 使用主色实心按钮；章节 Tab 带 `role="tablist"`、`aria-selected`，「更多」章节有 `aria-expanded`。
- **调整**：顶栏在窄屏未 sticky；长章节名在「更多」Tab 内 ellipsis 至 140px（`max-width: 992px`），可考虑 tooltip 展示全名。

### 编辑区 + 预览区（`ct-editor-panel` / `ct-preview-panel`）

- **符合**：左右分栏、A4 预览分页/连续模式、缩放与翻页控件具备 44px 触控与 `prefers-reduced-motion`；富文本工具栏 `focus-visible` 内描边符合 `--vm-focus-border-color`。
- **保留亮点**：预览工具栏 `role="toolbar"` 与分组 `aria-label` 是全场最佳 a11y 实践，可复用到列表操作区。
- **调整**：编辑区 Word 画布 `210mm` 固定宽，小屏下横向滚动不可避免，需在容器上提示「可横向滑动查看版式」。

### 弹窗（删除 / 停用 / 未保存离开 / 版本日志）

- **符合**：`ct-modal-wrap` 统一包裹；停用与离开编辑有明确二次确认文案。
- **调整**：版本日志 Modal 宽 720px、快照预览 900px，小屏应验证 `max-width: calc(100vw - 32px)` 是否生效。

## 响应式与可访问性

| 维度 | 结论 |
|---|---|
| 桌面（≥1280px） | 编辑双栏与预览体验完整；列表需横向滚动但可接受 |
| 平板/窄屏（≤992px） | 编辑列 `max-height: none` 已放开；表格仍强制 min-width，体验明显降级 |
| 键盘 | 章节 Tab、预览控件、部分按钮有 `focus-visible`；行内 link 操作依赖 Tab 顺序，密集时冗长 |
| 语义 | 筛选、章节、预览工具栏标注较好；表格操作按钮未统一 `aria-label`（仅靠文字） |
| 对比度 | 正文 `#52525b` on 白 generally OK；表头 `#71717a` on `#f6f7f7` 建议复核 AA |
| 动效 | 多处 `@media (prefers-reduced-motion: reduce)` 已覆盖工具栏与章节 Tab |

## 证据与评估说明

- **浏览器/截图**：未启动本地预览与浏览器截图；结论来自源码、`contract-template.css`、`index.tsx` ConfigProvider token 及 detector 输出。
- **Scanner**：已运行 `impeccable/scripts/detect.mjs --json`（exit 0，含 side-tab、overused-font Inter、flat-type-hierarchy、em-dash-overuse 等 warning）；已筛入 P2/P3 相关项，em-dash 主要来自合同正文 HTML 种子，非 UI chrome。
- **设计依据说明**：项目根 `DESIGN.md` 为 Vercel 营销规范，与本原型实现不一致；审查采用实现声明的 `src/themes/linear/DESIGN.md` + ONE-OS token 覆写作为对齐基准。
- **独立评估**：`degraded`（单轮完成设计阅读 + 源码 + detector；未拆分子代理，未做浏览器实机检查）。
