docs: 重写界面设计规范，补充视觉气质、颜色 token、组件状态等内容
This commit is contained in:
Wenjie Zhang
parent
45c5ee7685
commit
72b8adafba
@ -1,68 +1,291 @@
|
|||||||
# 界面设计规范
|
# 界面设计规范
|
||||||
|
|
||||||
## 总览
|
本文档定义 Yuxi 前端界面的基础设计规范，适用于 `web/src` 下的新页面、新组件和现有 UI 调整。它同时面向人类开发者和 AI coding agent：修改界面前先阅读本页，优先复用现有组件、CSS 变量和交互模式。
|
||||||
|
|
||||||
语析平台的 UI 设计致力于打造简洁、高效、一致的用户体验。设计理念以功能为核心，视觉表现为辅助，避免过度装饰，让用户专注于知识管理与 Agent 开发的核心任务。
|
## 1. 视觉气质
|
||||||
|
|
||||||
## 设计原则
|
Yuxi 是知识库、知识图谱与 Agent 开发平台，界面应保持克制、清晰、工程化。设计服务于长时间阅读、配置、调试和数据管理，不做营销页式装饰。
|
||||||
|
|
||||||
### 简洁
|
核心原则：
|
||||||
|
|
||||||
- 界面元素应精简，去除不必要的视觉元素
|
- 功能优先：视觉层级帮助用户理解任务、状态和下一步操作，不为装饰牺牲信息密度。
|
||||||
- 每个组件应有明确的用途，避免功能性冗余
|
- 一致优先：相似功能使用相同布局、颜色、状态和交互反馈。
|
||||||
- 留白适度，提升可读性和操作效率
|
- 轻量优先：用背景、边框、字号和留白建立层级，避免重阴影、夸张渐变和非功能性动效。
|
||||||
|
- 可维护优先：新增样式必须基于现有 token 和组件模式，不为单次需求引入新的设计体系。
|
||||||
|
|
||||||
### 一致性
|
## 2. 颜色与 Token
|
||||||
|
|
||||||
- 全局保持统一的视觉风格和交互模式
|
颜色必须优先使用 `web/src/assets/css/base.css` 和 `web/src/assets/css/base.dark.css` 中定义的 CSS 变量。不要在组件中随意新增硬编码色值；确需新增全局色值时，先补充 token 并说明用途。
|
||||||
- 颜色、字体、间距等遵循 [base.css](web/src/assets/css/base.css) 中的设计变量
|
|
||||||
- 相似功能的组件使用相同的设计模式
|
|
||||||
|
|
||||||
## 禁止项
|
### 主色
|
||||||
|
|
||||||
以下 UI 做法在本项目中明确禁止：
|
`--main-*` 和 `--main-color` 用于品牌主色与关键交互：
|
||||||
|
|
||||||
| 禁止项 | 说明 |
|
| Token | 使用场景 |
|
||||||
|--------|------|
|
| --- | --- |
|
||||||
| 悬停位移 | 组件在 hover 状态下不得产生位置偏移 |
|
| `--main-color` | 主按钮、选中态、重点链接、关键图标 |
|
||||||
| 过度阴影 | 禁止使用浓重阴影进行装饰，仅在必要时使用微弱阴影区分层级 |
|
| `--main-700` / `--main-600` / `--main-500` | 主色文字、hover、active、强调状态 |
|
||||||
| 过度渐变 | 禁止使用夸张渐变，优先使用纯色或微弱渐变 |
|
| `--main-50` / `--main-30` / `--main-10` | 主色浅背景、选中行背景、轻量提示背景 |
|
||||||
| 装饰性动效 | 禁止非功能性的装饰动画 |
|
|
||||||
| 悬停放大 | 禁止 hover 时放大组件尺寸 |
|
|
||||||
| 颜色滥用 | 禁止使用过于鲜艳或刺眼的颜色 |
|
|
||||||
|
|
||||||
## 组件规范
|
主色只用于表达“当前选择、主要操作、关键入口”。不要把主色当作普通装饰色铺在卡片或大面积背景上。
|
||||||
|
|
||||||
### 技术栈
|
### 中性色
|
||||||
|
|
||||||
- 包管理器：pnpm
|
`--gray-*` 是默认界面骨架，用于背景、文本、边框和分割线：
|
||||||
- 图标库：lucide-vue-next（注意尺寸控制），作为 button 需要添加 lucide-icon-btn class 来保证居中
|
|
||||||
|
| Token | 使用场景 |
|
||||||
|
| --- | --- |
|
||||||
|
| `--gray-0` | 页面和卡片主背景 |
|
||||||
|
| `--gray-10` / `--gray-25` / `--gray-50` | 次级背景、hover 背景、弱分区背景 |
|
||||||
|
| `--gray-100` / `--gray-150` / `--gray-200` | 分割线、输入框边框、卡片边框 |
|
||||||
|
| `--gray-900` / `--gray-1000` | 标题和主要正文 |
|
||||||
|
| `--gray-600` / `--gray-500` / `--gray-400` | 辅助说明、占位文本、禁用文本 |
|
||||||
|
|
||||||
|
文本也可以使用 Ant Design 兼容语义变量：`--color-text`、`--color-text-secondary`、`--color-text-tertiary`。组件内优先选语义变量；需要更细层级时再使用 `--gray-*`。
|
||||||
|
|
||||||
|
### 语义色
|
||||||
|
|
||||||
|
语义色只用于状态和反馈，不用于装饰：
|
||||||
|
|
||||||
|
| Token 组 | 使用场景 |
|
||||||
|
| --- | --- |
|
||||||
|
| `--color-success-*` | 成功、已完成、连接正常 |
|
||||||
|
| `--color-error-*` | 错误、危险操作、删除、失败 |
|
||||||
|
| `--color-warning-*` | 警告、待处理、需要注意但未失败 |
|
||||||
|
| `--color-info-*` | 信息提示、说明性状态 |
|
||||||
|
| `--color-accent-*` | 少量辅助强调，不能替代主色 |
|
||||||
|
|
||||||
|
状态标签建议使用浅背景 + 深文字，例如 `background: var(--color-success-50); color: var(--color-success-700);`。不要只依靠颜色传达状态，必要时配合文字或图标。
|
||||||
|
|
||||||
|
### 图表色
|
||||||
|
|
||||||
|
图表和统计可视化优先使用 `--chart-palette-*`。不要复用错误色、警告色做普通图表分类，避免与状态反馈混淆。
|
||||||
|
|
||||||
|
### 暗色模式
|
||||||
|
|
||||||
|
Yuxi 通过 `:root.dark` 覆盖同名 token。新增 UI 必须使用 CSS 变量而不是固定浅色值，并检查浅色、暗色两套表现。
|
||||||
|
|
||||||
|
新增组件时至少检查：
|
||||||
|
|
||||||
|
- 背景、卡片、输入框不出现纯白硬编码导致的暗色穿帮。
|
||||||
|
- 文本和边框在暗色模式下仍有足够对比度。
|
||||||
|
- hover、focus、disabled、selected、error 等状态在暗色模式下可辨认。
|
||||||
|
- 图表、代码块和第三方组件需要显式传入 theme 时，使用 `useThemeStore()` 的现有模式。
|
||||||
|
|
||||||
|
## 3. 字体与文本层级
|
||||||
|
|
||||||
|
全局字体栈定义在 `web/src/assets/css/main.css`，新增组件不要私自引入新字体。代码、命令、路径和技术标识可使用 monospace，优先复用现有 `@mono-font` 或系统 monospace 栈。
|
||||||
|
|
||||||
|
建议层级：
|
||||||
|
|
||||||
|
| 角色 | 建议样式 | 使用场景 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 页面标题 | 20-24px，600 | 页面主标题、弹窗主标题 |
|
||||||
|
| 分组标题 | 16-18px，600 | 卡片标题、表单分组标题 |
|
||||||
|
| 正文 | 14-15px，400 | 常规说明、列表内容 |
|
||||||
|
| 辅助说明 | 12-13px，400 | helper text、元信息、时间、统计说明 |
|
||||||
|
| 标签/状态 | 12px，500 | tag、chip、状态徽标 |
|
||||||
|
| 代码/路径 | 12-14px，monospace | 文件路径、命令、代码片段 |
|
||||||
|
|
||||||
|
文本规范：
|
||||||
|
|
||||||
|
- 标题要短，优先描述对象，不写营销式口号。
|
||||||
|
- 按钮文案使用明确动作，如“保存配置”“重新检测”“删除文件”。
|
||||||
|
- 危险操作必须让文案直接表达后果，如“删除知识库”。
|
||||||
|
- 不使用 placeholder 替代表单 label；placeholder 只做输入示例。
|
||||||
|
- 不使用负字距或按视口宽度缩放字体，避免宽屏和小屏出现不可控排版。
|
||||||
|
|
||||||
|
## 4. 组件样式
|
||||||
|
|
||||||
|
### 技术栈约束
|
||||||
|
|
||||||
|
- 包管理器：`pnpm`
|
||||||
|
- 图标库：优先使用 `lucide-vue-next`
|
||||||
- 样式语言：LESS
|
- 样式语言：LESS
|
||||||
- 样式变量：必须使用 [base.css](web/src/assets/css/base.css) 中定义的颜色变量，且适配暗色模式
|
- 颜色变量：使用 `base.css` / `base.dark.css` 中的 CSS 变量
|
||||||
|
- UI 基础：复用 Ant Design Vue 和项目现有组件模式，避免为单次需求封装新组件体系
|
||||||
|
|
||||||
|
### 按钮
|
||||||
|
|
||||||
### 组件示例
|
按钮应按操作优先级区分：
|
||||||
|
|
||||||
```vue
|
| 类型 | 使用场景 | 样式规则 |
|
||||||
<template>
|
| --- | --- | --- |
|
||||||
<div class="my-component">
|
| 主按钮 | 页面主操作、确认提交 | 使用主色背景或 Ant Design primary，不在同一区域放多个主按钮 |
|
||||||
<LucideIcon :icon="Icons.Settings" :size="16" />
|
| 次按钮 | 返回、取消、普通操作 | 使用中性边框和浅背景，hover 只增强边框或背景 |
|
||||||
<span>设置</span>
|
| 文本/链接按钮 | 表格行内操作、轻量入口 | 保持轻量，不扩大视觉权重 |
|
||||||
</div>
|
| 危险按钮 | 删除、撤销、清空等不可逆操作 | 使用 error 语义色，并配合确认弹窗或明确文案 |
|
||||||
</template>
|
| 图标按钮 | 工具栏、折叠、刷新、复制 | 使用 `lucide-icon-btn` 保证图标与文本居中 |
|
||||||
|
|
||||||
<style lang="less" scoped>
|
交互状态：
|
||||||
|
|
||||||
.my-component {
|
- hover 可以改变 `background`、`border-color`、`color`，不要位移或放大。
|
||||||
display: flex;
|
- focus 必须可见，不能移除键盘焦点样式。
|
||||||
align-items: center;
|
- disabled 使用弱化文本和背景，不绑定 hover 强反馈。
|
||||||
gap: 8px;
|
- loading 应保留按钮宽度，避免布局跳动。
|
||||||
color: @text-color;
|
|
||||||
// 简洁样式，无阴影、无渐变、无悬停位移
|
### 输入框与表单
|
||||||
}
|
|
||||||
</style>
|
表单用于配置和管理任务，优先保证可读性和错误可恢复：
|
||||||
|
|
||||||
|
- 输入框背景使用 `--gray-0` 或 Ant Design 默认容器色。
|
||||||
|
- 边框使用 `--gray-150` / `--gray-200`，focus 使用主色或框架默认 focus ring。
|
||||||
|
- label 必须稳定显示，helper text 放在输入框下方。
|
||||||
|
- 错误信息使用 `--color-error-*`，并写清楚修复方式。
|
||||||
|
- 多字段表单按逻辑分组，避免把无关设置塞进同一行。
|
||||||
|
|
||||||
|
### 卡片、列表与表格
|
||||||
|
|
||||||
|
Yuxi 的信息界面以配置卡片、列表和表格为主，默认使用轻量分层：
|
||||||
|
|
||||||
|
- 普通卡片：`background: var(--gray-0); border: 1px solid var(--gray-150); border-radius: 8px;`
|
||||||
|
- 次级区域：可使用 `var(--gray-10)` / `var(--gray-25)` 做轻背景。
|
||||||
|
- 点击态列表行：hover 只改变背景或边框，不使用 `transform`。
|
||||||
|
- 表格行内操作保持紧凑，避免每行出现多个高权重按钮。
|
||||||
|
- 空状态要说明“当前没有什么”和“下一步可以做什么”，不要只显示图标。
|
||||||
|
|
||||||
|
阴影只用于真实浮层，如弹窗、抽屉、下拉菜单、tooltip。普通卡片和列表不要用阴影制造装饰性层级。
|
||||||
|
|
||||||
|
### 状态标签
|
||||||
|
|
||||||
|
状态标签使用语义色浅背景 + 深文字：
|
||||||
|
|
||||||
|
| 状态 | 推荐 token |
|
||||||
|
| --- | --- |
|
||||||
|
| 成功/正常 | `--color-success-50` + `--color-success-700` |
|
||||||
|
| 失败/错误 | `--color-error-50` + `--color-error-700` |
|
||||||
|
| 警告/待处理 | `--color-warning-50` + `--color-warning-900` |
|
||||||
|
| 信息/运行中 | `--color-info-50` + `--color-info-700` |
|
||||||
|
| 普通/未知 | `--gray-100` + `--gray-600` |
|
||||||
|
|
||||||
|
标签可以使用 pill 圆角，但不要把 pill 形状扩散到所有按钮和卡片。
|
||||||
|
|
||||||
|
### 图标
|
||||||
|
|
||||||
|
- 常规图标尺寸使用 16px、18px 或 20px。
|
||||||
|
- 图标颜色默认继承文本色；需要强调时使用语义 token。
|
||||||
|
- 图标按钮添加 `lucide-icon-btn`，避免图标与文本或按钮中心线错位。
|
||||||
|
- 不为同一概念混用多个图标；相同操作在不同页面保持一致。
|
||||||
|
|
||||||
|
## 5. 布局与间距
|
||||||
|
|
||||||
|
间距以 4px / 8px 为基础节奏：
|
||||||
|
|
||||||
|
| 场景 | 建议值 |
|
||||||
|
| --- | --- |
|
||||||
|
| 图标与文本间距 | 6px / 8px |
|
||||||
|
| 表单项内部间距 | 6px / 8px |
|
||||||
|
| 卡片内部 padding | 16px / 20px / 24px |
|
||||||
|
| 列表行间距 | 8px / 12px |
|
||||||
|
| 页面主要区块间距 | 24px / 32px |
|
||||||
|
| 弹窗内容区间距 | 16px / 24px |
|
||||||
|
|
||||||
|
布局原则：
|
||||||
|
|
||||||
|
- 配置型页面保持适度信息密度，不做大面积营销式留白。
|
||||||
|
- 相邻操作靠近对应内容，页面级操作放在标题区或工具栏。
|
||||||
|
- 一组按钮中主操作在视觉上最明确，取消/返回等次操作弱化。
|
||||||
|
- 宽屏下限制正文行长，避免说明文字横跨整个页面。
|
||||||
|
- 小屏下优先纵向堆叠，避免强行压缩表格和表单字段。
|
||||||
|
|
||||||
|
## 6. 深度与层级
|
||||||
|
|
||||||
|
Yuxi 默认采用“背景 + 边框”的轻量层级：
|
||||||
|
|
||||||
|
| 层级 | 处理方式 | 使用场景 |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| 页面背景 | `var(--gray-0)` 或布局已有背景 | 主页面 |
|
||||||
|
| 次级背景 | `var(--gray-10)` / `var(--gray-25)` | 分区、弱提示、列表 hover |
|
||||||
|
| 卡片边界 | `1px solid var(--gray-150)`，8px 圆角 | 配置卡片、内容块 |
|
||||||
|
| 浮层 | 框架默认阴影或轻量 `--shadow-*` | 弹窗、抽屉、dropdown、tooltip |
|
||||||
|
| 焦点 | 主色 outline / Ant Design focus ring | 键盘可达控件 |
|
||||||
|
|
||||||
|
不要在普通内容卡片上使用重阴影。只有当元素真实覆盖其他内容、需要表达浮层关系时，才允许使用阴影。
|
||||||
|
|
||||||
|
## 7. Do / Don't
|
||||||
|
|
||||||
|
### Do
|
||||||
|
|
||||||
|
- 使用 `base.css` 和 `base.dark.css` 中的 token。
|
||||||
|
- 为新增交互补齐 hover、focus、disabled、loading、empty、error 等必要状态。
|
||||||
|
- 用背景、边框、字号、间距建立层级。
|
||||||
|
- 保持浅色和暗色模式一致可用。
|
||||||
|
- 复用 `lucide-vue-next`、Ant Design Vue 和项目已有组件模式。
|
||||||
|
- 在复杂配置区保留简短说明，帮助用户理解设置影响。
|
||||||
|
|
||||||
|
### Don't
|
||||||
|
|
||||||
|
- 不要在 hover 时使用位移、放大、旋转等装饰性 transform。
|
||||||
|
- 不要使用浓重阴影装饰普通卡片。
|
||||||
|
- 不要使用夸张渐变或大面积高饱和背景。
|
||||||
|
- 不要把语义色用于纯装饰。
|
||||||
|
- 不要新增一次性 helper、样式体系或无复用价值的抽象。
|
||||||
|
- 不要硬编码浅色模式色值导致暗色模式失效。
|
||||||
|
- 不要在同一区域放置多个同等视觉权重的主操作。
|
||||||
|
|
||||||
|
## 8. 响应式行为
|
||||||
|
|
||||||
|
响应式设计以“功能不丢失、信息不挤压”为优先：
|
||||||
|
|
||||||
|
- 小屏下表单字段纵向排列，按钮组可换行。
|
||||||
|
- 侧栏、抽屉和弹窗要保证最小宽度内内容可读。
|
||||||
|
- 表格在小屏下允许横向滚动；不要把关键字段压缩到不可读。
|
||||||
|
- 图标按钮和主要操作需要保持可点击区域，移动端目标尺寸尽量不小于 40px。
|
||||||
|
- 长文本使用省略号时，应提供 tooltip、title 或详情入口查看完整内容。
|
||||||
|
- 图谱、图表、代码块等宽内容应保留横向滚动或自适应缩放策略。
|
||||||
|
|
||||||
|
## 9. Agent Prompt Guide
|
||||||
|
|
||||||
|
AI agent 修改或生成 Yuxi UI 时，优先按这一节执行。
|
||||||
|
|
||||||
|
### Quick Reference
|
||||||
|
|
||||||
|
- 页面背景：`var(--gray-0)`
|
||||||
|
- 次级背景：`var(--gray-10)` / `var(--gray-25)`
|
||||||
|
- 主要文本：`var(--color-text)` 或 `var(--gray-900)`
|
||||||
|
- 次级文本：`var(--color-text-secondary)` 或 `var(--gray-600)`
|
||||||
|
- 边框：`var(--gray-150)` / `var(--gray-200)`
|
||||||
|
- 主色：`var(--main-color)`
|
||||||
|
- 卡片圆角：`8px`
|
||||||
|
- 小控件圆角：`4px` / `6px`
|
||||||
|
- 状态标签圆角：`999px`
|
||||||
|
- 常规图标尺寸：`16px` / `18px` / `20px`
|
||||||
|
- 卡片 padding：`16px` / `20px` / `24px`
|
||||||
|
- 普通 hover：只改变背景、边框或文字颜色
|
||||||
|
|
||||||
|
### Example Prompts
|
||||||
|
|
||||||
|
实现配置卡片：
|
||||||
|
|
||||||
|
```text
|
||||||
|
实现一个 Yuxi 风格的配置卡片：背景使用 var(--gray-0)，边框 1px solid var(--gray-150)，圆角 8px，不加阴影。标题使用 var(--color-text)，说明文字使用 var(--color-text-secondary)。hover 只轻微改变边框或背景，不使用 transform。
|
||||||
```
|
```
|
||||||
|
|
||||||
|
实现工具栏按钮：
|
||||||
|
|
||||||
|
```text
|
||||||
|
实现一个工具栏按钮：优先使用 lucide-vue-next 图标，图标尺寸 16px，按钮添加 lucide-icon-btn。默认使用中性色，hover 时使用 var(--main-color) 或 var(--main-10) 强化，不位移、不放大。
|
||||||
|
```
|
||||||
|
|
||||||
|
实现状态标签：
|
||||||
|
|
||||||
|
```text
|
||||||
|
实现状态标签：成功使用 var(--color-success-50) 背景和 var(--color-success-700) 文字；错误使用 var(--color-error-50) 背景和 var(--color-error-700) 文字；警告使用 var(--color-warning-50) 背景和 var(--color-warning-900) 文字。圆角使用 999px，文字保持 12px。
|
||||||
|
```
|
||||||
|
|
||||||
|
### 实现检查清单
|
||||||
|
|
||||||
|
- 使用现有 CSS 变量，没有新增随意硬编码色值。
|
||||||
|
- 浅色和暗色模式都检查过。
|
||||||
|
- hover、focus、disabled、loading、empty、error 状态符合场景。
|
||||||
|
- 没有使用 hover 位移、放大、旋转或装饰性动画。
|
||||||
|
- 普通卡片没有使用重阴影。
|
||||||
|
- 图标来自 `lucide-vue-next`，尺寸和对齐符合现有模式。
|
||||||
|
- API 接口、组件位置、样式语言符合前端开发规范。
|
||||||
|
|
||||||
## 参考资料
|
## 参考资料
|
||||||
|
|
||||||
- [base.css](web/src/assets/css/base.css) - 全局样式变量
|
- `web/src/assets/css/base.css`：浅色模式 token
|
||||||
|
- `web/src/assets/css/base.dark.css`：暗色模式 token
|
||||||
|
- `web/src/assets/css/main.css`：全局字体、布局基础样式和 `lucide-icon-btn`
|
||||||
|
- [Awesome DESIGN.md](https://github.com/VoltAgent/awesome-design-md)：面向 AI agent 的 `DESIGN.md` 样例集合
|
||||||
|
|||||||
@ -48,6 +48,7 @@
|
|||||||
- 为知识库检索工具补充 `metadata.filepath` 注入：在 `query_kb` 统一出口基于会话可见知识库构建 `file_id -> /home/gem/kbs/...` 映射并回填检索结果，注入逻辑复用知识库只读后端命名规则；并将工具调用范围收敛为 Milvus（仅支持 Milvus chunks 列表且要求显式 `file_id`），不再兼容无显式 `file_id` 的推断注入，新增单测覆盖该约束
|
- 为知识库检索工具补充 `metadata.filepath` 注入：在 `query_kb` 统一出口基于会话可见知识库构建 `file_id -> /home/gem/kbs/...` 映射并回填检索结果，注入逻辑复用知识库只读后端命名规则；并将工具调用范围收敛为 Milvus（仅支持 Milvus chunks 列表且要求显式 `file_id`），不再兼容无显式 `file_id` 的推断注入，新增单测覆盖该约束
|
||||||
- 调整 Milvus 混合检索实现：集合 schema 增加 Milvus 内置 BM25 稀疏向量字段、BM25 函数和中文 analyzer 配置，`keyword` 模式改为 BM25 全文检索，`hybrid` 模式改为 Milvus 原生向量 + BM25 混合检索，并同步更新检索参数说明。
|
- 调整 Milvus 混合检索实现：集合 schema 增加 Milvus 内置 BM25 稀疏向量字段、BM25 函数和中文 analyzer 配置，`keyword` 模式改为 BM25 全文检索，`hybrid` 模式改为 Milvus 原生向量 + BM25 混合检索，并同步更新检索参数说明。
|
||||||
- 修复前端依赖安全告警：通过 `pnpm.overrides` 将传递依赖 `flatted` 锁定到 `3.4.2`、`lodash-es` 锁定到 `4.18.1`，并同步更新 `pnpm-lock.yaml` 以消除 DriftGuard 报告的高危 CVE
|
- 修复前端依赖安全告警：通过 `pnpm.overrides` 将传递依赖 `flatted` 锁定到 `3.4.2`、`lodash-es` 锁定到 `4.18.1`，并同步更新 `pnpm-lock.yaml` 以消除 DriftGuard 报告的高危 CVE
|
||||||
|
- 重写界面设计规范：参考 `DESIGN.md` 写法补充视觉气质、颜色 token、组件状态、布局层级、响应式与 Agent Prompt Guide，并基于该规范收敛首页视觉表现，移除装饰性渐变、重阴影、hover 位移和入场动画。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user