# UI 设计方案

## 设计目标

界面服务于高风险模型测试操作：优先显示系统状态、当前进度、错误原因和下一步操作，同时保留类 Apple 产品的克制、层次和留白。不用装饰性动画掩盖真实等待，不将密钥或敏感请求数据作为视觉素材。

## 组件基础

按钮、表单、卡片、表格、标签、弹窗、步骤、进度和空状态统一使用项目现有的 `antd`。禁止页面自行引入第二套组件库或局部重写组件形状。两套主题只能替换颜色，不得改变组件尺寸、圆角和信息层级。

## 强制设计令牌

以下令牌定义在 `src/styles.css`，所有页面必须复用：

| 令牌 | 值 | 用途 |
| --- | --- | --- |
| `--radius-control` | `8px` | Button、Input、Select、Tag 等控件 |
| `--radius-surface` | `16px` | Card、Modal、Alert、Table 等容器 |
| `--space-card` | `24px` | 卡片和内容面板内边距 |
| `--space-section` | `24px` | 同层内容区块之间的间距 |

禁止在页面样式中新增一次性胶囊圆角（例如 `999px`）或为相同层级使用不同圆角。Switch、圆形进度和头像等由功能决定形状的组件除外。需要新尺寸时，先扩展全局令牌并补充一致性测试，再在页面使用。

颜色必须来自 `src/styles.css` 的主题变量或 `src/design/theme.ts` 的 Ant Design token。普通文字与背景对比度至少为 WCAG AA `4.5:1`；大号文字至少 `3:1`。状态不得只靠颜色表达，必须同时保留文字或图标。

## 页面布局规则

- Card 内容默认使用 `--space-card`，同级 Card 或内容区块使用 `--space-section`。
- 页面不得通过负 margin 或相邻零间距制造视觉粘连。
- 同一组标签尺寸、圆角和内边距必须一致；结论只通过语义色、字重和状态点强化。
- 多列内容在 960px 以下收为单列；700px 以下保证导航、表单和统计区可重排。
- 新页面优先复用现有 PageHeader、AsyncState、ReportSummary 和 Ant Design 组件。

## 两套可切换方案

| 方案 | 用途 | 视觉特征 |
| --- | --- | --- |
| `blue` | 默认安全控制台 | 使用 Ant Design 深色算法，深蓝布局、高对比信息、冷色状态强调，适合长时间监控 |
| `light` | 浅色专业工作台 | 浅灰布局、白色表面、Spark 紫色主操作，适合报告审阅 |

登录页和应用顶栏均提供“切换前端 UI 方案”按钮。选择保存在 `localStorage`，刷新和重新登录后仍保留。

## 页面层级

- 登录：品牌与价值主张在左，唯一主任务登录在右；窄屏只保留登录任务。
- 应用框架：侧边栏承载主导航与身份，顶栏显示活跃任务和主题切换，内容区只保留当前业务。
- 数据概览：先显示可行动指标，再显示最近运行，不使用无决策价值的装饰图表。
- 表单：按完成任务的顺序分组，就地校验，主提交操作保持唯一。
- 运行详情：阶段、进度、计数和当前样例位于首屏，结果和报告位于下方标签页。
- 结果卡片：顶部使用统一 Tag 明确标识“类型 / 模式 / 执行状态 / 仲裁结论”，将后端原始值转为中文语义。执行状态和仲裁结论使用两个独立筛选器，不混合 `completed/error` 与 `pass/fail`；执行 ID 搜索与两个筛选器组合生效，并支持忽略大小写的片段匹配。所有标签使用相同的 `8px` 圆角；结论只增加字重和状态点。通过为绿色、未通过或错误为红色、待复核为橙色，文字始终保留。
- 结果卡片在 Run 完成或部分错误时提供“重新执行”；使用 Ant Design 确认框说明结果将被替换。提交、运行中状态以按钮文字和信息提示表达，不只依赖颜色；Run 非终态时同 Run 的全部单条重试按钮禁用。重试目标使用信息提示说明跟踪状态并置顶显示，不修改用户已有筛选；提示提供“停止跟踪”按钮。

## 响应式与可访问性

960px 以下将多列卡片收为单列，700px 以下将侧边栏改为页首导航。主题切换和状态不仅依赖颜色，破坏性操作使用文字和确认弹窗。系统尊重 `prefers-reduced-motion`，所有主要交互均使用语义按钮、表单标签和可见错误文案。

## 提交门禁

所有 UI 修改提交前必须运行 `pnpm check`。其中：

- `tests/unit/design/consistency.test.ts` 防止圆角、间距和规范文档漂移。
- `tests/unit/design/contrast.test.ts` 校验双主题标签与主按钮对比度。
- `tests/integration/pages.test.tsx` 验证全部页面可挂载及关键路由行为。