# KnowFlow UI 改造指南

基于 2B 软件标准的专业 UI 设计改造

**版本**: v2.1.6
**改造日期**: 2025-10-18
**设计标准**: 参考 Salesforce, Microsoft 365, Notion, Linear

---

## 📊 改造概览

### 已完成的核心改造

✅ **设计系统建立**
- 创建统一的设计 Token 体系 (`web/src/theme/design-tokens.less`)
- 基于 Logo 蓝白基调设计完整配色方案
- 建立 8px 基准的间距系统
- 定义轻量化阴影系统

✅ **全局主题配置**
- 更新 Ant Design 主题配置 (`web/src/theme/theme.ts`)
- 统一变量文件 (`web/src/theme/vars.less`, `web/src/less/variable.less`)
- 配色从混乱的 3 种蓝色统一为品牌蓝色体系

✅ **主布局优化**
- 侧边栏宽度从 88px 扩展到 240px（更符合 2B 标准）
- 白色背景 + 轻阴影替代原有深色背景
- 内容区域增加圆角和卡片阴影

✅ **侧边栏菜单改造**
- 横向布局（图标 + 文字）替代纵向拥挤布局
- 菜单项高度增加到 48px（更易点击）
- 激活状态：左侧蓝色指示条 + 浅蓝背景
- Hover 状态平滑过渡动画

---

## 🎨 设计系统详解

### 1. 配色方案

