# Agents Team - UI 视觉标准文档

> 版本: v1.0  
> 日期: 2026-03-14  
> 适用范围: Web 前端界面开发

---

## 1. 设计原则

### 1.1 核心理念
- **简洁优先**: 去除冗余装饰，聚焦内容展示
- **深色主题**: 采用专业深色配色，减少视觉疲劳
- **信息层级**: 通过颜色和间距清晰区分信息层级
- **流畅交互**: 平滑的过渡动画提升用户体验

### 1.2 布局架构
采用经典的三栏式布局：
```
┌──────────────────────────────────────────────────────────────────────┐
│  [左侧边栏]      [中间主区域]              [右侧面板 - 像素办公室]    │
│  ─────────      ─────────────             ───────────────────        │
│  可折叠          对话/内容区               Agent详情/像素办公室       │
│  项目列表         输入框(底部)              420px 宽度                │
│  设置入口           480px 宽度                                        │
└──────────────────────────────────────────────────────────────────────┘
```

**布局尺寸规范：**
- 左侧边栏: 260px (可折叠至 60px)
- 中间对话区域: 最大 480px，居中显示
- 右侧像素办公室: 420px 固定宽度
- 输入框区域: 最大 640px，与对话区域协调

---

## 2. 色彩系统

### 2.1 基础色彩变量

```css
:root {
  /* 背景色 */
  --bg-primary: #0d0d0d;        /* 主背景 - 纯黑 */
  --bg-secondary: #141414;      /* 次级背景 - 侧边栏 */
  --bg-tertiary: #1a1a1a;       /* 三级背景 */
  --bg-elevated: #242424;       /*  elevated 背景 - 卡片/输入框 */
  --bg-hover: #2a2a2a;          /* 悬停状态 */
  
  /* 文字色 */
  --text-primary: #ffffff;      /* 主文字 */
  --text-secondary: #a1a1a1;    /* 次级文字 */
  --text-tertiary: #6e6e6e;     /* 三级文字 - 提示/禁用 */
  
  /* 边框 */
  --border-color: #2a2a2a;      /* 默认边框 */
  --border-hover: #3a3a3a;      /* 悬停边框 */
}
```

### 2.2 强调色

```css
:root {
  /* 主强调色 - 青绿色系 */
  --accent-primary: #10a37f;        /* 主按钮/高亮 */
  --accent-primary-hover: #0d8c6d;  /* 悬停状态 */
  --accent-secondary: #19c59f;      /* 渐变/装饰 */
  
  /* Agent 角色色 */
  --agent-lead: #f59e0b;        /* Lead - 琥珀色 */
  --agent-worker: #3b82f6;      /* Worker - 蓝色 */
  --agent-reviewer: #8b5cf6;    /* Reviewer - 紫色 */
  
  /* 状态色 */
  --status-success: #10a37f;    /* 成功/运行中 */
  --status-warning: #f59e0b;    /* 警告/等待 */
  --status-error: #ef4444;      /* 错误 */
  --status-neutral: #6b7280;    /* 中性/默认 */
}
```

### 2.3 色彩使用规范

| 场景 | 颜色变量 | 示例 |
|------|----------|------|
| 页面背景 | `--bg-primary` | #0d0d0d |
| 侧边栏背景 | `--bg-secondary` | #141414 |
| 卡片/输入框 | `--bg-elevated` | #242424 |
| 主要按钮 | `--accent-primary` | #10a37f |
| 主要文字 | `--text-primary` | #ffffff |
| 次要说明 | `--text-secondary` | #a1a1a1 |
| 边框 | `--border-color` | #2a2a2a |

---

## 3. 间距系统

### 3.1 间距变量

```css
:root {
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 12px;
  --spacing-lg: 16px;
  --spacing-xl: 24px;
  --spacing-2xl: 32px;
}
```

### 3.2 使用规范

| 场景 | 间距值 | 用途 |
|------|--------|------|
| 图标与文字 | `--spacing-xs` (4px) | 内联图标间距 |
| 紧凑元素 | `--spacing-sm` (8px) | 小按钮、标签 |
| 标准间距 | `--spacing-md` (12px) | 卡片内边距、表单字段 |
| 区块间距 | `--spacing-lg` (16px) | 区块分隔 |
| 大区块 | `--spacing-xl` (24px) | 页面边距、大区块 |
| 超大间距 | `--spacing-2xl` (32px) | Hero 区域、特殊区块 |

---

## 4. 圆角系统

```css
:root {
  --radius-sm: 6px;      /* 小按钮、标签 */
  --radius-md: 8px;      /* 标准按钮、输入框 */
  --radius-lg: 12px;     /* 卡片、面板 */
  --radius-xl: 16px;     /* 大卡片、模态框 */
  --radius-full: 9999px; /* 胶囊形、圆形 */
}
```

