# 客户端 UI/UX 整改执行计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 基于当前客户端代码事实，把 renderer 收敛成更稳定、更专业、更易维护的 AI 桌面工作台。

**Architecture:** 不重写业务链路，不改 Electron IPC 合约。先固化事实基线和样式边界，再逐步压薄 `App.tsx`、收敛 CSS 覆盖、补齐工作台交互和可访问性。

**Tech Stack:** Electron renderer, Vite, React 19, TypeScript, plain CSS modules via `apps/ui/src/styles.css`, existing smoke hooks.

## Progress Sync - 2026-05-25

- Current committed progress: `4c81b90 style(ui): calm renderer shell visuals`.
- Validation passed after the CSS work: `corepack pnpm --filter @qjclaw/ui typecheck`; `corepack pnpm build`.
- Phase 1 is complete except baseline screenshots.
- Phase 2 has completed token cleanup, visual-noise reduction, and validation; duplicate layout ownership still needs a dedicated review pass.
- Phase 3, Phase 4, and Phase 5 have not started.

---

## 1. 当前事实基线

### 代码结构

- `apps/ui/src/App.tsx` 当前约 1674 行，仍承担顶层状态编排、视图切换、会话控制、设置 props 组装、smoke hooks 和启动遮罩。
- `apps/ui/src/styles.css` 已是入口文件，只 import `apps/ui/src/styles/*.css`。
- 主样式分散在 `base.css`、`components.css`、`shell.css`、`chat.css`、`settings.css`、`plugins.css`、`knowledge.css`、`tasks.css`、`automation.css`、`theme-openclaw.css`。
- 聊天主工作区已拆到 `features/chat/ConversationWorkspaceView.tsx`，但 props 数量过多，说明页面边界仍不够稳定。
- 通用 UI 组件已存在：`Button`、`IconButton`、`Panel`、`ScrollArea`、`StatusChip`、`Tabs`。

### UI/UX 基线

- 产品类型：AI 生产力桌面客户端，核心体验应接近运营工作台，而不是营销页或普通聊天 demo。
- 当前优势：两栏骨架稳定、聊天/附件/流式状态完整、部分 focus 和 `aria-live` 已存在。
- 当前风险：CSS 多层覆盖、视觉蓝紫/玻璃/渐变偏多、移动断点不完整、导航密集但缺少 skip link、部分页面仍有 emoji 或手写 SVG 图标。
- 重点约束：继续保留 `conversation-shell`、`conversation-main-layout`、`conversation-content-area`、`conversation-panel`，不得破坏 smoke helpers 依赖的 DOM 和 selector。

## 2. 执行原则

- 不做一次性重写，每个阶段必须独立通过 typecheck/build。
- 优先修维护风险，再修视觉观感。
- 不改 `packages/shared-types` IPC 契约，除非单独立项。
- 不删除或隐藏现有 UI 控件，除非先确认 smoke helpers 和 renderer test 不依赖。
- 修改 `App.tsx` 时只用小 patch，避免中文编码损坏；修改后检查无 UTF-8 BOM。
- 工作台视觉以灰白为主、蓝色为状态和关键操作辅助，减少紫色渐变、彩色发光和过强阴影。

## 3. Phase 1 - 建立 UI 回归基线

**目标:** 先形成可复测基线，避免后续 UI 调整凭主观判断推进。

**Files:**

- Modify: `docs/2026-05-25-client-ui-ux-execution-plan.md`
- Read-only reference: `apps/ui/src/App.tsx`
- Read-only reference: `apps/ui/src/styles.css`
- Read-only reference: `apps/ui/src/styles/*.css`
- Read-only reference: `apps/ui/test/*.test.ts`

- [x] **Step 1: 记录当前核心文件规模**

  Run:

  ```sh
  wc -l apps/ui/src/App.tsx apps/ui/src/styles.css apps/ui/src/styles/*.css
  ```

  Expected:

  - 记录 `App.tsx` 行数。
  - 记录每个 CSS 文件行数。
  - 如果 `theme-openclaw.css`、`shell.css`、`components.css` 仍是最大样式文件，后续 CSS 收口优先从这三处开始。

  Progress note:

  - `App.tsx`: 1674 lines.
  - Largest CSS files remain `shell.css` 1782, `theme-openclaw.css` 1600, `components.css` 1521.

