# 界面设计规范

本文档定义 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` 样例集合