### 使用规范

| 组件 | 圆角值 |
|------|--------|
| 小按钮/标签 | `--radius-md` (8px) |
| 输入框 | `--radius-lg` (12px) |
| 卡片/面板 | `--radius-lg` (12px) |
| 大卡片 | `--radius-xl` (16px) |
| 状态标签 | `--radius-full` (胶囊形) |
| 头像 | `--radius-lg` (12px) 或圆形 |

---

## 5. 字体规范

### 5.1 字体栈

```css
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, 
             "Helvetica Neue", Arial, sans-serif;
```

### 5.2 字号层级

| 层级 | 大小 | 字重 | 用途 |
|------|------|------|------|
| 页面标题 | 32px | 700 | 首页 Hero |
| 区块标题 | 18px | 600 | 表单标题 |
| 卡片标题 | 16px | 600 | 面板标题 |
| 正文 | 14px | 400 | 普通文字 |
| 小字 | 13px | 400 | 次要信息 |
| 标签 | 12px | 500 | 标签、时间戳 |
| 微字 | 11px | 500 | 状态标签 uppercase |

---

## 6. 组件规范

### 6.1 按钮

#### 主要按钮 (Primary)
```css
.primary-button {
  padding: 12px 16px;
  background: var(--accent-primary);
  color: white;
  border-radius: var(--radius-lg);
  font-size: 14px;
  font-weight: 500;
  transition: background 150ms ease;
}

.primary-button:hover {
  background: var(--accent-primary-hover);
}
```

#### 次要按钮 (Secondary)
```css
.secondary-button {
  padding: 12px 16px;
  background: var(--bg-elevated);
  color: var(--text-secondary);
  border-radius: var(--radius-lg);
  font-size: 14px;
  font-weight: 500;
  transition: all 150ms ease;
}

.secondary-button:hover {
  background: var(--bg-hover);
  color: var(--text-primary);
}
```

#### 图标按钮
```css
.icon-button {
  width: 40px;
  height: 40px;
  border-radius: var(--radius-md);
  display: flex;
  align-items: center;
  justify-content: center;
  color: var(--text-secondary);
  transition: all 150ms ease;
}

.icon-button:hover {
  background: var(--bg-hover);
  color: var(--text-primary);
}
```

### 6.2 输入框

#### 标准输入框
```css
.input-field {
  width: 100%;
  padding: 12px 16px;
  background: var(--bg-elevated);
  border: 1px solid var(--border-color);
  border-radius: var(--radius-lg);
  color: var(--text-primary);
  font-size: 14px;
  transition: all 150ms ease;
}

.input-field:focus {
  outline: none;
  border-color: var(--accent-primary);
  background: var(--bg-hover);
}

.input-field::placeholder {
  color: var(--text-tertiary);
}
```

#### Kimi 风格聊天输入框
```css
.chat-input-container {
  display: flex;
  align-items: flex-end;
  gap: 8px;
  background: var(--bg-elevated);
  border: 1px solid var(--border-color);
  border-radius: 24px;        /* 大圆角，胶囊形状 */
  padding: 8px 8px 8px 16px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  transition: all 150ms ease;
}

.chat-input-container:focus-within {
  border-color: var(--accent-primary);
  box-shadow: 0 2px 12px rgba(16, 163, 127, 0.15);
}

/* 左侧工具按钮区 */
.chat-input-tools {
  display: flex;
  align-items: center;
  gap: 4px;
  padding-right: 8px;
  border-right: 1px solid var(--border-color);
}

.input-tool-btn {
  width: 28px;
  height: 28px;
  border: none;
  background: transparent;
  color: var(--text-secondary);
  border-radius: 8px;
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
}

.input-tool-btn:hover {
  background: var(--bg-hover);
  color: var(--text-primary);
}

/* 发送按钮 - 圆形 */
.input-action-btn.send {
  width: 32px;
  height: 32px;
  border: none;
  border-radius: 50%;         /* 圆形 */
  background: var(--accent-primary);
  color: white;
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
}

.input-action-btn.send:hover:not(:disabled) {
  background: var(--accent-primary-hover);
  transform: scale(1.05);
}
```

### 6.3 卡片/面板

```css
.card {
  background: var(--bg-secondary);
  border: 1px solid var(--border-color);
  border-radius: var(--radius-lg);
  padding: 16px;
}

.card-elevated {
  background: var(--bg-elevated);
  border: 1px solid var(--border-color);
  border-radius: var(--radius-xl);
  padding: 24px;
}
```

### 6.4 状态标签 (Status Badge)