基于 Logo 渐变色 (#2563eb → #0ea5e9) 建立品牌色系：

```less
// 主品牌色
@brand-primary-500: #3b82f6;  // 主色调
@brand-primary-600: #2563eb;  // Logo 起始色
@brand-gradient: linear-gradient(135deg, #2563eb 0%, #0ea5e9 100%);

// 中性色系
@neutral-50: #f8fafc;   // 页面背景
@neutral-100: #f1f5f9;  // 卡片背景
@neutral-200: #e2e8f0;  // 边框
@neutral-500: #64748b;  // 次要文本
@neutral-900: #0f172a;  // 主文本

// 功能色
@color-success: #10b981;
@color-warning: #f59e0b;
@color-error: #ef4444;
@color-info: #0ea5e9;
```

### 2. 间距系统（8px 基准）

```less
@space-xs: 4px;
@space-sm: 8px;
@space-md: 16px;
@space-lg: 24px;
@space-xl: 32px;
```

### 3. 圆角系统

```less
@radius-sm: 6px;   // 小组件
@radius-md: 8px;   // 按钮、输入框
@radius-lg: 12px;  // 卡片
@radius-xl: 16px;  // 大卡片
```

### 4. 阴影系统（轻量化）

```less
// 从原来过重的 box-shadow: 10px 10px 5px 0px rgba(0,0,0,0.5)
// 改为轻量化设计：
@shadow-sm: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
@shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
@shadow-card: @shadow-sm;
@shadow-card-hover: @shadow-md;
```

---

## 🔧 已改造的组件

### 1. 主布局 (layouts/index.tsx)

**改动前**:
```tsx
<Sider width="88px" className={styles.siderStyle}>
```

**改动后**:
```tsx
<Sider width="240px" className={styles.siderStyle}>
```

**视觉效果**:
- ✅ 侧边栏宽度更合理
- ✅ 白色背景 + 右侧边框
- ✅ 轻阴影增加层次感

### 2. 侧边栏菜单 (layouts/components/header/)

**改动前**:
- 纵向布局（图标上、文字下）
- 宽度 72px，高度 56px
- 激活状态只改变颜色

**改动后**:
- 横向布局（图标 + 文字）
- 宽度 100%，高度 48px
- 激活状态：
  - 左侧 3px 蓝色指示条
  - 浅蓝色背景 (#eff6ff)
  - 深蓝色文字 (#2563eb)

**CSS 关键改进**:
```less
.ragItemActive {
  background: @brand-primary-50;
  color: @brand-primary-600;

  &::before {
    content: '';
    position: absolute;
    left: 0;
    width: 3px;
    height: 24px;
    background: @brand-primary-600;
  }
}
```

### 3. 滚动条样式

**改动前**:
```less
background: #1570ef;  // 深蓝色
```

**改动后**:
```less
background: @brand-primary-300;  // 浅蓝色
&:hover { background: @brand-primary-500; }
```

---

## 📝 后续改造建议

虽然我已完成核心布局改造，但以下页面组件仍需进一步优化：

### 1. 聊天界面 (pages/chat/)

**现有问题**:
- 阴影过重：`box-shadow: 10px 10px 5px 0px rgba(0,0,0,0.5)`
- 背景色混乱：`#f8f8f8`, `#f8fafc`, `rgba(59, 130, 246, 0.08)`
- 卡片间距不统一

**改造建议**:
```less
// web/src/pages/chat/index.less
@import '../../theme/design-tokens.less';

.chatWrapper {
  .chatAppCard {
    background: @color-bg-primary;
    border: 1px solid @color-border-default;
    border-radius: @card-border-radius;
    box-shadow: @shadow-card;
    transition: all @transition-base;

    &:hover {
      box-shadow: @shadow-card-hover;
      border-color: @brand-primary-200;
    }
  }

  .chatAppCardSelected {
    background: @brand-primary-50;
    border-color: @brand-primary-500;
    box-shadow: @shadow-md;
  }
}
```

### 2. 知识库列表 (pages/knowledge/)

**现有问题**:
- 添加卡片使用背景图片而非 CSS
- 卡片样式不够现代
- 缺少 hover 交互

**改造建议**:
```less
// web/src/pages/knowledge/index.less
.knowledgeCardContainer {
  .addCard {
    width: 293px;
    height: 138px;
    background: linear-gradient(135deg, @brand-primary-50 0%, @brand-primary-100 100%);
    border: 2px dashed @brand-primary-300;
    border-radius: @card-border-radius;
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    cursor: pointer;
    transition: all @transition-base;

    &:hover {
      border-color: @brand-primary-500;
      background: linear-gradient(135deg, @brand-primary-100 0%, @brand-primary-200 100%);
      transform: translateY(-2px);
      box-shadow: @shadow-card-hover;
    }
  }
}
```

### 3. 文件管理 (pages/file-manager/)

**改造建议**:
```less
// 使用设计 Token
.fileManagerWrapper {
  :global(.ant-table) {
    background: @color-bg-primary;
    border-radius: @radius-lg;
    overflow: hidden;
    box-shadow: @shadow-card;

    thead > tr > th {
      background: @neutral-50;
      border-bottom: 1px solid @color-border-default;
      color: @color-text-secondary;
      font-weight: @font-weight-semibold;
    }

    tbody > tr {
      transition: background @transition-base;

      &:hover {
        background: @neutral-50;
      }
    }
  }
}
```

---

## 🚀 使用指南

### 如何使用设计 Token

所有新增或修改的样式文件应导入设计 Token：

```less
// 在任何 .less 文件开头添加
@import '../../theme/design-tokens.less';  // 根据文件路径调整层级

// 然后使用 Token
.myComponent {
  color: @color-text-primary;
  background: @color-bg-primary;
  padding: @space-md;
  border-radius: @radius-lg;
  box-shadow: @shadow-card;
}
```

### 常用 Token 速查

| 用途 | Token | 值 |
|------|-------|-----|
| 主色 | `@brand-primary-500` | #3b82f6 |
| 主文本 | `@color-text-primary` | #0f172a |
| 次文本 | `@color-text-secondary` | #475569 |
| 背景 | `@color-bg-primary` | #ffffff |
| 页面背景 | `@neutral-50` | #f8fafc |
| 边框 | `@color-border-default` | #e2e8f0 |
| 卡片阴影 | `@shadow-card` | 轻量 |
| 圆角 | `@radius-lg` | 12px |
| 间距 | `@space-md` | 16px |

---

## 🎯 设计原则

### 1. 一致性优先
- 使用设计 Token，杜绝硬编码颜色
- 统一圆角、间距、阴影规格

### 2. 轻量化设计
- 避免过重阴影
- 减少视觉噪音
- 留白适当

### 3. 2B 软件特征
- 专业、严谨、高效
- 清晰的信息层级
- 易用的交互反馈

### 4. 响应式设计
- 使用 Flexbox/Grid 布局
- 避免固定像素宽度
- 适配不同屏幕尺寸

---

## 📦 文件结构

```
web/src/
├── theme/
│   ├── design-tokens.less      # ✅ 新增：设计 Token
│   ├── theme.ts                # ✅ 更新：Ant Design 主题
│   └── vars.less               # ✅ 更新：兼容性变量
├── less/
│   └── variable.less           # ✅ 更新：引用 Token
├── layouts/
│   ├── index.tsx               # ✅ 更新：侧边栏宽度 240px
│   ├── index.less              # ✅ 重写：使用 Token
│   └── components/header/
│       └── index.less          # ✅ 重写：专业菜单样式
└── pages/
    ├── chat/
    │   └── index.less          # ⏳ 待改造
    ├── knowledge/
    │   └── index.less          # ⏳ 待改造
    ├── search/
    │   └── index.less          # ⏳ 待改造
    ├── agent/
    │   └── index.less          # ⏳ 待改造
    └── file-manager/
        └── index.less          # ⏳ 待改造
```

---

## 🔄 迁移清单

对于需要更新的现有组件，请按以下步骤操作：

### Step 1: 导入设计 Token
```less
// 文件开头添加
@import '../../theme/design-tokens.less';
```

### Step 2: 替换硬编码颜色

**替换前**:
```less
.myCard {
  background: #f8f8f8;
  color: #0d1c2e;
  border: 1px solid #d9d9d9;
  box-shadow: 10px 10px 5px 0px rgba(0, 0, 0, 0.5);
}
```

**替换后**:
```less
.myCard {
  background: @color-bg-primary;
  color: @color-text-primary;
  border: 1px solid @color-border-default;
  box-shadow: @shadow-card;
}
```

### Step 3: 使用统一间距
```less
// 替换前
padding: 16px 24px;
margin-bottom: 20px;

// 替换后
padding: @space-md @space-lg;
margin-bottom: @space-lg;
```

### Step 4: 使用统一圆角
```less
// 替换前
border-radius: 8px;

// 替换后
border-radius: @radius-lg;
```

---

## 🎨 视觉对比

### 侧边栏改造对比

**改造前**:
- 宽度：88px（过窄）
- 布局：纵向（图标上、文字下）
- 激活状态：仅颜色变化
- 背景：灰色 (#f8fafc)

**改造后**:
- 宽度：240px（符合 2B 标准）
- 布局：横向（图标 + 文字）
- 激活状态：左侧指示条 + 浅蓝背景 + 深蓝文字
- 背景：白色 + 右侧边框 + 轻阴影

### 配色统一对比

**改造前** (混乱):
- 主色：`#338AFF`, `#1570EF`, `#3b82f6`
- 灰色：`#64748b`, `#475569`, `#6b7280`, `#999999`

**改造后** (统一):
- 主色：`@brand-primary-500` (#3b82f6)
- 灰色：`@neutral-*` 系列（50-900 共 9 级）

---

## 🐛 已知问题

1. **Less 编译**
   - 确保 Less 编译器支持嵌套 `@import`
   - 如遇循环依赖，检查 `vars.less` 中的变量定义

2. **Ant Design 主题**
   - 部分 Ant Design 组件可能需要全局样式覆盖
   - 已在 `layouts/index.less` 中添加关键覆盖

3. **浏览器兼容性**
   - CSS 变量在 IE11 不支持
   - 建议最低浏览器版本：Chrome 88+, Safari 14+, Firefox 78+

---

## ✅ 验收标准

UI 改造是否成功，可从以下几个维度验收：

### 1. 配色一致性
- [ ] 所有蓝色使用品牌色系
- [ ] 灰色使用中性色系
- [ ] 无硬编码颜色值

### 2. 布局合理性
- [ ] 侧边栏宽度 240px
- [ ] 菜单项高度 48px
- [ ] 间距使用 8px 基准

### 3. 交互反馈
- [ ] Hover 状态平滑过渡
- [ ] 激活状态明显区分
- [ ] 点击有视觉反馈

### 4. 专业度
- [ ] 阴影轻量化
- [ ] 圆角统一
- [ ] 整体简洁大方

---

## 📚 参考资源

### 设计系统
- [Ant Design 设计语言](https://ant.design/docs/spec/introduce-cn)
- [Tailwind CSS 配色](https://tailwindcss.com/docs/customizing-colors)
- [Material Design 色彩系统](https://material.io/design/color)

### 2B 软件设计参考
- [Salesforce Lightning Design System](https://www.lightningdesignsystem.com/)
- [Microsoft Fluent UI](https://developer.microsoft.com/en-us/fluentui)
- [Notion Design](https://www.notion.so/)
- [Linear Design](https://linear.app/)

---

## 👨‍💻 技术支持

如有问题，请参考：
- 设计 Token 文档：`web/src/theme/design-tokens.less` 中的注释
- 迁移示例：本文档"迁移清单"章节
- GitHub Issues

---

**改造完成时间**: 2025-10-18
**设计师**: Claude (基于 2B 软件标准)
**开发状态**: ✅ 核心完成，⏳ 页面待优化