# Hotline Agent UI 设计系统

本文件是前端视觉唯一事实源。聊天、独立工具页、Harness 和静态技能控制台共用中性色与语义色。统一调整于 2026-11-08。

## 样式入口

- `static/console/tokens.css` 定义共享颜色、字体、圆角、阴影、遮罩与旧变量别名。Vue 通过 `frontend/src/main.js` 导入，静态技能控制台通过 `/console/tokens.css` 加载。
- `frontend/src/style.css` 承载主应用和独立工具页的结构与组件样式。
- `frontend/src/chat.css` 承载聊天布局与工作区授权弹窗，使用共享颜色。
- `frontend/src/harness.css` 承载 Harness 布局。选择器限定在 `.harness-shell`，避免同名顶栏、时间线和按钮影响聊天页。
- `frontend/src/theme.css` 统一通用控件、焦点、禁用态、弹窗高度与小屏补充规则。
- `static/console/console.css` 承载独立技能控制台的结构与组件样式。

## 色板

| 令牌 | 浅色 | 深色 | 用途 |
| --- | --- | --- | --- |
| `--canvas` | `#ffffff` | `#1a1b18` | 工作画布 |
| `--sidebar` | `#f7f7f5` | `#202220` | 侧栏 |
| `--surface` | `#ffffff` | `#212320` | 表单、浮层和卡片 |
| `--surface-subtle` | `#f5f6f2` | `#242622` | 预览、代码片段和辅助区 |
| `--surface-hover` | `#eeefec` | `#2e312b` | 悬停和选中 |
| `--line` | `#dedfda` | `#484c42` | 控件和面板描边 |
| `--line-soft` | `#e4e5e1` | `#34372f` | 分隔线 |
| `--text` | `#242522` | `#e8eae4` | 正文 |
| `--text-secondary` | `#60625c` | `#b2b6ad` | 次级文字 |
| `--muted` | `#696c64` | `#a0a599` | 辅助文字 |
| `--accent` | `#292a27` | `#e9ece5` | 主操作 |
| `--on-accent` | `#ffffff` | `#1a1b18` | 主操作前景 |
| `--success` | `#287a50` | `#80c79a` | 成功和在线 |
| `--warning` | `#8a5c16` | `#e0b06a` | 等待、审批和警告 |
| `--error` | `#b73e43` | `#ef9696` | 失败和危险操作 |

信息类链接与分类图标使用 `--info`、`--violet` 及对应浅背景。语义状态同时显示文字，避免只靠颜色传达信息。`--h-*`、`--bg`、`--card` 等兼容变量映射到共享令牌，不单独定义调色板。

显式 `data-theme="light"` 或 `data-theme="dark"` 优先。未指定主题时通过 `prefers-color-scheme` 跟随系统，系统主题变化由 CSS 响应。代码高亮区保留深色代码背景。

## 排版与控件

- 系统字体栈优先使用 Segoe UI、苹方、微软雅黑和 Noto Sans SC。正文 13–14px，行高约 1.6。
- 聊天欢迎标题 28px，小屏 24px。独立工具页标题 24px，设置区标题 18px。Harness 保持紧凑信息密度，辅助文字至少 11px。
- 编号、版本、耗时与测量数据使用等宽字体和等宽数字。普通表单使用系统正文字体。
- 主要和次要操作采用 8px 圆角，常规按钮至少 38px 高。工具图标通常 32–36px，聊天发送按钮保留圆形。
- 需求澄清卡片用中性描边承载：标题行说明需要确认，三个方向各占一条（标题 + 一句话说明），下方留一个自由输入框与继续按钮；按钮 8px 圆角、常规高度不小于 38px，作答后收起输入区只留一行说明。
- 表单、按钮、链接、下拉框和折叠摘要均有可见键盘焦点。禁用控件保持禁用光标和降低透明度。
- 正文、表单和预览区使用主题令牌，避免在组件中写死浅色底与深色字。

## 布局与响应式

- 聊天桌面工具栏 52px、会话栏 248px、标题栏 54px。消息和输入区最大宽度 760px，页面限定为视口高度，侧栏和消息流独立滚动。
- 桌面各页面共用 52px 主导航栏、36px 导航按钮和 19px 图标，切换页面保持位置与尺寸一致。文档滚动条预留固定空间，避免内容横向跳动。
- 聊天输入区的模式栏、文字区和底部工具栏独立排列，文字区与工具栏间距 8px。聚焦时只加深圆角外框，内部文本框不再绘制矩形焦点框。多行输入在限定高度内滚动，切换页面后恢复草稿高度。
- 空白会话的欢迎标题与输入框居中。有消息时恢复顶部消息流和底部输入框。
- 主导航在 ≤960px 显示为底部图标栏，保留所有工具和设置入口并适配底部安全区。聊天在此尺寸使用会话抽屉，≤560px 推荐任务纵向排列，低高度窗口保持输入框可达。
- 独立工具页使用侧栏与工作面两列，≤760px 收敛为单列。插件操作在 ≤700px 分行，长名称和配置说明可换行。
- Harness 桌面导航约 232px，宽屏工作台按内容分列，中屏两列，≤780px 使用导航抽屉与单列内容。完整运行列表在小屏保持可访问。
- 宽表格在自身容器横向滚动。长路径、标识符和详情内容换行，不撑宽页面。
- 普通弹窗采用 16px 圆角，最大高度限制在视口内并可滚动。工作区上传、授权和命名窗口沿用聊天控件与焦点管理，上传期间不允许关闭。
- 添加工作区时默认折叠文件预览，只展示文件夹名称、文件数量和总大小。预览使用可点击和键盘操作的折叠标题，展开后显示最多 6 项文件与剩余数量，上传与取消按钮始终可达。
- 会话列表中的删除按钮直接执行删除。请求期间禁用删除按钮，成功后移除对应会话，失败时保留会话并显示错误提示。

## 层级与动效

- 通过背景色阶、描边和留白区分层级。浮层使用单层柔和阴影与统一遮罩，不使用模糊遮罩。
- 保留 Hotline 耳机标识和现有 Lucide 图标系列。移除标题上重复的装饰性英文标签。
- 标题下不重复介绍页面功能，页脚不重复模块名称与职责。仅保留状态、错误、必要的格式约束和操作提示，空态使用简短说明。
- 悬停只调整颜色与描边，通常 130–140ms。用户选择减少动态效果时关闭循环动画与过渡。
- 演示、未接入、空态、加载与失败状态必须明确标注，保留现有功能含义。
- 流式回答的处理进度和参考来源默认折叠，输出期间保持收起，可手动展开。展开处理进度后显示当前阶段小字、文档名和工具名或技能名，过程列表使用 12px 次级文字与轻量状态图标，不添加卡片描边。仅展示实际收到的阶段，结束后折叠为步数和耗时，失败时展开记录。

## 验证

前端修改运行 `npm --prefix frontend run build`。项目验证同时运行 `python -m compileall python_backend` 与 `python skill-center/test_center.py`，本机使用 `.venv/Scripts/python.exe`。

视觉检查覆盖桌面、中屏、窄屏与低高度窗口，以及浅色、深色、焦点、禁用、空态、失败和长内容。实际业务数据与路由验证遵循根目录 `AGENTS.md`。
