# OpenClaw 客户端灰白蓝科技感 UI 改造方案

## 1. 目标

在不改业务逻辑的前提下，重构桌面客户端的视觉系统和交互层级。

最终方向是 **灰白主工作台 + 蓝色科技感 + 克制生产力工具风**：

- 保留现有左侧导航栏、右侧工作区结构。
- 保留当前偏灰白的整体基调。
- 蓝色只作为科技感强调色，用在激活态、状态、聚焦、关键操作。
- 降低当前浅蓝玻璃拟态和紫色渐变的存在感。
- 让客户端更像专业 AI 桌面工作台，而不是普通网页后台或聊天 demo。

## 2. 设计参考

本方案结合三类参考，不直接照搬某一种：

- Cursor：右侧 AI 工作区、底部输入、对话执行状态的专注感。
- Linear：克制信息密度、清晰层级、低噪音边框和阴影。
- Raycast：快速操作感、蓝色光感、明确状态反馈。

当前客户端已有的灰白浅色基调继续保留，但需要收敛视觉语言。

## 3. 现有问题

- `apps/ui/src/styles.css` 中核心布局类存在多轮定义和覆盖，维护风险高。
- 当前视觉同时存在紫色、浅蓝、灰白、玻璃、渐变，主线不够统一。
- 左侧栏承载主导航、数字员工、专家树、会话列表，信息密度偏高。
- 右侧工作区的聊天、专家、插件、设置页不像同一套产品系统。
- hover 位移、强阴影、大圆角容易让界面偏轻浮，不够工具化。
- focus、错误提示、键盘导航、滚动区边界需要进一步统一。
- 部分中文注释或文案已有乱码迹象，后续修改必须避免编码扩大污染。

## 4. 修改范围

### 4.1 必改文件

- `apps/ui/src/styles.css`
  - 统一设计 token：颜色、边框、阴影、圆角、间距。
  - 收敛重复定义的核心布局类。
  - 重写 `.conversation-shell ...` 下聊天工作区的视觉样式。
  - 统一插件、专家、设置页的卡片、标题区、状态 chip、滚动区。
  - 补齐 hover、focus-visible、disabled、scrollbar 等交互状态。

- `apps/ui/src/App.tsx`
  - 仅做必要的结构类名整理和无业务语义增强。
  - 保留现有事件处理、状态流、IPC 调用、专家选择、会话逻辑。
  - 不移除现有 DOM 节点、按钮、自动化 selector。
  - 可补充 `aria-label`、`role="alert"`、`aria-live` 等可访问性属性。
  - 如实现消息 hover 时间，只在消息渲染结构中增加时间节点和格式化 helper，不改 `ChatMessage` 契约。

### 4.2 不修改范围

- 不改 Electron main process。
- 不改 preload bridge。
- 不改 `packages/shared-types` IPC 契约。
- 不改 workspace、runtime、gateway、项目执行逻辑。
- 不改专家、插件、会话、附件上传业务流程。
- 不改构建、打包、安装脚本。

## 5. 布局方案

### 5.1 整体结构

继续使用两列桌面结构：

- 左侧：固定导航栏，建议宽度 `260px-280px`。
- 右侧：主工作区，占满剩余宽度。

不得把右侧工作区改成侧栏式单列页面，也不得引入第二套主壳布局。

### 5.2 左侧导航栏

左侧栏分为三段：

- 顶部：品牌区、主导航、新建会话。
- 中部：数字员工和专家分组。
- 底部：会话列表和必要状态入口。

交互要求：

- 当前主导航使用浅蓝底、蓝色左侧激活线或细边框。
- 专家 active 状态使用蓝色边框或蓝色浅底，不使用重阴影。
- 专家树和会话列表分别拥有稳定滚动区。
- 鼠标 hover 只改变背景、边框、文字色，不做明显位移。

### 5.3 右侧工作区

右侧统一为一个灰白工作台：

- 外层背景：浅灰白。
- 主工作面板：白色或近白色。
- 顶部：页面标题、当前专家/模式、运行状态 chip。
- 中部：消息列表、插件卡片、设置表单等内容。
- 底部：Composer 或页面操作区。

聊天页要求：

- 消息列表独立滚动。
- Composer 固定在右侧工作区底部。
- 输入框 resize 不破坏工作区高度。
- 状态提示不遮挡消息内容。

插件、专家、设置页要求：

- 共用同一套灰白卡片系统。
- 标题、说明、状态、操作按钮的层级一致。
- 页面滚动边界清晰，不出现窗口级混乱滚动。

## 6. 视觉方案

### 6.1 色彩

建议色彩方向：

- 页面背景：`#F5F7FA`、`#F8FAFC`
- 面板背景：`#FFFFFF`、`#FDFEFF`
- 主文本：`#0F172A`
- 次文本：`#475569`
- 弱文本：`#64748B`
- 主蓝：`#2563EB`
- 亮蓝：`#38BDF8`
- 浅蓝底：`#EFF6FF`
- 边框：`rgba(148, 163, 184, 0.22)`

原则：

- 灰白为主，蓝色为辅。
- 不使用大面积紫色渐变。
- 不使用大面积高透明玻璃。
- CTA 橙色如保留，只能用于极少数关键动作，不进入常规导航。

### 6.2 圆角和阴影

- 小控件：`10px-12px`
- 卡片：`14px-18px`
- 主工作面板：`20px-24px`
- 阴影以轻量为主，优先用细边框表达层级。
- 避免当前过强的彩色阴影和大面积发光。

### 6.3 消息样式

