# Feature Specification: Frago GUI界面设计重构

**Feature Branch**: `009-gui-design-redesign`
**Created**: 2025-12-04
**Status**: Draft
**Input**: User description: "通过008迭代创建了GUI初级版本，本迭代专注解决GUI界面设计问题。重点改善配色方案、视觉样式、用户一眼看懂的界面设计。"

## 设计背景分析

### 当前界面问题诊断

参考 `specs/008-gui-app-mode/design.jpg` 和现有实现，当前界面存在以下核心问题：

1. **配色缺乏层次感**
   - 深色主背景 `#1a1a2e` 与次级背景 `#16213e` 对比度不足
   - 强调色 `#00d9ff` (青色) 过于突兀，与整体暗色调缺乏和谐过渡
   - 信息消息气泡使用相同青色背景，视觉上过于刺眼

2. **布局认知负担重**
   - 顶部导航+标签导航+内容区+底部状态栏四层结构略显复杂
   - 主页同时承载欢迎信息、输入区、输出区、进度条，功能堆叠
   - 用户首次打开时难以快速理解"这是什么应用""我应该做什么"

3. **视觉引导缺失**
   - 没有明确的视觉焦点引导用户第一眼该看哪里
   - 各功能区域边界模糊，卡片式设计但缺乏有效的视觉分隔

4. **交互状态反馈弱**
   - 连接状态、任务状态等关键信息淹没在底部状态栏
   - 消息气泡样式过于简单，难以区分不同类型的系统反馈

### 设计目标

将 Frago GUI 从"开发者工具界面"提升为"专业级 AI 助手应用"，让用户：
- **一眼看懂**: 打开即知这是一个可对话的 AI 自动化助手
- **知道该做什么**: 明确的输入引导和交互暗示
- **感受到专业感**: 深色主题下的优雅配色，体现自动化工具的科技感

## User Scenarios & Testing *(mandatory)*

### User Story 1 - 首次打开感知应用定位 (Priority: P1)

作为首次使用 Frago GUI 的用户，打开应用后我希望在3秒内理解这是什么应用、我可以用它做什么，这样我不会感到迷茫或不知所措。

**Why this priority**: 首印象决定用户是否愿意继续探索。如果用户打开应用后感到困惑，很可能直接关闭。这是所有其他体验的前提。

**Independent Test**: 可通过邀请5位未接触过 Frago 的用户进行首次打开测试，记录他们在前10秒内的注视点和第一句话来验证。

**Acceptance Scenarios**:

1. **Given** 用户首次打开 Frago GUI
   **When** 界面完成加载（<2秒）
   **Then** 界面中央显示明确的主输入区域，配合简洁的引导文案，用户立即知道"可以在这里输入命令或问题"

2. **Given** 用户首次打开 Frago GUI
   **When** 用户扫视整个界面
   **Then** 界面层次分明：输入区 > 结果区 > 功能导航，视觉焦点自然落在输入区域

---

### User Story 2 - 在深色主题下获得舒适的视觉体验 (Priority: P1)

作为长时间使用 Frago GUI 的用户，我希望深色主题配色和谐、对比度适中，在持续使用过程中眼睛不会疲劳。

**Why this priority**: 自动化任务通常需要用户持续关注输出结果，糟糕的配色会导致视觉疲劳，直接影响使用体验和效率。

**Independent Test**: 可通过对比测试，让用户在新旧配色方案下各使用30分钟，记录眼睛疲劳程度评分。

**Acceptance Scenarios**:

1. **Given** 用户在深色环境下使用 Frago GUI
   **When** 连续使用30分钟以上
   **Then** 用户不会因为强烈的颜色对比或过高的亮度感到眼睛不适

2. **Given** 用户查看消息对话流
   **When** 用户消息和系统消息交替显示
   **Then** 两种消息类型通过色调差异清晰区分，但整体配色和谐统一

---

### User Story 3 - 快速定位和使用核心功能 (Priority: P2)

作为熟练用户，我希望能快速在不同功能模块间切换（对话、配方、Skills、历史），并且每个模块的用途一目了然。

**Why this priority**: 效率是工具类应用的核心价值，导航清晰度直接影响用户的操作效率。

**Independent Test**: 测量用户从主页切换到配方列表并运行一个配方所需的点击次数和时间。

**Acceptance Scenarios**:

1. **Given** 用户在主页进行对话
   **When** 用户需要查看可用配方
   **Then** 导航标签清晰可见，一次点击即可切换到配方列表

2. **Given** 用户浏览配方列表
   **When** 用户想运行某个配方
   **Then** 配方卡片上有明确的操作提示（如运行按钮或点击即运行的视觉暗示）

---

### User Story 4 - 实时感知系统状态和任务进度 (Priority: P2)

作为正在执行自动化任务的用户，我希望界面能实时清晰地展示当前任务状态、进度和连接状态，这样我知道系统是否在正常工作。

**Why this priority**: 自动化任务可能耗时较长，用户需要明确的状态反馈来判断是否需要等待或干预。

**Independent Test**: 启动一个长时间运行的任务，验证进度更新的及时性和可见性。

**Acceptance Scenarios**:

1. **Given** 用户发送了一个需要执行的命令
   **When** 系统开始处理
   **Then** 界面立即显示加载/处理状态，用户明确知道"系统正在工作"

2. **Given** 有任务正在运行
   **When** 任务状态发生变化（开始、进行中、完成、失败）
   **Then** 状态变化通过视觉元素（颜色、动画、图标）清晰反馈给用户

