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) 建立品牌色系：

// 主品牌色
@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 基准）

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

3. 圆角系统

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

4. 阴影系统（轻量化）

// 从原来过重的 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)

改动前:

<Sider width="88px" className={styles.siderStyle}>

改动后:

<Sider width="240px" className={styles.siderStyle}>

视觉效果:

✅ 侧边栏宽度更合理
✅ 白色背景 + 右侧边框
✅ 轻阴影增加层次感

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

改动前:

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

改动后:

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

CSS 关键改进:

.ragItemActive {
  background: @brand-primary-50;
  color: @brand-primary-600;

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

3. 滚动条样式

改动前:

background: #1570ef;  // 深蓝色

改动后:

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)
卡片间距不统一

改造建议:

// 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 交互

改造建议:

// 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/)

改造建议:

// 使用设计 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 文件开头添加
@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

// 文件开头添加
@import '../../theme/design-tokens.less';

Step 2: 替换硬编码颜色

替换前:

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

替换后:

.myCard {
  background: @color-bg-primary;
  color: @color-text-primary;
  border: 1px solid @color-border-default;
  box-shadow: @shadow-card;
}

Step 3: 使用统一间距

// 替换前
padding: 16px 24px;
margin-bottom: 20px;

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

Step 4: 使用统一圆角

// 替换前
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 级）

🐛 已知问题

Less 编译
- 确保 Less 编译器支持嵌套 @import
- 如遇循环依赖，检查 vars.less 中的变量定义
Ant Design 主题
- 部分 Ant Design 组件可能需要全局样式覆盖
- 已在 layouts/index.less 中添加关键覆盖
浏览器兼容性
- CSS 变量在 IE11 不支持
- 建议最低浏览器版本：Chrome 88+, Safari 14+, Firefox 78+

✅ 验收标准

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

1. 配色一致性

所有蓝色使用品牌色系
灰色使用中性色系
无硬编码颜色值

2. 布局合理性

侧边栏宽度 240px
菜单项高度 48px
间距使用 8px 基准

3. 交互反馈

Hover 状态平滑过渡
激活状态明显区分
点击有视觉反馈

4. 专业度

阴影轻量化
圆角统一
整体简洁大方

📚 参考资源

设计系统

2B 软件设计参考

👨‍💻 技术支持

如有问题，请参考：

设计 Token 文档：web/src/theme/design-tokens.less 中的注释
迁移示例：本文档"迁移清单"章节
GitHub Issues

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

FilesExpand file tree

UI_REDESIGN_GUIDE.md

Latest commit

History

UI_REDESIGN_GUIDE.md

File metadata and controls

KnowFlow UI 改造指南

📊 改造概览

已完成的核心改造

🎨 设计系统详解

1. 配色方案

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

3. 圆角系统

4. 阴影系统（轻量化）

🔧 已改造的组件

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

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

3. 滚动条样式

📝 后续改造建议

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

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

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

🚀 使用指南

如何使用设计 Token

常用 Token 速查

🎯 设计原则

1. 一致性优先

2. 轻量化设计

3. 2B 软件特征

4. 响应式设计

📦 文件结构

🔄 迁移清单

Step 1: 导入设计 Token

Step 2: 替换硬编码颜色

Step 3: 使用统一间距

Step 4: 使用统一圆角

🎨 视觉对比

侧边栏改造对比

配色统一对比

🐛 已知问题

✅ 验收标准

1. 配色一致性

2. 布局合理性

3. 交互反馈

4. 专业度

📚 参考资源

设计系统

2B 软件设计参考

👨‍💻 技术支持