- [x] **Step 2: 记录核心布局类定义位置**

  Run:

  ```sh
  rg -n "^\\.(shell|sidebar|main-shell|content-area|conversation-panel|message-list|composer-shell)\\b|\\.conversation-shell \\." apps/ui/src/styles/*.css
  ```

  Expected:

  - 输出所有核心类定义位置。
  - 标出基础定义、聊天覆盖、主题覆盖三类来源。
  - 不在本阶段删除样式，只形成清单。

  Progress note:

  - Base/core definitions: `components.css` (`content-area`, `message-list`, `composer-shell`), `shell.css` (`shell`, `sidebar`, `main-shell`).
  - Conversation overrides: `chat.css` under `.conversation-shell ...`.
  - Theme skin overrides: `theme-openclaw.css` under `.shell.openclaw-theme ...` and `.conversation-shell ...`.

- [x] **Step 3: 跑基础验证**

  Run:

  ```sh
  corepack pnpm --filter @qjclaw/ui typecheck
  corepack pnpm build
  ```

  Expected:

  - 两个命令通过。
  - 如果失败，先修复当前失败，不进入 Phase 2。

  Progress note:

  - Passed on 2026-05-25: `corepack pnpm --filter @qjclaw/ui typecheck`.
  - Passed on 2026-05-25: `corepack pnpm build`.

- [x] **Step 4: 保存基线截图**

  Start app:

  ```sh
  corepack pnpm dev
  ```

  Capture these views manually or with Playwright:

  - Chat home
  - Expert chat
  - Task panel
  - Automation tasks
  - Knowledge
  - Settings

  Expected:

  - 每个页面有桌面宽度截图。
  - 至少补一张窄宽度截图，确认 `min-width: 960px` 的实际行为。

  Progress note:

  - Saved on 2026-05-25 under `docs/artifacts/2026-05-25-client-ui-ux-baseline/`.
  - Desktop screenshots: `chat-home.png`, `expert-chat.png`, `task-panel.png`, `automation-tasks.png`, `knowledge.png`, `settings.png`.
  - Narrow screenshot: `narrow-720-settings-min-width.png`, confirming the current desktop-first `min-width: 960px` contract creates horizontal overflow below that width.

## 4. Phase 2 - 收敛 CSS 骨架和视觉 token

**目标:** 让核心布局类只有清晰的基础层和主题层，减少后续 UI 回归。

**Files:**

- Modify: `apps/ui/src/styles/base.css`
- Modify: `apps/ui/src/styles/components.css`
- Modify: `apps/ui/src/styles/shell.css`
- Modify: `apps/ui/src/styles/chat.css`
- Modify: `apps/ui/src/styles/theme-openclaw.css`

- [x] **Step 1: 建立 token 边界**

  In `apps/ui/src/styles/theme-openclaw.css`, keep all product-level theme variables under:

  ```css
  .shell.openclaw-theme {
    --revamp-canvas: #f5f7fa;
    --revamp-surface: #ffffff;
    --revamp-surface-soft: #f8fafc;
    --revamp-text: #0f172a;
    --revamp-text-muted: #475569;
    --revamp-text-soft: #64748b;
    --revamp-blue: #2563eb;
    --revamp-blue-strong: #1d4ed8;
    --revamp-blue-soft: #eff6ff;
    --revamp-border: rgba(148, 163, 184, 0.24);
    --revamp-border-strong: rgba(148, 163, 184, 0.38);
    --revamp-shadow: 0 14px 32px rgba(15, 23, 42, 0.06);
    --revamp-shadow-soft: 0 8px 18px rgba(15, 23, 42, 0.04);
  }
  ```

  Expected:

  - Purple variables may remain only where still referenced by legacy expert-specific styles.
  - New or touched styles use the gray/blue token set above.

  Progress note:

  - Completed by `4c81b90`; product-level `--revamp-*` variables now live under `.shell.openclaw-theme`.
  - Touched visual styles were moved toward gray/blue tokens and reduced purple usage.