---

### Edge Cases

- 用户在低分辨率显示器上使用时，布局如何自适应？
- 当配方列表或历史记录为空时，界面如何优雅地引导用户？
- 用户使用高对比度辅助功能时，配色方案如何保持可访问性？
- 连接断开时，界面如何在不干扰用户的情况下持续提示？

## Requirements *(mandatory)*

### Functional Requirements

**配色方案重构**

- **FR-001**: 系统必须采用更柔和的深色主题配色，主背景色调偏向深灰蓝而非纯黑，降低对比度以减少视觉疲劳
- **FR-002**: 强调色必须从高饱和度青色调整为更温和的色调（如低饱和度蓝、紫或绿），与深色背景形成和谐过渡
- **FR-003**: 系统消息和用户消息必须使用可区分但和谐的色调差异，避免使用过亮或过饱和的颜色
- **FR-004**: 交互元素（按钮、链接、选中状态）的颜色必须在深色背景上保持足够对比度的同时不刺眼

**布局优化**

- **FR-005**: 主页布局必须以输入区域为视觉焦点，其他元素围绕输入区组织
- **FR-006**: 导航标签必须精简为最核心的功能入口，减少用户的选择负担
- **FR-007**: 结果/对话区域必须占据足够的视觉空间，支持显示长内容而不感觉拥挤
- **FR-008**: 状态信息必须整合到不干扰主内容区但仍可见的位置

**视觉层次**

- **FR-009**: 界面必须建立清晰的视觉层次：主要操作区 > 内容展示区 > 辅助功能区
- **FR-010**: 各功能区域之间必须通过适当的留白、分隔线或阴影建立视觉边界
- **FR-011**: 空状态（如无历史记录）必须提供友好的引导文案和视觉提示

**交互反馈**

- **FR-012**: 任务执行状态必须通过醒目但不刺眼的视觉元素展示（如微动效、图标变化）
- **FR-013**: 加载状态必须有平滑的过渡动画，避免界面跳动
- **FR-014**: 消息发送后必须立即有视觉反馈（如消息气泡出现动画）

### Key Entities

- **色彩系统**: 定义应用的完整色板，包括背景色阶、文字色阶、强调色、功能色（成功/警告/错误）
- **间距系统**: 定义统一的间距规范（8px 网格或 4px 网格），保证界面一致性
- **组件状态**: 定义各交互组件在不同状态（默认、悬停、激活、禁用、加载）下的视觉表现

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: 80%的新用户在首次打开应用后10秒内能正确描述应用的主要用途（基于用户测试）
- **SC-002**: 用户在新配色方案下连续使用1小时的视觉疲劳评分比旧版降低30%（基于问卷调查）
- **SC-003**: 从主页到执行一个配方的操作路径不超过3次点击
- **SC-004**: 界面在600×1200至600×1600像素范围内保持布局完整，无元素重叠或溢出

## Assumptions

- 深色主题仍是主要设计方向，本次重构不新增浅色主题支持
- 配色调整不涉及图标系统的改动，现有图标继续使用
- 布局优化在现有HTML结构基础上进行，不大规模重构组件层级
- 用户测试可以通过内部测试人员模拟进行，不需要大规模外部用户测试

## 设计规范

### 推荐配色方案

**深色主题 - 科技感与舒适度平衡**

```css
/* 背景色阶 - 低饱和度深灰蓝 */
--bg-base: #0d1117;        /* 最深背景，窗口底色 */
--bg-raised: #161b22;      /* 抬升层，卡片/面板 */
--bg-overlay: #21262d;     /* 覆盖层，下拉菜单/模态框 */
--bg-subtle: #30363d;      /* 微妙强调，悬停状态 */

/* 文字色阶 */
--text-primary: #e6edf3;   /* 主要文字 */
--text-secondary: #8b949e; /* 次要文字 */
--text-muted: #6e7681;     /* 辅助文字 */
--text-link: #58a6ff;      /* 链接文字 */

/* 强调色 - 柔和的蓝 */
--accent-primary: #58a6ff;    /* 主强调色 */
--accent-secondary: #388bfd;  /* 次强调色 */
--accent-muted: #1f6feb;      /* 淡强调色 */

/* 功能色 */
--color-success: #3fb950;
--color-warning: #d29922;
--color-error: #f85149;

/* 边框 */
--border-default: #30363d;
--border-muted: #21262d;
```

### 布局建议

**主页结构精简**
```
┌──────────────────────────────────────┐
│  顶部栏: Logo + 状态指示器 + 设置    │ 44px
├──────────────────────────────────────┤
│  导航: 对话 | 配方 | Skills | 历史   │ 40px
├──────────────────────────────────────┤
│                                      │
│     输入区域 (视觉焦点)              │ 自适应
│     placeholder: "输入命令或问题..."  │
│     [发送按钮]                       │
│                                      │
├──────────────────────────────────────┤
│                                      │
│     对话/结果展示区                  │ 主要空间
│     (消息气泡流)                     │
│                                      │
│                                      │
└──────────────────────────────────────┘
```

### 消息气泡样式建议

- **用户消息**: 右对齐，使用 `--accent-muted` 背景，圆角 12px
- **系统消息**: 左对齐，使用 `--bg-raised` 背景，圆角 12px
- **系统提示**: 居中，使用 `--bg-overlay` 背景，圆角 8px，较小字号
- **错误消息**: 左对齐，`--color-error` 边框，淡红色背景