```css
.status-badge {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  padding: 2px 8px;
  border-radius: 9999px;
  font-size: 11px;
  font-weight: 500;
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

/* 状态变体 */
.status-badge.success {
  background: rgba(16, 163, 127, 0.15);
  color: #34d399;
  border: 1px solid rgba(16, 163, 127, 0.3);
}

.status-badge.warning {
  background: rgba(245, 158, 11, 0.15);
  color: #fbbf24;
  border: 1px solid rgba(245, 158, 11, 0.3);
}

.status-badge.neutral {
  background: rgba(100, 116, 139, 0.15);
  color: #94a3b8;
  border: 1px solid rgba(100, 116, 139, 0.3);
}
```

### 6.5 消息气泡

```css
/* Agent 消息 */
.message-bubble {
  padding: 16px;
  background: var(--bg-secondary);
  border: 1px solid var(--border-color);
  border-radius: var(--radius-lg);
  max-width: 80%;
}

/* 用户消息 */
.message-bubble.user {
  background: var(--bg-elevated);
  border-color: var(--accent-primary);
  margin-left: auto;
}
```

### 6.6 像素办公室 (Pixel Office)

像素办公室是右侧面板的核心功能，以像素风格展示项目中的 Agents 状态。

#### 办公室布局
```css
.pixel-office-panel {
  width: 420px;
  height: 100%;
  background: var(--bg-secondary);
  border-left: 1px solid var(--border-color);
  display: flex;
  flex-direction: column;
}

.office-room {
  position: relative;
  background: var(--bg-tertiary);
  border-radius: 12px;
  padding: 24px;
  min-height: 320px;
}

/* 地板网格 */
.office-floor {
  position: absolute;
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.office-floor-tile {
  flex: 1;
  background: var(--bg-hover);
  border-radius: 6px;
  opacity: 0.5;
}
```

#### 像素角色
```css
.pixel-character {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
  transition: transform 150ms ease;
}

.pixel-character:hover {
  transform: translateY(-2px);
}

.pixel-avatar {
  position: relative;
  width: 44px;
  height: 44px;
  background: var(--bg-elevated);
  border: 2px solid var(--border-color);
  border-radius: 8px;
  display: flex;
  align-items: center;
  justify-content: center;
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
}

/* 角色徽章 */
.pixel-role-badge {
  position: absolute;
  top: -6px;
  right: -6px;
  width: 18px;
  height: 18px;
  background: var(--bg-elevated);
  border: 1px solid var(--border-color);
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 10px;
}

/* 状态指示点 */
.pixel-status-dot {
  position: absolute;
  bottom: -2px;
  left: 50%;
  transform: translateX(-50%);
  width: 8px;
  height: 8px;
  border-radius: 50%;
  border: 2px solid var(--bg-secondary);
}

.pixel-status-dot.typing {
  background: #10a37f;
  animation: pulse 1.5s ease-in-out infinite;
}

.pixel-status-dot.reading { background: #3b82f6; }
.pixel-status-dot.waiting { background: #f59e0b; }
.pixel-status-dot.idle { background: #6b7280; }
```

#### 角色图标映射
| 角色 | 图标 |
|------|------|
| Lead | 👑 |
| Developer | 💻 |
| Reviewer | 👀 |
| Architect | 🏗️ |
| Tester | 🧪 |
| 其他 | 🤖 |

---

## 7. 布局规范

### 7.1 三栏布局

```css
:root {
  /* 布局尺寸变量 */
  --sidebar-width: 260px;
  --sidebar-collapsed-width: 60px;
  --agent-panel-width: 420px;
  --chat-max-width: 480px;
  --input-max-width: 640px;
}

.app-layout {
  display: flex;
  height: 100vh;
  width: 100vw;
  overflow: hidden;
}

/* 左侧边栏 */
.sidebar {
  width: var(--sidebar-width);
  background: var(--bg-secondary);
  border-right: 1px solid var(--border-color);
  flex-shrink: 0;
}

.sidebar-collapsed {
  width: var(--sidebar-collapsed-width);
}

/* 中间主区域 */
.main-content {
  flex: 1;
  display: flex;
  flex-direction: column;
  min-width: 0;
  background: var(--bg-primary);
}

/* 对话消息区域 - 收窄居中 */
.messages-container {
  max-width: var(--chat-max-width);
  margin: 0 auto;
  width: 100%;
}

/* 输入框区域 - Kimi 风格 */
.chat-input-wrapper {
  max-width: var(--input-max-width);
  margin: 0 auto;
  width: 100%;
}

/* 右侧面板 - 像素办公室 */
.agent-panel {
  width: var(--agent-panel-width);
  background: var(--bg-secondary);
  border-left: 1px solid var(--border-color);
  flex-shrink: 0;
}
```

### 7.2 内容区域结构

```
中间主区域:
├── header (60px 高度)
│   ├── 标题 + 状态标签
│   └── 操作按钮
├── agent-selector (可滚动)
│   └── Agent 切换标签
├── chat-area (flex: 1, 可滚动)
│   └── 消息列表
└── chat-input-container
    ├── toolbar (模型/上下文)
    └── input-area (输入框+发送)
```