- [x] **Step 2: Reduce duplicate core layout definitions**

  Keep responsibilities:

  - `base.css`: reset, root tokens, font, body.
  - `components.css`: generic reusable components only.
  - `shell.css`: base shell layout and non-theme structural behavior.
  - `chat.css`: conversation-specific structure only under `.conversation-shell`.
  - `theme-openclaw.css`: final product skin and current gray/blue visual theme.

  Expected:

  - No new global `.message-list` or `.composer-shell` visual overrides outside the intended layer.
  - Conversation-only changes remain scoped under `.conversation-shell ...`.

  Progress note:

  - Partially addressed by `4c81b90`.
  - Still open: dedicated review of ownership overlap across `components.css`, `shell.css`, `chat.css`, and `theme-openclaw.css`.
  - Completed on 2026-05-25: removed shell/sidebar/main-shell responsive overrides from `components.css`, kept shell responsive ownership in `shell.css`, and removed structural `main-shell`/`content-area` overrides from `theme-openclaw.css`.
  - Documented the desktop-first `min-width: 960px` shell contract in `shell.css`.

- [x] **Step 3: Remove obvious visual noise**

  In touched rules:

  - Replace heavy color shadows with `var(--revamp-shadow-soft)` or border-only states.
  - Avoid new `translateY` hover movement.
  - Keep card radius at or below existing app norms unless the rule already requires larger panels.
  - Do not add decorative orbs, bokeh, or unrelated gradients.

  Expected:

  - Left sidebar and workspace feel calmer.
  - Active/hover/focus states remain visible.

  Progress note:

  - Completed by `4c81b90`; removed several `translateY` hover effects, softened shadows, reduced decorative gradients, and replaced purple scrollbar/drag states with blue/gray variants.

- [x] **Step 4: Validate after CSS edits**

  Run:

  ```sh
  corepack pnpm --filter @qjclaw/ui typecheck
  corepack pnpm build
  ```

  Expected:

  - Both pass.
  - `git diff -- apps/ui/src/styles.css apps/ui/src/styles/*.css` shows targeted CSS changes only.

  Progress note:

  - Passed on 2026-05-25: `corepack pnpm --filter @qjclaw/ui typecheck`.
  - Passed on 2026-05-25: `corepack pnpm build`.
  - CSS work was committed as `4c81b90 style(ui): calm renderer shell visuals`.
  - Re-ran after ownership cleanup on 2026-05-25: `corepack pnpm --filter @qjclaw/ui typecheck`; `corepack pnpm build`.

## 5. Phase 3 - 压薄 App.tsx 的 UI 编排

**目标:** 降低 `App.tsx` 的维护风险，但不碰 stream 主链路和 smoke action 协议。

**Files:**

- Modify: `apps/ui/src/App.tsx`
- Modify: `apps/ui/src/features/chat/ConversationWorkspaceView.tsx`
- Modify: `apps/ui/src/features/settings/SettingsPanels.tsx`
- Create or modify focused hooks only under existing `apps/ui/src/features/*`

- [ ] **Step 1: 拆出纯 props 组装**

  Move only pure prop-building logic from `App.tsx` into focused helpers or hooks when all inputs are already available.

  Candidate boundaries:

  - Conversation workspace props.
  - Settings panel props.
  - Sidebar derived labels and entries.

  Expected:

  - No behavior change.
  - No IPC calls move across ownership boundaries in this step.
  - `App.tsx` line count decreases, but line count is not the success metric; clearer ownership is.

- [ ] **Step 2: Keep high-risk flows in place**

  Do not move these during this phase:

  - stream request lifecycle
  - `__QJC_SMOKE__`
  - `__QJC_SMOKE_ACTIONS__`
  - composer submit/cancel
  - session creation/closing
  - startup overlay retry/export actions

  Expected:

  - Existing smoke tests do not need selector or action rewrites.

