AstrBot-Desktop/docs/ui-redesign-plan.md

3.9 KiB

AstrBot Desktop UI 重构方案

Design read

这是一个 Windows 桌面工具型应用,面向需要同时管理陪伴实例和运维实例的用户;视觉应偏安静、可信、信息密度可控的工作台,而不是营销网站或 SaaS 落地页。

设计原则

  • 保留业务逻辑和交互路径,先重构视觉层和布局层。
  • 采用单一冷色中性 token 系统,蓝色只承担交互和连接状态,不使用紫蓝渐变。
  • 主任务优先:聊天输入和当前槽位最突出,诊断/连接元信息作为次级层。
  • 让错误、离线、空会话、上传中、重连中都能在同一位置理解和恢复。
  • 桌面优先,窄窗口可收缩;不把移动端营销布局套进桌面工具。
  • 普通 UI 不增加动画;桌宠既有状态动画保留,并加入 reduced-motion 兜底。

不变合同

范畴 保留内容
页面 chat、connections、desktop、pet、diagnostics
连接 companion / operations 独立 REST、SSE、Token、会话、消息、未读状态
数据 profile_id、server_instance_id、conversation_id 及现有 schema
IPC 现有 invoke() commands 和 listen() event names
安全 Rust 持有凭据和本机权限;React 不获得任意文件/命令执行能力
测试 保留现有 Vitest、Playwright、Rust workspace 检查入口

分阶段队列

P0 — 先稳定工作台骨架

  • src/styles.css:抽取颜色、边框、间距、状态和 z-index tokens;补全统一 :focus-visible、disabled、error、loading 语义。
  • src/App.tsx:保持页面 key 和事件逻辑不变,清理页面头部层级与导航可读性。
  • src/features/chat/ChatPanel.tsx:把运行时状态、槽位 tabs、会话列表、消息流、composer 分成明确的语义区域。
  • 验证:Vitest、typecheck、lint、Vite build;聊天页新增关键交互回归断言。

P1 — 完善核心页面

  • src/features/profiles/ProfileManager.tsx、CredentialEnrollmentCard.tsx:统一表单布局、字段标签、错误/成功反馈和敏感信息说明。
  • src/features/chat/StatusBubble.tsx:统一连接状态颜色、读屏文本和小窗口窄尺寸。
  • src/App.tsx 的 DesktopBehaviorPage、DiagnosticsPage:减少重复卡片,建立明确的设置/诊断分组。
  • 验证:表单与槽位隔离测试、键盘导航检查、窄窗口 Playwright。

P2 — 性能与一致性

  • 页面级拆分 App.tsx 中非聊天视图,降低首屏 JS 体积。
  • 清理重复主题覆盖,保留 dark/light 两套可验证 token。
  • 统一消息、状态、按钮、表单的可访问名称与 tooltip;补齐 reduced motion。
  • 验证:生产构建体积对比、Playwright 截图/溢出检查、完整 Rust + frontend gate。

首批实施范围

只改聊天页视觉层,具体文件:

  • src/features/chat/ChatPanel.tsx:仅在需要时补充语义属性或可见标签,不改变数据处理。
  • src/styles.css:新增/调整 chat 相关 token 与布局规则,保留现有 class 兼容。
  • src/App.tsx:如需调整聊天页外壳,只改 ChatPage 的呈现结构,不改导航和 IPC。
  • src/App.test.tsx:补充聊天页视觉相关的可访问名称/状态回归,不重写现有业务测试。

完成标准

  • 聊天发送、切槽位、切会话、附件、语音、重连、停止生成、打开快捷窗口行为不变。
  • 主聊天区域在 1280px、1024px、680px 窗口下无横向溢出。
  • 键盘能到达导航、槽位 tabs、会话、消息操作、输入和发送按钮,焦点可见。
  • 深浅色主题对比度满足 WCAG AA;错误和连接状态不只依赖颜色。
  • 前端 typecheck、lint、unit test、build 通过。