# Research: Frago GUI 界面设计重构

**Date**: 2025-12-04
**Status**: Completed

## 研究目标

解决 spec.md 中提出的设计问题，为配色方案重构提供理论依据和具体实施方案。

---

## 1. 当前问题诊断

### 现有配色分析

| 变量 | 当前值 | 问题 |
|------|--------|------|
| `--bg-primary` | `#1a1a2e` | 偏紫，与内容区对比不足 |
| `--bg-secondary` | `#16213e` | 与主背景差异仅 4% 亮度 |
| `--accent-primary` | `#00d9ff` | 饱和度 100%，过于刺眼 |
| `--text-primary` | `#eaeaea` | 接近纯白，长时间阅读疲劳 |

### 对比度测试结果

- 当前文字 `#eaeaea` 在背景 `#1a1a2e` 上：**12.8:1** (过高)
- 当前强调色 `#00d9ff` 在背景 `#1a1a2e` 上：**10.6:1** (过于刺眼)

**结论**: 对比度过高导致视觉疲劳，需要降低到舒适区间 (7:1 - 11:1)

---

## 2. 行业最佳实践

### WCAG 对比度标准

| 元素类型 | 最低要求 (AA) | 推荐值 |
|----------|--------------|--------|
| 正文文字 | 4.5:1 | 7:1 - 11:1 |
| 大标题 | 3:1 | 4.5:1+ |
| UI 组件 | 3:1 | 4.5:1+ |

### 深色主题设计原则

1. **避免纯黑纯白**
   - 背景用 `#121212` 或 `#0d1117` 代替 `#000000`
   - 文字用 `rgba(255,255,255,0.87)` 代替 `#ffffff`

2. **使用海拔系统表现层次**
   - 通过白色叠加 (5%-16%) 区分层级
   - 避免依赖阴影（深色背景上难以察觉）

3. **降低强调色饱和度**
   - 光亮模式使用饱和色
   - 深色模式降低 10%-20% 饱和度

4. **60-30-10 配色规则**
   - 60% 主背景（深灰）
   - 30% 次级颜色（中灰/卡片）
   - 10% 强调色（品牌色）

---

## 3. 竞品配色分析

### GitHub Dark

```css
--bg-base: #0d1117;        /* 最深背景 */
--bg-raised: #161b22;      /* 卡片背景 */
--bg-overlay: #21262d;     /* 下拉菜单 */
--text-primary: #e6edf3;   /* 主文字 */
--text-secondary: #8b949e; /* 次文字 */
--accent: #58a6ff;         /* 链接/强调 */
```

**特点**: 冷色调深蓝灰，专业感强，适合开发者工具

### VS Code Dark+

```css
--bg-primary: #1e1e1e;     /* 编辑器背景 */
--bg-secondary: #252526;   /* 侧边栏 */
--accent: #007acc;         /* 微软蓝 */
```

**特点**: 中性灰色，高可读性，久经考验

### ChatGPT

```css
--bg-primary: #343541;     /* 暖灰色背景 */
--bg-message: #444654;     /* 助手消息 */
--accent: #10a37f;         /* 青绿色 */
```

**特点**: 暖色调灰色，对话气泡微妙色差

### Claude.ai

```css
--bg-primary: #1a1a1a;     /* 接近纯黑 */
--bg-message: #2f2f2f;     /* 消息背景 */
--accent: #cc785c;         /* 橙红色 */
```

**特点**: 简洁单色调，以内容为核心

---

## 4. 决策：推荐配色方案

### 决策：采用 GitHub Dark 风格

**选择理由**:
1. 与 spec.md 中推荐的配色方案一致
2. 冷色调符合自动化工具的科技感定位
3. 多层次灰色系统成熟，易于扩展
4. 开发者群体熟悉度高

**考虑的替代方案**:
- VS Code Dark+: 过于中性，缺乏品牌特色
- ChatGPT 暖灰: 偏离 Frago 的科技工具定位
- Material Dark: 需要完整的设计系统支持

### 最终配色方案

```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;
```

### 对比度验证

| 组合 | 对比度 | 评级 |
|------|--------|------|
| 主文字 `#e6edf3` / 背景 `#0d1117` | 15.2:1 | AAA |
| 次文字 `#8b949e` / 背景 `#0d1117` | 6.8:1 | AA |
| 强调色 `#58a6ff` / 背景 `#0d1117` | 7.9:1 | AAA |
| 强调色 `#58a6ff` / 背景 `#161b22` | 6.4:1 | AA |

---

## 5. 消息气泡配色

### 决策：采用微妙色差方案

**设计原则**: 用户消息和系统消息通过色调差异区分，但保持整体和谐

```css
/* 用户消息 - 右对齐，强调色背景 */
.message-user {
    background: #1f6feb;        /* --accent-muted */
    color: #ffffff;
}

/* 助手消息 - 左对齐，抬升层背景 */
.message-assistant {
    background: #161b22;        /* --bg-raised */
    color: #e6edf3;
}

/* 系统提示 - 居中，覆盖层背景 */
.message-system {
    background: #21262d;        /* --bg-overlay */
    color: #8b949e;
}

/* 错误消息 - 红色边框 */
.message-error {
    background: rgba(248, 81, 73, 0.1);
    border: 1px solid #f85149;
    color: #f85149;
}
```

---

## 6. 交互状态规范

### 按钮状态

| 状态 | 背景色 | 文字色 |
|------|--------|--------|
| 默认 | `#238636` | `#ffffff` |
| 悬停 | `#2ea043` | `#ffffff` |
| 按下 | `#238636` | `#ffffff` |
| 禁用 | `#21262d` | `#8b949e` |

### 输入框状态

| 状态 | 边框色 | 背景色 |
|------|--------|--------|
| 默认 | `#30363d` | `#0d1117` |
| 聚焦 | `#58a6ff` | `#0d1117` |
| 错误 | `#f85149` | `rgba(248, 81, 73, 0.1)` |

### 导航标签状态

| 状态 | 文字色 | 指示器 |
|------|--------|--------|
| 默认 | `#8b949e` | 无 |
| 悬停 | `#e6edf3` | 无 |
| 激活 | `#58a6ff` | 底部 2px 蓝色条 |

---

## 7. 间距系统

### 决策：采用 8px 网格

| Token | 值 | 用途 |
|-------|-----|------|
| `--spacing-xs` | 4px | 紧凑间距 |
| `--spacing-sm` | 8px | 小间距 |
| `--spacing-md` | 16px | 标准间距 |
| `--spacing-lg` | 24px | 大间距 |
| `--spacing-xl` | 32px | 特大间距 |

---

## 8. 动画规范

### 过渡时间

| Token | 值 | 用途 |
|-------|-----|------|
| `--transition-fast` | 0.1s | 悬停效果 |
| `--transition-normal` | 0.2s | 状态变化 |
| `--transition-slow` | 0.3s | 页面切换 |

### 缓动函数

```css
--ease-out: cubic-bezier(0.33, 1, 0.68, 1);
--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
```

---

## 9. 实施优先级

### P0 - 核心变更（必须）

1. 更新 CSS 变量中的配色定义
2. 调整消息气泡样式
3. 修正导航标签激活状态

### P1 - 重要优化

4. 添加输入框聚焦动画
5. 改进进度条视觉效果
6. 优化卡片悬停效果

### P2 - 锦上添花

7. 添加页面切换动画
8. 改进空状态插图
9. 优化滚动条样式

---

## 参考资料

- [GitHub Primer Design System](https://primer.style/foundations/color)
- [Material Design Dark Theme](https://m2.material.io/design/color/dark-theme.html)
- [WCAG 2.1 Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