- [ ] **Step 3: Reduce oversized component props**

  For `ConversationWorkspaceView`, group related props into typed objects only when ownership is obvious:

  - `status`
  - `emptyState`
  - `messages`
  - `composer`
  - `actions`

  Expected:

  - Component call site becomes easier to read.
  - Existing child component props stay unchanged unless required.

- [ ] **Step 4: Validate App.tsx encoding and tests**

  Run:

  ```sh
  /usr/bin/python3 -c "from pathlib import Path; p=Path('apps/ui/src/App.tsx'); b=p.read_bytes(); print(b[:3]); assert b[:3] != b'\\xef\\xbb\\xbf'"
  git diff -- apps/ui/src/App.tsx
  corepack pnpm --filter @qjclaw/ui typecheck
  ```

  Expected:

  - First command prints bytes that are not UTF-8 BOM.
  - Diff contains no mojibake and no unrelated Chinese copy changes.
  - UI typecheck passes.

## 6. Phase 4 - 修正核心工作流 UI/UX

**目标:** 优先改善用户每天会反复使用的界面：聊天、任务、自动化、设置。

**Files:**

- Modify: `apps/ui/src/features/chat/ChatComposer.tsx`
- Modify: `apps/ui/src/features/chat/MessageList.tsx`
- Modify: `apps/ui/src/features/tasks/TaskPanelView.tsx`
- Modify: `apps/ui/src/features/automation/AutomationTasksView.tsx`
- Modify: `apps/ui/src/features/settings/SettingsPanels.tsx`
- Modify: matching CSS files under `apps/ui/src/styles/`

- [ ] **Step 1: Chat composer**

  Requirements:

  - Keep Enter send and Shift+Enter newline behavior.
  - Keep attachment upload button and drag-drop.
  - Keep resize handle.
  - Ensure disabled state remains readable.
  - Ensure focus state uses one consistent blue ring.

  Expected:

  - Composer does not resize the main shell unexpectedly.
  - Attachment chip text truncates cleanly.
  - Submit button remains icon-first with accessible label.

- [ ] **Step 2: Message list**

  Requirements:

  - Keep user messages right-aligned and assistant messages left-aligned.
  - Keep assistant markdown card readable at long line lengths.
  - Keep copy/delete action buttons keyboard reachable.
  - Keep streaming trace `aria-live` behavior.

  Expected:

  - Long Chinese, English, URLs, and code blocks do not break layout.
  - Message actions do not shift message height when appearing.

- [ ] **Step 3: Task panel icon cleanup**

  Replace visible emoji used as UI icons with existing icon components or local SVG components.

  Known target:

  - `apps/ui/src/features/tasks/TaskPanelView.tsx`: package icon in the content output heading.

  Expected:

  - No visible emoji icons remain in primary tool controls or headings.
  - Existing Chinese text remains unchanged except for necessary label updates.

- [ ] **Step 4: Automation tasks density**

  Requirements:

  - Keep list, detail, form, and run history usable without window-level scroll confusion.
  - Filter buttons and edit/create actions must have clear active and disabled states.
  - Error state must use `role="alert"` or visible announced equivalent.

  Expected:

  - The page reads as an operational tool, not a card-heavy marketing layout.
  - Long task prompts truncate or wrap predictably.

- [ ] **Step 5: Settings hierarchy**

  Requirements:

  - Keep config source toggle visible and keyboard reachable.
  - Secret reveal and copy controls must stay accessible.
  - Save/reset/edit buttons must communicate disabled state clearly.
  - Tabs must preserve `aria` semantics from existing `Tabs` component.

  Expected:

  - Users can scan required vs optional config groups quickly.
  - Editing one section does not visually imply other sections are editing.

- [ ] **Step 6: Validate key workflows**

  Run:

  ```sh
  corepack pnpm --filter @qjclaw/ui typecheck
  corepack pnpm build
  ```

  If touched flow has existing source tests, also run:

  ```sh
  node --test apps/ui/test/taskPanelViewSource.test.ts
  node --test apps/ui/test/settingsPanelsSource.test.ts
  node --test apps/ui/test/chatCancelSource.test.ts
  ```

  Expected:

  - Typecheck and build pass.
  - Relevant source tests pass.