- 用户消息：浅蓝气泡，右对齐。
- AI 消息：白色内容卡，左对齐。
- 代码、trace、执行状态：使用低饱和蓝灰卡片。
- 系统提示：浅蓝状态条，明确但不抢正文注意力。
- 用户消息气泡必须使用浅蓝色，不使用白色或深蓝实心色，确保和 AI 回复卡片区分明显。
- 鼠标移到用户消息气泡或助手回复文本区域时，在该消息左下角显示发送/生成时间。
- 时间格式固定为 `yyyy-mm-dd HH:mm:ss`，例如 `2026-04-29 15:30:08`。
- 时间文字使用小字号、低对比度灰蓝色，只在 hover/focus-within 时显示，不常驻占用阅读注意力。
- 时间显示不能改变消息主体布局高度，优先使用绝对定位或预留轻量位置处理。

### 6.4 Composer

- 使用白色输入面板。
- focus 时显示蓝色描边和轻微蓝色光晕。
- 附件、技能、发送按钮统一使用蓝色体系。
- 禁用状态必须可读，不允许只降低到很低透明度。

## 7. 交互方案

- 所有可点击元素必须有 `cursor: pointer`。
- hover 不造成布局位移，避免明显 `translateY`。
- focus-visible 使用统一蓝色 ring。
- disabled 状态降低强调，但保留文字可读性。
- 错误提示使用 `role="alert"` 或 `aria-live="polite"`。
- Tab 顺序应与视觉顺序一致。
- 长列表使用内部滚动，不让整个应用窗口滚动。
- 可折叠专家分组必须保留 `aria-expanded` 和 `aria-controls`。

## 8. 实施步骤

1. 先建立 `styles.css` 覆盖清单，标出所有核心布局类的早期定义、响应式定义、末尾主题覆盖。
2. 明确删除/保留策略：保留基础布局定义和必要响应式规则，删除重复主题覆盖，避免继续靠文件末尾叠加修补。
3. 建立统一 token：颜色、圆角、边框、阴影、间距，并把旧紫色/玻璃/强阴影 token 降级或替换为灰白蓝体系。
4. 收敛主壳样式，只保留一套稳定的 `shell/sidebar/main-shell/content-area` 定义。
5. 重写 `.conversation-shell ...` 范围内的聊天工作区样式，确保聊天页样式不泄漏到插件和设置页。
6. 统一左侧栏主导航、专家树、会话列表的视觉和滚动区。
7. 统一聊天、专家、插件、设置页的卡片和状态样式。
8. 在 `App.tsx` 中只补充必要语义属性、结构类名、消息时间显示节点和格式化 helper，不改业务逻辑。
9. 清理旧样式覆盖，避免新旧主题并存。
10. 跑类型检查和构建。
11. 做聊天、专家、插件、设置四个页面的人工回归和截图验收。

## 9. 风险点

- `styles.css` 现有重复定义较多，删除或调整顺序可能引发布局回归。
- 当前文件末尾已有 `.shell.openclaw-theme` 和 `.conversation-shell` 主题覆盖，如果不先收敛覆盖层，会继续形成新旧主题叠加。
- `App.tsx` 文件很大，哪怕小结构调整也可能影响隐藏的自动化依赖。
- 消息时间显示依赖 `ChatMessage.createdAt`，字段已存在，但仍需要修改消息 DOM；应避免新增状态或改 IPC 契约。
- 左侧栏内容较多，小屏高度下仍可能拥挤，需要重点验证滚动。
- Composer 高度依赖 `conversationWorkspaceRef` 和当前 resize 逻辑，CSS 改动可能影响高度计算。
- 插件、专家、设置页共用样式后，局部页面可能需要少量例外样式。
- 中文文案和注释已有乱码，编辑时必须避免扩大编码问题。
- 如果旧样式清理不彻底，会出现新旧主题互相覆盖。

## 10. 测试计划

### 10.1 自动验证

```powershell
corepack pnpm typecheck
corepack pnpm build
```

如条件允许，补充一次截图验证：

- 启动 `corepack pnpm dev`。
- 分别截取聊天、专家、插件、设置页。
- 覆盖 `375px`、`768px`、`1024px`、`1440px` 四个宽度。
- 检查右侧工作区不是空白、不是侧栏化、没有明显遮挡或滚动断层。

### 10.2 人工回归

聊天首页：

- 消息列表正常滚动。
- Composer 固定底部。
- 输入框 resize 正常。
- 发送、附件、技能按钮状态正常。
- 系统提示和错误提示可见。

专家页：

- 专家分组展开/收起正常。
- 专家 active 状态清晰。
- 专家切换不破坏当前会话逻辑。
- 专家执行状态可读。

插件页：

- 插件卡片布局正常。
- 状态 chip 可读。
- 页面滚动区不溢出。

设置页：

- 表单、按钮、密钥输入、目录选择样式正常。
- 保存、恢复、错误、成功提示可见。
- 长内容不挤压主工作区。

响应式：

- `375px`
- `768px`
- `1024px`
- `1440px`

可访问性：

- Tab 顺序合理。
- focus-visible 明显。
- 错误提示不是只靠颜色。
- 普通文本对比度不低于 4.5:1。

## 11. 验收标准

- 视觉上明确是灰白主基调，蓝色科技感只做强调。
- 左侧导航和右侧工作区仍保持稳定两列结构。
- 聊天、专家、插件、设置页像同一套产品系统。
- 没有业务行为变化。
- 没有新增 TypeScript 或构建错误。
- 没有明显滚动、遮挡、输入框高度回归。
- 截图验收中聊天、专家、插件、设置页在目标宽度下都保持正确高度和滚动边界。
- 没有新增中文乱码或编码污染。
