wehub-resource-sync
292 lines
13 KiB
Markdown
292 lines
13 KiB
Markdown
# 界面设计规范
|
||
|
||
本文档定义 Yuxi 前端界面的基础设计规范，适用于 `web/src` 下的新页面、新组件和现有 UI 调整。它同时面向人类开发者和 AI coding agent：修改界面前先阅读本页，优先复用现有组件、CSS 变量和交互模式。
|
||
|
||
## 1. 视觉气质
|
||
|
||
Yuxi 是知识库、知识图谱与 Agent 开发平台，界面应保持克制、清晰、工程化。设计服务于长时间阅读、配置、调试和数据管理，不做营销页式装饰。
|
||
|
||
核心原则：
|
||
|
||
- 功能优先：视觉层级帮助用户理解任务、状态和下一步操作，不为装饰牺牲信息密度。
|
||
- 一致优先：相似功能使用相同布局、颜色、状态和交互反馈。
|
||
- 轻量优先：用背景、边框、字号和留白建立层级，避免重阴影、夸张渐变和非功能性动效。
|
||
- 可维护优先：新增样式必须基于现有 token 和组件模式，不为单次需求引入新的设计体系。
|
||
|
||
## 2. 颜色与 Token
|
||
|
||
颜色必须优先使用 `web/src/assets/css/base.css` 和 `web/src/assets/css/base.dark.css` 中定义的 CSS 变量。不要在组件中随意新增硬编码色值；确需新增全局色值时，先补充 token 并说明用途。
|
||
|
||
### 主色
|
||
|
||
`--main-*` 和 `--main-color` 用于品牌主色与关键交互：
|
||
|
||
| Token | 使用场景 |
|
||
| --- | --- |
|
||
| `--main-color` | 主按钮、选中态、重点链接、关键图标 |
|
||
| `--main-700` / `--main-600` / `--main-500` | 主色文字、hover、active、强调状态 |
|
||
| `--main-50` / `--main-30` / `--main-10` | 主色浅背景、选中行背景、轻量提示背景 |
|
||
|
||
主色只用于表达“当前选择、主要操作、关键入口”。不要把主色当作普通装饰色铺在卡片或大面积背景上。
|
||
|
||
### 中性色
|
||
|
||
`--gray-*` 是默认界面骨架，用于背景、文本、边框和分割线：
|
||
|
||
| 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
|
||
- 颜色变量：使用 `base.css` / `base.dark.css` 中的 CSS 变量
|
||
- UI 基础：复用 Ant Design Vue 和项目现有组件模式，避免为单次需求封装新组件体系
|
||
|
||
### 按钮
|
||
|
||
按钮应按操作优先级区分：
|
||
|
||
| 类型 | 使用场景 | 样式规则 |
|
||
| --- | --- | --- |
|
||
| 主按钮 | 页面主操作、确认提交 | 使用主色背景或 Ant Design primary，不在同一区域放多个主按钮 |
|
||
| 次按钮 | 返回、取消、普通操作 | 使用中性边框和浅背景，hover 只增强边框或背景 |
|
||
| 文本/链接按钮 | 表格行内操作、轻量入口 | 保持轻量，不扩大视觉权重 |
|
||
| 危险按钮 | 删除、撤销、清空等不可逆操作 | 使用 error 语义色，并配合确认弹窗或明确文案 |
|
||
| 图标按钮 | 工具栏、折叠、刷新、复制 | 使用 `lucide-icon-btn` 保证图标与文本居中 |
|
||
|
||
交互状态：
|
||
|
||
- hover 可以改变 `background`、`border-color`、`color`，不要位移或放大。
|
||
- focus 必须可见，不能移除键盘焦点样式。
|
||
- disabled 使用弱化文本和背景，不绑定 hover 强反馈。
|
||
- loading 应保留按钮宽度，避免布局跳动。
|
||
|
||
### 输入框与表单
|
||
|
||
表单用于配置和管理任务，优先保证可读性和错误可恢复：
|
||
|
||
- 输入框背景使用 `--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 接口、组件位置、样式语言符合前端开发规范。
|
||
|
||
## 参考资料
|
||
|
||
- `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` 样例集合
|