## 7. Phase 5 - 可访问性和响应式补齐

**目标:** 解决 UI-ux-pro-max 指出的高优先级问题：键盘导航、skip link、错误提示、图片 alt、响应式边界。

**Files:**

- Modify: `apps/ui/src/App.tsx`
- Modify: `apps/ui/src/features/shell/AppSidebar.tsx`
- Modify: `apps/ui/src/features/shell/Sidebar.tsx`
- Modify: `apps/ui/src/styles/base.css`
- Modify: `apps/ui/src/styles/shell.css`
- Modify: `apps/ui/src/styles/theme-openclaw.css`

- [ ] **Step 1: Add skip link**

  Add a visually hidden but focus-visible skip link near the top of the shell:

  ```tsx
  <a className="skip-link" href="#main-content">跳到主内容</a>
  ```

  Add id to main content:

  ```tsx
  <main id="main-content" className={...}>
  ```

  Expected:

  - First Tab focuses skip link.
  - Pressing Enter moves focus target to main content.

- [ ] **Step 2: Add skip link styles**

  Add CSS:

  ```css
  .skip-link {
    position: fixed;
    top: 10px;
    left: 10px;
    z-index: 10000;
    padding: 8px 12px;
    border-radius: 8px;
    background: #ffffff;
    color: #1d4ed8;
    border: 1px solid rgba(37, 99, 235, 0.38);
    transform: translateY(-140%);
  }

  .skip-link:focus-visible {
    transform: translateY(0);
    outline: 2px solid rgba(37, 99, 235, 0.56);
    outline-offset: 2px;
  }
  ```

  Expected:

  - Hidden by default.
  - Visible only when focused.

- [ ] **Step 3: Confirm nav tab order**

  Manual validation:

  - Tab order starts at skip link.
  - Then window controls if focusable.
  - Then sidebar primary navigation.
  - Then page/workspace content.
  - Then composer or page actions.

  Expected:

  - No keyboard trap.
  - No hidden active control receives focus unless intentionally screen-reader-only.

- [ ] **Step 4: Define desktop responsive contract**

  Current shell uses `min-width: 960px`. Keep that if the product is desktop-only, but document it in CSS comments and acceptance notes.

  Expected:

  - At widths below 960px, behavior is intentional: either horizontal app viewport constraint or a later mobile-specific plan.
  - Do not pretend mobile is supported unless the shell actually supports it.

- [ ] **Step 5: Validate accessibility basics**

  Manual checks:

  - Error messages announce via `role="alert"` or `aria-live`.
  - Meaningful images have alt text; decorative images use `alt=""`.
  - Buttons with icon-only visuals have `aria-label`.
  - Heading hierarchy per page starts with one clear `h1` or equivalent page title.

  Expected:

  - No obvious keyboard-only blocker in chat, settings, task panel, automation tasks.

## 8. Final Acceptance Checklist

- [ ] `corepack pnpm --filter @qjclaw/ui typecheck` passes.
- [ ] `corepack pnpm build` passes.
- [ ] Relevant source tests pass for touched views.
- [ ] `App.tsx` has no UTF-8 BOM.
- [ ] `git diff -- apps/ui/src/App.tsx` shows no Chinese mojibake.
- [ ] Chat, experts, tasks, automation, knowledge, settings render with correct height and scrolling.
- [ ] Left sidebar remains left column; right workspace remains full work area.
- [ ] No core smoke selector or `__QJC_SMOKE_ACTIONS__` contract is removed.
- [ ] No visible emoji remains in primary tool controls after Phase 4.
- [ ] Focus-visible states are visible in sidebar, composer, tabs, settings controls, and message actions.

## 9. Suggested Commit Sequence

1. `docs(ui): add client ui ux execution plan`
2. `refactor(ui): document and reduce shell style overlap`
3. `refactor(ui): reduce app renderer prop assembly`
4. `fix(ui): polish chat workspace interactions`
5. `fix(ui): align task automation settings workbench ui`
6. `fix(ui): add renderer keyboard navigation affordances`

Each commit should include the validation commands run in the commit body or PR description.