---

## 8. 交互规范

### 8.1 过渡动画

```css
:root {
  --transition-fast: 150ms ease;
  --transition-normal: 250ms ease;
}

/* 通用过渡 */
.interactive {
  transition: all var(--transition-fast);
}

/* 悬停效果 */
.hover-lift:hover {
  transform: translateY(-1px);
}

/* 按钮点击 */
.button:active {
  transform: scale(0.98);
}
```

### 8.2 滚动条样式

```css
::-webkit-scrollbar {
  width: 8px;
  height: 8px;
}

::-webkit-scrollbar-track {
  background: transparent;
}

::-webkit-scrollbar-thumb {
  background: var(--border-color);
  border-radius: 9999px;
}

::-webkit-scrollbar-thumb:hover {
  background: var(--border-hover);
}
```

---

## 9. 图标规范

### 9.1 图标尺寸

| 场景 | 尺寸 |
|------|------|
| 小图标 (内联) | 16px |
| 标准图标 | 18px |
| 大图标 | 20px |
| 按钮图标 | 与文字搭配 |

### 9.2 图标风格
- 使用 SVG 图标
- 线条粗细: 2px
- 风格: 线性图标 (outline)
- 颜色: 继承父元素颜色

### 9.3 常用图标

```tsx
// 发送
<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
  <path d="M22 2L11 13M22 2l-7 20-4-9-9-4 20-7z" />
</svg>

// 暂停
<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
  <rect x="6" y="4" width="4" height="16" rx="1" />
  <rect x="14" y="4" width="4" height="16" rx="1" />
</svg>

// 设置
<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
  <circle cx="12" cy="12" r="3" />
  <path d="M12 1v6m0 6v6m4.22-10.22l4.24-4.24M6.34 17.66l-4.24 4.24M23 12h-6m-6 0H1m20.24 4.24l-4.24-4.24M6.34 6.34L2.1 2.1" />
</svg>
```

---

## 10. 响应式设计

### 10.1 断点

```css
/* 大屏幕 - 三栏完整显示 */
@media (min-width: 1201px) {
  /* 默认样式 */
}

/* 中等屏幕 - 右侧面板可收起 */
@media (max-width: 1200px) {
  .agent-panel {
    position: fixed;
    right: 0;
    transform: translateX(100%);
  }
  .agent-panel.open {
    transform: translateX(0);
  }
}

/* 小屏幕 - 左侧边栏可收起 */
@media (max-width: 768px) {
  .sidebar {
    position: fixed;
    left: 0;
    transform: translateX(-100%);
  }
  .sidebar.open {
    transform: translateX(0);
  }
}
```

### 10.2 移动端适配
- 侧边栏变为抽屉式
- 输入框变为垂直布局
- 触摸目标最小 44px

---

## 11. 代码示例

### 11.1 完整组件示例

```tsx
// StatusBadge 组件
function StatusBadge({ 
  tone, 
  children 
}: { 
  tone: "success" | "warning" | "neutral" | "error"; 
  children: React.ReactNode;
}) {
  const toneClasses = {
    success: "bg-emerald-500/15 text-emerald-400 border-emerald-500/30",
    warning: "bg-amber-500/15 text-amber-400 border-amber-500/30",
    neutral: "bg-slate-500/15 text-slate-400 border-slate-500/30",
    error: "bg-rose-500/15 text-rose-400 border-rose-500/30",
  };
  
  return (
    <span className={`px-2 py-0.5 text-xs font-medium rounded-full border ${toneClasses[tone]}`}>
      {children}
    </span>
  );
}
```

### 11.2 CSS 类名命名规范

使用语义化命名：
- `.sidebar` - 侧边栏
- `.main-content` - 主内容区
- `.chat-input-container` - 聊天输入容器
- `.agent-panel` - Agent 面板
- `.message-bubble` - 消息气泡

避免使用：
- 无意义的缩写
- 颜色相关的类名 (如 `.red-button`)
- 具体尺寸 (如 `.width-200`)

---

## 12. 检查清单

在提交代码前，请确认：

- [ ] 使用了正确的色彩变量
- [ ] 间距符合规范
- [ ] 圆角一致
- [ ] 字体层级清晰
- [ ] 过渡动画流畅
- [ ] 响应式适配完成
- [ ] 暗色主题下对比度足够
- [ ] 交互状态完整 (hover, active, disabled)

---

## 附录: 参考资源

- 设计灵感: Kimi (kimi.moonshot.cn), Claude (claude.ai)
- 色彩工具: https://colorhunt.co/
- 图标库: Lucide Icons (https://lucide.dev/)
- CSS 变量: 现代浏览器均支持

---

**文档维护**: 如有更新需求，请同步修改本文档。